cmhub/docs/phase-0-review.md

Phase 0 骨架审核报告（T-001 ~ T-003）

审核人：Claude Code（全栈视角）｜日期：2026-07-02｜结论：验收通过。 进入 Phase 1（T-101）前，建议先做 T-004 骨架修补（本文 P1/P2）。 本文面向 codex 执行：每条修补项给出「症状 / 位置 / 怎么改 / 怎么验证」。修补任务见 06-tasks.md 的 T-004。

一、验收核对（全部达标）

任务	验收要点	结果
T-001	manage.py 可跑、runserver 起得来、init 脚本真实命令、文档占位替换	✅
T-002	五个 app、首迁移前定义自定义 User + AUTH_USER_MODEL、env 读密钥无明文、MySQL+utf8mb4	✅
T-003	superuser 能登录 /admin/、manage.py test 至少 1 条通过（实际 2 条）	✅

二、做对的（勿在修补中回退）

以下是已正确落地的关键点，T-004 修补时不要改坏：

1. 自定义 User 先于首次迁移：apps/users/migrations/0001_initial.py 只依赖 auth，AUTH_USER_MODEL='users.User' 已设，db_table='user'。Django 头号坑已避开。
2. PyMySQL 胶水：config/__init__.py 的 pymysql.install_as_MySQLdb()——不可删。
3. 密钥零泄露：SECRET_KEY / DB 密码全走 env；.env、ai_models.json 均未被 git 跟踪且在 .gitignore。
4. 测试库隔离：坚持独立 test_cmhub 测试库，不碰业务库 cmhub。
5. cryptography 依赖（MySQL8 caching_sha2_password + 未来 api_key 加密预留）；admin 继承 DjangoUserAdmin 做脱敏/过滤/只读。

三、修补清单

P1 · 现在改（趁地基未固化，低成本高收益）

P1-1 User.email 加 unique=True

• 症状：email 必填但不唯一，允许同邮箱重复注册，与需求（02-requirements.md）「邮箱验证注册」语义冲突；后续 allauth 邮箱验证 / 找回密码通常要求 email 唯一。现在 user 表基本为空，是加约束的最便宜时机；拖到 T-501 再加要额外迁移 + 清洗重复数据。
• 位置：apps/users/models.py（email 字段定义处）。
• 怎么改：email = models.EmailField("email address", unique=True)。
• 前提/权衡：若产品最终确定「只用 username 登录、email 仅展示」，可不改——但需在本文此条标注「产品确认不需要」。默认动作：加 unique。
• 注意：改前确认业务库 user 表无重复邮箱（superuser 用唯一邮箱）；否则先清理。
• 验证：makemigrations users（应生成一条 AlterField）→ migrate → check → test 全绿。

P1-2 requires-python 落地 + init 脚本校验解释器版本

• 症状：03-tech-stack.md 要求「骨架须写死 requires-python=">=3.12,<3.14"，init 脚本校验解释器版本」。当前用 requirements.txt（表达不了 Python 版本约束），init.sh/init.ps1 只硬调 python3.12 / py -3.12 命令、无显式版本断言——换台机器解释器指向 3.13 或不存在时不会明确报错。文档一致性欠账。
• 位置：项目根（无 pyproject.toml）；init.sh 顶部；init.ps1 顶部。
• 怎么改（二选一，取轻——推荐 A）：
  • A（推荐，最小改动）：在 init.sh / init.ps1 安装依赖前加一步 Python 版本断言：解析解释器版本，若不在 >=3.12,<3.14 则打印错误并退出（非 0）。
  • B：新增 pyproject.toml 写 requires-python=">=3.12,<3.14"（仅在配合构建/安装工具时才强制，较重；若采用需同步 03-tech-stack.md 的依赖管理说明）。
• 验证：用非 3.12 解释器（或模拟）跑 init，应明确报错退出；用 3.12 正常走完安装 + check。

P2 · 规范性（趁早理顺）

P2-1 INSTALLED_APPS 顺序

• 症状：rest_framework 与 apps.* 排在整个 django.contrib.* 之前。APP_DIRS=True 下模板按 INSTALLED_APPS 顺序查找——将来 portal 做用户端模板时，本地 app 模板会优先于 admin，若不慎放了同名模板（如 admin/base_site.html）会意外覆盖后台。当前无模板，是潜在隐患。
• 位置：config/settings.py 的 INSTALLED_APPS。
• 怎么改：调整为 django.contrib.*（admin/auth/contenttypes/sessions/messages/staticfiles）在前 → rest_framework → apps.users|portal|billing|ai|api。
• 验证：check / test 仍全绿；/admin/ 正常。

P2-2 补 .env.example

• 症状：.gitignore 有 !.env.example 白名单，说明本应提供样例，但文件缺失；新人不知道要配哪些环境变量。
• 位置：项目根。
• 怎么改：新增 .env.example，列出 MYSQL_HOST/PORT/DATABASE/USER/PASSWORD/CHARSET、DJANGO_SECRET_KEY、DJANGO_DEBUG、DJANGO_ALLOWED_HOSTS 等键，值用占位符（不含任何真实值）。以 env.md 为准。
• 验证：git status 显示 .env.example 被跟踪（未被 .gitignore 忽略）。

P2-3 同步根 README.md 当前状态

• 症状：根 README.md 的「当前状态」仍停在 T-001 / 下一步 T-002，已落后于 T-003 完成后的现实状态。
• 位置：项目根 README.md。
• 怎么改：更新为 Phase 0 已完成、当前先做 T-004 修补、之后进入 T-101。
• 验证：README.md 与 docs/current-state.md 的下一步口径一致。

P3 · 后续任务处理（不在 T-004 范围，仅登记）

• REST_FRAMEWORK 认证配置：DEFAULT_AUTHENTICATION_CLASSES 等（对外 API 只认 Key 不认 session）——留给 T-301。
• sql_mode 完整性：init_command 仅 STRICT_TRANS_TABLES，会覆盖 MySQL 默认 sql_mode 其余项；对 InnoDB 防截断已够，可后续补 NO_ENGINE_SUBSTITUTION 等。
• 生产 SECRET_KEY 保护：DEBUG=False 且 SECRET_KEY 仍为默认 django-insecure-* 时应主动报错——留给部署任务 T-403。

四、说明：未本地复跑

审核机（WSL）无 python3.12，未本地复跑 check/test。本报告基于：静态审查（代码 + 迁移文件 + 配置）+ codex 的执行记录（记录含真实报错与修复过程：MySQL 授权、MySQL8 caching_sha2_password 需 cryptography，可信度高）。

T-004 修补后，请重跑 check / test / init，并把命令与结果记入 progress.md 作为证据（按 06-tasks.md 使用规则第 5 条）。

五、T-004 完成定义

• P1-1、P1-2、P2-1、P2-2、P2-3 全部处理（P1-1 若产品确认不需要则标注跳过）。
• check 0 issues、test 全绿、init 通过，证据入 progress.md。
• P3 各项已在 06-tasks.md 对应任务（T-301 / T-403）或 Backlog 有登记，不遗失。