cmhub/progress.md

执行进度记录

本文件是只追加的历史流水，用来记录任务执行过程、验证命令、阻塞点和关键决策。 当前目录、当前命令、下一个可领取任务等可覆盖快照，写入 docs/current-state.md。

职责边界

• docs/06-tasks.md：任务看板，维护任务状态、依赖和验收要点。
• progress.md：历史流水，只追加记录每轮执行发生了什么。
• docs/current-state.md：当前快照，可覆盖更新仓库现实、可运行命令和下一步。

不要在本文重复维护当前目录结构、当前运行命令或下一个任务；这些信息以 docs/current-state.md 为准。

记录格式

每完成或中断一轮任务，在文件末尾追加一条记录：

## 【YYYY-MM-DD】T-【编号】 【任务名】

- 状态：【DONE / BLOCKED / PARTIAL】
- 变更：【修改了哪些文件或模块】
- 验证：【运行的真实命令和结果】
- 阻塞：【如有，写明原因和需要谁决策】
- 决策：【如有，记录本轮确定的关键取舍】
- 下一步：【建议下一个任务 ID 或待确认事项】

执行记录

2026-06-29 文档初始化（非任务）

• 状态：DONE
• 变更：基于 D:\github\harness_coding_docs 模板，结合需求讨论生成 cmhub 全套 harness 文档（AGENTS/CLAUDE、docs/00–06、api、routes、current-state、README、progress、init 脚本）；通用流程文档（adoption/clean-state/method-map/evaluator/quality）从模板复制。
• 验证：仅文档，无代码可跑。
• 决策：技术栈 Django+DRF+django-admin；预付费点数模型（充值按汇率转点存本地，调用扣本地点数，不实时查支付系统）；生成接口同步返回；充值由支付系统服务端回调入账（验签+幂等）。
• 下一步：领取 T-001 初始化 Django + DRF 骨架。支付系统接口文档待提供（T-304 前需要）。

2026-06-29 设计优化：可插拔供应商（别名 + 适配器）（非任务）

• 状态：DONE
• 变更：把「两个接口 + 后台配模型」的设计从简化版抬到可治理版，更新到多个文档：
  • 04-architecture.md：AI 调用层改为 Provider 适配器架构；新增 ModelAlias 表与 AiModel 的 capabilities/加密 key；PricingRule 改为按别名定价；CallRecord 增 alias + model_used；计费时序加入别名解析与能力校验；难点表补充抽象泄漏/供应商耦合/配置热生效/审计；项目结构加 apps/ai/providers/。
  • api.md：对外 model 字段明确为能力别名；新增 parameters 透传；响应加 model_used；图片默认返回 URL；AI 模块合约改为别名解析 + Provider 适配器接口。
  • 03-tech-stack.md / 02-requirements.md / 05-coding-rules.md / routes.md / 06-tasks.md：同步别名机制、密钥加密、配置审计、对象存储等决策与任务。
• 验证：仅文档；自检文档间链接与任务依赖一致（T-302 依赖更新为 T-104）。
• 决策：① 对外绑能力别名而非具体模型 SKU；② api_type 升级为显式 Provider 适配器层 + capabilities 声明 + parameters 透传；③ 供应商密钥加密存储 + 配置热生效 + 后台变更审计。按账号授权别名、按比例分流/故障转移列入 Backlog（接口预留，MVP 不实现）。
• 下一步：领取 T-001 初始化 Django + DRF 骨架（Phase 1 任务已重排为 T-101 适配器层 / T-102 别名解析 / T-103 审计 / T-104 跑通）。

2026-07-01 设计决策：桌面端全同步接入 + V2 异步预研（非任务）

• 状态：DONE
• 变更：把「桌面端不改、全同步接入 cmhub」的可用性结论与前提写入两个每轮必读文档：
  • 03-tech-stack.md 第二节「同步生成而非任务队列」决策下补：桌面端可不改交互骨架、只换 service 层 URL/密钥即可接入；同步可用的三前提；何时转 V2 异步的触发信号。
  • 04-architecture.md 第五节新增 5.1 同步方案可用性结论：超时链路层层放大对齐（点名 timeout_seconds:0、Gunicorn 30s、Nginx 60s 三个默认值雷，建议统一 300s）、worker 数按峰值总并发预留、适用边界与 V2 触发条件。
