docs(readme): 编写项目README文档，描述功能与架构
- 完整撰写玉宗珠宝设计大师项目README，介绍项目概况及核心功能 - 说明用户认证系统实现及优势，包含JWT鉴权和密码加密细节 - 详细描述品类管理系统，支持多流程类型和多种玉石品类 - 说明设计图生成方案及技术，包含Pillow生成示例及字体支持 - 介绍设计管理功能，支持分页浏览、预览、下载和删除设计 - 个人信息管理模块说明，涵盖昵称、手机号、密码的安全修改 - 绘制业务流程图和关键数据流图，清晰展现系统架构与数据流 - 提供详细API调用链路及参数说明，涵盖用户、品类、设计接口 - 列明技术栈及版本，包含前后端框架、ORM、认证、加密等工具 - 展示目录结构，标明后端与前端项目布局 - 规划本地开发环境与启动步骤，包括数据库初始化及运行命令 - 说明服务器部署流程和Nginx配置方案 - 详细数据库表结构说明及环境变量配置指导 - 汇总常用开发及测试命令，方便开发调试与部署管理
This commit is contained in:
changyoutongxue
8
backend/app/routers/__init__.py
Normal file
8
backend/app/routers/__init__.py
Normal file
@@ -0,0 +1,8 @@
|
||||
# API 路由模块
|
||||
from . import categories, designs, users
|
||||
|
||||
__all__ = [
|
||||
"categories",
|
||||
"designs",
|
||||
"users",
|
||||
]
|
||||
63
backend/app/routers/auth.py
Normal file
63
backend/app/routers/auth.py
Normal file
@@ -0,0 +1,63 @@
|
||||
"""
|
||||
认证路由
|
||||
提供用户注册、登录和获取当前用户信息的 API
|
||||
"""
|
||||
from fastapi import APIRouter, Depends, HTTPException, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from ..database import get_db
|
||||
from ..schemas.user import UserCreate, UserLogin, UserResponse, Token
|
||||
from ..services.auth_service import register_user, authenticate_user
|
||||
from ..utils.deps import get_current_user
|
||||
from ..utils.security import create_access_token
|
||||
from ..models.user import User
|
||||
|
||||
|
||||
router = APIRouter(prefix="/api/auth", tags=["认证"])
|
||||
|
||||
|
||||
@router.post("/register", response_model=UserResponse)
|
||||
def register(user_data: UserCreate, db: Session = Depends(get_db)):
|
||||
"""
|
||||
用户注册
|
||||
|
||||
创建新用户账号，用户名必须唯一
|
||||
"""
|
||||
try:
|
||||
user = register_user(db, user_data)
|
||||
return user
|
||||
except ValueError as e:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail=str(e)
|
||||
)
|
||||
|
||||
|
||||
@router.post("/login", response_model=Token)
|
||||
def login(user_data: UserLogin, db: Session = Depends(get_db)):
|
||||
"""
|
||||
用户登录
|
||||
|
||||
验证用户名和密码，返回 JWT access token
|
||||
"""
|
||||
user = authenticate_user(db, user_data.username, user_data.password)
|
||||
if not user:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_401_UNAUTHORIZED,
|
||||
detail="用户名或密码错误",
|
||||
headers={"WWW-Authenticate": "Bearer"},
|
||||
)
|
||||
|
||||
# 生成 JWT token，sub 字段存储用户 ID
|
||||
access_token = create_access_token(data={"sub": str(user.id)})
|
||||
return Token(access_token=access_token, token_type="bearer")
|
||||
|
||||
|
||||
@router.get("/me", response_model=UserResponse)
|
||||
def get_me(current_user: User = Depends(get_current_user)):
|
||||
"""
|
||||
获取当前登录用户信息
|
||||
|
||||
需要认证，从 token 中解析用户身份
|
||||
"""
|
||||
return current_user
|
||||
71
backend/app/routers/categories.py
Normal file
71
backend/app/routers/categories.py
Normal file
@@ -0,0 +1,71 @@
|
||||
"""
|
||||
品类相关路由
|
||||
提供品类、子类型、颜色的查询接口
|
||||
"""
|
||||
from fastapi import APIRouter, Depends, HTTPException, status
|
||||
from sqlalchemy.orm import Session
|
||||
from typing import List
|
||||
|
||||
from ..database import get_db
|
||||
from ..models import Category, SubType, Color
|
||||
from ..schemas import CategoryResponse, SubTypeResponse, ColorResponse
|
||||
|
||||
router = APIRouter(prefix="/api/categories", tags=["品类"])
|
||||
|
||||
|
||||
@router.get("", response_model=List[CategoryResponse])
|
||||
def get_categories(db: Session = Depends(get_db)):
|
||||
"""
|
||||
获取所有品类列表
|
||||
按 sort_order 排序，无需认证
|
||||
"""
|
||||
categories = db.query(Category).order_by(Category.sort_order).all()
|
||||
return categories
|
||||
|
||||
|
||||
@router.get("/{category_id}/sub-types", response_model=List[SubTypeResponse])
|
||||
def get_category_sub_types(
|
||||
category_id: int,
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
获取品类下的子类型
|
||||
无需认证
|
||||
"""
|
||||
# 检查品类是否存在
|
||||
category = db.query(Category).filter(Category.id == category_id).first()
|
||||
if not category:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="品类不存在"
|
||||
)
|
||||
|
||||
sub_types = db.query(SubType).filter(
|
||||
SubType.category_id == category_id
|
||||
).order_by(SubType.sort_order).all()
|
||||
|
||||
return sub_types
|
||||
|
||||
|
||||
@router.get("/{category_id}/colors", response_model=List[ColorResponse])
|
||||
def get_category_colors(
|
||||
category_id: int,
|
||||
db: Session = Depends(get_db)
|
||||
):
|
||||
"""
|
||||
获取品类下的颜色选项
|
||||
无需认证
|
||||
"""
|
||||
# 检查品类是否存在
|
||||
category = db.query(Category).filter(Category.id == category_id).first()
|
||||
if not category:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="品类不存在"
|
||||
)
|
||||
|
||||
colors = db.query(Color).filter(
|
||||
Color.category_id == category_id
|
||||
).order_by(Color.sort_order).all()
|
||||
|
||||
return colors
|
||||
201
backend/app/routers/designs.py
Normal file
201
backend/app/routers/designs.py
Normal file
@@ -0,0 +1,201 @@
|
||||
"""
|
||||
设计相关路由
|
||||
提供设计生成、查询、删除、下载接口
|
||||
"""
|
||||
import os
|
||||
from fastapi import APIRouter, Depends, HTTPException, status, Query
|
||||
from fastapi.responses import FileResponse
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from ..database import get_db
|
||||
from ..models import User, Design
|
||||
from ..schemas import DesignCreate, DesignResponse, DesignListResponse
|
||||
from ..utils.deps import get_current_user
|
||||
from ..services import design_service
|
||||
|
||||
router = APIRouter(prefix="/api/designs", tags=["设计"])
|
||||
|
||||
|
||||
def design_to_response(design: Design) -> DesignResponse:
|
||||
"""将 Design 模型转换为响应格式"""
|
||||
return DesignResponse(
|
||||
id=design.id,
|
||||
user_id=design.user_id,
|
||||
category={
|
||||
"id": design.category.id,
|
||||
"name": design.category.name,
|
||||
"icon": design.category.icon,
|
||||
"sort_order": design.category.sort_order,
|
||||
"flow_type": design.category.flow_type
|
||||
},
|
||||
sub_type={
|
||||
"id": design.sub_type.id,
|
||||
"category_id": design.sub_type.category_id,
|
||||
"name": design.sub_type.name,
|
||||
"description": design.sub_type.description,
|
||||
"preview_image": design.sub_type.preview_image,
|
||||
"sort_order": design.sub_type.sort_order
|
||||
} if design.sub_type else None,
|
||||
color={
|
||||
"id": design.color.id,
|
||||
"category_id": design.color.category_id,
|
||||
"name": design.color.name,
|
||||
"hex_code": design.color.hex_code,
|
||||
"sort_order": design.color.sort_order
|
||||
} if design.color else None,
|
||||
prompt=design.prompt,
|
||||
carving_technique=design.carving_technique,
|
||||
design_style=design.design_style,
|
||||
motif=design.motif,
|
||||
size_spec=design.size_spec,
|
||||
surface_finish=design.surface_finish,
|
||||
usage_scene=design.usage_scene,
|
||||
image_url=design.image_url,
|
||||
status=design.status,
|
||||
created_at=design.created_at,
|
||||
updated_at=design.updated_at
|
||||
)
|
||||
|
||||
|
||||
@router.post("/generate", response_model=DesignResponse)
|
||||
def generate_design(
|
||||
design_data: DesignCreate,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
提交设计生成请求
|
||||
需要认证
|
||||
"""
|
||||
try:
|
||||
design = design_service.create_design(
|
||||
db=db,
|
||||
user_id=current_user.id,
|
||||
design_data=design_data
|
||||
)
|
||||
return design_to_response(design)
|
||||
except ValueError as e:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail=str(e)
|
||||
)
|
||||
|
||||
|
||||
@router.get("", response_model=DesignListResponse)
|
||||
def get_designs(
|
||||
page: int = Query(1, ge=1, description="页码"),
|
||||
page_size: int = Query(20, ge=1, le=100, description="每页数量"),
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
获取当前用户的设计历史列表（分页）
|
||||
需要认证
|
||||
"""
|
||||
designs, total = design_service.get_user_designs(
|
||||
db=db,
|
||||
user_id=current_user.id,
|
||||
page=page,
|
||||
page_size=page_size
|
||||
)
|
||||
|
||||
return DesignListResponse(
|
||||
items=[design_to_response(d) for d in designs],
|
||||
total=total,
|
||||
page=page,
|
||||
page_size=page_size
|
||||
)
|
||||
|
||||
|
||||
@router.get("/{design_id}", response_model=DesignResponse)
|
||||
def get_design(
|
||||
design_id: int,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
获取设计详情
|
||||
只能查看自己的设计，非本人设计返回 404
|
||||
"""
|
||||
design = design_service.get_design_by_id(
|
||||
db=db,
|
||||
design_id=design_id,
|
||||
user_id=current_user.id
|
||||
)
|
||||
|
||||
if not design:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="设计不存在"
|
||||
)
|
||||
|
||||
return design_to_response(design)
|
||||
|
||||
|
||||
@router.delete("/{design_id}")
|
||||
def delete_design(
|
||||
design_id: int,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
删除设计
|
||||
只能删除自己的设计，非本人设计返回 404
|
||||
"""
|
||||
success = design_service.delete_design(
|
||||
db=db,
|
||||
design_id=design_id,
|
||||
user_id=current_user.id
|
||||
)
|
||||
|
||||
if not success:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="设计不存在"
|
||||
)
|
||||
|
||||
return {"message": "删除成功"}
|
||||
|
||||
|
||||
@router.get("/{design_id}/download")
|
||||
def download_design(
|
||||
design_id: int,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
下载设计图
|
||||
只能下载自己的设计，非本人设计返回 404
|
||||
"""
|
||||
design = design_service.get_design_by_id(
|
||||
db=db,
|
||||
design_id=design_id,
|
||||
user_id=current_user.id
|
||||
)
|
||||
|
||||
if not design:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="设计不存在"
|
||||
)
|
||||
|
||||
if not design.image_url:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="设计图片不存在"
|
||||
)
|
||||
|
||||
# 转换 URL 为文件路径
|
||||
file_path = design.image_url.lstrip("/")
|
||||
|
||||
if not os.path.exists(file_path):
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_404_NOT_FOUND,
|
||||
detail="设计图片文件不存在"
|
||||
)
|
||||
|
||||
return FileResponse(
|
||||
path=file_path,
|
||||
filename=f"design_{design_id}.png",
|
||||
media_type="image/png"
|
||||
)
|
||||
75
backend/app/routers/users.py
Normal file
75
backend/app/routers/users.py
Normal file
@@ -0,0 +1,75 @@
|
||||
"""
|
||||
用户相关路由
|
||||
提供用户信息更新、密码修改接口
|
||||
"""
|
||||
from fastapi import APIRouter, Depends, HTTPException, status
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from ..database import get_db
|
||||
from ..models import User
|
||||
from ..schemas import UserResponse, UserUpdate, PasswordChange
|
||||
from ..utils.deps import get_current_user
|
||||
from ..utils.security import verify_password, get_password_hash
|
||||
|
||||
router = APIRouter(prefix="/api/users", tags=["用户"])
|
||||
|
||||
|
||||
@router.put("/profile", response_model=UserResponse)
|
||||
def update_profile(
|
||||
user_data: UserUpdate,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
更新个人信息
|
||||
需要认证
|
||||
"""
|
||||
# 更新非空字段
|
||||
if user_data.nickname is not None:
|
||||
current_user.nickname = user_data.nickname
|
||||
|
||||
if user_data.phone is not None:
|
||||
# 检查手机号是否已被其他用户使用
|
||||
if user_data.phone:
|
||||
existing_user = db.query(User).filter(
|
||||
User.phone == user_data.phone,
|
||||
User.id != current_user.id
|
||||
).first()
|
||||
if existing_user:
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail="手机号已被使用"
|
||||
)
|
||||
current_user.phone = user_data.phone
|
||||
|
||||
if user_data.avatar is not None:
|
||||
current_user.avatar = user_data.avatar
|
||||
|
||||
db.commit()
|
||||
db.refresh(current_user)
|
||||
|
||||
return current_user
|
||||
|
||||
|
||||
@router.put("/password")
|
||||
def change_password(
|
||||
password_data: PasswordChange,
|
||||
db: Session = Depends(get_db),
|
||||
current_user: User = Depends(get_current_user)
|
||||
):
|
||||
"""
|
||||
修改密码
|
||||
需要认证，旧密码错误返回 400
|
||||
"""
|
||||
# 验证旧密码
|
||||
if not verify_password(password_data.old_password, current_user.hashed_password):
|
||||
raise HTTPException(
|
||||
status_code=status.HTTP_400_BAD_REQUEST,
|
||||
detail="旧密码错误"
|
||||
)
|
||||
|
||||
# 更新密码
|
||||
current_user.hashed_password = get_password_hash(password_data.new_password)
|
||||
db.commit()
|
||||
|
||||
return {"message": "密码修改成功"}
|
||||
Reference in New Issue
Block a user