YuShiSheJiShi/README.md

玉宗 - 珠宝设计大师

AI 驱动的珠宝玉石设计生成系统，支持 12 种玉石品类的智能设计图生成。

功能特性

1. 用户认证系统

• 功能说明：支持用户注册、登录、退出，JWT Token 鉴权
• 实现方式：后端使用 python-jose 生成 JWT Token（有效期 1440 分钟），密码通过 passlib + bcrypt 加密存储；前端通过 Axios 拦截器自动携带 Token，401 响应自动跳转登录页
• 优点：无状态认证，前后端分离友好；密码 bcrypt 加密，安全可靠

2. 品类管理系统

• 功能说明：12 种玉石品类（牌子、珠子、手把件、雕刻件、摆件、手镯、耳钉、耳饰、手链、项链、戒指、表带），支持子类型和颜色选择
• 实现方式：品类通过 flow_type 字段区分三种工作流程：full（选子类型，如牌子选牌型）、size_color（选尺寸+颜色，如珠子）、simple（直接设计）；前端 SubTypePanel 组件根据 flow_type 动态渲染不同的选择界面
• 优点：灵活的品类工作流适配不同产品特性，用户操作路径清晰

3. 设计图生成

• 功能说明：用户选择品类参数后输入设计描述，系统生成 800×800 PNG 设计图
• 实现方式：后端 mock_generator 使用 Pillow 生成设计图，包含品类信息、颜色映射（中文颜色名→HEX）、自动文字颜色对比计算、系统中文字体检测（PingFang/STHeiti/DroidSansFallback）；设计记录先创建（status=generating），生成完成后更新为 completed
• 优点：即时生成预览图，支持颜色定制；后续可替换为真实 AI 模型

4. 设计管理

• 功能说明：用户中心查看设计历史列表（分页），支持预览、下载、删除设计
• 实现方式：设计列表通过 DesignListResponse 分页返回（默认每页 20 条），图片通过 FileResponse 下载；删除时同步清理数据库记录和磁盘文件
• 优点：完整的设计生命周期管理，支持历史设计的查看和复用

5. 个人信息管理

• 功能说明：修改昵称、手机号、密码
• 实现方式：手机号唯一性校验，密码修改需验证旧密码；前端表单使用 Element Plus 表单验证
• 优点：安全的密码修改流程，手机号去重保障数据一致性

业务流程

整体流程图

graph TB
    A[用户注册/登录] --> B[设计页 - 选择品类]
    B --> C{品类类型}
    C -->|full| D[选择子类型/牌型]
    C -->|size_color| E[选择尺寸 + 颜色]
    C -->|simple| F[直接进入]
    D --> G[生成页 - 输入设计描述]
    E --> G
    F --> G
    G --> H[提交生成请求]
    H --> I[后端生成设计图]
    I --> J[预览设计图]
    J --> K{用户操作}
    K -->|下载| L[下载 PNG 文件]
    K -->|重新生成| G
    K -->|查看历史| M[用户中心]
    M --> N[设计历史列表]
    N -->|点击卡片| G

各阶段详细流程

1. 用户认证：注册时检查用户名唯一性 → 密码 bcrypt 加密 → 创建用户记录 → 注册成功后自动登录 → 获取 JWT Token 存储到 localStorage
2. 品类选择：进入设计页自动加载品类列表 → 左侧导航选择品类 → 根据 flow_type 加载对应的子类型/颜色数据 → 右侧面板显示选择界面
3. 设计生成：跳转生成页携带品类参数 → 输入设计描述（最多 500 字） → 提交请求 → 显示水墨风格加载动画 → 生成完成后展示预览
4. 设计管理：用户中心加载设计列表 → 卡片网格展示 → 支持分页浏览、下载 PNG、删除（确认弹窗）、点击卡片跳转重新编辑

关键数据流图

graph LR
    A[前端 Store] -->|Axios + Token| B[API 路由]
    B -->|Depends 注入| C[Service 层]
    C -->|SQLAlchemy ORM| D[MySQL 数据库]
    C -->|Pillow 生成| E[uploads/ 目录]
    E -->|StaticFiles 服务| F[前端图片展示]