• 验证：仅文档；ai_models.json 现存 timeout_seconds: 0，迁入服务端时须改有限值（关联约束已写入 04 第五节）。
• 决策：① MVP 桌面端不改、桌面端 → cmhub → 中转站 全同步，多一跳不影响可用性，点数一致性更简单（一次请求闭环：预扣→同步调→成功/失败退点）；② 同步可用的硬前提是「超时链路 + worker 容量」配对，否则「小量正常、上量假死」；③ 适用边界为单接入方小并发批量，V2 异步（队列）延后，但适配器接口与 call_record 三态需为异步预留口子。
• 安全提醒：ai_models.json 内三把 sk- 为明文真实密钥，视为已泄露，迁入时须加密存储（Fernet/KMS）并轮换；密钥不进桌面端。
• 下一步：不改变任务看板顺序，仍从 T-001 起步；V2 异步化触发条件见 03/04，暂不排期。

2026-07-01 设计决策：版本锁定 + 数据库选型（MySQL 8.4 独立实例）（非任务）

• 状态：DONE
• 变更：结合实际部署环境（一台 VPS，实测 15G 内存 / available 7.4G / 无 swap，已装 MySQL 5.7 供其他服务用），定稿版本与数据库选型，更新 03-tech-stack.md（技术栈表语言/框架/数据库三行 + 决策记录三条）、04-architecture.md（数据库条目 + 第五节并发扣点难点补 CHECK 版本注意）、README.md 技术栈行。
• 验证：仅文档。
• 决策：
  • ① 框架/语言锁定 Django 5.2 LTS + Python 3.12（requires-python ">=3.12,<3.14"）；禁用已 EOL 的 Django 4.0/4.1；理由是安全/维护窗口，非性能（性能瓶颈在等上游+worker，见 5.1）。
  • ② 数据库定 MySQL 8.4 LTS，cmhub 专用独立实例。放弃复用 VPS 已有的 MySQL 5.7：5.7 跑不了 Django 5.2（需 ≥8.0.11）、已 EOL、不支持 CHECK 约束；曾评估「坚持 5.7」会连锁把 Django 拖回 4.0(EOL)+Python≤3.10+cmbot 兼容风险，被否。内存宽裕（7.4G），单开独立实例与已有 5.7 隔离、互不影响。
  • ③ 硬性约束：InnoDB + utf8mb4；CHECK 需 MySQL ≥8.0.16 才生效，扣点主防线是 select_for_update / UPDATE ... WHERE balance>=N，不能只靠 CHECK；MySQL 默认隔离级别 REPEATABLE READ，计费按此语义验证；开发亦用 MySQL，不用 SQLite（会忽略 FOR UPDATE，测不出并发扣点）。
• 待办提醒：T-001 骨架落地时须选 MySQL 驱动（mysqlclient 或 PyMySQL）、DATABASES 配 charset=utf8mb4、连接指向独立实例端口；机器建议补 2–4G swap；03 部署维度仍为「待定」，部署基线待后续定稿。
• 下一步：不改变任务看板顺序，仍从 T-001 起步（Django+DRF 骨架，按上述版本/数据库落地）。

2026-07-01 定位扩展：新增自助用户端（B2B → B2B+B2C）（非任务）

• 状态：DONE
• 变更：按用户新增需求（终端用户自助注册/扫码充值/API Key 管理/查记录），把项目从纯 B2B API 网关扩展为「自助用户端 + 计费 API + 运营后台」三合一，系统性更新文档：
  • 定位/需求：01-vision、00-ai-start-here、02-requirements、project-brief、project-onepager（用户角色加注册用户；MVP 加用户端；移除"自助注册"非目标；注册不送点数）。
  • 架构：04-architecture（系统结构加用户端；数据模型 Account→User+UserWallet+ApiKey；两套认证；4.2 加自助扫码下单时序；难点加 API Key 哈希/注册滥用/Web-API worker 隔离/充错账户；项目结构 apps；架构纪律）。
  • 合约/路由/规则：api.md（认证主体 User、recharge/create 转正扫码、API 只认 Key）、routes.md（用户端页面路由、admin 改 User/Wallet/ApiKey）、03-tech-stack（用户端形态 Django SSR+Bootstrap+allauth、鉴权、部署 worker 隔离）、05-coding-rules（范围、API Key 哈希、API 只认 Key、锁 wallet）。
  • 任务：06-tasks（T-002 首迁移前定自定义 User；T-201 改 User/Wallet/ApiKey；T-203 锁 wallet；T-305 扫码下单；新增 Phase 4 用户端 T-501~504；里程碑加 M4 用户端）。
  • README、current-state 同步。
