非遗油纸伞文化数字体验平台

非遗油纸伞文化数字体验平台

一、项目概述

1.1 项目定位

本项目是一个面向非物质文化遗产油纸伞文化传播与数字交互的综合 Web 平台。平台以「文化展示 + 沉浸体验 + 用户创作 + 知识传播」为主线，将油纸伞的历史渊源、制作工艺、文化内涵与现代 Web 技术相结合，帮助公众以可感知、可参与的方式了解并传承这一传统技艺。

1.2 核心目标

1.3 适用场景

• 非遗文化数字化展示与教学
• 计算机设计 / 课程设计类 Web 全栈项目
• 传统文化主题互动体验站点

二、技术架构

2.1 整体架构

采用经典前后端分离架构：前端 Vue3 SPA 负责页面渲染与交互，后端 Express 提供 RESTful API，MySQL 持久化业务数据。

2.2 技术栈明细

前端（vue3/）

后端（express/）

2.3 接口约定

• 基础路径：/api
• 统一响应格式：

{
  "code": 200,
  "msg": "success",
  "data": {}
}

• 鉴权方式：请求头 Authorization: Bearer <token>
• 前端代理：开发时 Vite 将 /api、/uploads 代理至 http://localhost:4923

三、项目目录结构

chinese-oil-paper-umbrella/
├── oilpaper_umbrella_platform.sql   # 数据库完整结构与初始数据
├── 项目说明.md                       # 本文档
│
├── express/                         # 后端服务
│   ├── app.js                       # Express 应用入口（CORS、静态资源、路由挂载）
│   ├── bin/www                      # HTTP 服务启动（默认端口 4923）
│   ├── config/
│   │   ├── db.js                    # MySQL 连接池配置
│   │   ├── index.js                 # 应用级配置（密钥等）
│   │   └── security.js              # 安全相关配置
│   ├── controllers/                 # 控制器：auth / user / works / quiz / upload / admin
│   ├── routes/                      # 路由定义，统一挂载于 /api
│   ├── middlewares/
│   │   └── auth.js                  # JWT 鉴权、可选鉴权、管理员鉴权
│   ├── util/                        # 工具：加密、角色、微信等
│   ├── scripts/                     # 数据库初始化 SQL 片段
│   ├── uploads/                     # 用户上传图片存储目录
│   └── public/                      # 后端静态资源
│
└── vue3/                            # 前端应用
    ├── index.html
    ├── vite.config.js               # 开发服务器、路径别名、API 代理
    ├── src/
    │   ├── api/                     # 接口封装（request.js + index.js）
    │   ├── assets/                  # 图片、视频、音频、字体、全局样式
    │   ├── components/              # 公共组件（导航栏、页脚、上传、编辑器等）
    │   ├── config/                  # 背景音乐、点击音效映射
    │   ├── directives/              # 自定义指令（如点击音效）
    │   ├── layouts/                 # WebsiteLayout（前台）、MainLayout（后台）
    │   ├── router/index.js          # 路由与权限守卫
    │   ├── stores/user.js           # 用户登录态 Pinia Store
    │   ├── utils/                   # 格式化、加密等工具
    │   └── views/                   # 页面视图（见下文功能模块）
    └── public/
        └── models/model.glb         # 3D 油纸伞模型文件

四、功能模块说明

4.1 前台功能

体验增强特性

• 背景音乐（BgmFab）：首页、3D 页等支持切换与播放控制
• 点击音效（clickSfx）：关键交互按钮附带传统风格音效
• 思源字体 + 水墨视觉：整体 UI 偏向中式非遗美学

4.2 管理后台（/admin）

需 管理员角色（role = 99） 登录后访问，路由守卫与后端 adminAuth 双重校验。

4.3 用户角色体系

五、数据库设计

数据库名：oilpaper_umbrella_platform，字符集 utf8mb4。

5.1 表结构概览

表间通过外键关联，删除用户或分类时级联处理关联数据。

5.2 初始化数据

执行根目录 oilpaper_umbrella_platform.sql 可一次性创建库表并导入：

• 默认管理员账号：admin（role=99）
• 3 个答题分类、9 道示例题目
• 6 件示例展厅作品

六、API 接口一览

6.1 认证 /api/auth

6.2 用户 /api/users

6.3 作品 /api/works

6.4 问答 /api/quiz

6.5 上传 /api/upload

6.6 管理 /api/admin

以上接口均需 登录 + role=99。

七、环境要求与启动指南

7.1 环境要求

7.2 数据库配置

1. 创建 MySQL 数据库（或由 SQL 脚本自动创建）
2. 导入数据：

mysql -u root -p < oilpaper_umbrella_platform.sql

3. 修改后端数据库连接（express/config/db.js）：

{
  host: "localhost",
  port: "3306",
  user: "root",
  password: "你的密码",
  database: "oilpaper_umbrella_platform"
}

7.3 启动后端

cd express
npm install          # 或 pnpm install
npm run dev          # nodemon 启动，默认 http://localhost:4923

7.4 启动前端

cd vue3
npm install
npm run dev          # 默认 http://localhost:5174，自动打开浏览器

7.5 生产构建

# 前端打包
cd vue3 && npm run build    # 产物在 vue3/dist/

# 后端可将 dist 静态文件托管，或前后端分域名部署
# 生产环境需配置前端 API 基地址，并设置 JWT_SECRET 环境变量

7.6 默认访问地址

八、安全与配置说明

8.1 JWT 密钥

后端 middlewares/auth.js 使用环境变量 JWT_SECRET，未设置时回退默认值 oil_paper_umbrella_secret。生产环境务必通过环境变量配置强密钥。

8.2 密码存储

用户密码使用 bcrypt 加盐哈希，明文不存入数据库。

8.3 CORS

当前后端 app.js 配置 origin: "*"，适合开发调试；生产环境建议收紧为前端实际域名。

8.4 上传限制

图片上传经 Multer 处理，存储于 express/uploads/，通过 /uploads 静态路径访问。注意磁盘空间与文件类型校验。

九、前端路由与权限

路由定义见 vue3/src/router/index.js：

• 前台路由嵌套在 WebsiteLayout 下，共享导航栏与页脚
• /admin/* 路由设置 meta.requireAdmin: true
• 全局 beforeEach 守卫：未登录跳转 /login?redirect=...；非管理员访问后台则重定向首页
• 页面 document.title 格式：{页面标题} - 非遗油纸伞文化平台

十、项目亮点总结

1. 文化 + 技术融合：时间轴叙事、工艺视频、3D 模型、DIY 绘制形成完整体验链
2. 视觉与交互统一：水墨国风 UI、GSAP 动效、音效反馈，强化沉浸感
3. 完整业务闭环：注册登录 → 创作 → 发布 → 展厅互动 → 知识问答 → 管理运营
4. 分层清晰的后端：Controller / Route / Middleware 职责分明，便于扩展
5. 可运维的管理端：ECharts 统计、用户角色、作品与题库一站式管理

十一、常见问题

Q：前端请求 404 或跨域失败？
确认后端已启动在 4923 端口，且 vite.config.js 代理配置未被修改。

Q：数据库连接失败？
检查 MySQL 服务是否运行、db.js 账号密码是否正确、是否已导入 SQL。

Q：无法进入管理后台？
确认登录账号 role 为 99，可在数据库 users 表中修改。

Q：3D 模型不显示？
确认 vue3/public/models/model.glb 存在；浏览器需支持 WebGL。

Q：上传图片无法访问？
确认 express/uploads 目录存在写权限，且通过 /uploads/文件名 访问。