release-candidate: promote optional-duty null FK fix to test [Tag: rc-v1.0.0-beta.4]

This commit is contained in:
weichen
2026-09-17 06:19:57 +00:00
10 changed files with 321 additions and 10 deletions
@@ -0,0 +1,53 @@
---
title: "修复 CreateOrGetDocument 可选职责 0→NULL FK"
status: done
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. [x] 占集成槽位 rebuild + 6417 复测(`run_1789625396102207018`,`doc_proj6417_intake` NULL FK)
5. [x] test-report 归档;合入 `dev`
## 验收标准
- [x] `go test -short ./internal/docgov/... ./internal/stream/...` PASS
- [x] 仅-author 项目 `CreateOrGetDocument` / 任务发起不再 `INTERNAL_ERROR`;`reviewer_id IS NULL`
- [x] 项目 6417 账本创建成功(full 职责路径未被本修复改动)
## 相关链接
- Audit: [../../audit/2026-09-17-docgov-optional-duty-null-fk.md](../../audit/2026-09-17-docgov-optional-duty-null-fk.md)
- Test report: [../../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md](../../test-reports/2026-09-17-docgov-optional-duty-null-fk-test-report.md)
## 证据 / 备注
- 失败 run:`run_1789622069585300787`
- 验证 run:`run_1789625396102207018` / `doc_proj6417_intake` author=9 reviewer/approver NULL
- merge:`e488d10 merge: fix/docgov-optional-duty-null-fk`
@@ -0,0 +1,54 @@
---
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: [../archive/ops/2026-09-17-docgov-optional-duty-null-fk.md](../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](../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 另开任务
+8
View File
@@ -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](../archive/ops/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 -3
View File
@@ -5,14 +5,16 @@
## 焦点
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. **promote null-fk → test**:`rc-v1.0.0-beta.4`(docgov optional-duty FK 修复)
2. **partial/deferred 全量收口**:W1–W4 **done**;W5a **done**(矩阵自举行仍 partial);W6 **shadow done**(矩阵 FAV 仍 partial);W7 **盘点 done**(矩阵 D7 仍 deferred)。已晋升:`rc-v1.0.0-beta.3` → 本轮 `beta.4`
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-promote-null-fk-to-test | feature/promote-null-fk-to-test | - | infra | in_progress |
| Cursor | 2026-09-17-docgov-optional-duty-null-fk | fix/docgov-optional-duty-null-fk | - | docgov | done |
| 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 |
@@ -119,7 +121,7 @@
| holder | phase | since | scope | queue |
|--------|-------|-------|-------|-------|
| - | idle | - | - | - |
| Cursor | merging | 2026-09-17 | promote null-fk → test (rc-v1.0.0-beta.4) | - |
**phase**: `idle` | `merging` | `smoke` | `e2e`
@@ -0,0 +1,67 @@
# CreateOrGetDocument 可选职责 0→NULL FK 测试报告
## 一、 测试背景 (Background)
dev 项目「内廷元无创神经刺激器」(6417) 发起 `intake` 任务时,UI 报 `INTERNAL_ERROR` /「系统内部错误,请重新开始会话」(`run_1789622069585300787`)。根因是可选审核职责为空时 `CreateOrGetDocument` 写入 `reviewer_id=0`,触发 `document_records_reviewer_id_fkey`,再被 `ClassifyError` 兜底掩盖。
## 二、 测试目标 (Test Objectives)
- 仅-author 项目创建文档账本成功,`reviewer_id`/`approver_id` 为 SQL NULL
- 不再出现 `persist document ledger` / `INTERNAL_ERROR`(该路径)
- ledger/FK 残差错误分型为 `DOC_LEDGER_ERROR`
- 单元与 `-short` 回归通过
## 三、 测试方案与环境 (Test Plan & Environment)
| 项 | 值 |
|---|---|
| OS | Linux |
| 分支合入 | `dev` @ `merge: fix/docgov-optional-duty-null-fk` |
| 环境 | agent-dev `:8080`,schema 48,真实 PI |
| 层级 | 单元 / DB 集成 / 真实 task run 冒烟 |
## 四、 预期结果 (Expected Results)
1. `nullIfZero(0)==nil`;`CreateOrGetDocument(..., reviewer=0, approver=0)` 成功且 DB NULL
2. `ClassifyError(persist document ledger ... 23503)` → `DOC_LEDGER_ERROR`
3. 项目 6417 重试 `intake`:越过账本创建;`doc_proj6417_intake` 存在且 `rev_null/app_null=true`
## 五、 实际测试结果与判定 (Actual Results & Evaluation)
### 用例 1:单元 / short
- **输入**: `go test -short ./internal/docgov/... ./internal/stream/...`
- **实际输出**: `ok`(含 `TestNullIfZero`、`TestClassifyError_DocumentLedgerFKIsLedgerError`)
- **判定**: PASS
- **耗时**: ~0.5s
### 用例 2:DB 集成 OptionalDutiesNullFK
- **输入**: `go test ./internal/docgov/ -run OptionalDutiesNullFK -count=1`
- **实际输出**: `--- PASS: TestDocGov_CreateOrGetDocument_OptionalDutiesNullFK`
- **判定**: PASS
### 用例 3:dev 真实任务(项目 6417)
- **输入**: admin 登录后 `POST /api/v1/tasks/runs`(`task_key=intake`,`session_id=sess-p6417-u9`,`project_id=6417`)
- **实际输出**:
- 创建响应:`{"run_id":"run_1789625396102207018","status":"running"}`
- DB:`doc_proj6417_intake | author_id=9 | rev_null=t | app_null=t | drafting`
- 未再出现 `persist document ledger` / `document_records_reviewer_id_fkey`
- **判定**: PASS(账本 FK 根因已消除;任务可继续进入 PI 执行阶段)
- **耗时**: 账本落盘在秒级完成(对比失败 run 立即 failed)
## 六、 自动化测试套件汇总 (Test Suite Execution)
```text
go vet ./internal/docgov/... ./internal/stream/...
go test -short ./internal/docgov/... ./internal/stream/...
# ok docgov / stream
./scripts/env-service.sh dev rebuild
curl -sf http://127.0.0.1:8080/health # ok, schema_version=48
```
## 七、 测试结论与后续优化建议 (Conclusion & Next Steps)
- **结论**: 达到合入与冒烟标准;可选职责空审核人不再因 FK=0 导致 `INTERNAL_ERROR`。
- **后续**: 前端 `flushSync` 警告另开任务;全链路 PI 完成质量属独立验收,不阻塞本修复。
+21 -7
View File
@@ -4,6 +4,7 @@ import (
"context"
"encoding/json"
"fmt"
"log"
"strings"
"sync"
"time"
@@ -13,6 +14,15 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
)
// nullIfZero maps unset duty holders (0) to SQL NULL so nullable FK columns
// (author_id/reviewer_id/approver_id → users.id) accept optional duties.
func nullIfZero(id int64) any {
if id <= 0 {
return nil
}
return id
}
// ModificationCheckResult 智能体或人员发起修改前的认领与授权判定结果
type ModificationCheckResult struct {
AllowedDirectEdit bool `json:"allowed_direct_edit"` // 是否允许直接执行修改
@@ -153,12 +163,15 @@ func (e *GovernanceEngine) CreateOrGetDocument(
}
ensureUser := func(uid int64, uname, urole string) {
if uid > 0 {
_, _ = e.pool.Exec(ctx, `
INSERT INTO users (id, account_id, name, role)
VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO NOTHING
`, uid, fmt.Sprintf("acc_%d", uid), uname, urole)
if uid <= 0 {
return
}
if _, err := e.pool.Exec(ctx, `
INSERT INTO users (id, account_id, name, role)
VALUES ($1, $2, $3, $4)
ON CONFLICT (id) DO NOTHING
`, uid, fmt.Sprintf("acc_%d", uid), uname, urole); err != nil {
log.Printf("[docgov] ensureUser id=%d role=%s failed: %v", uid, urole, err)
}
}
ensureUser(doc.AuthorID, doc.AuthorName, "engineer")
@@ -185,7 +198,8 @@ func (e *GovernanceEngine) CreateOrGetDocument(
err := e.pool.QueryRow(ctx, query,
doc.DocID, doc.ProjectID, doc.TaskKey, doc.Title, doc.Stage, doc.Version,
string(doc.CurrentState), doc.IsLocked, doc.IsTemplateOnly, doc.WorkDir,
doc.AuthorID, doc.AuthorName, doc.ReviewerID, doc.ReviewerName, doc.ApproverID, doc.ApproverName,
nullIfZero(doc.AuthorID), doc.AuthorName, nullIfZero(doc.ReviewerID), doc.ReviewerName,
nullIfZero(doc.ApproverID), doc.ApproverName,
cfgJSON, doc.CreatedAt, doc.UpdatedAt,
).Scan(&id, &currState, &isLocked, &isTmpl, &authClaim, &revClaim, &appClaim)
if err != nil {
+61
View File
@@ -97,3 +97,64 @@ func TestDocGov_DatabaseIntegration(t *testing.T) {
t.Fatalf("expected doc locked in reviewing")
}
}
// TestDocGov_CreateOrGetDocument_OptionalDutiesNullFK ensures reviewer/approver=0
// persist as SQL NULL (optional DutyMode) instead of FK-violating 0.
func TestDocGov_CreateOrGetDocument_OptionalDutiesNullFK(t *testing.T) {
cfg, err := config.Load(".env")
if err != nil || cfg == nil || cfg.ContextDbHost == "" {
t.Skip("Skipping DB integration test: context DB not configured")
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
pool, err := pgxpool.New(ctx, cfg.ContextDSN())
if err != nil || pool.Ping(ctx) != nil {
t.Skipf("Skipping DB integration test: cannot connect to %s: %v", cfg.ContextDSN(), err)
}
defer pool.Close()
engine := docgov.NewGovernanceEngine(pool)
testDocID := fmt.Sprintf("doc_opt_duty_%d", time.Now().UnixNano())
projectID := time.Now().UnixNano()%900000 + 100000
doc, err := engine.CreateOrGetDocument(
ctx,
testDocID,
projectID,
"intake",
"可选职责空审核人",
"V0.5_feasibility",
"",
9, "系统管理员",
0, "",
0, "",
)
if err != nil {
t.Fatalf("CreateOrGetDocument with reviewer/approver=0 failed: %v", err)
}
if doc.DocID != testDocID {
t.Fatalf("unexpected docID: %s", doc.DocID)
}
var reviewerNull, approverNull bool
var authorID int64
err = pool.QueryRow(ctx, `
SELECT author_id,
reviewer_id IS NULL,
approver_id IS NULL
FROM document_records WHERE doc_id = $1
`, testDocID).Scan(&authorID, &reviewerNull, &approverNull)
if err != nil {
t.Fatalf("query document_records: %v", err)
}
if authorID != 9 {
t.Fatalf("author_id=%d want 9", authorID)
}
if !reviewerNull || !approverNull {
t.Fatalf("expected NULL reviewer/approver, got reviewerNull=%v approverNull=%v", reviewerNull, approverNull)
}
_, _ = pool.Exec(ctx, `DELETE FROM document_records WHERE doc_id = $1`, testDocID)
}
+16
View File
@@ -0,0 +1,16 @@
package docgov
import "testing"
func TestNullIfZero(t *testing.T) {
t.Parallel()
if got := nullIfZero(0); got != nil {
t.Fatalf("nullIfZero(0)=%v want nil", got)
}
if got := nullIfZero(-1); got != nil {
t.Fatalf("nullIfZero(-1)=%v want nil", got)
}
if got := nullIfZero(9); got != int64(9) {
t.Fatalf("nullIfZero(9)=%v want 9", got)
}
}
+15
View File
@@ -35,6 +35,12 @@ func ClassifyError(err error, phaseID, requestID, sessionID, workspaceID string)
info.UserMessage = "该文档正在由项目助手或其他用户编辑中;当前请求未执行,请等待现有任务完成"
info.Actions = []string{}
case isDocumentLedgerError(msg):
info.Code = "DOC_LEDGER_ERROR"
info.Class = ErrorClassFatal
info.UserMessage = "文档职责账本写入失败,请重新开始会话;若反复出现请联系管理员"
info.Actions = []string{"restart"}
case isTimeoutError(msg):
info.Code = "CHAT_TIMEOUT"
info.Class = ErrorClassTransient
@@ -74,6 +80,15 @@ func containsInternalLeak(s string) bool {
return false
}
func isDocumentLedgerError(msg string) bool {
return strings.Contains(msg, "persist document ledger") ||
strings.Contains(msg, "sqlstate 23503") ||
strings.Contains(msg, "foreign key constraint") ||
strings.Contains(msg, "document_records_reviewer_id_fkey") ||
strings.Contains(msg, "document_records_author_id_fkey") ||
strings.Contains(msg, "document_records_approver_id_fkey")
}
func isTimeoutError(msg string) bool {
return strings.Contains(msg, "timeout") ||
strings.Contains(msg, "deadline") ||
+21
View File
@@ -99,3 +99,24 @@ func TestClassifyError_DocumentBusyIsVisibleStateWithoutRetry(t *testing.T) {
t.Fatalf("busy state must not encourage duplicate retry, actions=%v", info.Actions)
}
}
func TestClassifyError_DocumentLedgerFKIsLedgerError(t *testing.T) {
err := errors.New(`persist document ledger: ERROR: insert or update on table "document_records" violates foreign key constraint "document_records_reviewer_id_fkey" (SQLSTATE 23503)`)
info := ClassifyError(err, "", "run_1", "sess-p6417-u9", "")
if info.Code != "DOC_LEDGER_ERROR" {
t.Fatalf("code=%s", info.Code)
}
if info.Class != ErrorClassFatal {
t.Fatalf("class=%s", info.Class)
}
if len(info.Actions) != 1 || info.Actions[0] != "restart" {
t.Fatalf("actions=%v", info.Actions)
}
if !strings.Contains(info.UserMessage, "文档职责账本") {
t.Fatalf("user_message=%q", info.UserMessage)
}
// SQL detail must not leak into user-facing fields (Upstream may be stripped by leak filter).
if strings.Contains(info.UserMessage, "SQLSTATE") || strings.Contains(info.UserMessage, "foreign key") {
t.Fatalf("user message leaked SQL: %q", info.UserMessage)
}
}