# 要求知识库 v3 — 数据模型与编排

> 这份文档解释「为什么现在是这样编排、哪些地方还不能当全量条款库用」。  
> 生成时间：2026-11-06；生成脚本：`tools/kb-build.mjs`。

## 1. 这次改了什么

旧结构是**文档优先**：标准卡 → 条款译文 → 原子 → 外部解读，四套内容并排；用户能看到很多信息，但很难回答三个问题：

1. 这句话到底是**标准要求**，还是编辑/外部解读？
2. 这条要求属于哪一版标准，是否已被替代？
3. 它适用于哪个产品、部件、阶段，证据到什么程度？

v3 不再把“卡片”当最小单位，而是把链路拆成：

```text
StandardFamily（标准族）
  └─ StandardVersion（版本）
       ├─ Relation（adopts / modified_from / supersedes / amendment）
       ├─ Requirement（要求；稳定 ID）
       │    ├─ clause + quote + page/bbox（页码当前为空）
       │    ├─ applicability（产品/部件/法规属性/阶段）
       │    ├─ parameter + condition + value + unit
       │    └─ evidence_status（官方全文/官方预览/仅外部/编辑摘录）
       └─ Claim（主张：卡片结论 / 外部解读 / 专家文章）
            └─ requirement_ids（自动链；未链会显式标出）
```

## 2. 覆盖度是显式的，不假装全量

当前数据事实：

- **74 条标准**，但只有 **222 条条款样本**。
- **73/74 条标准是 2–3 条条款**，1 条是 4 条。
- **928 个要求（原子）**，平均每标准 12.5 个。
- **0 个要求有页码/bbox**；只有条款 + 原文摘录。页码只在本地 `docs/replicas/<id>/lines.json` 中做严格子串命中时才回填；当前 0 条命中，不靠人工猜测补页码。

因此每条标准标 **L1–L3**：

| 等级 | 含义 | 当前 |
| --- | --- | --- |
| **L1** | 每标准 2–4 条精选条款，用于导读/评审提示 | **74/74** |
| **L2** | 关键章节基本覆盖，能支撑专项评审 | 0 |
| **L3** | 接近全量条款 + 图表/附录 | 0 |

> 这不是“编排失败”，而是把原来的隐含定位说清楚：**现在是精选导读 + 原子化样板，不是全量条款库**。  
> 要升级到 L2/L3，必须补原文、补条款、补页码，不能靠多写卡片。

## 3. 稳定 ID 规则

要求 ID 不使用顺序号，避免插入一条就把后面全部重编号：

```text
req-<标准 id>-<sha1(std|clause|kind|text_zh|parameter|condition)[0:10]>
```

- 例：`req-cn-gb-t-30038-2013-xxxxxxxxxx`
- 旧原子 ID 保留为 `legacy_id`，映射表：`data/id-map.json`。
- 门户的“打开原原子卡”仍用 legacy ID；要求台账/导出用稳定 ID。
- 如果原文措辞变化，ID 会变化——这是有意的：**要求内容变了，就应该是一条新要求**。

## 4. 证据状态

每个要求都带 `evidence_status`，门户用颜色区分：

| 值 | 含义 | 当前数量 |
| --- | --- | --- |
| `official_text` | 本地有全文 PDF，摘录可回原文 | 39 |
| `official_preview` | 官方在线预览可读，摘录来自预览 | 95 |
| `external_only` | 没有官方正文，只有已核对外部解读 | 224 |
| `editorial_excerpt` | 编辑摘录/条款译文，未取得官方正文 | 570 |

外部解读另带 `source_tier`、`read`、`boundary`，**不等于标准原文**。卡片主张统一标 `editorial`，不是规范文本。

## 5. 主张链（Claim）

