From 149dec8993e39f0c9956e9de66024d048984359c Mon Sep 17 00:00:00 2001 From: weichen Date: Thu, 17 Sep 2026 06:08:35 +0000 Subject: [PATCH] docs(ops): claim and audit docgov optional-duty null FK fix Co-authored-by: Cursor --- ...2026-09-17-docgov-optional-duty-null-fk.md | 53 +++++++++++++++++++ .doc/audit/INDEX.md | 8 +++ .doc/ops/CURRENT.md | 5 +- ...2026-09-17-docgov-optional-duty-null-fk.md | 51 ++++++++++++++++++ 4 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 .doc/audit/2026-09-17-docgov-optional-duty-null-fk.md create mode 100644 .doc/ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md diff --git a/.doc/audit/2026-09-17-docgov-optional-duty-null-fk.md b/.doc/audit/2026-09-17-docgov-optional-duty-null-fk.md new file mode 100644 index 00000000..ac74fce2 --- /dev/null +++ b/.doc/audit/2026-09-17-docgov-optional-duty-null-fk.md @@ -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 另开任务 diff --git a/.doc/audit/INDEX.md b/.doc/audit/INDEX.md index 7dc0de5f..fd874660 100644 --- a/.doc/audit/INDEX.md +++ b/.doc/audit/INDEX.md @@ -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) diff --git a/.doc/ops/CURRENT.md b/.doc/ops/CURRENT.md index 9d268df0..000bf070 100644 --- a/.doc/ops/CURRENT.md +++ b/.doc/ops/CURRENT.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 | diff --git a/.doc/ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md b/.doc/ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md new file mode 100644 index 00000000..0377b355 --- /dev/null +++ b/.doc/ops/short-term/2026-09-17-docgov-optional-duty-null-fk.md @@ -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