bid-doctor/docs/architecture/addendum-plan.md

补遗追加实现方案 v0.1（2026-11-05）

范围：FR-M2-10 补遗追加（简化版）：追加的补遗 / 澄清文件单独解析、扣 1 次解析，新条目标注来源并入清单；日期类字段以最新文件为准，在旧值上标「已被补遗 N 更新」，由用户确认；不自动判断条目「新增 / 变更 / 作废」（P1）。 依据：03-functional-requirements.md、02-user-journeys.md J2 第 1 步、01-scope-roles.md（「追加解析 + 来源标注」，影响分析是 P1）、data-model.md §5.2「补遗」、openapi.yaml（/projects/{id}/fields/{key}/pending、/checklist-items/{id}/supersession）、原型 project-new.html?addendum=1 parsing.html?addendum=1 checklist.html project.html 的关键日期卡。 状态：AD1–AD6 已全部按建议确认（2026-11-05，docs/decisions.md）。

0. 结论速览

• 一半已经有了：后端上传时可以选补遗 / 澄清（编号「补遗 N」「澄清 N」），能单独解析、扣 1 次解析、失败退回；新条目记着来自哪份文件；项目字段的新值和旧值不同时先放进待确认（pending_value），不覆盖。
• 缺的：日期类条目的「已被补遗 N 更新」关联；两个确认接口（字段新值、日期条目）；并入后清单回到草稿；前端的追加入口、解析结果、确认界面、来源筛选。
• 按 FR 只做日期类的自动关联。原型里「★ 参数原为 480G、补遗改成 960G」那种逐条对照属于「变更判断」，是 P1，这次不做（AD2）。
• 补遗的新条目直接进正式清单，和招标文件的新旧条目都查：宁可多报，不漏报（AD1）。
• 没有补遗样本：10 份样本里一份都没有。这次用虚构的更正公告测链路；国动项目如果有更正公告，请一起给我，这是第一份真实补遗。

1. 现状

环节	现在	要补的
上传、编号	role = addendum / clarification，各自从 1 编号	前端入口
解析、扣点	和招标文件同一条流水线，扣 1 次解析，失败、超时、取消退回	解析结果页按补遗写（新增几条、哪些日期有新值）
清单项来源	origin_document_id 指向补遗；但接口的 origin_label 只有「AI」「人工添加」	origin_label 对补遗来的条目写「补遗 1」；读标页按来源筛选；并入后清单回到草稿
项目字段	新值和旧值不同 → pending_value，等确认	确认接口和界面；确认后同步冗余列
日期类条目	没有关联（superseded_by_id 列已建，没写）	并入时关联、确认接口、界面
分包	补遗不改已有的分包	不变

2. 并入时做什么（后端）

补遗解析完、并入清单时，在现有的 checklist.merge 之后多做三件事：

1. 新条目照常进清单：和招标文件一样按校验结果进正式清单或待确认区，标「补遗 N」。
2. 关联日期类条目：补遗里每条有具体时间的「日期与递交」条目（投标截止、开标、提疑截止、保证金截止、投标有效期），在更早的文件（招标文件、编号更小的补遗）里找同一种日期、还在正式清单里的条目，时间不同的把旧条目的 superseded_by_id 指向新条目，等用户确认。时间相同的不关联（补遗只是复述）。
3. 清单回到草稿：已确认的清单改为草稿，历史版本保留，要求重新确认（原型：「补遗 1 并入后待重新确认」）。

解析任务的结果里加：items_added（新增几条）、dates_superseded（几处日期有新值）、fields_pending（几个项目字段有新值），解析页按这三个数写。

3. 确认（后端）

按契约实现两个接口：

• POST /projects/{id}/fields/{key}/pending（accept: true / false）：
  • 采用：补遗的值变成 AI 值（出处换成补遗那一句），清掉人工值（以补遗为准；用户之后还可以再改），冗余列同步；
  • 不采用：丢掉待确认值，保持原值；
  • 采用投标截止时间时，清单里「投标截止」日期条目的更新一起确认（AD3），不用在读标页再点一次；
  • 都写审计（project_field.resolve_pending）。
• POST /checklist-items/{id}/supersession（accept: true / false，对旧条目调用）：
  • 采用：旧条目软删除（可以恢复），新条目保留；
  • 保留两条：解除关联，两条都在，由用户自己处理；
  • 都写审计（checklist_item.resolve_supersession）。

接口返回里补上已有字段：清单项的 superseded_by（新条目编号、来自哪份补遗）、清单概况的 superseded_pending（还有几处没确认）、关键日期的 superseded_pending。

没确认之前查标用旧值（AD4）：项目字段的契约就是「确认后才生效」（data-model.md §5.2）。检查预览提示「补遗 1 带来的新值还有 N 处没确认」，不阻止发起检查（红线 4）。确认后截止时间变了，已有的检查结果按 PI5 提示重新检查。

4. 前端

• 追加入口：概览页右上角和读标页清单栏各放一个「追加补遗 / 澄清」，进新建项目页的补遗模式（原型 project-new.html?addendum=1）。补遗模式下不填项目名称，文件类型选补遗或澄清答复，说明写「补遗单独解析，新条目标注『补遗 N』并入清单。标博士不判断哪些旧条目已作废，并入后由你核对」，按钮旁写扣 1 次解析。招标文件还没解析完时不显示入口（AD5）。
• 解析页：标题「解析补遗 1」；完成后写「新增 N 条 · M 处日期有新值 · K 个项目字段有新值 · 清单回到草稿，核对后重新确认」，下一步「核对补遗」进读标页、只看这份补遗的条目。
• 概览页：
  • 项目要点里有待确认值的字段写「补遗 1：新值 → 原值」，带出处，给「采用 / 不采用」；
  • 关键日期卡：被更新、还没确认的日期显示「已被补遗 1 更新，待确认」；确认后显示新值并注「已按补遗 1 更新 · 原为 11月18日 09:30」（原型 project.html）。