- 卡片：`oneLine / why / structure / verify / pitfall` 各生成一条 `Claim`。
- 外部解读：每个 `items[]` 生成一条 `Claim`。
- 专家文章：每条 `knowledge-sources.json → sources[].key_points[]` 生成一条 `claim_type: article` 的 `Claim`；带作者、URL、A/B/C 层级、质量分和原文边界。
- 每条 Claim 通过关键词/部件/主题自动匹配到最多 3 条要求，标 `link_status: auto | unlinked`。
- **自动链不是等价证明**，只是把“编辑结论/外部观点/文章观点”拉回可复核的要求 ID。
- 当前：1042 条主张，663 条已链，379 条未链；其中文章主张 238 条，很多未链只是标准不在库内；未链在 UI 里显式标黄。

## 6. 试验矩阵

`data/test-matrix.json` / `data/exports/test-matrix.csv` 把以下字段分开：

```text
method | parameter | condition | value | unit | acceptance | evidence_status
```

- 空值就是原文没给，不补数字。
- `acceptance` 优先取同标准内 `tests/refines/depends` 关系指向的判据原子；没有关系时，才从含“不应/不得/不超过/至少”的句子提取。
- 当前 903 行；这是“可核对的行”，不是完整试验大纲。

## 7. 版本/变更雷达

`data/lifecycle.json` 是人工维护的版本关系，`data/change-radar.json` 是构建产物。

已登记：

- GB/T 30038-2013 → GB/T 30038-2026（2027-02-01 实施，全部代替）。
- GB/T 20234.1/.3/.4-2023 换版 + CQC 证书转换截止 2025-04-30 / 撤销 2025-07-31。
- GB/T 31467-2023 合并 .1/.2-2015。
- KS R 1034 2023-12-05 修订（只改公式）。
- UN R95：Rev.1 历史档、Rev.4 Amend.4 最新检索条目、Rev.5 未核实。
- ISO 16750-3:2007 → 2023；ISO 20653:2006 → 2023。

> 没有日期的版本只建关系，不编日期；不确定的版本标 `uncertain`。

## 8. 门户模块

| 模块 | 回答的问题 |
| --- | --- |
| **决策台** | 我的产品/阶段/地区，应该看哪些标准？ |
| **标准地图** | 这个标准族有哪些版本？谁替代谁？哪些只是登记、没有库内卡片？ |
| **要求台账** | 这条要求的稳定 ID、适用性、参数、证据是什么？ |
| **试验矩阵** | 方法、条件、数值、判据分别是什么？空在哪里？ |
| **变更雷达** | 哪些替代/认证截止日正在逼近？ |
| **覆盖质量** | 哪些标准只有 L1？哪些没有页码？哪些主张未链？ |
| **证据链** | 卡片/外部解读/专家文章到底链到了哪条要求？哪些没链？ |
| **专家与文章** | 哪些期刊/实验室/工程师值得读？哪些标准相关？边界是什么？ |
| **术语/导出** | 术语建议；要求台账、试验矩阵、DFMEA 种子、专家文章、主张链下载。 |

## 9. 构建与校验

```powershell
node tools/build.mjs        # 标准/条款/档案 + 自动调用 kb-build
node tools/kb-build.mjs     # 只重建 v3 知识库
```

`build.mjs` 末尾会执行 `kb-build.mjs`；构建后检查：

```text
data/kb.json
data/requirements.json
data/claims.json
data/knowledge-sources.json
data/test-matrix.json
data/change-radar.json
data/coverage.json
data/id-map.json
data/exports/requirements.csv
data/exports/test-matrix.csv
data/exports/dfmea-seed.csv
portal/kb-data.js
```

## 10. 边界（必须保留）

- **不把 L1 说成全量**；不把外部解读说成标准原文。
- **不把专家文章说成标准要求**；文章要点只作评审线索，`evidence_status: external_only`。
- **不编页码/条款号/限值**；页码为空就显示“无页码”。
- **不把自动链说成等价**；`same_parameter` 只表示同参数名，不表示同严酷度。
- **不绕过**官方访问控制、验证码、Cloudflare。
- 术语表是工程译法建议，不是官方术语。