# 后端模块说明 ## 模块边界 - `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/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`。 ## 验证 后端修改后优先执行： ```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`。验证：后端编译通过，真实预下单和通知验签待填写微信商户配置后联调。