py-web 项目协作说明

项目概览

这是一个 FastAPI + SQLite 后端和 Vue 3 + Ant Design Vue + VueQuill 前端组成的玩具管理系统。

模块目录可以包含自己的 AGENTS.md，更靠近代码的说明优先约束对应目录内的改动。

后端模块

app/main.py：创建 FastAPI 应用，注册 CORS、健康检查和业务路由。
app/database.py：管理 SQLite 数据库路径、建表逻辑和 Database 依赖注入。
app/schemas.py：集中定义 Pydantic 请求体和响应体模型。
app/routers/auth.py：认证接口，提供验证码、登录、当前用户和退出登录。
app/routers/users.py：用户管理接口，提供 /users 的增删改查。
app/routers/todos.py：Todo 接口，提供 /todos 的增删改查。
app/routers/temples.py：寺院管理接口，提供 /temples 的增删改查。
app/routers/products.py：商品管理接口，提供 /products 的增删改查。
app/routers/orders.py：订单管理接口，提供 /orders 的增删改查。
app/routers/payments.py：微信支付接口，提供 JSAPI 预下单和支付通知处理。
app/routers/deploy.py：自动部署 webhook 接口，供 Gitea 推送后触发前端构建。
app/routers/rituals.py：法事管理接口，提供 /ritual-services 的增删改查。
app/routers/uploads.py：图片上传接口，提供 /uploads/images 并上传到阿里云 OSS。
app/config.py：项目运行配置，目前预留阿里云 OSS 配置。
index.py：兼容启动入口，导出 app.main 中的 app。

后端默认数据库文件是 app.sqlite3。开发时可以使用 DATABASE_PATH 指定当前用户可写的数据库文件，例如：

DATABASE_PATH=/tmp/py-web.sqlite3 .venv/bin/uvicorn index:app --reload

前端模块

front/src/main.ts：创建 Vue 应用，注册 vue-router 和 Ant Design Vue。
front/src/router/index.ts：按后端功能模块划分路由。
front/src/layouts/AdminLayout.vue：后台主布局，承载业务模块页面。
front/src/views/login/LoginPage.vue：登录页面，调用后端认证接口。
front/src/views/temples/TempleManagement.vue：寺院管理页面。
front/src/views/products/ProductManagement.vue：商品管理页面。
front/src/views/products/ProductDetail.vue：商品新建和编辑页面。
front/src/views/orders/OrderManagement.vue：订单管理页面。
front/src/views/rituals/RitualManagement.vue：法事管理页面。
front/src/views/users/UserManagement.vue：用户管理页面，调用后端 /users 接口。
front/src/api/http.ts：统一前端请求封装。
front/src/api/auth.ts：登录认证接口封装。
front/src/api/users.ts：用户接口封装。
front/src/api/uploads.ts：图片上传接口封装。
front/src/api/payments.ts：微信支付接口封装。

前端更细的模块约定见 front/AGENTS.md，后端更细的模块约定见 app/AGENTS.md。

当前前端路由：

/login    静态登录页
/temples  寺院管理
/products 商品管理
/products/create 新建商品
/products/:productId/edit 编辑商品
/orders   订单管理
/ritual-services 法事管理
/users    用户管理