• 验证：仅文档。
• 决策：
  • ① 前端形态选 Django 模板 SSR 单体（+Bootstrap/allauth/crispy），不引前后端分离框架。
  • ② 用户模型：User(auth 登录态) / UserWallet(点数余额，扣点锁 wallet、与 auth 解耦) / ApiKey(User 1:N，sha256 哈希存储、明文只显示一次)。
  • ③ 认证分两套认同一 User：用户端 session+CSRF，对外 API 只挂 API Key（不挂 Session，防绕过计费）。
  • ④ 充值：recharge/create 转正，用户端自助扫码下单 + 回调入账，订单绑定 user 防充错账户，金额 Decimal 向下取整。
  • ⑤ 注册不送免费点数（必须充值才有点数，降低薅羊毛）；注册须邮箱验证、生成接口须限流。
  • ⑥ 单体部署按路径把图片 API 与用户端页面分流到不同 worker 池。
• 待办提醒：支付系统扫码下单 + 回调接口文档仍未提供，是 T-304/T-305 充值的硬阻塞；自定义 User 必须在首次 migrate 前定义（Django 硬约束）。
• 下一步：任务仍从 T-001 起步；用户端任务见 Phase 4（T-501~504）。

2026-07-01 补全支付协议（参考同系统 PHP 实现，解除充值 blocker）（非任务）

• 状态：DONE
• 变更：从 Obsidian 笔记（虎观虾皮一键采购 扫码支付购买流程-技术文档 + 扫码支付迁移到Django-实施指南）提取同一支付系统的扫码支付协议，补进当前 Django 仓库文档：
  • api.md：充值段重写为微信 V3 native + 支付宝当面付双回调（/recharge/callback/wechat、/alipay）+ create（pay_method、code_url/qr_code）+ status 轮询；金额单位、验签、幂等、应答格式明确。
  • 04-architecture.md 4.2：补通道协议、库、金额单位、回调应答、@csrf_exempt、主动查单兜底。
  • 03-tech-stack.md：充值对接行加库 wechatpayv3/python-alipay-sdk。
  • routes.md：拆微信/支付宝回调端点 + status。
  • 06-tasks.md：T-304 拆双回调+主动查单，T-305 加 weixin/alipay+轮询。
  • 05-coding-rules.md：回调 @csrf_exempt + 主动查单兜底。
  • current-state.md：blocker 降级。
• 验证：仅文档。
• 决策：
  • ① 路线确认：继续当前 Django 仓库，Obsidian 的 Go(Gin+GoAdmin) cmhub 方案仅作支付逻辑参考（用户拍板）。
  • ② 支付通道：微信 V3 native（wechatpayv3，金额分，回调 SDK 验签解密、TRANSACTION.SUCCESS、应答 {code:SUCCESS}）；支付宝当面付 trade.precreate（python-alipay-sdk，金额元，verify、TRADE_SUCCESS/FINISHED、应答 success）。
  • ③ 二维码不含业务数据，靠 out_trade_no(=order_no) 在回调关联；回调 @csrf_exempt；幂等 select_for_update+status!=pending；须主动查单兜底。
  • ④ 只取支付层，不引入 Obsidian 源里的套餐/会员有效期/邀请返佣业务（那是虎观助手专有）；充值入账走本项目 UserWallet+points_ledger+ExchangeRate。
• 待办提醒：blocker 从「协议缺失」降级为「仅缺商户密钥/证书真实值」，不阻塞开发，可先 mock。原 PHP 遗留坑（测试后门号、H5 金额写死、支付宝 debug 沙箱、明文密钥）不迁入。
• 下一步：任务仍从 T-001 起步；充值见 T-304/T-305（可 mock 先行）。

