admin/app/AGENTS.md

后端模块说明

模块边界

• 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/feature_icons.py：图标管理接口，按寺院隔离，支持跨寺院复制图标。
• routers/ad_slots.py：广告位管理接口，按寺院隔离，只维护广告位置定义。
• routers/ads.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 签名、验签、通知解密和请求工具。

用户模型

当前用户模型字段：

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、设备和新环境登录标记；短信/邮箱二次验证和通知通道后续接入。

商品模型

商品详情模型包含：

商品名称、商品别称、商品描述、支付按钮名称、随喜按钮名称、排序号、分享时显示参与人数、
商品封面、商品图片、上架时间、开售时间、结束时间、下架时间、结束倒计时、
是否展示到首页、商品规格、商品详情、微信分享配置、功德证书预留、是否自动处理

商品规格存储为 JSON 列表，字段为：

名称、单价、库存、排序、是否超度

图标与广告位模型

• 图标存储在 feature_icons 表，字段包含图标名称、图标地址、跳转类型、跳转链接、关联商品、排序号、是否启用，并按 temple_id 隔离。
• 图标跳转类型为 link 或 app；link 必须填写跳转地址，app 必须选择当前寺院商品。
• 图标支持从其他寺院复制到当前寺院；应用类型图标复制后不直接跨寺院关联来源商品，需要重新选择当前寺院商品。
• 广告位存储在 ad_slots 表，表示首页广告、详情页广告、支付页广告等位置定义，字段包含名称、编码、说明、排序号、是否启用，并按 temple_id 隔离。
• 广告内容存储在 ads 表，字段包含广告位、广告名称、广告图、跳转类型、跳转链接、关联商品、排序号、是否启用，并按 temple_id 隔离。

上传与 OSS 配置

图片上传接口为 /uploads/images，用于商品封面、商品图片等图片资源。OSS 配置预留在 config.py，可直接填写或通过同名环境变量覆盖：

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、DEPLOY_LOG_PATH；如 webhook 进程拿到旧 Node，可设置 DEPLOY_NODE_BIN_DIR 指向新 Node 所在目录。
• 部署脚本为 scripts/deploy_front.sh，负责在服务器项目目录执行 git pull、进入前端目录安装依赖并执行 pnpm build；webhook 接口只投递后台任务并立即返回 202 accepted，构建结果查看 DEPLOY_LOG_PATH。
• webhook 密钥不得写入源码或文档；.env.example 只能保留占位值。

验证

后端修改后优先执行：

.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 签名校验测试通过。
• 2026-07-27：自动部署 webhook 改为后台执行构建，接口在签名校验、分支检查和加锁后立即返回 202 accepted，后台任务将构建结果写入部署日志，避免 Gitea Delivery 因等待响应超时。验证：后端编译通过，webhook 后台任务触发测试通过。
• 2026-07-27：新增图标管理和广告位管理后端模块，增加 feature_icons、ad_slots 表和 /feature-icons、/ad-slots 寺院隔离 CRUD 接口，图标支持从其他寺院复制。验证：后端编译通过。
• 2026-07-27：广告模型拆分为广告位和广告，ad_slots 改为位置定义，新增 ads 表和 /ads CRUD 接口，广告内容必须绑定当前寺院广告位。验证：后端编译通过，广告位与广告接口冒烟测试通过。