前端通过 Vite 代理把 /api/* 转发到 FastAPI 后端，默认目标是 http://127.0.0.1:8000。

商品、订单、法事属于寺院隔离数据。前端通过顶部寺院选择器维护当前寺院，并在请求头 X-Temple-Id 中传给后端；后端按该寺院过滤数据。

依赖与运行约定

Python 包写入根目录 requirements.txt，由用户在本地安装。
前端包写入 front/package.json，由用户在 front 目录执行 pnpm install。
不使用 sudo 启动开发服务，避免 SQLite 文件被 root 创建。
后端启动命令：

DATABASE_PATH=/tmp/py-web.sqlite3 .venv/bin/uvicorn index:app --reload

前端启动命令：

cd front
pnpm dev

改动边界

新增后端业务模块时，优先新增 app/routers/<module>.py 和对应 app/schemas.py 模型。
新增前端业务模块时，优先新增 front/src/views/<module>/、front/src/api/<module>.ts，并在 front/src/router/index.ts 注册路由。
登录认证已接入，后台路由由前端守卫检查登录状态；认证令牌由后端 HttpOnly Cookie 管理，前端不保存 token。
自动部署接口为 /deploy/webhook，生产环境经 Nginx 的 /api/deploy/webhook 暴露给 Gitea；部署密钥、项目目录、前端目录、部署分支、脚本路径和日志路径通过 .env 或环境变量配置。

修改记录约定

以后只有较重要的代码、配置、依赖、目录结构、路由、数据模型、接口、认证权限或协作规则变更，才同步更新本文件的“修改记录”。
修改记录使用简体中文，包含日期、改动范围、核心内容和验证情况。
只记录实际完成的改动，不把待办计划写成已完成事项。
纯样式微调、文案微调和无行为影响的小改动通常不记录，以节省协作时间。

修改记录

2026-07-22：新增项目级协作说明，记录 FastAPI 后端模块、Vue 前端模块、运行命令和改动边界；同时约定后续修改都同步到本文件。
2026-07-22：用户管理模型变更为注册时间、姓名、手机号、昵称、头像、是否管理员、总消费；同步更新后端 SQLite 表结构迁移、Pydantic 模型、/users CRUD 接口、前端用户表格与表单；新增 app/AGENTS.md 和 front/AGENTS.md 记录模块级约定。验证：后端临时 pycache 编译通过，用户 CRUD 冒烟测试通过，旧用户表迁移测试通过，前端 pnpm typecheck 和 pnpm build 通过。
2026-07-22：前端应用名称改为可配置，默认值为“自在福田”，新增 front/src/config/app.ts 并替换布局与登录页写死名称；后台布局新增基于路由 meta.title 的导航面包屑。验证：pnpm typecheck 和 pnpm build 通过，构建仅保留 Ant Design Vue 首包体积提示。
2026-07-22：用户管理新增手机号查询能力，后端 /users 支持 phone 查询参数，前端用户管理页增加手机号查询与重置操作。验证：后端编译通过，手机号查询接口测试通过，前端 pnpm typecheck 和 pnpm build 通过。
2026-07-22：新增寺院管理、商品管理、订单管理、法事管理模块；后端增加 temples、products、orders、ritual_services 表和 CRUD 路由，商品/订单/法事通过 X-Temple-Id 做寺院级数据隔离；前端新增对应 API、路由、管理页面和顶部寺院选择器。验证：后端编译通过，寺院隔离接口测试通过，前端 pnpm typecheck 和 pnpm build 通过。
2026-07-23：商品详情模型变更为完整详情结构，后端扩展 products 表、Pydantic 模型和 /products CRUD，前端重做商品列表与详情编辑，支持规格表格行编辑、商品详情编辑和微信分享配置。验证：后端编译通过，商品详情 CRUD 测试通过，旧商品表迁移测试通过，前端 pnpm typecheck 和 pnpm build 通过。
2026-07-23：商品新建和编辑从列表弹窗调整为独立页面，新增 /products/create 和 /products/:productId/edit 路由，详情页通过路由 meta.module = products 保持商品管理菜单高亮。验证：pnpm typecheck 和 pnpm build 通过。
2026-07-23：商品封面和商品图片改为上传组件，后端新增 /uploads/images 阿里云 OSS 上传接口和 app/config.py OSS 配置占位，requirements.txt 新增 oss2、python-multipart。验证：后端编译通过，未配置 OSS 上传接口提示测试通过，前端 pnpm typecheck 和 pnpm build 通过。
2026-07-23：商品详情编辑器从内置 contenteditable 替换为 VueQuill，front/package.json 新增 @vueup/vue-quill 依赖，详情内容继续以 HTML 保存到 details_html。验证：待安装依赖后执行。
2026-07-23：新增登录认证功能，后端支持动态验证码、bcrypt 密码哈希、失败次数限制、账号临时锁定、HttpOnly/Secure Cookie 会话、退出登录和登录 IP/设备日志；前端登录页支持用户名、密码、验证码、自动聚焦、账号 trim、密码显示/隐藏、提交 loading、友好错误提示和路由守卫；requirements.txt 新增 bcrypt。验证：后端编译通过，前端 pnpm typecheck 和 pnpm build 通过，运行态登录测试待安装 bcrypt 后执行。
2026-07-23：商品模型新增商品描述字段，后端补充 products.description 迁移、Pydantic 模型和 CRUD 读写，前端商品 API 类型与商品编辑基础信息表单同步。验证：后端编译通过，前端 pnpm typecheck 和 pnpm build 通过，运行态接口测试待安装 bcrypt 后执行。
2026-07-23：新增微信支付 JSAPI 预下单和支付通知处理，后端增加 payment_transactions 支付流水表、微信支付 API v3 签名/通知验签/回调解密工具和配置占位，前端订单管理页增加微信预下单入口；requirements.txt 新增 cryptography。验证：后端编译通过，前端 pnpm typecheck 和 pnpm build 通过，真实预下单和支付通知待填写微信商户配置后联调。
2026-07-27：新增 Gitea 自动部署 webhook，后端 /deploy/webhook 校验 Gitea HMAC 签名或部署 token 后执行 scripts/deploy_front.sh，脚本负责拉取代码、安装前端依赖并执行 pnpm build；新增 .env.example 记录部署环境变量。验证：后端编译通过，webhook 密钥与 Gitea 签名校验测试通过。
2026-07-27：自动部署 webhook 从同步构建调整为后台构建，接口校验通过后立即返回 202 accepted，后台执行结果写入 DEPLOY_LOG_PATH，避免 Gitea Delivery 等待前端构建超时。验证：后端编译通过，webhook 后台任务触发测试通过。
2026-07-27：移除前端 Todo 占位模块，删除 /todos 前端路由、侧边栏入口和占位页面；后端 Todo 接口保留。验证：前端类型检查和构建通过。

10 KiB Raw Blame History Unescape Escape