From 4118efd0cacd3cf0227575c05b2159fe708a4f5c Mon Sep 17 00:00:00 2001 From: jianghaifeng Date: Sat, 17 Oct 2026 14:17:17 +0800 Subject: [PATCH] =?UTF-8?q?docs(inbox):=20=E6=8C=89=20specs=20=E8=A1=A5?= =?UTF-8?q?=E5=85=A8=20K2=20=E6=89=A7=E8=A1=8C=E8=A7=84=E8=8C=83=E4=B8=8E?= =?UTF-8?q?=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/plans/INBOX.md | 32 +++++++++++++++++++++++++++----- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md index 94c5b40..8e42479 100644 --- a/docs/plans/INBOX.md +++ b/docs/plans/INBOX.md @@ -15,7 +15,7 @@ > 6. **禅道同步**：任务「开始/完成」时同步更新禅道任务状态。 > 7. **验收归用户**：每批做完**停在干净交接点**，由用户亲自验证；回执必须含「用户可照做的验证步骤 + 每步预期结果」。 > 8. **门禁（不达标不提交）**：后端 = `mvn test` 全过（核心接口须有契约测试）；Web = `pnpm build:pro` 通过 + eslint 零错误；Flutter = `dart analyze lib test` 零告警 + `flutter test` 全过。 -> 9. **分支**：在 `develop` 提交并 `git push origin develop`；**绝不动 `main`**（dev→main 走 PR，由用户操作）。 +> 9. **分支（按 `GIT_WORKFLOW.md`）**：从 `develop` 拉 `feature/<模块>-<简述>`，小步提交；完成后 `git checkout develop && git merge --no-ff feature/...` 再 `git push origin develop`；**绝不动 `main`**（dev→main 走 PR，由用户操作）。 > 10. **设备验证必须「设备侧取证」（2026-10-16 新增，血的教训）**：真机 / 模拟器 / 小程序等目标设备的验证，**证据必须产自设备侧**（设备侧集成测试、设备日志、设备截图、设备侧抓到的连接）。**禁止**用"在开发机上 `curl` 某地址返回 200"证明设备可达 —— 本机 curl 本机网卡地址必然 200，这是**假阳性**（已实际误导过一次：`10.157.242.1` 是开发机 VPN 网卡地址，手机根本不可达，导致真机「剧目列表加载失败」）。**拿不到设备侧证据的，一律标「未验证」**，不得写成"已验证"。 --- @@ -28,6 +28,25 @@ > 规范以 specs 为准（`docs/plans/codex-研发任务清单.md` 阶段 A3/A5、`docs/16-测试用例库.md` CONTENT/RECORD、`docs/09-测试计划.md`）； > 接口只认 `FruitServer/docs/api-phase1.md` §1.3 / §1.5 / §1.6，**契约里没有的接口一律不许自造**。 +### 〇、开工前必读（按 specs 顺序，缺一不可） + +1. `AGENTS.md`（项目上下文、强制约束、自主执行与沟通节奏） +2. `CODING_STANDARDS.md`（三端红线、Dart/Flutter 专章、门禁总表） +3. `GIT_WORKFLOW.md`（Git Flow、提交格式、审查门槛） +4. `FruitServer/docs/api-phase1.md` §0 / §1.3 / §1.5 / §1.6（接口唯一权威） +5. `docs/plans/codex-研发任务清单.md`（A3/A5）、`docs/16-测试用例库.md`（CONTENT/RECORD）、`docs/09-测试计划.md` +6. 本 INBOX 条目 + +**硬性执行口径（摘自上述规范，违反即打回）** + +- **Git**：从 `develop` 拉 `feature/flutter-k2-library` 开发；提交信息 `type(scope): 描述`（`type` ∈ feat/fix/docs/test/refactor/style/perf/chore，≤50 字符，一个 commit 只做一件事）；完成后 `git merge --no-ff` 回 `develop` 再 push；**禁止直接改 `main`**；只 `git add` 自己的文件，禁止 `git add -A`/`.`。 +- **TDD**：先写测试（红灯）→ 实现（绿灯）→ 重构；测试命名 `should_<期望>_when_<条件>`；核心类（repository/service/logic）必配 `*_test.dart`。 +- **Dart**：`provider` binding/logic/view 三层；`dio`；全程 `async/await`，**禁裸 `then()`**；IO 失败用结果对象/控制器错误字段承接，**不把异常直接抛到 UI**；禁止空 catch。 +- **代码规模**：函数 ≤50 行、参数 ≤5、类 ≤300 行、单文件 ≤500 行、嵌套 ≤4 层、圈复杂度 ≤10；除 `0/1/-1/null/空串/布尔` 外禁止魔法值。 +- **注释**：每个 public 类/方法必须有文档注释；文件头写一行中文职责；新文件首行 `// Author: fruit.com.cn`；代码/注释/提交信息**不得出现任何 AI 痕迹**。 +- **留痕**：每步「叙述 + 工具命令 + 原始输出 + 解读」，追加到 `docs/plans/PROGRESS.md`；做前先写 `docs/plans/2026-10-17-K2.md`（步骤/影响文件/风险/待确认）。 +- **l10n 生成物**（`lib/l10n/app_localizations*.dart`）豁免作者头，但 `.arb` 必须手写三份。 + ### 一、PM 已勘察的现状（实测，直接用） - `ReelShort`（`develop` `00280ca`）已接：`/app/home/feed`、`/app/discover/feed`、`/app/dramas/{id}`、`/app/episodes/{id}/play`、`/app/watch/progress`（POST/GET）、`/app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`/app/favorites`（toggle/list/delete）、账号 4 个接口。 @@ -105,13 +124,16 @@ ### 四、门禁（不达标不提交） 1. `dart analyze lib test` **零告警**；`flutter test` **全过**（存量 33 个测试文件不得跑红）。 -2. 新增测试至少覆盖：分类→section 映射（含无分区空态）、记录页 N+1 详情请求去重/并发上限/单条失败降级、删除与清空回滚、收藏取消回滚、下载策略/授权列表渲染、未登录 AuthGate。 -3. **真机/设备侧验证由用户执行**（红线 7、10）：回执里给"用户可照做的步骤 + 每步预期结果"，**禁止用开发机 `curl` 冒充设备可达**；拿不到设备证据就标「未验证」。 -4. 在 `ReelShort` **`develop`** 提交并 `git push origin develop`；**不动 `main`**。 +2. `flutter build apk --debug` 通过（CODING_STANDARDS §6 门禁总表含构建）；若本机缺 Android SDK，回执里贴失败原始输出并标「未验证」，不得静默跳过。 +3. 新增测试至少覆盖：分类→section 映射（含无分区空态）、记录页 N+1 详情请求去重/并发上限/单条失败降级、删除与清空回滚、收藏取消回滚、下载策略/授权列表渲染、未登录 AuthGate；核心类覆盖率 ≥80%。 +4. **真机/设备侧验证由用户执行**（红线 7、10）：回执里给"用户可照做的步骤 + 每步预期结果"，**禁止用开发机 `curl` 冒充设备可达**；拿不到设备证据就标「未验证」。 +5. Git：`feature/flutter-k2-library` 开发 → `git merge --no-ff` 回 `develop` → `git push origin develop`；**不动 `main`**；合并/推送前再跑一次门禁。 ### 五、节奏与留痕 -- 先写 `FruitServer/docs/plans/2026-10-17-K2.md`：范围、影响文件清单、上述 3 个契约缺口、风险。 +- 先写 `FruitServer/docs/plans/2026-10-17-K2.md`：范围、影响文件清单、上述 3 个契约缺口、风险、待确认。 +- **TDD 节奏**：每块先写测试（红灯）→ 实现（绿灯）→ 重构；每完成一个模块跑一次门禁，零告警才继续。 +- 每步在公司 `PROGRESS.md` 追加「叙述 + 命令 + 原始输出 + 解读」（PM 验收口径，缺一即打回）。 - 做完**停下写回执**（追加到 `docs/plans/PROGRESS.md` + 本条下），回执必须含： - 哪些页面已走真数据、哪些仍是本地/未做； - 用户可照做的验证步骤与每步预期；