docs(xingbang): 适配项目开发流程并建立经验驱动预审新版文档

2026-09-28 17:02:33 +08:00
parent 4d5a420671
commit 9d2399feed
26 changed files with 1164 additions and 266 deletions
@@ -16,7 +16,7 @@
 - [ ] 每个实质改动映射到最小且覆盖它的项目检查（单测/契约/集成/E2E/视觉/迁移/打包之一），并在最后一次编辑后运行
 - [ ] 验证失败按"复现 → 定位（可归因的诊断）→ 因果假设 → 最小 owner 修复"链处理；重试不加诊断 ≠ 修复证据
 - [ ] 修复后在最终状态上**重跑同一检查**（或记录等价性理由）
- [ ] 评审（dk-review 四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项
+- [ ] 评审（正确性/一致性/安全/测试四维）完成：正确性/一致性/安全/测试，无未解决的阻塞项
 - [ ] 门禁结果与最终修订绑定（不是"跑过"而是"这个 revision 过了"）

 ---
@@ -62,22 +62,22 @@
 残余风险：    未覆盖范围、跳过守卫的用例、需人工确认项
 ```

-### 3.2 验证分层建议（本仓）
+### 3.2 验证分层与实际入口

 | 层 | 内容 | 触发 |
 |---|---|---|
-| L0 静态 | typecheck（`npm run typecheck`：tsc --noEmit + 双 tsconfig） | 每次提交 |
-| L1 单测 | 组件/工具/逻辑（vitest，colocated `*.test.ts`，`npm test`） | 每次提交 |
-| L2 契约/守卫 | 跨进程契约对齐（`src/main/ipc-alignment.test.ts`）、迁移守卫（`migrations.test.ts`）、架构守卫（`architecture-guardrails.test.ts`）、docs 基线 | 触碰共享层/迁移 |
-| L3 集成 | 主进程+渲染、宿主装配 | 主链路 |
-| L4 E2E | `npm run test:e2e`（playwright，需先构建） | 关键用户流/发布前 |
-| L5 打包冒烟 | `build/ci-local.ps1`（Windows）/ `build/ci-local.sh`（macOS/Linux）：干净安装+全量门禁+安装包+启动冒烟 | 发布前 |
+| L0 静态 | git diff --check；npm run build包含类型检查；文档链接/编号/事实检查 | 对应改动后 |
+| L1 单测 | 在backend工作目录用其venv执行python -m unittest discover -s . -p test_*.py -v；建议由verify统一执行 | 后端行为修改 |
+| L2 契约/守卫 | backend/test_assistant_components.py等已有测试与scripts/test_*.cjs；按新契约增加反例 | 契约/权限/页面规则修改 |
+| L3 集成 | API + services + 临时测试数据库/fixtures，禁依赖真实客户库 | 主链路 |
+| L4 E2E | 真实浏览器按本批用例操作并断言，记录实际入口/环境；当前未确认统一E2E套件 | 关键用户流 |
+| L5 打包冒烟 | Docker Compose config；获授权后独立资源上运行verify.py --docker，另做目标环境验收 | 发布前 |

-> 本仓测试体系单一事实源：`docs/architecture/testing-architecture.md`；E2E 执行线见 `docs/e2e/e2e-architecture-and-automation.md`。验证要求按此落地，发现矩阵缺口在阶段 ⑧ 反馈。
+> 实际总入口为 `scripts/verify.py`：项目backend/venv执行，日志在test-evidence。当前没有package.json中的typecheck、test或test:e2e脚本，不得写成已执行。新版测试规划见 [v2验证](../v2/06-validation.md)。行为修改必须跑总入口，纯文档可用相关链接/编号/路径/diff检查。

 ### 3.3 交付物清单
 - 验证记录（含失败→修复→复验链）
- 审查结论（dk-review 输出，阻塞项清零）
+- 审查结论（四维逐项记录；独立评审未完成须说明，不能自称已获他人批准）
 - 测试覆盖增量说明（新增测试对应的 AC/BR/E）

 ---
@@ -94,7 +94,7 @@

 ## 5. 轻量路径（小改动）

- 一行修复：对应单测 + 全量 typecheck + 该模块相关测试，记录即可。
+- 小行为修复：对应测试 + scripts/verify.py，保留完整日志；纯文档：链接、编号、事实与diff检查。
 - 任何改动都不得跳过 R-6.3/R-6.4（诊断与复验）与 R-6.7（门禁）。

 ---
@@ -104,3 +104,5 @@
 - 输入：阶段 ⑤ [05-implementation.md](05-implementation.md)、规格 [01-requirement.md](01-requirement.md) 的 AC
 - UI 验证细则：阶段 ④ [04-ui-spec.md](04-ui-spec.md) §4
 - 通过后进入：阶段 ⑦ [07-delivery.md](07-delivery.md)
+
+变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。