一、项目概述

匠韵集 是一个专注于非物质文化遗产（非遗）领域的全栈电商平台，旨在通过数字化手段连接非遗匠人与消费者，促进非遗文化的传播与商业化。平台涵盖商品交易、在线课程（匠艺学堂）、社区论坛、定制服务及 AI 智能助手等多元业务，服务于消费者、匠人与平台管理员三方角色。

项目信息	说明
项目名称	匠韵集（JiangYunJi）
项目类型	全栈 Web 应用
核心领域	非物质文化遗产电商 + 在线教育 + 社区
用户角色	游客 / 普通用户 / 匠人 / 管理员（角色互斥，匠人入驻后仅能使用商家端功能）

二、技术栈总览

2.1 后端技术栈

技术	用途
FastAPI	REST API 框架
Uvicorn	ASGI 服务器
SQLAlchemy	ORM 框架（MySQL）
PyMySQL	MySQL 数据库驱动
Pydantic	数据验证与配置管理
python-jose	JWT Token（HS256）
passlib[bcrypt]	密码哈希
elasticsearch-py	全文搜索客户端
pymongo	MongoDB 驱动（论坛）
pika	RabbitMQ 客户端（延时队列）
httpx	异步 HTTP（Dify AI SSE 流式）
python-alipay-sdk	支付宝沙箱支付（RSA2）
redis-py	缓存 / 分布式锁
阿里云 SMS SDK	短信验证码

2.2 前端技术栈

技术	用途
Vue 3	Composition API 响应式 UI 框架
Vite	构建工具 / 开发服务器
Vue Router 4	SPA 路由 + 路由守卫
Pinia	状态管理（用户状态）
Element Plus	UI 组件库
Axios	HTTP 客户端
ECharts	图表（匠人仪表盘）
qrcode.vue	支付二维码

2.3 基础设施与外部服务

服务	用途
MySQL	主数据库（业务数据）
Redis	缓存 + 分布式锁
Elasticsearch	全文搜索（商品 / 课程）
MongoDB	论坛社区数据
RabbitMQ	延时消息队列（订单超时取消）
Dify AI	文案生成 + 非遗问答（SSE 流式）
支付宝沙箱	在线支付（RSA2 签名）
阿里云 SMS	短信验证码

三、系统架构

3.1 整体架构

3.2 后端分层架构

backend/
├── main.py                  # 应用入口，路由注册，CORS，静态文件
├── config.py                # pydantic-settings 全局配置
├── dependencies.py          # 依赖注入（JWT 认证，角色校验）
├── auth_token.py            # JWT 签发 / 解码
├── auth_utils.py            # 密码哈希 / 验证 / 强度校验
├── sms_service.py           # 阿里云短信服务
├── rabbitmq.py              # RabbitMQ 连接 + 延时消息发布
├── consumer.py              # 消费者进程（超时订单取消）
├── sensitive_words.py       # 敏感词过滤
├── seed.py                  # 种子数据脚本
├── router/                  # 路由层（13 个模块）
├── crud/                    # 数据操作层（9 个模块）
├── schemas/models.py        # 数据模型（20+ 张表）
├── es/                      # Elasticsearch 模块
│   ├── es_client.py         # ES 客户端
│   ├── es_index.py          # 索引管理（IK 分词器）
│   ├── es_sync.py           # MySQL → ES 数据同步
│   └── es_search.py         # 搜索服务（高亮 / 聚合 / 建议）
└── scripts/                 # 迁移脚本（21 个）

3.3 前端架构

frontend/src/
├── main.js                  # 入口（Element Plus + Pinia + Router）
├── router/index.js          # 路由配置 + 路由守卫
├── stores/user.js           # Pinia 用户状态
├── api/
│   ├── index.js             # Axios 实例 + 拦截器
│   └── modules.js           # API 模块封装（12 个）
├── components/              # 公共组件
├── views/                   # 页面组件（40+ 个）
└── assets/styles/           # 全局样式

四、核心功能模块

4.1 用户认证与授权

