docs(ops): claim and audit docgov optional-duty null FK fix

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 06:08:35 +00:00
parent fa2407f92c
commit 149dec8993
4 changed files with 115 additions and 2 deletions
@@ -0,0 +1,53 @@
+---
+title: "可选职责空审核人 CreateOrGetDocument 写 reviewer_id=0 触发 FK"
+status: done
+created: 2026-09-17
+updated: 2026-09-17
+severity: high
+---
+
+# 可选职责空审核人 CreateOrGetDocument 写 reviewer_id=0 触发 FK
+
+## 现象
+
+dev 项目「内廷元无创神经刺激器」(6417) 发起 `intake` 任务后 UI 显示：
+
+- `code: INTERNAL_ERROR`
+- `userMessage: 系统内部错误，请重新开始会话`
+- `requestId: run_1789622069585300787`
+- `sessionId: sess-p6417-u9`
+
+浏览器偶发 `flushSync was called from inside a lifecycle method`（错误态重渲染副作用，非根因）。
+
+## 根因分析
+
+1. app-dev 日志：`persist document ledger: ... document_records_reviewer_id_fkey (SQLSTATE 23503)`
+2. 项目成员仅 `document_duty=author`（user 9），无 reviewer/approver
+3. `resolveTaskDocumentDuties` 合法返回 `ReviewerID=0`
+4. [`internal/docgov/engine.go`](../../internal/docgov/engine.go) `CreateOrGetDocument` 把 `0` 写入可空 FK，PG 拒绝（无 `users.id=0`）
+5. `ClassifyError` 默认分支掩盖为 `INTERNAL_ERROR`
+
+对照：[`internal/docduty/store.go`](../../internal/docduty/store.go) heal 路径已有 `nullIfZero`，**创建路径漏改**。
+
+复现：`INSERT ... reviewer_id=0` → 同 FK 错误。近 7 天同因至少 3 次（6417/6359/6274）。
+
+## 严重度
+
+`high`（任何无 reviewer 职责的项目首次落文档账本均会失败；可扩散至 test/main）
+
+## 关联整改
+
+- Short-term: [../ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md](../ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md)
+- Fix branch: `fix/docgov-optional-duty-null-fk`
+
+## 证据
+
+- `docker logs shuimu-agent-app-dev` @ `2026-09-17T05:14:29Z` run_1789622069585300787
+- `task_runs.error_message` 与上述一致；`document_records` 对 project 6417 为 0 行
+- 手工 `INSERT reviewer_id=0` → `Key (reviewer_id)=(0) is not present in table "users"`
+
+## 后续
+
+- 创建路径 0→NULL；ClassifyError 增加 `DOC_LEDGER_ERROR`
+- 不强制配置 reviewer（保持可选职责语义）
+- flushSync 另开任务
@@ -13,6 +13,14 @@

 ## 核心文档（按阅读顺序推荐）

+### 可选职责空审核人 CreateOrGetDocument FK（2026-09-17）
+
+**文件**: [2026-09-17-docgov-optional-duty-null-fk.md](./2026-09-17-docgov-optional-duty-null-fk.md)
+
+**结论**: 无 reviewer 职责时 `CreateOrGetDocument` 写 `reviewer_id=0` 触发 FK，被 `ClassifyError` 掩盖为 `INTERNAL_ERROR`；heal 路径已有 `nullIfZero`，创建路径漏改。
+
+**整改**: [short-term](../ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md) · branch `fix/docgov-optional-duty-null-fk`
+
 ### FEATURE-MATRIX production-ready 连续性审计（2026-09-16）

 **文件**: [2026-09-16-feature-matrix-production-readiness-audit.md](./2026-09-16-feature-matrix-production-readiness-audit.md)
@@ -5,14 +5,15 @@

 ## 焦点

