Agent-System/.doc/audit/2026-09-17-docgov-optional-duty-null-fk.md

title, status, created, updated, severity

title	status	created	updated	severity
可选职责空审核人 CreateOrGetDocument 写 reviewer_id=0 触发 FK	done	2026-09-17	2026-09-17	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 CreateOrGetDocument 把 0 写入可空 FK，PG 拒绝（无 users.id=0）
5. ClassifyError 默认分支掩盖为 INTERNAL_ERROR

对照：internal/docduty/store.go heal 路径已有 nullIfZero，创建路径漏改。

复现：INSERT ... reviewer_id=0 → 同 FK 错误。近 7 天同因至少 3 次（6417/6359/6274）。

严重度

high（任何无 reviewer 职责的项目首次落文档账本均会失败；可扩散至 test/main）

关联整改

• Short-term: ../archive/ops/2026-09-17-docgov-optional-duty-null-fk.md
• Fix branch: fix/docgov-optional-duty-null-fk
• Test report: ../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md

证据

• 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 另开任务