119 lines
10 KiB
Markdown
119 lines
10 KiB
Markdown
# 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` 指定当前用户可写的数据库文件，例如：
|
||
|
||
```bash
|
||
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`。
|
||
|
||
当前前端路由：
|
||
|
||
```text
|
||
/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 创建。
|
||
- 后端启动命令：
|
||
|
||
```bash
|
||
DATABASE_PATH=/tmp/py-web.sqlite3 .venv/bin/uvicorn index:app --reload
|
||
```
|
||
|
||
- 前端启动命令：
|
||
|
||
```bash
|
||
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 接口保留。验证：前端类型检查和构建通过。
|