YuShiSheJiShi/README.md

# 玉宗 - 珠宝设计大师

AI 驱动的珠宝玉石设计生成系统，支持 12 种玉石品类的智能设计图生成，双 AI 模型多视角生图，内置后台管理系统。

## 功能特性

### 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. AI 多视角设计图生成
- **功能说明**：用户选择品类参数后，可配置 6 个可选设计参数（雕刻工艺、设计风格、题材纹样、尺寸规格、表面处理、用途场景），输入设计描述后系统自动生成多视角设计图（每个品类 2~4 张不同视角）
- **双模型支持**：
  - **SiliconFlow FLUX.1 [dev]**（默认）：~0.13元/张，性价比高
  - **火山引擎 Seedream 4.5**（备选）：~0.30元/张，高质量
- **提示词系统**：自动将中文参数（品类/子类型/颜色/6个设计参数+视角）构建为专业英文 prompt，包含玉雕行业专业术语、摄影角度、质量标签
- **按品类视角配置**：
  | 品类 | 视角数 | 视角列表 |
  |------|--------|----------|
  | 牌子 | 3 | 效果图(45°)、正面图、背面图 |
  | 珠子 | 2 | 效果图(45°)、正面图 |
  | 手把件/雕刻件/摆件 | 4 | 效果图(45°)、正面图、侧面图、背面图 |
  | 手镯 | 3 | 效果图(45°)、正面图、侧面图 |
  | 耳钉/耳饰/手链/项链/表带 | 2 | 效果图(45°)、正面图 |
  | 戒指 | 3 | 效果图(45°)、正面图、侧面图 |
- **降级机制**：AI 生图失败时自动降级到 mock_generator 生成占位图
- **可选参数**：
  - **雕刻工艺**：浮雕、圆雕、镂空雕、阴刻、线雕、俍色雕、薄意雕、素面，支持自定义输入
  - **设计风格**：古典传统、新中式、写实、抽象意境、极简素面，支持自定义输入
  - **题材纹样**：观音、弥勒、莲花、貔貅、龙凤、麒麟、山水、花鸟、人物、回纹、如意、平安扣，支持自定义输入
  - **尺寸规格**：根据品类动态变化（牌子尺寸/手镯内径/手把件大小等），支持自定义输入
  - **表面处理**：高光抛光、亚光/哑光、磨砂、保留皮色，支持自定义输入
  - **用途场景**：日常佩戴、收藏鉴赏、送礼婚庆、把玩文玩，支持自定义输入
- **实现方式**：后端 `prompt_builder` 自动构建专业英文 prompt → `ai_generator` 调用 AI API 生图 → 下载保存到本地 → 创建 `DesignImage` 多视角记录；降级时使用 `mock_generator` Pillow 生成占位图
- **优点**：AI 真实生图 + 多视角展示，专业玉雕提示词系统，双模型热切换 + 降级兜底

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

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

### 6. 后台管理系统
- **功能说明**：管理员专属后台，支持仪表盘、系统配置、用户管理、品类管理、设计管理五大模块
- **实现方式**：
  - **权限控制**：用户表 `is_admin` 字段 + `get_admin_user` 依赖注入，非管理员访问返回 403
  - **系统配置**：`system_configs` 表存储配置项，数据库配置优先于 .env 文件；敏感信息（API Key）脱敏显示
  - **品类管理**：支持品类、子类型、颜色的增删改查，含颜色拾色器
  - **用户管理**：搜索、分页、设置/取消管理员、删除用户
  - **设计管理**：查看所有用户设计，按状态筛选，管理员删除
  - **前端独立布局**：左侧导航 + 内容区，管理后台与前台完全分离
- **优点**：AI 配置可热更新（无需重启服务），品类数据可视化管理，用户权限分级控制

## 业务流程

### 整体流程图

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

### 各阶段详细流程

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

### 关键数据流图

```mermaid
graph LR
    A[前端 Store] -->|“Axios + Token”| B[API 路由]
    B -->|“Depends 注入”| C[Service 层]
    C -->|prompt_builder| D1[英文 Prompt 构建]
    D1 -->|ai_generator| D2[AI 生图 API]
    D2 -->|下载保存| E[uploads/ 目录]
    C -->|SQLAlchemy ORM| D[MySQL 数据库]
    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, carving_technique?, design_style?, motif?, size_spec?, surface_finish?, usage_scene? |
| `/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 |
| `/api/admin/dashboard` | GET | 管理仪表盘统计 | Bearer Token (管理员) |
| `/api/admin/configs` | GET | 获取系统配置 | group? |
| `/api/admin/configs` | PUT | 更新系统配置 | configs: {key: value} |
| `/api/admin/configs/init` | POST | 初始化默认配置 | - |
| `/api/admin/users` | GET | 用户列表 | page, page_size, keyword? |
| `/api/admin/users/{id}/admin` | PUT | 设置管理员 | is_admin |
| `/api/admin/categories` | GET/POST | 品类列表/创建 | name, flow_type, sort_order |
| `/api/admin/categories/{id}` | PUT/DELETE | 更新/删除品类 | - |
| `/api/admin/sub-types` | POST | 创建子类型 | category_id, name |
| `/api/admin/colors` | POST | 创建颜色 | category_id, name, hex_code |
| `/api/admin/designs` | GET | 所有设计列表 | page, status? |