• 读标页：
  • 来源筛选：全部 / 招标文件 / 补遗 1 / ……，每项带条数；
  • 被更新的日期条目写「已被补遗 1 更新：新值 ……」，给「确认更新（删除旧条目）」和「保留两条」；
  • 并入后顶部提示「补遗 1 新增 N 条。标博士不判断哪些旧条目被它改了或作废了，请核对：改了的旧条目可以修改或删除」，带「只看补遗 1」。
• 查标页：检查预览里有没确认的新值时出上面那条提示。

5. 测试

• 虚构一份更正公告样例（server/tests/fixtures/addendum-mini.pdf，内容全虚构）：改投标截止时间、开标时间，新增一条 ★ 参数，复述一条没改的日期。
• 集成测试：追加 → 解析 → 扣 1 次 → 新条目标「补遗 1」、清单回到草稿、截止时间进待确认、日期条目关联（复述的不关联）；字段采用 / 不采用；采用截止时间时日期条目一起确认；日期条目采用（旧条目软删除、可以恢复）/ 保留两条；检查预览的提示；只读项目 409。
• 假模型能不能从样例里抽出日期要看它的规则；抽不出时测试里用接口建条目。浏览器里走一遍追加到确认的全程。
• 用真实模型对这份虚构样例跑一次解析看看抽取结果，花费几分钱（AD6）。

6. 工作量和顺序

1. 后端：并入时关联日期、清单回到草稿、两个确认接口、接口字段补齐、检查预览提示，以及测试样例和测试。约半天。
2. 前端：补遗模式的上传页、解析页的补遗结果、概览页的确认、读标页的来源筛选和日期确认。约半天。

7. 待确认事项

编号	事项	建议
AD1	补遗的新条目进正式清单还是待确认区	按招标文件同一套规则进正式清单（没出处、校验没过的照样进待确认区），标「补遗 N」，读标页给「只看补遗 N」和核对提示，清单回到草稿要求重新确认。新旧条目都在、都查，宁可多报，不漏报；全放待确认区的话，用户不逐条采纳就查不到补遗的新要求
AD2	哪些条目自动标「已被补遗更新」	只做日期类（同一种日期、时间不同），按 FR。原型里参数类「原为 480G → 现为 960G」的逐条对照是变更判断，P1；先等真实补遗样本看写法
AD3	怎么确认	字段在概览页逐个「采用 / 不采用」，日期条目在读标页逐条确认；采用投标截止时间时清单里的「投标截止」条目一起确认。采用时清掉人工值，以补遗为准
AD4	没确认之前查标用哪个值	旧值，确认后生效（数据模型原定）；检查预览提示还有几处没确认，不阻止检查
AD5	招标文件没解析完能不能追加补遗	不能，界面上招标文件解析成功后才显示入口。没有招标文件时补遗的日期没有可关联的旧值
AD6	用真实模型对虚构样例跑一次解析	跑一次（DeepSeek，几分钱），看抽取对补遗写法（「原为……现更正为……」）的表现；结果只记录，这次不按它调提示词

8. 落地记录（2026-11-05）

• 后端：checklist/addendum.py（并入时关联日期条目、确认 / 保留两条、采用截止时间时一起确认「投标截止」条目）；project/edit.resolve_pending（采用时补遗的值变成 AI 值、出处换成补遗那一句、清掉人工值）；清单项接口补 origin_document、superseded_by，origin_label 对补遗来的条目写「补遗 N」；清单概况 superseded_pending；关键日期 replaces（「已按补遗 1 更新 · 原为……」）；解析结果 dates_superseded、fields_pending；检查预览 pending_updates。
• 补遗不改项目是谁：解析补遗时项目名称、编号、采购人、代理机构、法律体系不进待确认。测试里发现，更正公告的标题会被抽成「项目名称」，和招标文件的不同，每份补遗都会冒出一条没意义的待确认。
• 时间比较按北京时间补时区：模型给的时间有时带时区、有时不带，补遗复述原时间时不能误判成「有新值」。
• ORM 给 JSONB 列写 None 存的是 JSON null，不是 SQL NULL，SQL 里数待确认值时要排除 JSON null。
• 前端：补遗模式的上传页（选补遗 / 澄清答复）、解析页的补遗结果和「核对补遗」、概览页「追加补遗 / 澄清」和字段「采用 / 不采用」、关键日期的待确认和「已按补遗 1 更新」、读标页的来源筛选、核对提示、「只看日期更新」和逐条确认、条目上的「补遗 1」标签、检查预览的提示。
• AD6 结果：用 DeepSeek Flash 对虚构的更正公告（推后递交截止时间、新增一条 ★ 参数）跑了一次解析（6 次调用）：两处改动都抽对了，★ 参数归为技术参数 + 无效条款、新截止时间 12 月 8 日，出处都是「补遗 1 · 第 1 页」，没有多抽。只是一份很规整的虚构样例，「原为……现更正为……」那种写法这份样例里没有，真实补遗到了再看。
• 浏览器里走过：追加补遗 → 解析结果 → 概览采用新截止时间（项目头、要点、关键日期一起变，旧的「投标截止」条目自动删除）→ 读标页只看补遗 1。