2026-07-01 吸收 AI 模型调用机制（来自 Go 方案 §16.6）（非任务）

• 状态：DONE
• 变更：从 Obsidian Golang-Gin-GoAdmin-技术方案 §16.6 提取三个上游模型的真实调用机制（业务规则/上游契约，非技术栈），补进 04-architecture.md（3.1 + AI 层职责）、api.md（待确认 + image 改图必传）、03-tech-stack.md、06-tasks.md（T-101 验收）。
• 验证：仅文档。
• 决策：
  • ① GPT-5.5（chat）标准 chat/completions；Nano Banana 2（api_type=auto）走 chat/completions 多模态返图、需自定义解析、可文/图生图；GPT Image 2（images_edits）走 images/edits 改图、原图必传。
  • ② 两个图片模型非标准 images/generations，每模型独立 url+key；图片返回结构（URL/base64/位置）首次对接抓真实响应再定解析。
  • ③ 只吸收 AI 模型机制，不吸收 Go 方案的会员套餐/续期/折扣/邀请返佣/多端 JWT（属虎观采购业务或 Go 栈，非 cmhub 定位）；鉴权继续用 API Key（比桌面端 JWT 更安全，不在桌面端存密码）。
• 下一步：T-101/T-102 实现适配器时按此机制，首次对接 api.vectorengine.ai 抓真实响应确认图片返回结构。

2026-07-01 文档优化：定位一致性 + 充值 schema + 调用状态 + 环境配置（非任务）

• 状态：DONE
• 变更：按全栈落地前优先级修正文档：
  • docs/README.md / project-brief.md / project-onepager.md：定位同步为「自助用户端 + 计费型 AI 能力网关 + 运营后台」三合一，并加入 env.md 导航。
  • docs/04-architecture.md / docs/api.md / docs/06-tasks.md：充值订单改为下单时锁定 exchange_rate 与 points_granted，回调入账使用订单值并校验金额；call_record.status 明确为 pending -> success / failed，失败退点通过 points_ledger(refund, ref_call_id) 关联。
  • docs/env.md：新增环境变量与配置清单，覆盖 Django、MySQL、AI 密钥加密、微信/支付宝、对象存储与上线检查。
  • docs/03-tech-stack.md / docs/current-state.md / docs/00-ai-start-here.md / docs/02-requirements.md / 汇报文档：同步环境配置入口、当前快照与支付 blocker 降级口径。
• 验证：文档修改；用 rg 定位相关段落，未运行代码测试（仓库当前尚无代码）。
• 阻塞：无。
• 决策：充值汇率采用「下单锁定」而非「回调时读取当前汇率」，便于页面展示预计到账点数，也避免用户扫码后后台改价导致入账变化；调用记录不增加 refunded 状态，账务冲正由点数流水表达。
• 下一步：仍从 T-001 初始化 Django + DRF 骨架开始。

2026-07-01 文档优化：里程碑口径同步（非任务）

• 状态：DONE
• 变更：同步汇报文档里程碑到 06-tasks.md 的 M1-M5 口径：project-brief.md 增加 M4 用户端可用、M5 验收上线；project-onepager.md 进度行同步 M4/M5。
• 验证：文档修改；用 rg 定位里程碑旧口径。
• 阻塞：无。
• 决策：以 06-tasks.md 的里程碑为权威，汇报文档只做同口径摘要。
• 下一步：仍从 T-001 初始化 Django + DRF 骨架开始。

2026-07-01 文档优化：Phase 顺序口径同步（非任务）

• 状态：DONE
• 变更：更新 docs/00-ai-start-here.md 的优先路径，Phase 3/4/5 与 docs/06-tasks.md 对齐：Phase 3 为对外 API 与充值，Phase 4 为用户端，Phase 5 为后台与发布。
• 验证：文档修改；用 rg 对照 00-ai-start-here.md 与 06-tasks.md 的 Phase 标题。
• 阻塞：无。
• 决策：任务阶段顺序以 06-tasks.md 为权威，入口文档只做一致的导航摘要。
• 下一步：仍从 T-001 初始化 Django + DRF 骨架开始。