• 三种登录方式：密码登录、短信验证码登录（自动注册）、管理员密钥登录
• 手机号注册 + 短信验证码验证
• JWT Token 认证（24h 过期，记住登录 30 天）
• 角色权限体系：user → artisan → admin，API 级别 require_role 控制；角色互斥，匠人入驻后仅可访问商家端（发布商品、管理订单、创建课程），不可作为普通消费者浏览商城或购买商品/课程
• 安全防护：密码错误 5 次锁定、bcrypt 哈希、密码强度校验

4.2 商品电商

• 商品管理：匠人发布商品（含 SKU 规格、运费模板）→ 管理员审核 → 佣金确认 → 上/下架
• 分类浏览：树形分类结构（5 个一级 + 19 个二级分类）
• 购物车：增删改查、批量结算
• 订单全流程：创建 → 支付 → 发货 → 收货（含取消），状态机管理
• 支付：支付宝沙箱（RSA2 签名），异步通知 + 同步回调双重保障
• 超时取消：10 分钟未支付自动取消（RabbitMQ TTL + 死信队列）
• 库存防超卖：Redis 分布式锁 + 数据库乐观锁双重保障
• 库存模糊展示：普通消费者（含登录用户）不显示精确库存数字，仅展示「有货 / 库存紧张 / 已售罄」状态；仅商品所属商家与管理员可查看精确库存

4.3 在线课程（匠艺学堂）

• 课程创建：匠人创建课程 → 章节 → 课时（视频上传，最大 500MB）
• 审核流程：管理员审核（通过 / 驳回附原因）
• 报名学习：免费课程直接加入，付费课程走支付流程
• 学习进度：课时级别进度追踪
• 免费试看：标记 is_free 的课时无需购买即可观看
• 课程评论：嵌套评论（需已报名）
• 学习笔记：仅本人可见

4.4 定制服务

• 需求发布：用户提交定制需求（描述 / 图片 / 预算 / 截止日期）
• 报价流程：匠人报价 → 用户接受或拒绝（拒绝可附理由）→ 匠人可重新报价
• 拒绝机制：用户拒绝报价（附理由，匠人可重新报价）/ 匠人拒绝需求（终态）
• 全流程状态机：pending → quoted → accepted → in_progress → shipped → completed，quoted → rejected → quoted（重新报价）
• 定制支付：独立支付流程，接受报价后 10 分钟内未支付自动取消
• 制作进度：匠人更新进度百分比

4.5 论坛社区

• 帖子：发帖（文字 + 图片 / 视频），编辑 / 删除，匠人发帖可关联一件商品
• 互动：点赞、收藏、评论（嵌套回复）
• 关注系统：用户关注用户，粉丝 / 关注列表
• 通知系统：5 种通知类型（点赞 / 收藏 / 评论 / 关注 / 课程评论）
• 数据存储：使用 MongoDB，支持灵活的嵌套文档结构

4.6 匠人管理

• 入驻申请：提交真实姓名 / 身份证 / 专长 / 店铺名 / 店铺头像 / 简介 / 证书
• 审核流程：管理员审核（通过 / 驳回附原因），通过后角色切换为 artisan
• 角色隔离：匠人入驻后仅可访问商家端功能（发布商品、管理订单、创建课程），不可作为普通消费者浏览商城或购买商品/课程
• 数据仪表盘：ECharts 可视化（商品数 / 今日订单 / 累计营收 / 趋势图）
• 交易流水：收入 / 佣金明细

4.7 佣金管理

• 比例配置：管理员按分类配置佣金比例（默认比例 + 分类比例）
• 自动匹配：商品审核通过时自动匹配分类佣金比例
• 佣金确认：匠人确认或申诉佣金比例
• 申诉流程：匠人申诉 → 管理员处理（通过可调整比例 / 驳回）

4.8 AI 服务（Dify 集成）

• AI 非遗问答（面向所有登录用户）：SSE 流式响应，打字机效果，多轮对话
• AI 文案生成（仅匠人）：商品描述 / 课程简介的生成与润色，SSE 流式
• 智能判断：输入 ≤20 字为生成模式，>20 字为润色模式

4.9 搜索功能（Elasticsearch）

• 商品全文检索：multi_match（name^3 + description），其中 ^3 表示 name 字段权重为 description 的 3 倍，高亮，分类 / 价格 / 库存筛选
• 课程全文检索：title^3 + description + craft_intro，其中 ^3 表示 title 字段权重为其他字段的 3 倍
• 搜索建议：completion suggester 自动补全
• 聚合查询：分类 / 品牌分布，价格区间统计
• 降级策略：ES 不可用时自动降级到 MySQL LIKE 查询

