docs: add phase 2 billing review

docs/current-state.md

@@ -12,16 +12,16 @@
 ## 当前快照
 
 - 日期：2026-07-02
-- 阶段：Phase 2 计费核心已完成 T-202；下一步进入 T-203 并发安全扣点 / 退点
+- 阶段：Phase 2 计费核心已完成 T-203；下一步进入 Phase 3 的 T-301 API Key 鉴权
 - 技术栈：系统 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 8.4 已接入 settings；用户端(模板 SSR/Bootstrap/allauth) 后续任务落地；详见 `03-tech-stack.md`
-- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `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-202 范围验证通过：`py_compile`、`manage.py check`、`makemigrations --check`、`migrate`、`showmigrations billing`、`manage.py test apps.billing --noinput --keepdb`（10 tests）、`manage.py test apps.users --noinput --keepdb`（2 tests）、`compileall apps`、`git diff --check`（仅 Windows CRLF 提示）、`./init.ps1`。全量 `manage.py test --noinput --keepdb` 当前发现 38 tests，但两次在远程 MySQL `43.128.3.240:3306` 连接超时/重置处失败；`apps.ai` 单独测试也在远程连接重建处超时，已跑过测试无断言失败。
+- 生产代码：已有最小 Django 工程骨架：`manage.py`、`config/`；T-002 已创建 `apps/users|portal|billing|ai|api`；T-003 已把自定义 `User` 注册进 django-admin；T-004 已完成 email 唯一性、init 版本断言、app 顺序、`.env.example` 与 `pyproject.toml`；T-101 已新增 `apps/ai/providers/`（Provider 接口、注册表、chat/gemini/images/images_edits 适配器）；T-102 已新增 `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-203 直接验证通过：`py_compile`、`manage.py test apps.billing.tests.BillingServiceTests --noinput --keepdb`（4 tests）、`manage.py test apps.billing.tests.ConcurrentDebitTests --noinput --keepdb`（1 test，2 线程并发扣点）、`manage.py check`、`makemigrations --check`、`compileall apps`、`git diff --check`（仅 Windows CRLF 提示）、`./init.ps1`。完整 `apps.billing` / 全量 `manage.py test` 当前仍受远程 MySQL `43.128.3.240:3306` 间歇连接超时/重置影响；已确认失败点为连接/测试库清理问题，不是 T-203 服务断言。
 - 数据：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`；Unix/WSL 用 `./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`；真实密钥/支付凭证不得写入代码或文档样例。充值订单在创建时锁定汇率与预计点数，回调入账使用订单值，不按新汇率重算
-- 当前 blocker：无代码 blocker。支付商户密钥/证书仍缺真实值，但不阻塞当前 Phase 2；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，已登记到 T-302/T-403。远程 MySQL 对全量测试存在间歇连接超时/重置，必要时重试或分 app 验证。
+- 当前 blocker：无代码 blocker。支付商户密钥/证书仍缺真实值，但不阻塞 T-301；真实 AI 上游 smoke 需要先配置 `AI_KEY_ENCRYPTION_KEY` 并导入 AiModel/ModelAlias。图片同步真实耗时风险仍未退，已登记到 T-302/T-403。远程 MySQL 对全量测试存在间歇连接超时/重置，必要时重试或分 app 验证。
 
 ## 当前目录要点
 
@@ -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`；T-101 新增 `requests`；T-102 使用既有 `cryptography` 做 Fernet 加密 |
 | `config/`（Django 工程） | 已有 | T-001 创建，含 settings / urls / wsgi / asgi |
-| `apps/`（users/portal/billing/ai/api） | 已有 | T-002 创建；`apps/users` 已定义自定义 `User`；T-003 已注册 admin 与 admin smoke test；T-004 已给 `User.email` 加唯一约束；T-101 已新增 `apps/ai/providers`；T-102 已新增 `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`；T-202 已在 billing 落 `PricingRule` / `ExchangeRate` 与 `pricing.py` |
+| `apps/`（users/portal/billing/ai/api） | 已有 | T-002 创建；`apps/users` 已定义自定义 `User`；T-003 已注册 admin 与 admin smoke test；T-004 已给 `User.email` 加唯一约束；T-101 已新增 `apps/ai/providers`；T-102 已新增 `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`；T-202 已在 billing 落 `PricingRule` / `ExchangeRate` 与 `pricing.py`；T-203 已新增 `apps/billing/services.py` |
 | `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-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 并发安全扣点 / 退点。
 - 正在进行：无。
 - 当前 blocker：无代码 blocker；远程 MySQL 全量测试偶发连接超时/重置。
-- 下一个可领取任务：**T-203 并发安全扣点 / 退点（billing 层）**。
+- 下一个可领取任务：**T-301 API Key 鉴权（DRF Authentication）**。
 
 ## 当前可运行内容
 
@@ -68,14 +68,14 @@ python3.12 manage.py smoke_ai_generation title --recorded
 python3.12 manage.py smoke_ai_generation image --recorded
 ```
 
-当前骨架可运行。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`，admin 保存/删除 `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；CallRecord 只存 `result_ref`/`result_summary`，没有 provider raw 字段。T-202 已落地 `PricingRule` / `ExchangeRate`：计费按 `operation_type + alias + resolution` 查 active 规则，优先精确分辨率，再回退默认价；缺规则抛 `NoPricingRuleError(code="no_pricing_rule")`；金额换点数按当前 active 汇率向下取整。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再用同一 smoke 命令去掉 `--recorded` 跑真实标题/图片。
+当前骨架可运行。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`，admin 保存/删除 `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；CallRecord 只存 `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 流水。真实上游生成未执行，原因是当前环境未配置 `AI_KEY_ENCRYPTION_KEY` 且数据库没有 AiModel/ModelAlias；后续配置后可用 `import_ai_models` 导入，再用同一 smoke 命令去掉 `--recorded` 跑真实标题/图片。
 
 ## 开始编码前检查
 
 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-203）。
+4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务（当前为 T-301）。
 5. 将该任务状态改为 `DOING`。
 
 ## 维护规则