API 调用链路

接口路径	方法	功能说明	关键参数
/api/auth/register	POST	用户注册	username, password, nickname
/api/auth/login	POST	用户登录	username, password
/api/auth/me	GET	获取当前用户	Bearer Token
/api/users/profile	PUT	更新个人信息	nickname, phone, avatar
/api/users/password	PUT	修改密码	old_password, new_password
/api/categories	GET	获取品类列表	-
/api/categories/{id}/sub-types	GET	获取子类型	category_id
/api/categories/{id}/colors	GET	获取颜色选项	category_id
/api/designs/generate	POST	生成设计	category_id, sub_type_id, color_id, prompt
/api/designs	GET	设计列表(分页)	page, page_size
/api/designs/{id}	GET	设计详情	design_id
/api/designs/{id}	DELETE	删除设计	design_id
/api/designs/{id}/download	GET	下载设计图	design_id

技术栈

分类	技术	版本	说明
前端框架	Vue 3	3.5.30	Composition API + <script setup>
构建工具	Vite	8.0.1	开发服务器 + 构建打包
类型系统	TypeScript	5.9.3	全项目类型化
UI 组件库	Element Plus	2.13.6	表单、弹窗、分页等
状态管理	Pinia	3.0.4	Composition API 风格 Store
路由	Vue Router	4.6.4	History 模式 + 路由守卫
HTTP 客户端	Axios	1.13.6	请求/响应拦截器
CSS 预处理	Sass	1.98.0	SCSS 语法
后端框架	FastAPI	0.109.2	异步 Python Web 框架
ORM	SQLAlchemy	2.0.27	同步模式
数据库驱动	PyMySQL	1.1.0	MySQL 连接
认证	python-jose	3.3.0	JWT Token
密码加密	passlib + bcrypt	1.7.4	bcrypt 哈希
图片生成	Pillow	10.2.0	PNG 设计图生成
数据库	MySQL	-	utf8mb4 编码

目录结构

YuShiSheJi/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── models/             # SQLAlchemy 数据模型
│   │   │   ├── user.py         # 用户模型
│   │   │   ├── category.py     # 品类/子类型/颜色模型
│   │   │   └── design.py       # 设计作品模型
│   │   ├── routers/            # API 路由
│   │   │   ├── auth.py         # 认证路由（注册/登录）
│   │   │   ├── categories.py   # 品类查询路由
│   │   │   ├── designs.py      # 设计生成/管理路由
│   │   │   └── users.py        # 用户信息路由
│   │   ├── schemas/            # Pydantic 数据验证
│   │   ├── services/           # 业务逻辑层
│   │   │   ├── auth_service.py # 认证业务
│   │   │   ├── design_service.py # 设计业务
│   │   │   └── mock_generator.py # 图片生成服务
│   │   ├── utils/              # 工具函数
│   │   │   ├── deps.py         # 认证依赖注入
│   │   │   └── security.py     # JWT/密码工具
│   │   ├── config.py           # 配置管理
│   │   ├── database.py         # 数据库连接
│   │   └── main.py             # 应用入口
│   ├── uploads/                # 生成图片存储目录
│   ├── .env                    # 环境变量
│   └── requirements.txt        # Python 依赖
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── api/                # API 接口定义
│   │   │   ├── request.ts      # Axios 实例（拦截器）
│   │   │   ├── auth.ts         # 认证接口
│   │   │   ├── category.ts     # 品类接口
│   │   │   └── design.ts       # 设计接口
│   │   ├── components/         # 公共组件
│   │   │   ├── AppHeader.vue   # 顶部导航栏
│   │   │   ├── CategoryNav.vue # 品类左侧导航
│   │   │   ├── SubTypePanel.vue# 子类型/颜色选择面板
│   │   │   ├── ColorPicker.vue # 颜色选择器
│   │   │   └── DesignPreview.vue # 设计预览（缩放/下载）
│   │   ├── stores/             # Pinia 状态管理
│   │   │   ├── user.ts         # 用户状态
│   │   │   ├── category.ts     # 品类状态
│   │   │   └── design.ts       # 设计状态
│   │   ├── views/              # 页面组件
│   │   │   ├── Login.vue       # 登录页
│   │   │   ├── Register.vue    # 注册页
│   │   │   ├── DesignPage.vue  # 设计页（品类选择）
│   │   │   ├── GeneratePage.vue# 生成页（输入描述+预览）
│   │   │   └── UserCenter.vue  # 用户中心（历史+信息）
│   │   ├── router/index.ts     # 路由配置 + 认证守卫
│   │   ├── assets/styles/theme.scss # 品牌主题色
│   │   └── main.ts             # 应用入口
│   ├── package.json
│   └── vite.config.ts          # Vite 配置（代理）
└── init_data.sql               # 数据库初始化脚本

