lixi
1891d9b7b4
CI / docs-build (push) Successful in 1m3s
- iteration-2 报告 01-08（PM 拆解/后端/Flutter 评估/现实核查/UI 规范/埋点规划/证据基线/Git 规划），04、06 已由正式角色复核定稿 - mkdocs 挂「第二迭代」导航，build --strict 通过 - ADR-009 新建 patbond-pet 模块、ADR-010 照片剪出 M2、ADR-011 dev 主干/master 发布、ADR-012 北极星与 H1-H4、ADR-013 废弃 health_record_action、ADR-014 DEBT-1 随 M2、ADR-015 照护人邀请后置 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
199 lines
9.8 KiB
Markdown
199 lines
9.8 KiB
Markdown
# 07 第二迭代开工前：证据基线审计（Evidence Baseline Audit）
|
||
|
||
**审计人**：Evidence Collector
|
||
**审计日期**：2026-09-07
|
||
**审计范围**：第一迭代收官声称的证据链完整性 + M2 开工基线快照
|
||
**方法**：只读审计。每条结论附可复现命令与实际输出；本报告不重复运行测试套件（「现在还绿不绿」由 Reality Checker 独立验证），静态计数不等于运行结果。
|
||
|
||
---
|
||
|
||
## 0. 结论速览
|
||
|
||
| 声称 | 判定 | 证据 |
|
||
|---|---|---|
|
||
| 20 份报告入档并挂 mkdocs 导航 | ✅ 完全证实 | §1 |
|
||
| OpenAPI 契约正式化 | ⚠️ 部分证实（缺 `/api/v1/events`） | §2.1 |
|
||
| ADR-001~008 编号完整 | ✅ 完全证实 | §2.2 |
|
||
| 三仓提交完整、工作区干净 | ✅ 完全证实 | §3 |
|
||
| 后端 82 测试 | ✅ 静态计数一致（82 个 `@Test`） | §4.2 |
|
||
| 前端 34 测试 | ✅ 静态计数一致（34 个 `test/testWidgets`） | §4.2 |
|
||
| E2E 烟囱测试 7/7 | ✅ 有档案证据（报告 18 全量输出 + 脚本入库） | §5.3 |
|
||
| CI（Gitea Actions）全绿 | ❌ 本地不可证（无归档 run 日志） | §5.1 |
|
||
|
||
**证据链完整率：8 大类声称中 6 项完全证实、1 项部分证实、1 项本地不可证 ≈ 81%。**
|
||
**证据缺口：2 个**（详见 §5）。**基线快照：已建立**（§4）。
|
||
|
||
---
|
||
|
||
## 1. 证据链审计：20 份报告与导航
|
||
|
||
### 1.1 文件存在性
|
||
|
||
```bash
|
||
ls /home/lx/workspace/patbond/patbond-doc/docs/development/iterations/iteration-1/ | sort
|
||
```
|
||
|
||
实际输出：`01-pm-task-breakdown.md` 至 `20-iteration-1-summary.md` 共 20 份，外加 `index.md`（进展看板），**21 个文件全部存在，无缺失**。
|
||
|
||
### 1.2 mkdocs 导航
|
||
|
||
```bash
|
||
grep -c "iterations/iteration-1/" patbond-doc/mkdocs.yml
|
||
# 输出：21
|
||
```
|
||
|
||
逐条核对 mkdocs.yml 第 12~32 行：进展看板 + 01~20 报告共 21 条导航，与文件一一对应。**报告-导航映射完整率 100%。**
|
||
|
||
---
|
||
|
||
## 2. 契约档案审计
|
||
|
||
### 2.1 openapi.yaml 接口路径
|
||
|
||
```bash
|
||
grep -nE "^ /" patbond-doc/docs/api/openapi.yaml
|
||
```
|
||
|
||
实际输出（5 条路径）：
|
||
|
||
| # | 路径 | 行号 |
|
||
|---|---|---|
|
||
| 1 | `/api/v1/auth/register` | 54 |
|
||
| 2 | `/api/v1/auth/login` | 86 |
|
||
| 3 | `/api/v1/auth/refresh` | 126 |
|
||
| 4 | `/api/v1/auth/logout` | 159 |
|
||
| 5 | `/api/v1/me` | 188 |
|
||
|
||
与契约自述范围（`title: Patbond API — Auth & Me（第一批公开接口）`，`version: 1.0.0`）一致，也与 `docs/api/index.md` 声称的「5 个端点」一致。
|
||
|
||
**但与代码实际公开接口比对存在缺口**：
|
||
|
||
```bash
|
||
grep -rhoE '@(Get|Post)Mapping\("[^"]*"' patbond-api --include="*.java" | grep -v target | sort -u
|
||
```
|
||
|
||
代码中的公开接口为 `/api/v1/auth/{register,login,refresh,logout}`、`/api/v1/me`，以及 **`POST /api/v1/events`（埋点批量上报，报告 13/19 交付，提交 6d47c5a）——此接口未入 openapi.yaml**。`docs/api/index.md` 明文约定「契约变更须先改 OpenAPI，再改实现（契约先行）」，events 接口违反了这条自定约定。判定：**契约档案部分完整**，M2 开工前应补录（或明确声明 internal/events 不在公开契约范围并记录该决定）。
|
||
|
||
另核实：`/internal/users/*`、`/internal/sessions/*` 为服务间内部接口，不入公开契约属合理范围。openapi.yaml 本身未直接挂 mkdocs 导航，但导航条目「API → 契约说明（api/index.md）」内有指向 openapi.yaml 的链接，mkdocs 构建会连带发布该文件，可接受。
|
||
|
||
### 2.2 ADR 编号完整性
|
||
|
||
ADR 实际位于 `docs/architecture/decisions.md`（注意：不在 development/ 目录下）。
|
||
|
||
```bash
|
||
grep -nE "^#+ .*ADR-[0-9]+" patbond-doc/docs/architecture/decisions.md
|
||
```
|
||
|
||
实际输出：ADR-001（Spring Boot 3）、002（移除 Nacos）、003（Token 策略）、004（账号密码登录）、005（品牌色正典）、006（测试容器化）、007（部署形态）、008（PostgreSQL 18），行号 8/20/42/51/55/65/75/88。**001~008 连续无断号，判定完整。**
|
||
|
||
---
|
||
|
||
## 3. 提交完整性审计
|
||
|
||
命令：`git -C <repo> log --oneline -20`、`git status --short --branch`、`git rev-list --left-right --count HEAD...@{u}`（2026-09-07 执行）。
|
||
|
||
### 3.1 三仓状态
|
||
|
||
| 仓库 | 分支 | HEAD | 工作区 | 与 upstream 差异 |
|
||
|---|---|---|---|---|
|
||
| patbond-api | dev | `0d81c38` | 干净（porcelain 无输出） | 0 ahead / 0 behind |
|
||
| patbond-flutter | dev | `3f8388e` | 干净 | 0 ahead / 0 behind |
|
||
| patbond-doc | main | `5537f92` | 干净 | 0 ahead / 0 behind |
|
||
|
||
**未提交文件清单：三仓均为空。** 第一迭代收官时「仅 flutter 待提交」的遗留已闭环（flutter 现有 CI 门禁三提交 3f8388e/45f94d2/b0207c9 在 dev 且已推送）。
|
||
|
||
### 3.2 声称提交与 git 历史比对
|
||
|
||
第一迭代总结（报告 20）声称的关键提交均可在历史中找到实体：
|
||
|
||
- patbond-api：埋点接收端 `6d47c5a`、会话清理 `6528a06`、CI 工作流 `3f6e818` + 修复 `b38b0d8`/`0d81c38`、Compose `ab0265c`、JWT 纵切 `4dc3dcd`、Flyway baseline `bd20adc` ——全部在 dev 历史中。用户自有提交 `b22eaed update` 位于 `6528a06` 之后，属已知正常情况。
|
||
- patbond-flutter：埋点 `60d67a3`、登录纵切 `8d890c0`、主题迁移 `af002ed`、phone 可空修复 `845e92f`、锁定码映射 `da25804` ——齐全。
|
||
- patbond-doc：报告迁入 `209021e`、收官 `8e0e1c5`/`64521bf`、CI `f267141`/`5537f92`、ADR-007/008 入档 `b747e09`/`18746ce` ——齐全。
|
||
|
||
**判定：声称已提交的内容真实存在于 git 历史，无虚报。**
|
||
|
||
---
|
||
|
||
## 4. M2 开工基线快照（验收对比基准）
|
||
|
||
> M2 结束时以本节为基准做前后对比。所有数字均注明取证方式。
|
||
|
||
### 4.1 三仓 HEAD（完整哈希）
|
||
|
||
| 仓库 | 分支 | HEAD commit |
|
||
|---|---|---|
|
||
| patbond-api | dev | `0d81c38fc6f1ea5ede3ad93bef89046a67e818e5` |
|
||
| patbond-flutter | dev | `3f8388e5d4f6dfc9ddf832ed77ebae7e5463ece9` |
|
||
| patbond-doc | main | `5537f92227c0cbad812f83c4374e589afbb17cbc` |
|
||
|
||
### 4.2 测试数基线
|
||
|
||
**取证方式：静态注解计数（grep），非运行结果**；运行态验证以 Reality Checker 同期报告为准。
|
||
|
||
```bash
|
||
# 后端：82（与声称一致；无 @ParameterizedTest/@RepeatedTest）
|
||
grep -rE "@Test\b" patbond-api --include="*.java" | grep -v "/target/" | wc -l
|
||
# 分模块：patbond-auth 31 / patbond-common 3 / patbond-user 48
|
||
|
||
# 前端：34（与声称一致，8 个测试文件）
|
||
grep -rE "^\s*(test|testWidgets)\(" patbond-flutter/test --include="*.dart" | wc -l
|
||
```
|
||
|
||
| 端 | 基线值 | 来源 |
|
||
|---|---|---|
|
||
| 后端测试 | **82**（auth 31 + common 3 + user 48） | 静态计数，与报告 20 声称一致 |
|
||
| 前端测试 | **34**（8 个 `*_test.dart`） | 静态计数，与报告 20 声称一致 |
|
||
| E2E 烟囱 | **7/7**（声称值） | 报告 18 归档输出，本次未重跑 |
|
||
|
||
前端测试文件清单：`test/analytics/analytics_service_test.dart`、`test/core/network/token_refresher_test.dart`、`test/core/widgets/app_text_field_test.dart`、`test/core/widgets/primary_button_test.dart`、`test/features/auth/{auth_repository,login_page,register_page}_test.dart`、`test/widget_test.dart`。
|
||
|
||
### 4.3 OpenAPI 接口基线
|
||
|
||
`patbond-doc/docs/api/openapi.yaml`（OpenAPI 3.0.3，version 1.0.0）共 **5 条路径**：`/api/v1/auth/register`、`/api/v1/auth/login`、`/api/v1/auth/refresh`、`/api/v1/auth/logout`、`/api/v1/me`。代码另有公开接口 `POST /api/v1/events` 未入契约（见 §5 缺口 1）。
|
||
|
||
### 4.4 Flyway 迁移基线
|
||
|
||
```bash
|
||
find patbond-api -path "*src/main*db/migration*" -name "*.sql" | sort
|
||
```
|
||
|
||
| 版本 | 文件（patbond-user 模块） |
|
||
|---|---|
|
||
| V1 | `V1__identity_media_baseline.sql` |
|
||
| V2 | `V2__create_platform_product_events.sql` |
|
||
|
||
**M2 的健康档案表迁移应从 V3 起编号。**
|
||
|
||
### 4.5 CI 与其他基线
|
||
|
||
- 三仓均存在 `.gitea/workflows/ci.yml`（api 2705B / flutter 2362B / doc 1038B），随 HEAD 入库。
|
||
- ADR 基线：ADR-001~008；M2 新决策从 ADR-009 起。
|
||
- E2E 脚本 `test_e2e_manual.dart` 已入 patbond-flutter git 追踪（位于仓库根目录而非 test/，见 §5 备注）。
|
||
|
||
---
|
||
|
||
## 5. 证据缺口清单
|
||
|
||
### 缺口 1（中）：`POST /api/v1/events` 未入 OpenAPI 契约
|
||
|
||
- **声称**：「OpenAPI 契约正式化」（报告 20）；`api/index.md` 约定契约先行。
|
||
- **现实**：契约仅覆盖 Auth & Me 5 端点；events 为已上线公开接口（提交 6d47c5a）但契约中不存在。
|
||
- **建议**：M2 第一波补录 events 到 openapi.yaml，或以 ADR/契约说明明文排除并给出理由。
|
||
|
||
### 缺口 2（中）：CI「全绿」无本地可复现证据
|
||
|
||
- **声称**：报告 20「ci.yml #6 全绿 3m18s」（细节具体，可信度中上）。
|
||
- **现实**：run 日志/截图未归档入 patbond-doc，本审计在本地仅能证实 ci.yml 文件存在，无法证实运行结果；需登录 Gitea 实例查看 Actions 页面方可复核。
|
||
- **建议**：后续迭代收官时将关键 CI run 的结论页截图或日志摘要归档入迭代报告，使该声称离线可验。
|
||
|
||
### 备注（低，非缺口）
|
||
|
||
1. ADR 实际路径为 `docs/architecture/decisions.md` 而非 development/ 下——引用时注意路径，内容本身完整。
|
||
2. `test_e2e_manual.dart` 放在 patbond-flutter 仓库根目录，不在 test/ 目录、不被 `flutter test` 纳入——属工程卫生问题，M2 可顺手归位。
|
||
3. openapi.yaml 未单列 mkdocs 导航，经 `api/index.md` 链接可达，可接受。
|
||
4. 本报告写入的 iteration-2 目录尚未挂 mkdocs 导航（本审计按约束不改 mkdocs.yml），待 doc 维护者统一挂载。
|
||
|
||
---
|
||
|
||
**结论**：第一迭代档案质量整体扎实——报告、导航、ADR、git 历史四条证据链均经实证核对无虚报；测试数静态计数与声称精确一致。两个缺口（events 契约缺录、CI 结果不可离线复核）均为可修补的档案问题，不阻塞 M2 开工。基线快照（§4）自本日起生效，M2 验收时据此对比。
|