-1. **partial/deferred 全量收口**：W1–W4 **done**；W5a **done**（矩阵自举行仍 partial）；W6 **shadow done**（矩阵 FAV 仍 partial）；W7 **盘点 done**（矩阵 D7 仍 deferred）。晋升 `test`：`rc-v1.0.0-beta.3`
-2. **运维**：nightly `DATA_DIR=dev` 已对齐；KB 宿主机分层加载 / fail-closed **done**（`fix/kb-host-auth-layered-load`）
+1. **fix/docgov-optional-duty-null-fk**：可选职责空审核人写 `reviewer_id=0` 触发 FK → `INTERNAL_ERROR`（项目 6417）；创建路径 0→NULL + `DOC_LEDGER_ERROR`
+2. **partial/deferred 全量收口**：W1–W4 **done**；W5a **done**（矩阵自举行仍 partial）；W6 **shadow done**（矩阵 FAV 仍 partial）；W7 **盘点 done**（矩阵 D7 仍 deferred）。晋升 `test`：`rc-v1.0.0-beta.3`
 3. **红线**：禁止整支 merge FAV；不默认升 `MULTI_INTENT_PLAN_TIER=full`（升 `confirm` 须 W4 闭环后独立授权）；`SEMANTIC_SUMMARY_REPLACE` 不随 W2 开启；FAV live 顺序 staging→artifact→publication、每级观察窗证据驱动（下限 ≥7 天）、`FAV_DEGRADED_READ=false`；flag 默认 off；项目 143 只读

 ## 并行认领

 | owner | task | branch | worktree | mutex | status |
 |-------|------|--------|----------|-------|--------|
+| Cursor | 2026-09-17-docgov-optional-duty-null-fk | fix/docgov-optional-duty-null-fk | - | docgov | in_progress |
 | Cursor | 2026-09-17-leftover-hygiene | chore/leftover-hygiene-2026-09-17 | - | ops | done |
 | Cursor | 2026-09-17-w2-semantic-summary-shadow | feature/w2-semantic-summary-shadow-live | - | chat | done |
 | Cursor | 2026-09-17-w3-pi-change-report-narrative | feature/w3-pi-change-report-narrative-live | - | docgov | done |
@@ -0,0 +1,51 @@
+---
+title: "修复 CreateOrGetDocument 可选职责 0→NULL FK"
+status: in_progress
+created: 2026-09-17
+updated: 2026-09-17
+owner: Cursor
+branch: fix/docgov-optional-duty-null-fk
+worktree: "-"
+mutex: docgov
+---
+
+# 修复 CreateOrGetDocument 可选职责 0→NULL FK
+
+## 目标
+
+无 reviewer/approver 职责时创建文档账本成功，不再因 `reviewer_id=0` FK 失败并被标成 `INTERNAL_ERROR`。
+
+## 范围
+
+- `internal/docgov/engine.go`：`nullIfZero` 写入 author/reviewer/approver
+- `internal/stream/classify.go`：`DOC_LEDGER_ERROR` 分型
+- 回归测试 + audit/test-report
+
+## 非目标
+
+- 不强制项目配置 reviewer
+- 不改前端 flushSync / 虚拟列表
+- 不改项目 6417 存量数据（代码修好后重试即可）
+
+## 步骤
+
+1. [x] CreateOrGetDocument 0→NULL
+2. [x] ClassifyError `DOC_LEDGER_ERROR`
+3. [x] 单元/回归测试（`-short` 已绿）
+4. [ ] 占集成槽位 rebuild + 6417 或等价复测
+5. [ ] test-report 归档；合入 `dev`
+
+## 验收标准
+
+- [ ] `go test -short ./internal/docgov/... ./internal/stream/...` PASS
+- [ ] 仅-author 项目 `CreateOrGetDocument` / 任务发起不再 `INTERNAL_ERROR`；`reviewer_id IS NULL`
+- [ ] full 职责项目仍写入非空 reviewer/approver
+
+## 相关链接
+
+- Audit: [../../audit/2026-09-17-docgov-optional-duty-null-fk.md](../../audit/2026-09-17-docgov-optional-duty-null-fk.md)
+- Test report: （验收后补）
+
+## 证据 / 备注
+
+- 触发 run：`run_1789622069585300787` / project 6417