304 lines
8.1 KiB
Markdown
304 lines
8.1 KiB
Markdown
# Phase 0 评审
|
||
|
||
> 评审日期：2026-07-06
|
||
> 评审视角：全栈开发工程师
|
||
> 评审范围：T-000 至 T-003 的文档、项目骨架、环境配置、启动脚本和验证基线。
|
||
|
||
## 结论
|
||
|
||
Phase 0 尚未完全达标。
|
||
|
||
2026-07-06 复查 DeepSeek 修复后，4 个原始问题中：
|
||
|
||
| 问题 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| `init.sh` / venv 与标准 bash 环境不匹配 | 未达标 | `init.sh` 仍调用不存在的 `.venv/bin/pip3.12` / `.venv/bin/python3.12` |
|
||
| production settings 缺少强制 `SECRET_KEY` | 已达标 | 缺少 `SECRET_KEY` 时会 fail fast；合法环境变量可正常读取 |
|
||
| 当前状态文档过期和自相矛盾 | 未达标 | `AGENTS.md`、`docs/current-state.md` 仍混用 WSL/bash 与 MSYS2 命令，且命令不可运行 |
|
||
| `.env.example` 说明容易误导 | 已达标 | 已说明 `.env` 不会自动加载，需要通过 shell / systemd / hosting environment 注入 |
|
||
|
||
因此当前仍不能进入 Phase 1。
|
||
|
||
Wagtail / Django 项目骨架、Python 3.12 venv、SQLite 数据库、依赖 pin、基础测试和 `manage.py check` / `manage.py test` 基线基本可用。但标准入口 `init.sh` 在仓库规定的 bash / WSL 环境下失败，这是阻断项。
|
||
|
||
在继续 Phase 1 前，建议先修复：
|
||
|
||
1. `init.sh` / venv 与标准 bash 环境不匹配。
|
||
2. production settings 缺少强制 `SECRET_KEY`。
|
||
3. 当前状态文档存在过期和自相矛盾内容。
|
||
|
||
## 主要问题
|
||
|
||
### 1. High：标准启动入口 `init.sh` 在 bash 下不可用
|
||
|
||
**复查状态：未达标。**
|
||
|
||
仓库规则规定标准环境是 WSL2 / Linux + bash，且 `init.sh` 是标准启动与验证入口：
|
||
|
||
- `AGENTS.md`：标准开发环境是 WSL2 / Linux。
|
||
- `AGENTS.md`：`init.sh` 是标准启动与验证入口。
|
||
|
||
但当前 `init.sh` 调用：
|
||
|
||
```bash
|
||
.venv/bin/pip install -r requirements.txt
|
||
.venv/bin/python manage.py check
|
||
```
|
||
|
||
实际 `.venv/bin/` 下只有 Windows / MSYS2 风格可执行文件：
|
||
|
||
```text
|
||
pip.exe
|
||
python.exe
|
||
python3.12.exe
|
||
```
|
||
|
||
没有：
|
||
|
||
```text
|
||
.venv/bin/pip
|
||
.venv/bin/python
|
||
```
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
bash -lc './init.sh'
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
./init.sh: line 20: .venv/bin/pip: No such file or directory
|
||
```
|
||
|
||
这会导致每轮开工流程中的“运行标准验证”失败，因此 T-001 / T-003 的标准入口验收不能算通过。
|
||
|
||
建议修复：
|
||
|
||
- 优先按 WSL / Linux 重新创建 `.venv`，确保 `.venv/bin/python` 和 `.venv/bin/pip` 存在。
|
||
- 或者正式修改项目开发环境决策为 MSYS2，但这会偏离当前仓库文档，不建议。
|
||
|
||
2026-07-06 复查结果：
|
||
|
||
`init.sh` 已改为调用：
|
||
|
||
```bash
|
||
.venv/bin/pip3.12
|
||
.venv/bin/python3.12
|
||
```
|
||
|
||
但实际 `.venv/bin/` 下仍只有：
|
||
|
||
```text
|
||
pip3.12.exe
|
||
python3.12.exe
|
||
```
|
||
|
||
脚本虽然检查了 `.exe` 是否存在，但执行命令时仍使用无后缀路径。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
bash -lc './init.sh'
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
./init.sh: line 28: .venv/bin/pip3.12: No such file or directory
|
||
```
|
||
|
||
手动执行文档中的标准命令也失败：
|
||
|
||
```bash
|
||
bash -lc '.venv/bin/python3.12 manage.py check'
|
||
```
|
||
|
||
结果：
|
||
|
||
```text
|
||
/bin/bash: .venv/bin/python3.12: No such file or directory
|
||
```
|
||
|
||
### 2. High：production settings 会回退到开发 `SECRET_KEY`
|
||
|
||
**复查状态：已达标。**
|
||
|
||
当前 `skelet/settings/base.py` 中：
|
||
|
||
```python
|
||
SECRET_KEY = os.environ.get("SECRET_KEY", "django-insecure-dev-key-change-me")
|
||
```
|
||
|
||
`skelet/settings/production.py` 没有覆盖或强制校验 `SECRET_KEY`。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
DJANGO_SETTINGS_MODULE=skelet.settings.production .venv/bin/python manage.py check --deploy
|
||
```
|
||
|
||
结果包含：
|
||
|
||
```text
|
||
security.W009: Your SECRET_KEY has less than 50 characters, less than 5 unique characters, or it's prefixed with 'django-insecure-'
|
||
```
|
||
|
||
进一步读取 settings，生产配置实际值仍为：
|
||
|
||
```text
|
||
DEBUG False
|
||
SECRET_KEY django-insecure-dev-key-change-me
|
||
ALLOWED_HOSTS ['']
|
||
```
|
||
|
||
这不是 Phase 0 本地开发的直接阻断项，但它是上线前安全风险。既然 T-002 已经涉及基础配置与环境样例，应尽早改成 production 缺少 `SECRET_KEY` 时 fail fast。
|
||
|
||
建议修复：
|
||
|
||
- 在 `production.py` 中强制读取 `SECRET_KEY`。
|
||
- 缺少或仍为开发默认值时抛出 `ImproperlyConfigured`。
|
||
- 同时清理 `ALLOWED_HOSTS=['']` 的空字符串问题。
|
||
|
||
2026-07-06 复查结果：
|
||
|
||
`skelet/settings/production.py` 已改为：
|
||
|
||
- 缺少 `SECRET_KEY` 或仍以 `django-insecure-` 开头时抛出 `ImproperlyConfigured`。
|
||
- `ALLOWED_HOSTS` 会过滤空字符串。
|
||
|
||
验证命令：
|
||
|
||
```bash
|
||
DJANGO_SETTINGS_MODULE=skelet.settings.production .venv/bin/python3.12.exe manage.py check --deploy
|
||
```
|
||
|
||
在未设置 `SECRET_KEY` 时，结果为预期失败：
|
||
|
||
```text
|
||
django.core.exceptions.ImproperlyConfigured: SECRET_KEY 环境变量缺失或仍为开发默认值。
|
||
```
|
||
|
||
设置合法环境变量后读取结果：
|
||
|
||
```text
|
||
DEBUG False
|
||
ALLOWED_HOSTS ['example.com', 'www.example.com']
|
||
```
|
||
|
||
原 `security.W009` 风险已消除。剩余 `SECURE_HSTS_SECONDS`、`SECURE_SSL_REDIRECT` 警告属于上线前 HTTPS 策略，不是本项原问题。
|
||
|
||
### 3. Medium：当前状态文档存在过期和自相矛盾内容
|
||
|
||
**复查状态：未达标。**
|
||
|
||
`AGENTS.md` 仍写：
|
||
|
||
```text
|
||
当前仓库处于 harness 文档初始化阶段，生产代码尚未初始化。
|
||
下一步 ... T-001
|
||
```
|
||
|
||
但任务看板中 Phase 0 已标为 DONE，实际代码也已初始化。
|
||
|
||
`docs/current-state.md` 中也存在矛盾：
|
||
|
||
```text
|
||
当前 blocker：无；下一步执行 T-002
|
||
```
|
||
|
||
同一文件后文又写：
|
||
|
||
```text
|
||
已完成：T-000、T-001、T-002、T-003
|
||
下一个可领取任务：T-101
|
||
```
|
||
|
||
这会误导后续 agent 的任务领取流程。
|
||
|
||
建议修复：
|
||
|
||
- 更新 `AGENTS.md` 当前阶段和下一步任务。
|
||
- 更新 `docs/current-state.md` 当前 blocker / 下一步，使其与 `docs/06-tasks.md` 一致。
|
||
|
||
2026-07-06 复查结果：
|
||
|
||
部分已修复：
|
||
|
||
- `AGENTS.md` 已改为 Phase 0 已完成，下一步 T-101。
|
||
- `docs/current-state.md` 的下一步已改为 T-101。
|
||
|
||
但仍有未达标内容：
|
||
|
||
- `AGENTS.md` 仍声明标准环境是 WSL2 / Linux + bash。
|
||
- `AGENTS.md` 验证命令仍写 `.venv/bin/python3.12 manage.py check`，但该命令在 bash 下不可运行。
|
||
- `docs/current-state.md` 仍写开发环境为 MSYS2/MinGW，并写“标准开发命令（在 MSYS2 bash 中运行）”。
|
||
- `docs/current-state.md` 的命令仍为 `.venv/bin/python manage.py check`，实际不存在 `.venv/bin/python`。
|
||
|
||
因此文档仍会误导后续 agent。
|
||
|
||
### 4. Low：`.env.example` 说明容易误导
|
||
|
||
**复查状态：已达标。**
|
||
|
||
`.env.example` 写：
|
||
|
||
```text
|
||
复制为 .env 并填入真实值
|
||
```
|
||
|
||
但当前项目没有加载 `.env` 的代码，也没有 `python-dotenv` 依赖。用户只复制 `.env` 并不会自动影响 Django settings。
|
||
|
||
建议二选一：
|
||
|
||
- 接入 dotenv，并明确加载路径。
|
||
- 或者修改说明，写明这些变量需要通过 shell / systemd / hosting environment 注入。
|
||
|
||
2026-07-06 复查结果：
|
||
|
||
`.env.example` 已明确说明：
|
||
|
||
- 本文件不直接加载到 Django settings。
|
||
- 部署时需通过 shell、systemd、托管平台或 Docker 注入环境变量。
|
||
- 真实 `.env` 被 `.gitignore` 忽略。
|
||
|
||
该项已达标。
|
||
|
||
## 已通过项
|
||
|
||
以下内容经检查或命令验证通过：
|
||
|
||
```bash
|
||
.venv/bin/python --version
|
||
# Python 3.12.12
|
||
|
||
.venv/bin/python manage.py check
|
||
# 0 errors，3 个 treebeard 兼容 warning
|
||
|
||
.venv/bin/python manage.py test
|
||
# 5 tests passed
|
||
```
|
||
|
||
其他通过项：
|
||
|
||
- Wagtail / Django 项目骨架已生成。
|
||
- `manage.py`、`skelet/`、`home/`、`search/`、`core/` 已存在。
|
||
- SQLite 数据库已 migrate。
|
||
- `requirements.txt` 已精确 pin 依赖版本。
|
||
- `home/tests.py` 有 smoke test，访问 `/` 返回 200。
|
||
- `.gitignore` 已忽略 `.venv/`、`db.sqlite3`、`media/`、`.env`、`deploy/` 和 `*.pem`。
|
||
- 当前 git 工作区干净。
|
||
|
||
## 是否允许进入 Phase 1
|
||
|
||
不建议直接进入 Phase 1。
|
||
|
||
最低修复门槛：
|
||
|
||
1. 修复 `init.sh`，确保在标准 bash / WSL 环境下可运行。
|
||
2. 修复 production `SECRET_KEY` 默认值风险。
|
||
3. 同步 `AGENTS.md` 和 `docs/current-state.md`，确保下一步任务明确为 T-101。
|
||
|
||
当前仍未满足最低修复门槛中的第 1 项和第 3 项。完成后，Phase 0 才可以视为达标，再进入 T-101。
|