@@ -12,16 +12,16 @@
## 当前快照
- 日期：2026-07-03
- 阶段：Phase 3 对外 API 安全加固；Phase 3 功能已完成到 T-305，
- 阶段：Phase 4 用户端起步；Phase 3 对外 API 与充值已完成到 T-306，下一步 T-501 注册 / 登录（allauth）
- 技术栈：系统 Python 3.12.3 + Django 5.2.15 + DRF 3.16.1 + PyMySQL 1.1.3 + cryptography 46.0.7 + requests 2.34.2 + django-admin； `MYSQL_CONNECT_TIMEOUT` / `MYSQL_READ_TIMEOUT` / `MYSQL_WRITE_TIMEOUT` ；用户端(模板 SSR/Bootstrap/allauth) 后续任务落地；详见 `03-tech-stack.md`
- 生产代码：已有最小 Django 工程骨架：`manage.py` 、`config/` ； `apps/users|portal|billing|ai|api` ； `User` 注册进 django-admin； `.env.example` 与 `pyproject.toml` ； `apps/ai/providers/` （ `AiModel` / `ModelAlias` 、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey` 、`PointsLedger` / `CallRecord` 、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate` 、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services` ，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call` ，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView` ；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder` 、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more` ； `create_recharge_order()` 、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status`
- 测试：T-305 验证通过： `./init.ps1` 、 `py_compile` 、 ` manage.py check``makemigrations --check` 、`py -3.12 -m compileall apps config` 、`py -3.12 manage.py test apps.billing apps.api --noinput --keepdb --verbosity 2` （ ），并用 `MYSQL_CONNECT_TIMEOUT=90` 补跑全量失败类 `BillingCoreModelTests` / `AdminSmokeTests` （10 tests OK）和最终下单服务补测 （ 完整 `py -3.12 manage.py test --noinput --keepdb --verbosity 2` 本轮 未作为绿灯：发现 81 tests，跑过 71 tests，其中已运行用例均无断言失败；远程 MySQL `43.128.3.240:3306` 连接超时导致 `BillingCoreModelTests.setUpClass` 与 `AdminSmokeTests.setUpClass` 失败 。
- 生产代码：已有最小 Django 工程骨架：`manage.py` 、`config/` ； `apps/users|portal|billing|ai|api` ； `User` 注册进 django-admin； `.env.example` 与 `pyproject.toml` ； `apps/ai/providers/` （ `AiModel` / `ModelAlias` 、Fernet 加密密钥存储、别名解析、admin 配置页、`import_ai_models` 导入命令；T-103 已新增 `AiConfigAuditLog` 审计表、admin 只读页面和后台保存/删除审计 hook；T-104/T-105 已完成录制 title/image smoke 与审核修补；T-201 已新增 `UserWallet` / `ApiKey` 、`PointsLedger` / `CallRecord` 、对应 admin 与迁移；T-202 已新增 `PricingRule` / `ExchangeRate` 、`apps.billing.pricing` 计费计算函数、admin 配置页与迁移；T-203 已新增 `apps.billing.services` ，实现并发安全预扣、成功确认与幂等失败退点；T-204 已新增 `billing.0003_pointsledger_unique_ledger_change_type_per_call` ，用 MySQL 可落地的 `ref_call + change_type` 复合唯一约束兜底防重复 refund；T-301 已新增 `apps.api.authentication.ApiKeyAuthentication` 与 `ExternalApiView` ；T-302 已新增生成接口编排、序列化器、图片本地存储和 `/api/v1/generate/title|image` 路由；T-303 已新增 `apps.billing.services.get_balance_snapshot()` 与 `/api/v1/balance` 余额查询接口；T-304 已新增 `RechargeOrder` 、充值回调验签适配器、幂等入账服务、微信/支付宝回调路由与迁移 `billing.0004_rechargeorder_and_more` ； `create_recharge_order()` 、微信/支付宝扫码下单 mock/SDK 入口、`/api/v1/recharge/create` 与 `/api/v1/recharge/status` ； `apps.api.throttles` 、 `apps.api.exceptions` 、 `REST_FRAMEWORK` 安全默认认证、生成/认证失败限流、 `image_url` SSRF 防护与响应大小上限、充值单笔金额上限
- 测试：T-306 已验证： `py -3.12 -m py_compile config/settings.py apps/api/exceptions.py apps/api/generation.py apps/api/authentication.py apps/api/views.py apps/api/serializers.py apps/api/throttles.py apps/api/tests.py` 、 `py -3.12 manage.py check``py -3.12 manage.py makemigrations --check --dry-run ` 、`py -3.12 -m compileall apps config` 、`./init.ps1` 均通过； ` py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2` 通过（39 tests OK，含 SSRF、限流、充值上限）；认证/生成限流单点补测通过 （ `py -3.12 manage.py test apps.billing apps.api --noinput --keepdb --verbosity 2` 未作为绿灯：62 tests 跑到末尾，功能用例输出均为 ok，最后远程 MySQL 在并发扣点测试的 flush/重连阶段 reset 连接；随后 `$env:MYSQL_CONNECT_TIMEOUT='90'; py -3.12 manage.py test apps.billing.tests.ConcurrentDebitTests --noinput --keepdb --verbosity 2` 通过（1 test OK） 。
- 数据：AI 上游调用与模型配置参考 `D:\chengma\cmbot` （ `src/services/ai_text_service.py` 、`ai_image_service.py` 、`config/ai_models.json` ）；真实 `ai_models.json` 不提交，需通过 `import_ai_models` 命令加密导入
- 标准启动路径：Windows 用 `./init.ps1` ； `./init.sh`
- 标准验证路径：Windows 用 `py -3.12 manage.py check` / `py -3.12 manage.py test`
- 设计基线：**自助用户端 + 对外 API + 运营后台**三合一单体；用户模型 `User` (auth)/`UserWallet` (点数，锁 wallet 扣点)/`ApiKey` (1:N，哈希存储)；对外两接口 + **能力别名 + Provider 适配器 ** （可插拔供应商）；自助扫码充值；注册不送点数。详见 `04-architecture.md` 与 2026-06-29 / 2026-07-01 的 `progress.md` 决策
- 配置基线：运行环境变量集中见 `docs/env.md` ；真实密钥/支付凭证不得写入代码或文档样例。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算。支付回调与下单由 `PAYMENT_CALLBACK_MODE` 控制：本地/测试可用 HMAC `mock` ，生产应为 `sdk` ；二维码本地有效期提示由 `PAYMENT_QR_EXPIRES_MINUTES` 控制。
- 当前 blocker： 待处理 `image_url` SSRF 上线前安全问题；远程 MySQL 连接当前不稳定，完整测试暂未单次全绿；T-305 相关测试已通过 。微信/支付宝真实商户密钥/证书与生产 SDK 依赖仍待提供/安装；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，已登记到 T-403。
- 配置基线：运行环境变量集中见 `docs/env.md` ；真实密钥/支付凭证不得写入代码或文档样例。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算。支付回调与下单由 `PAYMENT_CALLBACK_MODE` 控制：本地/测试可用 HMAC `mock` ，生产应为 `sdk` ；二维码本地有效期提示由 `PAYMENT_QR_EXPIRES_MINUTES` 控制。T-306 起对外 API 安全配置包含 `API_GENERATE_THROTTLE_RATE` 、 `API_AUTH_FAILURE_THROTTLE_RATE` 、 `IMAGE_URL_MAX_BYTES` 、 `IMAGE_URL_MAX_REDIRECTS` 、 `IMAGE_URL_CONNECT_TIMEOUT_SECONDS` 、 `IMAGE_URL_READ_TIMEOUT_SECONDS` 、 `RECHARGE_MAX_AMOUNT_CNY` 。
- 当前 blocker： 上线前 SSRF 风险已修复；远程 MySQL 连接仍可能很慢或间歇超时，完整测试需预留较长时间并优先用 `--keepdb` 串行跑 。微信/支付宝真实商户密钥/证书与生产 SDK 依赖仍待提供/安装；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，已登记到 T-403。
## 当前目录要点
@@ -33,7 +33,7 @@
| `init.sh` / `init.ps1` | 已有 | 启动验证入口，已固定系统 Python 3.12 命令，并校验解释器版本 `>=3.12,<3.14` |
| `requirements.txt` / `pyproject.toml` | 已有 | `requirements.txt` 管运行依赖；`pyproject.toml` 落地 `requires-python` ； `requests` ； `cryptography` 做 Fernet 加密 |
| `config/` （
| `apps/` （ ） `apps/users` 已定义自定义 `User` ； ； `User.email` 加唯一约束；T-101 已新增 `apps/ai/providers` ； `apps/ai/security.py` 、`aliases.py` 、`importers.py` 、management command 与 `ai.0001_initial` 迁移；T-103 已新增 `apps/ai/audit.py` 与 `ai.0002_aiconfigauditlog` 迁移；T-104/T-105 已新增 `smoke_ai_generation` 录制 title/image smoke 命令；T-201 已在 users 落 `UserWallet` / `ApiKey` ，在 billing 落 `PointsLedger` / `CallRecord` ； `PricingRule` / `ExchangeRate` 与 `pricing.py` ； `apps/billing/services.py` 落扣点/退点、余额快照、充值入账与充值下单；T-304/T-305 已在 `apps/billing/payment_gateways.py` 落回调验签、mock 下单与 SDK 入口；T-301/T-302/T-303/T-304/T-305 已在 api 落鉴权、生成接口编排、序列化器、图片存储、余额查询、充值回调、充值下单/状态查询与路由 |
| `apps/` （ ） `apps/users` 已定义自定义 `User` ； ； `User.email` 加唯一约束；T-101 已新增 `apps/ai/providers` ； `apps/ai/security.py` 、`aliases.py` 、`importers.py` 、management command 与 `ai.0001_initial` 迁移；T-103 已新增 `apps/ai/audit.py` 与 `ai.0002_aiconfigauditlog` 迁移；T-104/T-105 已新增 `smoke_ai_generation` 录制 title/image smoke 命令；T-201 已在 users 落 `UserWallet` / `ApiKey` ，在 billing 落 `PointsLedger` / `CallRecord` ； `PricingRule` / `ExchangeRate` 与 `pricing.py` ； `apps/billing/services.py` 落扣点/退点、余额快照、充值入账与充值下单；T-304/T-305 已在 `apps/billing/payment_gateways.py` 落回调验签、mock 下单与 SDK 入口；T-301~T-306 已在 api 落鉴权、生成接口编排、序列化器、图片存储、余额查询、充值回调、充值下单/状态查询、 `image_url` SSRF 防护、生成/认证限流与统一 429 错误响应 |
| `manage.py` | 已有 | T-001 创建 |
| `tests/` | 待建 | 随各任务补充 |
@@ -41,10 +41,10 @@
任务状态以 [`06-tasks.md` ](06-tasks.md ) 为准，历史执行记录见 [`../progress.md` ](../progress.md )。
- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询。
- 已完成：T-001 初始化 Django + DRF 项目骨架；T-002 建立 apps 目录、自定义 User 与配置；T-003 接通 django-admin 与最小测试；T-004 Phase 0 骨架审核修补；T-101 Provider 适配器层 + 移植 cmbot 调用；T-102 AiModel + ModelAlias 模型 + 别名解析；T-103 配置变更审计；T-104 跑通一次录制标题生成；T-105 Phase 1 AI 层审核修补；T-201 User / UserWallet / ApiKey / PointsLedger / CallRecord 模型；T-202 PricingRule / ExchangeRate 模型 + 计费计算；T-203 并发安全扣点 / 退点；T-204 Phase 2 计费核心审核加固；T-301 API Key 鉴权；T-302 生成标题 / 图片接口；T-303 余额查询接口；T-304 充值回调；T-305 扫码充值下单 + 轮询；
- 正在进行：无。
- 当前 blocker： T-306 SSRF 安全加固待做； 远程 MySQL 连接当前不稳定，完整测试暂未单次全绿 ；支付商户真实密钥/证书与生产 SDK 依赖仍待提供。
- 下一个可领取任务：**T-306 Phase 3 对外 API 安全加固 **。
- 当前 blocker：远程 MySQL 连接当前不稳定或很慢 ；支付商户真实密钥/证书与生产 SDK 依赖仍待提供；真实 AI 上游 smoke 仍需配置密钥和模型数据后执行 。
- 下一个可领取任务：**T-501 注册 / 登录（allauth） **。
## 当前可运行内容
@@ -78,14 +78,14 @@ python3.12 manage.py smoke_ai_generation image --recorded
- `POST /api/v1/recharge/callback/wechat`
- `POST /api/v1/recharge/callback/alipay`
当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email` ， `user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias` ， `resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog` ， `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix； `result_ref` /`result_summary` ，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate` ：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")` ；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()` ：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey` ，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance` ，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片。
当前骨架可运行。T-002 已在首次迁移前创建自定义 User，并按 `env.md` 接入 MySQL 8.4 / utf8mb4；远程 MySQL 已完成 Django 初始迁移。T-003 已接通 django-admin，测试可创建/销毁 `test_cmhub` 测试库；当前远程 MySQL 对频繁建库/销库仍可能间歇超时，必要时用 `--keepdb` 且串行跑测试。T-004 已应用 `users.0002_alter_user_email` ， `user.email` 已有唯一索引。T-101 的 AI provider 层只做 HTTP 调用与响应解析；T-102 已把 provider 运行配置接到数据库 `AiModel` / `ModelAlias` ， `resolve_alias()` 每次查当前 active 配置并按 `text` / `image` 能力校验。T-103 已补 `AiConfigAuditLog` ， `AiModel` / `ModelAlias` 时记录 actor、action、target、changed_fields、changes、created_at，密钥只记录 empty/set 状态。T-104/T-105 已用临时回滚配置跑通录制标题和录制图片生成。T-201 已落地钱包、API Key、点数流水和调用记录：API Key 明文只在创建 helper 返回，库内只存 hash/prefix； `result_ref` /`result_summary` ，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate` ：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")` ；金额换点数按当前 active 汇率向下取整。T-203 已落地 `precharge_call()` / `mark_call_success()` / `refund_call_points()` ：预扣锁钱包行，余额不足不写调用/流水；失败退点锁调用记录并幂等写 refund 流水。T-204 已完成复合唯一约束加固，并取得一次完整 `manage.py test` 单次全绿。T-301 已落地 `Authorization: Bearer <API_KEY>` 鉴权：成功后 `request.user` 为所属用户、`request.auth` 为 `ApiKey` ，缺失/无效 Key 返回 401，用户或 Key 禁用返回 403，外部 API 不接受 Web session。T-302 已落地生成接口：请求别名解析后按规则计费，预扣成功才调用 Provider，成功确认调用记录，`AiProviderError` / `AiCapabilityError` 等失败路径会退点；图片结果保存到本地 media 并返回 URL。T-303 已落地余额查询接口：`GET /api/v1/balance` 继承外部 API Key 鉴权，读取 billing 余额快照并返回 `user` 与 `points_balance` ，测试覆盖余额与流水累加一致。T-304 已落地充值回调：`RechargeOrder` 保存下单锁定的金额/汇率/点数，微信/支付宝回调先验签再按订单幂等入账，重复回调不重复加点，金额不一致不入账；主动查单兜底可调用 `query_and_apply_recharge_payment(order_no, query_func)` 复用同一入账路径。T-305 已落地扫码下单与轮询：用户端 session 登录后可 `POST /api/v1/recharge/create` 创建 pending 订单并拿到 mock/SDK 二维码票据，`GET /api/v1/recharge/status` 只返回本人订单并在 pending 时尝试主动查单补入账；API Key 不能调用这两个用户端接口。T-306 已落地对外 API 安全加固： `image_url` 下载在扣点前做协议白名单、公网地址校验、重定向逐跳校验和响应大小上限；DRF 全局默认不再隐式启用 Session/Basic；生成接口按 Key 限流，认证失败按 IP 限流；充值下单有单笔金额上限。 真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再通过接口跑真实标题/图片。
## 开始编码前检查
1. 读仓库级 `AGENTS.md` / `CLAUDE.md` 。
2. 读 `docs/00-ai-start-here.md` 。
3. 读 `docs/05-coding-rules.md` （尤其第 8 节资金安全）。
4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-306 ）。
4. 在 `docs/06-tasks.md` 领取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-501 ）。
5. 将该任务状态改为 `DOING` 。
## 维护规则
QiuSW