## 技术栈

| 分类 | 技术 | 版本 | 说明 |
|-----|------|------|-----|
| **前端框架** | 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 设计图生成（mock 降级） |
| **AI 生图** | SiliconFlow FLUX.1 / Seedream 4.5 | - | 双模型多视角生图 |
| **HTTP 客户端** | httpx | 0.27.0 | 异步调用 AI API + 图片下载 |
| **数据库** | MySQL | - | utf8mb4 编码 |

## 目录结构

```
YuShiSheJi/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── models/             # SQLAlchemy 数据模型
│   │   │   ├── user.py         # 用户模型
│   │   │   ├── category.py     # 品类/子类型/颜色模型
│   │   │   └── design.py       # 设计作品模型
│   │   ├── routers/            # API 路由
│   │   │   ├── auth.py         # 认证路由（注册/登录）
│   │   │   ├── categories.py   # 品类查询路由
│   │   │   ├── designs.py      # 设计生成/管理路由
│   │   │   ├── admin.py        # 管理后台路由
│   │   │   └── users.py        # 用户信息路由
│   │   ├── schemas/            # Pydantic 数据验证
│   │   ├── services/           # 业务逻辑层
│   │   │   ├── auth_service.py # 认证业务
│   │   │   ├── design_service.py # 设计业务（AI生图+降级）
│   │   │   ├── ai_generator.py # AI 生图服务（双模型）
│   │   │   ├── prompt_builder.py # 提示词构建器
│   │   │   ├── config_service.py # 配置服务（数据库优先于.env）
│   │   │   └── mock_generator.py # Mock图片生成（降级兜底）
│   │   ├── 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       # 设计接口
│   │   │   └── admin.ts        # 管理后台接口
│   │   ├── components/         # 公共组件
│   │   │   ├── AppHeader.vue   # 顶部导航栏
│   │   │   ├── AdminLayout.vue # 管理后台布局（侧边栏+内容区）
│   │   │   ├── CategoryNav.vue # 品类左侧导航
│   │   │   ├── SubTypePanel.vue# 子类型/颜色选择面板
│   │   │   ├── ColorPicker.vue # 颜色选择器
│   │   │   └── DesignPreview.vue # 设计预览（缩放/下载）
│   │   ├── stores/             # Pinia 状态管理
│   │   │   ├── user.ts         # 用户状态
│   │   │   ├── category.ts     # 品类状态
│   │   │   └── design.ts       # 设计状态
│   │   ├── views/              # 页面组件
│   │   │   ├── admin/          # 管理后台页面
│   │   │   │   ├── Dashboard.vue    # 仪表盘
│   │   │   │   ├── ConfigManage.vue # 系统配置管理
│   │   │   │   ├── UserManage.vue   # 用户管理
│   │   │   │   ├── CategoryManage.vue # 品类管理
│   │   │   │   └── DesignManage.vue # 设计管理
│   │   │   ├── 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` | 设计记录（用户、品类、子类型、颜色、描述、6个可选参数、图片URL、状态） |
| 设计 | `design_images` | AI 多视角设计图（视角名称、图片URL、AI模型、prompt、排序） |
| 配置 | `system_configs` | 系统配置（AI API Key、模型、尺寸等，支持后台管理动态修改） |

## 环境变量

| 配置项 | 默认值 | 必填 | 说明 |
|-------|--------|-----|------|
| `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` | 否 | 图片上传存储目录 |
| `SILICONFLOW_API_KEY` | 空 | 是(生图) | 硅基流动 API Key（FLUX.1 生图） |
| `SILICONFLOW_BASE_URL` | `https://api.siliconflow.cn/v1` | 否 | 硅基流动 API 地址 |
| `VOLCENGINE_API_KEY` | 空 | 否 | 火山引擎 API Key（Seedream 4.5 备选） |
| `VOLCENGINE_BASE_URL` | `https://ark.cn-beijing.volces.com/api/v3` | 否 | 火山引擎 API 地址 |
| `AI_IMAGE_MODEL` | `flux-dev` | 否 | 默认 AI 模型（flux-dev / seedream-4.5） |
| `AI_IMAGE_SIZE` | `1024` | 否 | 生成图片尺寸 |

## 常用命令

```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 文档
```