玉宗 - 珠宝设计大师

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 配置可热更新（无需重启服务），品类数据可视化管理，用户权限分级控制

业务流程

整体流程图

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

关键数据流图

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

启动步骤

# 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	设计记录（用户、品类、子类型、颜色、描述、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	否	生成图片尺寸

常用命令

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