2026-07-01 17:42:10 +08:00
# 执行进度记录
> 本文件是只追加的历史流水，用来记录任务执行过程、验证命令、阻塞点和关键决策。
> 当前目录、当前命令、下一个可领取任务等可覆盖快照，写入 [`docs/current-state.md`](docs/current-state.md)。
## 职责边界
- `docs/06-tasks.md` ：任务看板，维护任务状态、依赖和验收要点。
- `progress.md` ：历史流水，只追加记录每轮执行发生了什么。
- `docs/current-state.md` ：当前快照，可覆盖更新仓库现实、可运行命令和下一步。
不要在本文重复维护当前目录结构、当前运行命令或下一个任务；这些信息以 `docs/current-state.md` 为准。
## 记录格式
每完成或中断一轮任务，在文件末尾追加一条记录：
```markdown
## 【YYYY-MM-DD】T-【编号】 【任务名】
- 状态：【DONE / BLOCKED / PARTIAL】
- 变更：【修改了哪些文件或模块】
- 验证：【运行的真实命令和结果】
- 阻塞：【如有，写明原因和需要谁决策】
- 决策：【如有，记录本轮确定的关键取舍】
- 下一步：【建议下一个任务 ID 或待确认事项】
```
## 执行记录
## 2026-06-29 文档初始化（非任务）
- 状态：DONE
- 变更：基于 `D:\github\harness_coding_docs` 模板，结合需求讨论生成 `cmhub` 全套 harness 文档（AGENTS/CLAUDE、docs/00–
- 验证：仅文档，无代码可跑。
- 决策：技术栈 Django+DRF+django-admin；预付费点数模型（充值按汇率转点存本地，调用扣本地点数，不实时查支付系统）；生成接口同步返回；充值由支付系统服务端回调入账（验签+幂等）。
- 下一步：领取 T-001 初始化 Django + DRF 骨架。支付系统接口文档待提供（T-304 前需要）。
## 2026-06-29 设计优化：可插拔供应商（别名 + 适配器）（非任务）
- 状态：DONE
- 变更：把「两个接口 + 后台配模型」的设计从简化版抬到可治理版，更新到多个文档：
- `04-architecture.md` ： ； `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， 。放弃复用 VPS 已有的 MySQL 5.7：
- ③ 硬性约束：InnoDB + utf8mb4； `select_for_update` / `UPDATE ... WHERE balance>=N` ，不能只靠 CHECK；
- 待办提醒：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； ； ；
- `README` 、`current-state` 同步。
- 验证：仅文档。
- 决策：
- ① 前端形态选 **Django 模板 SSR 单体** （
- ② 用户模型：`User` (auth 登录态) / `UserWallet` (点数余额，扣点锁 wallet、与 auth 解耦) / `ApiKey` (User 1:N，
- ③ 认证分两套认同一 User：用户端 session+CSRF，对外 API 只挂 API Key（不挂 Session，防绕过计费）。
- ④ 充值：`recharge/create` 转正，用户端自助扫码下单 + 回调入账，订单绑定 user 防充错账户，金额 Decimal 向下取整。
- ⑤ **注册不送免费点数** （必须充值才有点数，降低薅羊毛）；注册须邮箱验证、生成接口须限流。
- ⑥ 单体部署按路径把图片 API 与用户端页面分流到不同 worker 池。
- 待办提醒：**支付系统扫码下单 + 回调接口文档仍未提供**，是 T-304/T-305 充值的硬阻塞；自定义 User 必须在首次 migrate 前定义（Django 硬约束）。
- 下一步：任务仍从 T-001 起步；用户端任务见 Phase 4（
## 2026-07-01 补全支付协议（参考同系统 PHP 实现，解除充值 blocker）（非任务）
- 状态：DONE
- 变更：从 Obsidian 笔记（虎观虾皮一键采购 `扫码支付购买流程-技术文档` + `扫码支付迁移到Django-实施指南` ）提取同一支付系统的扫码支付协议，补进当前 Django 仓库文档：
- `api.md` ：充值段重写为微信 V3 native + 支付宝当面付双回调（`/recharge/callback/wechat` 、`/alipay` ） `create` （ ） `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` ：
- 验证：仅文档。
- 决策：
- ① 路线确认：**继续当前 Django 仓库**，
- ② 支付通道：微信 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` （ `api.md` （待确认 + image 改图必传）、`03-tech-stack.md` 、`06-tasks.md` （
- 验证：仅文档。
- 决策：
- ① GPT-5.5（ `chat` ）标准 chat/completions； （ `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 骨架开始。
2026-07-01 18:01:23 +08:00
## 2026-07-01 T-001 初始化 Django + DRF 项目骨架
- 状态：DONE
- 变更：
- 新增 `manage.py` 、`config/` Django 工程骨架。
- 新增 `requirements.txt` ，锁定 Django 5.2 系列与 DRF 3.16 系列。
- `config/settings.py` 加入 `rest_framework` ， `SECRET_KEY` / `DEBUG` / `ALLOWED_HOSTS` 支持环境变量，默认仅用于本地开发。
- `init.ps1` / `init.sh` 替换为真实命令；按用户要求使用系统 Python 3.12，不使用虚拟环境。Windows 用 `py -3.12` ， `python3.12` 。
- 同步 `docs/00-ai-start-here.md` 、`docs/03-tech-stack.md` 、`docs/current-state.md` 、`docs/06-tasks.md` 、`README.md` 。
- 验证：
- `py -3.12 -m pip install -r requirements.txt` ：
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py test` ：通过，当前 0 tests。
- `./init.ps1` ：通过，完成依赖检查、`manage.py check` ，打印启动命令。
- `C:\Python312\python.exe manage.py runserver 127.0.0.1:8765 --noreload` ：端口 smoke 通过（TCP 8765 可连接），随后已停止进程。
- `bash -n init.sh` ：当前机器无可用 bash/WSL，无法本机验证 Unix 脚本。
- 阻塞：无。
- 决策：T-001 不接入 MySQL、不创建自定义 User、不创建 apps 目录；这些按任务边界留给 T-002。T-001 阶段暂保留 Django 默认 SQLite 配置用于框架启动检查，T-002 必须在首次迁移前改为自定义 User + MySQL 8.4 配置。
- 下一步：领取 T-002 建立 apps 目录、自定义 User 与配置。
2026-07-02 09:07:15 +08:00
## 2026-07-02 T-002 建立 apps 目录、自定义 User 与配置
- 状态：DONE
- 变更：
- 创建 `apps/` 包与 `apps/users|portal|billing|ai|api` 五个 Django app。
- `apps/users.models.User` 继承 `AbstractUser` ，新增 `payment_user_id` 、`status` 、`created_at` ，邮箱改为必填，`db_table="user"` ； `settings.AUTH_USER_MODEL="users.User"` 已设置。
- `settings.py` 增加根目录 `.env` 读取，数据库从 SQLite 切换到 MySQL，配置 `utf8mb4` 与严格 SQL 模式。
- 采用 `PyMySQL` 作为 MySQL 驱动，更新 `requirements.txt` 与 `config/__init__.py` 。
- 生成 `apps/users/migrations/0001_initial.py` 。
- 验证：
- `py -3.12 -m pip install -r requirements.txt` ：通过，安装 PyMySQL 1.1.3。
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py makemigrations users` ：通过，生成 `0001_initial.py` 。
- `py -3.12 manage.py migrate` ：首次失败，MySQL 返回 `ALTER command denied to user 'test'@'61.141.174.182' for table 'django_content_type'` ；用户在宝塔/MySQL 授权后，清理失败迁移留下的空表并重新执行，最终通过。
- `SHOW GRANTS FOR CURRENT_USER()` ：授权后显示 `GRANT ALL PRIVILEGES ON cmhub.* TO test@%` 。
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py test` ：通过，当前 0 tests。
- MySQL 验证：存在自定义 `user` 表，含 `payment_user_id` / `status` / `created_at` ；未创建默认 `auth_user` 表；`django_migrations` 共 19 条。
- 阻塞：已解除。曾因 MySQL 用户缺少 `ALTER/INDEX/DROP` 等迁移权限受阻。
- 决策：使用 PyMySQL 作为 MySQL 驱动；T-002 只落 apps、自定义 User、settings 与 MySQL 初始迁移，不提前实现 UserWallet/ApiKey 等 T-201 内容。
- 下一步：领取 T-003 接通 django-admin 与最小测试。
2026-07-02 09:46:32 +08:00
## 2026-07-02 T-003 接通 django-admin 与最小测试
- 状态：PARTIAL
- 变更：
- `apps/users/admin.py` ：用 `DjangoUserAdmin` 注册自定义 `User` ，后台列表展示 `username/email/status/is_staff/is_active/created_at` ，支持按 `status` 过滤、按 `username/email/payment_user_id` 搜索，`created_at` 只读。
- `apps/users/tests.py` ：新增最小 admin smoke test，覆盖自定义 User 已注册到 admin、superuser 可登录 `/admin/` 。
- `config/settings.py` ：本地默认 `ALLOWED_HOSTS` 增加 `testserver` ，匹配 Django test client。
- `docs/06-tasks.md` / `docs/current-state.md` ：记录 T-003 当前权限阻塞。
- 验证：
- `py -3.12 manage.py check` ：通过，0 issues。
- 手工创建临时 superuser 并用 Django test client 登录 `/admin/` ：登录成功，`GET /admin/` 返回 200；临时用户已清理。
- `py -3.12 manage.py test` ：未通过，Django 在创建 `test_cmhub` 测试库时报 `(1044, "Access denied for user 'test'@'%' to database 'test_cmhub'")` 。
- 进一步验证 `CREATE DATABASE IF NOT EXISTS test_cmhub ...` 同样返回 1044；当前授权仅覆盖 `cmhub.*` 。
- 阻塞：需要给 MySQL 用户增加测试库权限，建议优先只授权测试库范围：
- `GRANT ALL PRIVILEGES ON test_cmhub.* TO 'test'@'%';`
- `FLUSH PRIVILEGES;`
- 决策：不把 Django 测试改跑到业务库 `cmhub` ，避免测试清表/迁移影响真实开发数据；T-003 在标准 `manage.py test` 通过前不标 `DONE` 。
- 下一步：完成 MySQL 授权后重跑 `py -3.12 manage.py test` ，再跑 `py -3.12 manage.py check` / `./init.ps1` ，通过后把 T-003 标记 DONE。
## 2026-07-02 T-003 接通 django-admin 与最小测试（完成验收）
- 状态：DONE
- 变更：
- `requirements.txt` ：新增 `cryptography>=42,<47` ，用于支持 PyMySQL 连接 MySQL 8 默认 `caching_sha2_password` 认证。
- `docs/06-tasks.md` ：
- `docs/current-state.md` / `docs/03-tech-stack.md` ：同步当前依赖、验证结果与下一步任务。
- 验证：
- `py -3.12 -m pip install -r requirements.txt` ：通过，安装 `cryptography 46.0.7` 。
- `py -3.12 manage.py test` ：通过，2 tests OK，测试库 `test_cmhub` 创建与销毁正常。
- `py -3.12 manage.py check` ：通过，0 issues。
- `./init.ps1` ：通过，依赖同步与基础检查正常。
- 阻塞：无。
- 决策：保留独立 `test_cmhub` 测试库路径，标准测试不使用业务库 `cmhub` 。
- 下一步：领取 T-101 Provider 适配器层 + 移植 cmbot 调用。
2026-07-02 10:17:10 +08:00
## 2026-07-02 Phase 0 骨架审核（Claude Code review，非任务）
- 状态：DONE（审核完成）
- 变更：新增 `docs/phase-0-review.md` ； `06-tasks.md` 新增 T-004 修补任务；`docs/README.md` 导航登记；`current-state.md` 下一步改 T-004。
- 审核结论：**T-001~003 验收全部达标，质量高于骨架平均水准**。自定义 User 先于首次迁移、`AUTH_USER_MODEL` 已设、`PyMySQL install_as_MySQLdb()` 胶水到位、密钥全走 env 且 `.env` /`ai_models.json` 未被 git 跟踪、独立 `test_cmhub` 测试库——关键硬约束全对。
- 发现（详见 `phase-0-review.md` ）：
- P1（建议现在改）：`User.email` 未 `unique` ； `requires-python` 未落地、init 脚本无解释器版本断言。
- P2（规范性）：`INSTALLED_APPS` 顺序（本地 app 排在 contrib 前，模板查找隐患）；缺 `.env.example` 。
- P3（后续任务处理）：REST_FRAMEWORK 认证配置（T-301）、`sql_mode` 完整性、生产 SECRET_KEY 保护（T-403）。
- 未本地复跑：审核机无 `python3.12` ，结论基于静态审查 + codex 验证记录（记录真实，含 MySQL 授权 / caching_sha2 修复过程）。
- 下一步：codex 领 T-004，按 `phase-0-review.md` 修 P1/P2，全绿留证后再进 T-101。
## 2026-07-02 T-004 Phase 0 骨架审核修补
- 状态：DONE
- 变更：
- 文档先行：更新 `README.md` 、`docs/00-ai-start-here.md` 、`docs/03-tech-stack.md` 、`docs/04-architecture.md` 、`docs/api.md` 、`docs/current-state.md` 、`docs/env.md` 、`docs/06-tasks.md` ，把 T-004、邮箱唯一约束、Python 版本断言、`.env.example` 和下一步 T-101 口径同步。
- `apps/users.models.User.email` 增加 `unique=True` ，并生成/应用 `apps/users/migrations/0002_alter_user_email.py` 。
- `config/settings.py` 调整 `INSTALLED_APPS` 顺序为 `django.contrib.*` → `rest_framework` → 本地 apps。
- `init.ps1` / `init.sh` 在安装依赖前校验 Python 版本必须满足 `>=3.12,<3.14` 。
- 新增 `.env.example` （仅占位符，无真实密钥）与 `pyproject.toml` （落地 `requires-python` ）。
- 验证：
- 重复邮箱预检：业务库非空 email 无重复。
- `py -3.12 manage.py makemigrations users` ：生成 `0002_alter_user_email.py` 。
- `py -3.12 manage.py migrate` ：通过，应用 `users.0002_alter_user_email` 。
- 数据库索引验证：`user.email` 存在唯一索引 `user_email_54dc62b2_uniq` 。
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py test` ：通过，2 tests OK。
- `./init.ps1` ：通过，输出 Python 3.12.3 版本断言、依赖同步与基础检查。
- `py -3.12 manage.py makemigrations --check` ：通过，No changes detected。
- `git diff --check` ：通过，仅有 CRLF 提示。
- `bash -n init.sh` ：当前 Windows 未安装 WSL/bash，无法本机验证 Unix 脚本语法。
- 阻塞：无。
- 决策：保留 `requirements.txt` 作为运行依赖来源，`pyproject.toml` 只承载 Python 版本元数据；`.env.example` 使用占位符，不提交 `.env` 。
- 下一步：领取 T-101 Provider 适配器层 + 移植 cmbot 调用。
2026-07-02 10:33:15 +08:00
## 2026-07-02 T-101 Provider 适配器层 + 移植 cmbot 调用
- 状态：DONE
- 变更：
- 新增 `apps/ai/providers/` ： `ResolvedModel` 、`Provider` 协议、结果对象、错误类型、注册表、`chat` /`gemini` /`images` /`images_edits` 适配器。
- 从 `D:\chengma\cmbot\src\services\ai_text_service.py` / `ai_image_service.py` 移植纯 HTTP 与响应解析逻辑：URL 归一化、`api_type=auto` 识别、分辨率超时、chat/gemini payload、images/edits multipart、标题清洗、图片 data URL/base64/URL 解析。
- 服务端接口改为 bytes 输入，不依赖桌面端本地路径、GUI、线程或 Qt；HTTP session 可注入，便于测试。
- `requirements.txt` 新增 `requests>=2.32,<3` 。
- `apps/ai/tests.py` 新增 5 条 mock 单测，覆盖 provider 选择、chat 文本请求构造和标题解析、chat 多模态返图解析、images/edits multipart 请求构造和 base64 图片解析、能力不支持错误。
- 同步 `docs/api.md` 、`docs/03-tech-stack.md` 、`docs/current-state.md` 、`docs/06-tasks.md` 、`README.md` 、`docs/00-ai-start-here.md` 。
- 验证：
- 脱敏读取 `D:\chengma\cmbot\config\ai_models.json` ：顶层为 `models` 列表，共 3 个模型；仅打印非密钥字段，未暴露真实 key。
- `py -3.12 -m pip install -r requirements.txt` ：通过，安装 `requests 2.34.2` 及依赖。
- `py -3.12 manage.py test apps.ai` ：通过，5 tests OK。
- `py -3.12 manage.py test` ：通过，7 tests OK。
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py makemigrations --check` ：通过，No changes detected。
- `py -3.12 -m compileall apps` ：通过。
- `./init.ps1` ：通过，依赖同步含 `requests` ，基础检查正常。
- 阻塞：无。
- 决策：T-101 不创建 AiModel/ModelAlias 数据表、不做别名解析数据库读取、不接计费；先用 `ResolvedModel` dataclass 承接后续 T-102 的数据库模型。
- 下一步：领取 T-102 AiModel + ModelAlias 模型 + 别名解析。
2026-07-02 11:07:44 +08:00
## 2026-07-02 T-102 AiModel + ModelAlias 模型 + 别名解析
- 状态：DONE
- 变更：
- 新增 `AiModel` / `ModelAlias` 数据模型与 `apps/ai/migrations/0001_initial.py` ： `AiModel` 保存上游 url/model/api_type/capabilities/timeout/extra_body/is_active 与 Fernet 密文 `api_key_encrypted` ； `ModelAlias` 用 `operation_type + alias` 映射到具体模型，支持默认别名与启停。
- 新增 `apps/ai/security.py` ： `AI_KEY_ENCRYPTION_KEY` 驱动 Fernet 加解密，密文带 `fernet:` 前缀；拒绝明文 fallback。
- 新增 `apps/ai/aliases.py` ： `resolve_alias(operation_type, alias=None)` 每次查当前 active 配置，标题要求 `text` 能力，图片要求 `image` 能力，返回 provider 可用的 `ResolvedModel` 。
- 新增 `apps/ai/importers.py` 与 `import_ai_models` 管理命令：支持导入 `cmbot` 形状的 `ai_models.json` ，导入时加密 key、推断 capabilities，可选创建 `title-standard` / `image-standard` 默认别名。
- 完善 `apps/ai/admin.py` ： `api_key` 字段，密钥脱敏显示且不回显；缺少 Fernet 主密钥时以表单错误提示；`api_key_encrypted` 不暴露。
- 扩展 `apps/ai/tests.py` ：覆盖密钥加密/解密、别名解析、能力不匹配、inactive alias、配置导入、admin 脱敏与缺主密钥错误；同步更新 README、入口文档、技术栈、架构、API、环境配置、任务看板和当前状态。
- 验证：
- `py -3.12 manage.py migrate` ：通过，`ai.0001_initial` 已应用；`py -3.12 manage.py showmigrations ai` 显示 `[X] 0001_initial` 。
- `py -3.12 manage.py test apps.ai --noinput` ：通过，16 tests OK。
- `py -3.12 manage.py test --noinput` ：通过，18 tests OK。
- `py -3.12 manage.py check` ：通过，0 issues。
- `py -3.12 manage.py makemigrations --check` ：通过，No changes detected。
- `py -3.12 -m compileall apps` / `py -3.12 -m compileall apps\ai` ：通过。
- `./init.ps1` ：通过，依赖同步与基础检查正常。
- 验证期间远程 MySQL `43.128.3.240:3306` 多次短暂超时，`Test-NetConnection 43.128.3.240 -Port 3306` 恢复后重试通过；失败点均为建库/事务前连接超时，不是断言失败。
- 阻塞：无。
- 决策：
- 供应商密钥存储采用 `cryptography` Fernet 应用层加密，主密钥只走 `AI_KEY_ENCRYPTION_KEY` ；不实现明文兼容。
- T-102 不自动导入真实 `D:\chengma\cmbot\config\ai_models.json` ，避免真实上游 key 被误暴露；后续由管理员在确认环境密钥后手动执行导入命令。
- 默认别名唯一性先由 model validation、admin 与导入器保证；MySQL partial unique 约束留待审计/后台完善阶段评估。
- 下一步：领取 T-103 配置变更审计。
