非遗油纸伞文化数字体验平台一、项目概述1.1 项目定位本项目是一个面向非物质文化遗产油纸伞文化传播与数字交互的综合 Web 平台。平台以「文化展示 沉浸体验 用户创作 知识传播」为主线将油纸伞的历史渊源、制作工艺、文化内涵与现代 Web 技术相结合帮助公众以可感知、可参与的方式了解并传承这一传统技艺。1.2 核心目标目标维度说明文化传播通过时间轴叙事、工艺视频、图文解读等方式呈现油纸伞千年发展史数字交互提供 3D 模型旋转缩放、DIY 伞面绘制等沉浸式体验用户参与支持用户创作作品、发布至虚拟展厅并进行点赞、收藏、评论知识巩固提供分级知识问答记录答题成绩促进学习效果平台运营配套管理后台支持用户、作品、题库的集中管理与数据统计1.3 适用场景非遗文化数字化展示与教学计算机设计 / 课程设计类 Web 全栈项目传统文化主题互动体验站点二、技术架构2.1 整体架构采用经典前后端分离架构前端 Vue3 SPA 负责页面渲染与交互后端 Express 提供 RESTful APIMySQL 持久化业务数据。服务端浏览器/api 代理/uploads 代理Vue3 前端端口 5174Express API端口 4923MySQLoilpaper_umbrella_platform本地文件 uploads/2.2 技术栈明细前端vue3/类别技术用途框架Vue 3 Vite 7页面开发与构建路由 / 状态Vue Router 4、Pinia路由导航、用户登录态UI 组件Element Plus表单、表格、弹窗等管理端组件网络请求Axios封装/api请求与 Token 拦截3D 渲染Three.js油纸伞 GLB 模型加载与交互画布绘制Fabric.jsDIY 工坊伞面图案创作动画GSAP、Animate.css、Swiper首页时间轴、工艺页滚动动效图表ECharts vue-echarts管理后台数据可视化富文本Marked highlight.jsMarkdown 内容渲染样式Sass组件级样式与主题变量后端express/类别技术用途运行时Node.js服务端运行环境Web 框架Express 4HTTP 服务与路由数据库MySQL 8 mysql2 连接池数据持久化鉴权jsonwebtoken bcryptJWT 登录态、密码加密文件上传Multer作品图片上传至uploads/跨域cors开发环境跨域支持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 前台功能路由页面功能描述/首页左侧历史时间轴 全屏画卷式幻灯按朝代春秋末期→近现代讲述油纸伞发展史支持滚动/点击切换配合背景音乐与水墨视觉动效/craft工艺解读五道古法工艺流程选竹、制骨、裱纸、绘花、上油左侧流程轴 右侧视频/图文详情GSAP 滚动联动/model3d3D 交互基于 Three.js 加载 GLB 模型支持旋转、缩放、部件高亮水墨风格背景与自定义光标/model-3d3D 交互备用另一套 3D 展示实现可按需选用/diyDIY 工坊Fabric.js 画布支持画笔/橡皮、墨色选择、伞面底色纯色/渐变、贴纸纹样可导出作品并发布至展厅/quiz知识回顾展示答题分类历史渊源、制作工艺、文化内涵与传承含难度标识/quiz/:categoryId答题详情按分类逐题作答提交后记录得分与答题记录/gallery虚拟展厅公开展示用户作品支持排序、标签筛选/gallery/create发布作品上传 DIY 作品或图片填写标题、描述、标签/gallery/:id作品详情查看大图、作者信息登录用户可点赞、收藏、评论/profile个人中心查看/编辑个人资料管理我的作品、收藏与答题记录/login登录注册用户登录与注册登录后跳转原页面或首页体验增强特性背景音乐BgmFab首页、3D 页等支持切换与播放控制点击音效clickSfx关键交互按钮附带传统风格音效思源字体 水墨视觉整体 UI 偏向中式非遗美学4.2 管理后台/admin需管理员角色role 99登录后访问路由守卫与后端adminAuth双重校验。路由功能/admin/dashboard数据概览注册用户、作品总数、答题人次答题分类饼图最近作品与用户列表/admin/users用户列表查询修改用户角色普通用户 / 工作人员 / 管理员/admin/works全站作品管理编辑公开状态、标题描述等/admin/quiz题库管理分类 CRUD、题目 CRUD含选项 JSON、正确答案、解析4.3 用户角色体系role 值角色权限0普通用户前台全部功能DIY、发布作品、答题、互动1工作人员预留角色可按业务扩展99管理员访问/admin管理后台全部功能五、数据库设计数据库名oilpaper_umbrella_platform字符集utf8mb4。5.1 表结构概览表名说明主要字段users用户表username, password(bcrypt), nickname, avatar, role, is_deleteworks虚拟展厅作品author_id, title, cover_url, work_url, description, tags, is_public, like/favorite/comment_countwork_likes作品点赞user_id, work_id联合唯一work_favorites作品收藏user_id, work_id联合唯一work_comments作品评论user_id, work_id, content, is_deletequiz_categories答题分类name, sort, difficulty(easy/medium/hard), statusquiz_questions答题题目category_id, title, options(JSON), correct_answer, analysisquiz_records答题记录user_id, category_id, score, total_questions表间通过外键关联删除用户或分类时级联处理关联数据。5.2 初始化数据执行根目录oilpaper_umbrella_platform.sql可一次性创建库表并导入默认管理员账号adminrole993 个答题分类、9 道示例题目6 件示例展厅作品六、API 接口一览6.1 认证/api/auth方法路径说明鉴权POST/login用户登录返回 JWT否POST/register用户注册否6.2 用户/api/users方法路径说明鉴权GET/profile获取当前用户资料是PUT/profile更新昵称、头像等是6.3 作品/api/works方法路径说明鉴权GET/公开作品列表分页、排序否GET/my我的作品是GET/favorites我的收藏是GET/:id作品详情可选GET/:id/comments作品评论列表否POST/发布作品是POST/:id/like点赞是POST/:id/like/cancel取消点赞是POST/:id/favorite收藏是POST/:id/favorite/cancel取消收藏是POST/:id/comment发表评论是DELETE/:id删除作品作者本人是6.4 问答/api/quiz方法路径说明鉴权GET/categories答题分类列表否GET/questions按分类获取题目否GET/records答题记录可选POST/records提交答题结果是6.5 上传/api/upload方法路径说明鉴权POST/上传图片返回可访问 URL是6.6 管理/api/admin以上接口均需登录 role99。模块主要接口统计GET /stats用户GET /users、PUT /users/:id/role作品GET /works、PUT /works/:id题库分类与题目的增删改查/quiz/categories、/quiz/questions七、环境要求与启动指南7.1 环境要求依赖版本建议Node.js≥ 20.19.0 或 ≥ 22.12.0前端 engines 约束MySQL8.x包管理器npm / pnpm / yarn 均可7.2 数据库配置创建 MySQL 数据库或由 SQL 脚本自动创建导入数据mysql-uroot-poilpaper_umbrella_platform.sql修改后端数据库连接express/config/db.js{host:localhost,port:3306,user:root,password:你的密码,database:oilpaper_umbrella_platform}7.3 启动后端cdexpressnpminstall# 或 pnpm installnpmrun dev# nodemon 启动默认 http://localhost:49237.4 启动前端cdvue3npminstallnpmrun dev# 默认 http://localhost:5174自动打开浏览器7.5 生产构建# 前端打包cdvue3npmrun build# 产物在 vue3/dist/# 后端可将 dist 静态文件托管或前后端分域名部署# 生产环境需配置前端 API 基地址并设置 JWT_SECRET 环境变量7.6 默认访问地址服务地址前台首页http://localhost:5174管理后台http://localhost:5174/adminAPI 服务http://localhost:4923/api上传资源http://localhost:4923/uploads/八、安全与配置说明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格式{页面标题} - 非遗油纸伞文化平台十、项目亮点总结文化 技术融合时间轴叙事、工艺视频、3D 模型、DIY 绘制形成完整体验链视觉与交互统一水墨国风 UI、GSAP 动效、音效反馈强化沉浸感完整业务闭环注册登录 → 创作 → 发布 → 展厅互动 → 知识问答 → 管理运营分层清晰的后端Controller / Route / Middleware 职责分明便于扩展可运维的管理端ECharts 统计、用户角色、作品与题库一站式管理十一、常见问题Q前端请求 404 或跨域失败确认后端已启动在 4923 端口且vite.config.js代理配置未被修改。Q数据库连接失败检查 MySQL 服务是否运行、db.js账号密码是否正确、是否已导入 SQL。Q无法进入管理后台确认登录账号role为 99可在数据库users表中修改。Q3D 模型不显示确认vue3/public/models/model.glb存在浏览器需支持 WebGL。Q上传图片无法访问确认express/uploads目录存在写权限且通过/uploads/文件名访问。