非遗文化传播与主题挖掘系统

本项目是一个面向“非物质文化遗产（ICH）数字化展示与传播洞察”的全栈应用，围绕 “内容展示 + 互动沉淀 + 数据分析” 三条主线，提供从非遗项目内容管理、用户互动（点赞/收藏/评论/分享）、到基于文本数据的主题挖掘（LDA）与传播效果分析的完整闭环。

项目由 Flask 后端与 Vue3 前端组成，数据存储使用 MySQL。前端同时覆盖 用户端门户 与 管理端后台，并提供独立的 分析台（数据集上传、预处理、LDA 训练、报表导出与趋势聚合）。

---

项目目标与定位

核心目标

• 数字化展示：以结构化内容呈现非遗项目（分类、地区、级别、图文、媒体、坐标）。
• 互动沉淀：用户在内容消费过程中产生的互动行为（点赞/收藏/分享）与评论被持久化，为后续分析提供数据基础。
• 主题洞察：对传播文本（数据集中的内容）进行预处理与 LDA 主题挖掘，输出主题关键词、主题热度与相关项目入口。
• 运营评估：以时间粒度（日/周/月）聚合传播指标与互动趋势，形成可视化报表，为运营决策提供依据。

典型使用场景

• 面向公众的非遗项目检索与浏览：按分类/关键词/地区筛选，查看详情与地图分布。
• 内容运营人员在后台维护项目库：新增/编辑项目、上传封面、补齐经纬度与媒体素材。
• 数据分析人员在分析台导入传播数据：执行预处理、训练 LDA、查看主题结果与传播影响报表。
• 管理人员查看资源与互动概览：分类结构完整性、互动趋势与数据质量提示。

---

系统功能概览

用户端（Portal）

• 首页项目检索
  • 分类筛选（四大类，可扩展）
  • 关键词检索
  • 分页浏览与项目卡片展示（封面、摘要、地区、级别）
• 项目详情页（展陈式布局）
  • 标题、分类/地区/级别信息与互动按钮
  • 项目简介（summary + description）
  • 媒体展示（视频/音频）
  • 位置展示：基于经纬度嵌入在线地图（OpenStreetMap），支持外链打开
  • 评论区：发布与列表展示
• 主题展示页
  • 读取 LDA 训练结果：主题列表、关键词、热度、文本数
  • 按非遗分类筛选主题
  • 主题到项目展示页的联动入口
• 地图分布页
  • 基于经纬度散点图展示项目分布
  • 支持按分类与地区筛选
  • 点击散点跳转项目详情
• 个人中心
  • 基本信息维护（用户名/密码/头像）
  • 收藏列表、评论记录等个人数据沉淀

管理端（Admin）

• 项目管理
  • 新增/编辑/删除非遗项目
  • 上传封面/视频/音频（媒体文件存储在后端 uploads 目录并提供静态访问）
  • 维护经纬度与结构化字段（分类/地区/级别/摘要/描述）
• 分类管理
  • 分类维护（名称、编码、排序）
  • 用于统一检索、主题归类、地图筛选与内容结构化
• 用户管理
  • 查看用户列表与角色
  • 支持修改普通用户角色（user/admin）
  • 内置账号保护机制：内置账号（如 admin）标记为 built_in=1，后台禁止修改其角色，避免误操作导致无法登录
• 管理端概览（统计报表）
  • KPI：用户/项目/分类规模与数据完备度（封面/坐标/媒体）
  • 报表：按分类项目数、近 N 天互动趋势（点赞/收藏/分享/评论）

分析台（Analysis）

• 数据集管理
  • 上传 CSV 数据集（传播文本）
  • 数据集预览与导出
• 预处理与训练
  • 文本预处理（停用词/清洗/分词等）
  • 运行 LDA 训练，输出最佳主题数与主题关键词
• 分析报表
  • 传播效果与互动指标的时序聚合
  • 支持日/周/月粒度切换
  • 生成结构化 JSON 报告用于前端可视化

---

技术架构与工程结构

前端（Vue3）

• 技术栈：Vue 3 + Vite + Vue Router + Element Plus + ECharts
• 主要模块：
  • src/layouts/：用户端、管理端、分析台三套布局
  • src/pages/user/：用户端页面（首页/详情/主题/地图/个人中心）
  • src/pages/admin/：管理端页面（概览/项目/分类/用户）
  • src/pages/analysis/：分析台页面
  • src/api/client.js：API 客户端（统一 baseURL /api、统一解包 {code,msg,data}）
  • src/modules/auth/：认证状态管理（token、本地存储、me 信息）
• 交互特点：
  • 通过 Vite dev server 代理 /api 到后端，前端只关心 /api/... 路径
  • 图表使用统一封装 mountChart，支持 resize、动态 setOption

后端（Flask）

• 技术栈：Flask + SQLAlchemy Engine（以 SQL 文本为主）+ PyMySQL + dotenv
• 路由组织：
  • API 统一挂载在 /api（Blueprint api_bp）
  • 统一响应结构：{ code, msg, data }
• 数据层特点：
  • 使用 mysql_db.init_db() 在启动时保证表存在，并执行必要的增量迁移
  • 以 SQL 为主的读写方式，便于清晰掌控字段与索引

---

项目目录结构（文件与职责）

下面列出仓库关键目录与文件，便于快速定位功能与修改点（省略非关键构建产物）：