本地开发

环境要求

• Python 3.10+
• Node.js 18+
• MySQL 5.7+ / 8.0
• npm 或 pnpm

启动步骤

# 1. 创建数据库
mysql -u root -p -e "CREATE DATABASE yuzong CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 2. 初始化表结构（FastAPI 启动时 SQLAlchemy 自动创建表）并导入初始数据
mysql -u root -p yuzong < init_data.sql

# 3. 后端启动
cd backend
cp .env.example .env  # 修改数据库连接信息
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

# 4. 前端启动（新终端）
cd frontend
npm install
npm run dev

前端访问：http://localhost:3000 后端 API：http://localhost:8000 API 文档：http://localhost:8000/docs

服务器部署

部署步骤

# 1. 安装依赖
cd backend && pip install -r requirements.txt
cd frontend && npm install

# 2. 前端构建
cd frontend
npm run build  # 输出到 dist/ 目录

# 3. 配置后端环境变量
cd backend
vim .env  # 配置生产数据库地址和密钥

# 4. 启动后端服务
uvicorn app.main:app --host 0.0.0.0 --port 8000

# 5. Nginx 配置（前端静态文件 + API 反向代理）
# location / { root /path/to/frontend/dist; try_files $uri $uri/ /index.html; }
# location /api { proxy_pass http://127.0.0.1:8000; }
# location /uploads { proxy_pass http://127.0.0.1:8000; }

数据库

表结构说明

分类	表名	说明
用户	users	用户基本信息（用户名、密码、昵称、手机、头像）
品类	categories	12 种玉石品类（名称、图标、排序、流程类型）
品类	sub_types	品类子类型（牌型/尺寸，关联品类）
品类	colors	品类颜色选项（颜色名、HEX 色值，关联品类）
设计	designs	设计记录（用户、品类、子类型、颜色、描述、图片URL、状态）

环境变量

配置项	默认值	必填	说明
DATABASE_URL	mysql+pymysql://root:password@localhost:3306/yuzong	是	MySQL 连接字符串
SECRET_KEY	your-secret-key-change-this	是	JWT 签名密钥（生产环境务必修改）
ALGORITHM	HS256	否	JWT 算法
ACCESS_TOKEN_EXPIRE_MINUTES	1440	否	Token 有效期（分钟，默认 24 小时）
UPLOAD_DIR	uploads	否	图片上传存储目录

常用命令

# ========== 开发 ==========
cd backend && uvicorn app.main:app --reload --port 8000   # 启动后端（热重载）
cd frontend && npm run dev                                  # 启动前端开发服务器
cd frontend && npm run build                                # 前端生产构建

# ========== 数据库 ==========
mysql -u root -p yuzong < init_data.sql                     # 导入初始品类数据
mysql -u root -p -e "SELECT * FROM yuzong.categories;"      # 查看品类数据

# ========== 依赖管理 ==========
cd backend && pip install -r requirements.txt               # 安装后端依赖
cd frontend && npm install                                  # 安装前端依赖

# ========== 调试 ==========
curl http://localhost:8000/health                            # 后端健康检查
curl http://localhost:8000/docs                              # 查看 API 文档