116 lines
8.1 KiB
Markdown
116 lines
8.1 KiB
Markdown
# 后端模块说明
|
||
|
||
## 模块边界
|
||
|
||
- `main.py`：FastAPI 应用入口，负责注册中间件、健康检查和路由。
|
||
- `database.py`：SQLite 数据库路径、建表、轻量迁移和依赖注入。
|
||
- `schemas.py`：Pydantic 数据模型。
|
||
- `routers/auth.py`：登录认证、验证码、Cookie 会话和退出登录接口。
|
||
- `routers/users.py`：用户管理接口。
|
||
- `routers/todos.py`：Todo 管理接口。
|
||
- `routers/temples.py`：寺院管理接口。
|
||
- `routers/products.py`：商品管理接口，按寺院隔离。
|
||
- `routers/orders.py`：订单管理接口，按寺院隔离。
|
||
- `routers/payments.py`：微信支付接口，按寺院隔离发起 JSAPI 预下单并处理支付通知。
|
||
- `routers/deploy.py`：自动部署 webhook 接口，校验 Gitea 签名或部署 token 后触发前端构建脚本。
|
||
- `routers/rituals.py`：法事管理接口，按寺院隔离。
|
||
- `routers/uploads.py`：图片上传接口，上传到阿里云 OSS。
|
||
- `config.py`：项目运行配置，目前预留阿里云 OSS 配置。
|
||
- `security.py`：密码哈希、密钥哈希和会话令牌工具。
|
||
- `temple_scope.py`：读取 `X-Temple-Id` 并校验寺院存在。
|
||
- `wechat_pay.py`：微信支付 API v3 签名、验签、通知解密和请求工具。
|
||
|
||
## 用户模型
|
||
|
||
当前用户模型字段：
|
||
|
||
```text
|
||
id 用户 ID
|
||
registered_at 注册时间，后端创建时生成
|
||
name 姓名
|
||
phone 手机号，创建时必填并保持唯一
|
||
nickname 昵称
|
||
avatar 头像地址
|
||
is_admin 是否管理员
|
||
total_spent 总消费
|
||
```
|
||
|
||
## 数据库约定
|
||
|
||
- 开发时优先通过 `DATABASE_PATH` 指定当前用户可写的 SQLite 文件。
|
||
- 不使用 `sudo` 启动服务，避免数据库文件被 root 创建。
|
||
- 修改表结构时，在 `database.py` 中补充轻量迁移逻辑，兼容已有 SQLite 文件。
|
||
- 商品、订单、法事必须带 `temple_id`，接口查询和写入都要通过当前寺院上下文限制数据范围。
|
||
- 当前寺院上下文通过请求头 `X-Temple-Id` 传入。
|
||
|
||
## 认证安全约定
|
||
|
||
- 登录接口为 `/auth/login`，验证码接口为 `/auth/captcha`，退出接口为 `/auth/logout`，当前用户接口为 `/auth/me`。
|
||
- 密码使用 bcrypt 加盐哈希存储，不保存明文密码；默认演示账号为 `admin/admin123456` 和 `demo/demo123456`。
|
||
- 登录会话使用服务端 `auth_sessions` 表保存，浏览器只接收 `HttpOnly`、`Secure`、`SameSite=Lax` Cookie。
|
||
- `AUTH_REQUIRE_HTTPS` 默认开启；本地开发允许 localhost 非 HTTPS，生产环境应使用 HTTPS 或反向代理传递 `X-Forwarded-Proto: https`。
|
||
- 同一账号或 IP 短时间失败 5 次后要求验证码，10 次后临时锁定账号 15 分钟。
|
||
- 登录尝试和登录事件分别写入 `login_attempts`、`login_events`，用于记录 IP、设备和新环境登录标记；短信/邮箱二次验证和通知通道后续接入。
|
||
|
||
## 商品模型
|
||
|
||
商品详情模型包含：
|
||
|
||
```text
|
||
商品名称、商品别称、商品描述、支付按钮名称、随喜按钮名称、排序号、分享时显示参与人数、
|
||
商品封面、商品图片、上架时间、开售时间、结束时间、下架时间、结束倒计时、
|
||
是否展示到首页、商品规格、商品详情、微信分享配置、功德证书预留、是否自动处理
|
||
```
|
||
|
||
商品规格存储为 JSON 列表，字段为：
|
||
|
||
```text
|
||
名称、单价、库存、排序、是否超度
|
||
```
|
||
|
||
## 上传与 OSS 配置
|
||
|
||
图片上传接口为 `/uploads/images`，用于商品封面、商品图片等图片资源。OSS 配置预留在 `config.py`，可直接填写或通过同名环境变量覆盖：
|
||
|
||
```text
|
||
OSS_ENDPOINT、OSS_BUCKET_NAME、OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_PUBLIC_BASE_URL、OSS_UPLOAD_PREFIX
|
||
```
|
||
|
||
## 微信支付约定
|
||
|
||
- 当前接入微信支付 API v3 的 JSAPI 预下单，接口为 `/payments/wechat/jsapi`；支付结果通知接口为 `/payments/wechat/notify`。
|
||
- 业务订单仍存储在 `orders` 表，支付流水存储在 `payment_transactions` 表，使用 `out_trade_no` 关联微信支付交易。
|
||
- 预下单需要前端传入微信用户 `openid`；真正调起 `WeixinJSBridge` 通常在用户端 H5/公众号页面完成。
|
||
- 配置通过 `.env` 或环境变量提供：`WECHAT_PAY_APPID`、`WECHAT_PAY_MCH_ID`、`WECHAT_PAY_MCH_SERIAL_NO`、`WECHAT_PAY_API_V3_KEY`、`WECHAT_PAY_PRIVATE_KEY_PATH`、`WECHAT_PAY_PUBLIC_KEY_PATH`、`WECHAT_PAY_NOTIFY_URL`。
|
||
- 支付通知需要验签并用 APIv3 密钥解密；生产环境必须配置微信支付公钥或平台证书，不应开启 `WECHAT_PAY_SKIP_NOTIFY_VERIFY`。
|
||
|
||
## 自动部署约定
|
||
|
||
- 自动部署接口为 `/deploy/webhook`，生产环境通常通过 Nginx 映射为 `/api/deploy/webhook` 给 Gitea 调用。
|
||
- Gitea Webhook 应配置 `Secret`，后端会按原始请求体校验 `X-Gitea-Signature` 的 HMAC-SHA256 签名；也兼容 `X-Hub-Signature-256`。
|
||
- 部署配置通过 `.env` 或环境变量提供：`DEPLOY_WEBHOOK_SECRET`、`DEPLOY_PROJECT_DIR`、`DEPLOY_FRONT_DIR`、`DEPLOY_BRANCH`、`DEPLOY_SCRIPT_PATH`、`DEPLOY_COMMAND_TIMEOUT`、`DEPLOY_LOCK_PATH`；如 webhook 进程拿到旧 Node，可设置 `DEPLOY_NODE_BIN_DIR` 指向新 Node 所在目录。
|
||
- 部署脚本为 `scripts/deploy_front.sh`，负责在服务器项目目录执行 `git pull`、进入前端目录安装依赖并执行 `pnpm build`。
|
||
- webhook 密钥不得写入源码或文档；`.env.example` 只能保留占位值。
|
||
|
||
## 验证
|
||
|
||
后端修改后优先执行：
|
||
|
||
```bash
|
||
.venv/bin/python -m compileall index.py app
|
||
```
|
||
|
||
接口变更后使用 FastAPI `TestClient` 或 `/docs` 做最小 CRUD 验证。
|
||
|
||
## 修改记录
|
||
|
||
- 2026-07-22：用户模型变更为注册时间、姓名、手机号、昵称、头像、是否管理员、总消费；`database.py` 增加旧表补列和默认值迁移，`schemas.py` 和 `routers/users.py` 同步新字段。验证：临时 pycache 编译通过，用户 CRUD 冒烟测试通过，旧表迁移测试通过。
|
||
- 2026-07-22：`/users` 列表接口新增 `phone` 查询参数，支持按手机号模糊查询用户。验证：后端编译通过，手机号查询接口测试通过。
|
||
- 2026-07-22：新增寺院、商品、订单、法事后端模块；`products`、`orders`、`ritual_services` 通过 `X-Temple-Id` 做寺院级数据隔离。验证：后端编译通过，寺院隔离接口测试通过。
|
||
- 2026-07-23：商品详情模型扩展为完整详情字段，`products` 表增加别称、按钮名称、展示配置、图片、时间、规格 JSON、详情 HTML、微信分享、功德证书预留、自动处理、销量等字段；商品接口同步新模型并继续按 `X-Temple-Id` 隔离。验证：后端编译通过，商品详情 CRUD 测试通过，旧商品表迁移测试通过。
|
||
- 2026-07-23：新增 `/uploads/images` 图片上传接口，预留阿里云 OSS 配置并新增 `oss2`、`python-multipart` 依赖；OSS 未配置时接口返回明确 503 提示。验证：后端编译通过，未配置 OSS 上传接口提示测试通过。
|
||
- 2026-07-23：新增登录认证模块，支持服务端动态验证码、bcrypt 密码哈希、失败次数限制、账号临时锁定、HttpOnly/Secure Cookie 会话、退出登录、登录 IP/设备日志和新环境登录标记；`requirements.txt` 新增 `bcrypt`。验证：后端编译通过，运行态登录测试待安装 `bcrypt` 后执行。
|
||
- 2026-07-23：商品模型新增 `description` 商品描述字段，后端补充 `products.description` 轻量迁移、Pydantic 模型和 `/products` CRUD 读写。验证：后端编译通过，运行态接口测试待安装 `bcrypt` 后执行。
|
||
- 2026-07-23：新增微信支付 JSAPI 预下单和支付通知处理，增加 `payment_transactions` 支付流水表、微信支付 API v3 签名/通知验签/回调解密工具和配置占位；`requirements.txt` 新增 `cryptography`。验证：后端编译通过，真实预下单和通知验签待填写微信商户配置后联调。
|
||
- 2026-07-27：新增自动部署 webhook 模块，`/deploy/webhook` 支持 Gitea HMAC 签名校验、部署分支过滤、并发锁和构建脚本超时控制，`scripts/deploy_front.sh` 负责拉取代码并构建前端。验证：后端编译通过，webhook 密钥与 Gitea 签名校验测试通过。
|