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 表单验证
- **优点**：安全的密码修改流程，手机号去重保障数据一致性

## 业务流程

### 整体流程图

```mermaid
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、删除（确认弹窗）、点击卡片跳转重新编辑

### 关键数据流图

```mermaid
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

### 启动步骤

```bash
# 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

## 服务器部署

### 部署步骤

```bash
# 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` | 否 | 图片上传存储目录 |

## 常用命令

```bash
# ========== 开发 ==========
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 文档
```