4.10 管理后台

• 仪表盘数据统计
• 用户管理（启用 / 禁用）
• 匠人审核（通过 / 驳回）
• 商品审核（通过时自动匹配佣金）
• 课程审核、论坛审核
• 分类管理、轮播图管理
• 佣金管理（比例配置 + 申诉处理）
• 商家管理（申请审核 + 商家列表）

五、数据库设计

5.1 MySQL 8.0（主数据库）

数据库名：project2_db，字符集 utf8mb4，共 20+ 张表。

业务域	核心表
用户域	User、Artisan、ArtisanFollow、ArtisanReview
商品域	Category（树形）、Product（含佣金状态机）、ProductFavorite
交易域	CartItem、Order（goods_type 区分实物/课程）、OrderItem、Address
定制域	CustomOrder（8 种状态）、CustomMessage
课程域	Course、Chapter、Lesson、Enrollment、Comment、StudyNote
佣金域	CommissionRate、CommissionAppeal
其他	Banner、Transaction、BrowseHistory

5.2 MongoDB 6（论坛社区）

数据库名：jiangyunji_forum，集合包括：forum_posts、forum_comments、forum_browse_history、notifications、user_follows、post_favorites、post_likes。

5.3 Redis 7（缓存 / 锁）

• 商品库存缓存（TTL 24 小时）
• 分布式锁（SET NX EX，防止商品超卖）

5.4 Elasticsearch 8.11（搜索）

• 商品索引 products、课程索引 courses
• 使用 IK 中文分词器（ik_max_word 索引，ik_smart 搜索）

六、关键技术亮点

6.1 订单超时自动取消（RabbitMQ 延时队列）

采用 TTL + 死信队列（DLX）架构实现延时消息：

• 订单创建时发布 TTL 消息到延时队列
• 消息过期后转入死信队列
• 独立消费者进程监听死信队列，执行订单取消逻辑

6.2 商品防超卖（双重保障）

• Redis 分布式锁：SET NX EX 获取锁后再操作库存
• 数据库乐观锁：SQL 层面 WHERE stock >= qty 条件更新
• 两层防护确保高并发下不超卖

6.3 ES 搜索降级策略

• ES 服务不可用时，自动降级到 MySQL LIKE 查询
• 保证搜索功能始终可用，不影响用户体验

6.4 AI 流式响应（SSE）

• 通过 httpx 代理 Dify AI 的 SSE 流式响应
• 前端 EventSource 接收，实现打字机效果
• 支持多轮对话（conversation_id 维持上下文）

6.5 商品下架联动处理

商品下架时自动执行联动操作：

• 关联论坛帖子自动转为草稿状态
• 关联轮播图自动禁用
• 保证平台数据一致性

6.6 支付安全设计

• 支付宝 RSA2 签名验证
• 异步通知 + 同步回调双重保障
• 回调验签防止伪造请求

七、项目总结

7.1 项目特点

1. 业务覆盖全面：涵盖电商交易、在线教育、社区论坛、定制服务、AI 助手五大业务域
2. 技术栈现代且多元：后端 FastAPI + 5 种数据存储（MySQL / Redis / ES / MongoDB / RabbitMQ），前端 Vue 3 全家桶
3. 架构设计合理：分层清晰，职责分明，路由 → CRUD → 模型三层解耦
4. 安全机制完善：JWT 认证、角色权限、密码锁定、支付验签、防超卖、敏感词过滤

7.2 技术难点与解决方案

难点	解决方案
订单超时自动取消	RabbitMQ TTL + 死信队列 + 独立消费者进程
高并发防超卖	Redis 分布式锁 + 数据库乐观锁双重保障
搜索服务高可用	ES 不可用时自动降级到 MySQL LIKE 查询
AI 流式响应	httpx 代理 Dify SSE + 前端 EventSource 打字机效果
支付回调安全	RSA2 签名 + 异步通知 + 同步回调双重验签
数据一致性	商品下架联动处理帖子与轮播图
内网穿透域名变更	配置项化管理 Natapp 域名