Agent-System/.doc/remediation/2026-09-13-document-revision-reviewer-duty-sync.md

title, status, created, updated

title	status	created	updated
项目 reviewer 同步到受控文档职责	done	2026-09-13	2026-09-22

项目 reviewer 同步到受控文档职责

W3 UI-rerun 关闭（2026-09-22）：status=done。真实 Playwright 账本 PASS：ui-acceptance-results.json（main UI-00..16）+ ui-acceptance-results-post-restart.json（UI-15）。任务 tip 已合入本地 dev；详见 short-term 与 测试报告。

背景

链到 ../audit/2026-09-13-document-revision-reviewer-duty-sync.md。

目标

• 立项时指定的 reviewer 成员，在后续每份新生成受控文档上成为 reviewerId / reviewer
• 服务端职责为权威；前端不得靠名字或本地宽松回退提升
• 非成员仍无权；作者/批准人不串位
• 已有文档职责缺失或为非成员占位（如硬编码 2/3）时，服务端可重复自愈，而不是只改测试数据

分波次计划

波次	内容	验收
Wave 0	project_members.document_duty + 解析/自愈 + 任务生成去硬编码 + 前端持久化 duty	A author、B reviewer、C none；第二文档继承；幂等；写操作按权拒绝；go test -short / npm
Wave 1	占槽重跑真实 UI-13a（本轮不做）	矩阵 role=reviewer

设计

1. 访问角色仍是 owner/member/viewer；文档职责另存 document_duty（author/reviewer/approver/空），同一项目同一职责仅一名在任成员。
2. Resolve：author=指定编制人或创建者；reviewer/approver=指定职责，否则仅当请求 id 是在任成员才采用；禁止默认 2/3。
3. Heal：项目 document_duty 为权威。assigned 非零则对齐（错 ID——即使对方也是在任成员——或同 ID 旧名称）；assigned 为空才保留当前值，避免臆造/清空。禁止「任意 active member 就放过」。
4. 列表/生成走自愈；失败必须返回可诊断错误，生成路径不得假成功；CreateOrGetDocument 失败不得报告成功。成员增改/移出：advisory lock、读取旧/冲突 holder、成员更新、document_records 精确清 reviewer/approver 槽必须在同一事务；提交后服务层 heal 新 holder；失败仍 ERR_DUTY_SYNC。author 不因普通成员变更清空。HealProjectDocuments 必须与成员写共用同一 pg_advisory_xact_lock(project_id)，并在该事务内完成解析与文档更新，避免旧 heal 把已转移的 reviewer 写回。
5. 前端立项与立项后增改/恢复都发 document_dutyFromMemberRole。更新成员省略 project_role 时保留现有访问角色，禁止默认 member 把 owner 降级。
6. 迁移 owner 回填：创建者优先，否则最低 user_id，单行 UPDATE，避免部分唯一索引冲突。

验收标准

• 服务端解析与自愈单测（含错 ID 恰为成员、同 ID 旧名称、assigned 空、第二文档、幂等）
• 前端立项与成员增改/恢复 payload 带 document_duty；不按名字提权
• 更新成员缺 project_role 保留 owner；写权测试 author err==nil，reviewer/outsider 精确 forbidden
• go test -short ./...、相关 -race、npm test/build
• 隔离 PG（临时库 agent_duty_sync_itest_*，测完删除；未连 agent_system_dev、未启停容器）
• 真实 UI-13a（本轮不做）

兼容与剩余风险

• 兼容：未应用 00031 的环境不读 document_duty；应用后旧成员空 duty 不会被臆造为 reviewer。assigned 为空时自愈不清空已有在任成员。
• 6145：B 仍是 member + 空 duty。新 heal 会把错误成员 approver 对齐到 assigned（若有）；B 的文档 reviewer 仍是占位 2，直到成员 API 写入 document_duty=reviewer。
• 隔离 PG：TEST_DATABASE_URL 指向临时库，或 PG_ADMIN_URL + scripts/run-isolated-duty-sync-pg-tests.sh。禁止默认连 agent_system_dev。本轮不启停共享容器。

相关链接

• Audit: ../audit/2026-09-13-document-revision-reviewer-duty-sync.md
• Short-term: ../ops/short-term/2026-09-13-document-revision-reviewer-duty-sync.md