feiyi-cultural-python-vue3/
├─ flask-app/                         # Flask 后端
│  ├─ app.py                          # 后端入口：创建 app、注册 /api
│  ├─ .env                            # 环境变量（MySQL 连接、端口等）
│  ├─ requirements.txt                # Python 依赖
│  ├─ feiyi.csv                       # 默认示例数据集（dataset_id=default）
│  ├─ sql/
│  │  └─ schema.sql                   # 旧版建表 SQL（模板/参考用）
│  ├─ src/
│  │  ├─ api.py                       # API 路由（Blueprint），/api 下所有接口入口
│  │  ├─ services/
│  │  │  ├─ mysql_db.py               # MySQL URL、Engine、init_db（建表/迁移/种子数据）
│  │  │  ├─ ich_service.py            # 非遗业务：项目/分类/地图点位/互动/评论/统计
│  │  │  ├─ auth_service.py           # 认证：注册/登录、token、profile 更新
│  │  │  ├─ analysis.py               # 分析：预处理、LDA、报表聚合
│  │  │  ├─ datasets.py               # 数据集管理：上传、预览、导出
│  │  │  ├─ media_uploads.py          # 媒体上传与保存
│  │  │  └─ config_files.py           # 停用词/规则配置读写
│  │  └─ utils/
│  │     └─ responses.py              # 统一返回结构 {code,msg,data}
│  ├─ uploads/                        # 运行时上传目录（媒体等）
│  └─ outputs/                        # 运行时输出目录（词云、LDA 结果、报表等）
│
├─ vue3/                              # Vue3 前端
│  ├─ vite.config.js                  # Vite 配置：/api 代理到后端
│  ├─ package.json                    # 前端依赖与脚本
│  ├─ src/
│  │  ├─ main.js                      # 前端入口
│  │  ├─ style.css                    # 全局主题色与基础样式
│  │  ├─ api/client.js                # axios 实例 + unwrap（统一解包）
│  │  ├─ router/index.js              # 路由 + 权限守卫
│  │  ├─ modules/auth/useAuthStore.js # 认证 store（token/user，全局单例）
│  │  ├─ layouts/                     # 三套布局
│  │  │  ├─ UserLayout.vue
│  │  │  ├─ AdminLayout.vue
│  │  │  └─ AnalysisLayout.vue
│  │  ├─ pages/
│  │  │  ├─ user/                     # 用户端：首页/详情/主题/地图/个人中心
│  │  │  ├─ admin/                    # 管理端：概览/分类/项目/用户
│  │  │  └─ analysis/                 # 分析台：数据源/主题/影响等
│  │  └─ components/
│  │     ├─ Charts.js                 # ECharts 挂载封装（resize、setOption）
│  │     └─ LoadingHint.vue           # 统一加载提示
│  └─ public/                         # 静态资源（如有）
│
├─ feiyi_ich.sql                      # 新版 MySQL 快照（结构 + 演示数据，含 DROP TABLE）
├─ init-database.bat                  # Windows 一键导入 feiyi_ich.sql（会重建库）
├─ mac/
│  ├─ init_db_from_sql.sh             # macOS 一键导入 feiyi_ich.sql（自动建库）
│  ├─ setup_and_run.sh                # macOS：安装依赖并启动后端（不做 DB 初始化）
│  ├─ run.sh                          # macOS：快速启动后端（不安装依赖）
│  └─ 项目部署手册_macOS.md
├─ windows/
│  └─ 项目部署手册_Windows.md
└─ 项目说明.md

---

数据模型与关键字段

核心内容

• ich_categories：非遗分类（支持排序，默认四大类，可扩展）
• ich_items：非遗项目
  • title/summary/description：内容展示核心
  • region/level：检索与信息面板
  • cover_url/video_url/audio_url：媒体资源
  • longitude/latitude：地图展示与分布分析

用户与互动

• users
  • role：admin/user
  • built_in：是否内置账号（内置账号禁止修改角色）
  • avatar_url：头像
• ich_actions：互动动作（like/favorite/share），对同一用户与项目的同一动作做唯一约束
• ich_comments：评论记录（关联用户与项目）

数据分析相关

• datasets：上传数据集元信息
• posts：数据集文本明细（内容、发布时间、互动指标等）
• 训练/报表输出：生成于后端 outputs/ 目录，供前端读取展示

---

安全与权限策略

• 认证方式：基于 token（Bearer）访问需要权限的接口
• 权限边界：
  • 用户端：可匿名浏览，互动与个人中心需登录
  • 管理端与分析台：需登录；管理端需要 admin 角色
• 内置账号保护：
  • 数据库层：users.built_in 标记内置账号
  • 后端层：修改角色接口对 built_in=1 强制拒绝
  • 前端层：管理端用户列表对内置账号禁用角色下拉

---

交付物与可扩展方向

已具备的交付能力

• 用户端门户：检索、详情、地图、主题展示、个人中心
• 管理端：项目/分类/用户管理与统计概览
• 分析台：数据集上传、预处理、LDA 训练、报表输出
• 数据闭环：内容维护 → 用户互动沉淀 → 统计报表与趋势评估

可扩展方向（面向后续迭代）

• 更精细的地图：行政区划底图、聚合、热力、区域统计
• 内容结构增强：非遗传承人、时间轴、非遗项目图谱关联
• 推荐与个性化：基于收藏/点赞/浏览的召回与排序
• 数据治理：数据质量评分（坐标/封面/摘要/媒体完备率）与后台巡检清单
• 多数据集对比：多次训练结果对比与版本管理

---

总结

本项目以“非遗项目内容库”为核心，以“互动行为与评论”为数据沉淀，以“LDA 主题挖掘与传播分析”为洞察能力，形成贯穿 展示—运营—分析 的完整系统。其工程结构清晰、模块边界明确，便于持续扩展更多数据分析能力与展陈式内容体验。