数字我 Digital Me：全量入库（大文件走 Git LFS）

digital-me-backend/src/biannian-design.md

@@ -0,0 +1,231 @@
+# 编年 · 层 · 影响 —— 建模设计（biannian-design.md）
+
+> 第一步只交设计，不改一条数据、不建前端。全部数字都是 `node` 实跑 `src/tianxia.js`
+> 打印出来的，不是手数（脚本见文末「审计口径」）。基线：`npm test` = **601 通过**（本步未动）。
+
+---
+
+## 0. 结论速览
+
+| 事 | 数 | 状态 |
+|---|---|---|
+| 大事件(shi)总数 | **932** | 25 朝 |
+| 层 layer 已标 | **932 / 932（100%）** | ✅ ①「每事标层」实际上**已经做完** |
+| 层分布 | 事 830 / 制 92 / 道 10 | 道极吝啬（两千年才 10 个），符合判据 |
+| impact 已标 | **0 / 102 制道事件** | ❌ ②「制/道连下游影响」= 本产品线**真正的空白**，全部待做 |
+| 层值编码分裂 | 23 朝 pinyin，**2 朝(qin/beisong) 用汉字** | ⚠ 需归一（见 §2.1） |
+| zaichang 形状分裂 | array 7 朝 / string 12 朝 / 无 6 朝 | ⚠ 前端必须两种都吃（见 §2.4） |
+
+**一句话**：`layer` 已铺满，不用重做；产品线的正主功能是 **impact（影响链）**，102 个制/道
+事件一个都没连下游。补编年（③）是第三优先，且受「双证原文」红线约束，只补真查得实的。
+
+---
+
+## 1. 事件（shi）字段现状 —— 实测
+
+### 1.1 读取路径（不用改）
+`src/chao/<code>.js` 各 `export const CHAO_SHI` → `src/tianxia.js` 第 290 行原样挂到
+`CHAO[code].shi`（**passthrough，一个字段都不删**）→ `shiAt()` / `chenShiByReign()` 按年过滤后
+原样带出。⇒ **你在 chao 文件里给事件加的 `layer`/`impact`，tianxia 自动带出，无需改 tianxia**
+（唯一可选的小改：§2.3 的防御性 normalizer）。
+KG：`src/kg.js` 第 306–310 行为每条 shi 建 event 节点，且 `raw: s` **挂整条原始对象** ⇒
+`node.raw.layer` / `node.raw.impact` 自动可用，**别碰 kg.js**（它派生）。
+
+### 1.2 字段清单（当前两种 shape，都要向后兼容）
+
+**共有字段（所有朝）**
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `year` | number | 公元年（负=公元前）。KG 按 `${code}:${year}` 建索引 |
+| `shi` | string | **本纪原文逐字**（层/影响之外，这是唯一的"原文"栏） |
+| `juan` | string | 卷次，如 `《漢書》卷五` |
+| `layer` | `'shi'\|'zhi'\|'dao'` | 见 §2.1。**推演**（我们的读法） |
+| `kind` | `'yuanwen'` | shi 栏的性质；全部 `yuanwen`（逐字原文） |
+| `layerWhy` / `layerNote` | string | **强制**：每条层判据给理由，不许空标 |
+| `zaichang` | array \| string | 「那年什么位阶被卷进去」，**推演**（`kind:'tuiyan'` / `zaichangKind:'tuiyan'`） |
+
+**可选字段（部分朝已有）**：`yue`(月) `gz`(干支) `jinian`(纪年) `source`(默认`benji`)
+`witnesses`(见证数，xin/wu/xixia 有) `crossWitness` `zhengwu` `biaoCross` `shuangzheng`
+`yearOpen`/`yearNote`(系年存疑) `weiFa`(从未生效的制)。—— **新 schema 一律叠加，不动这些。**
+
+### 1.3 layer 现状：100% 已标，但编码分裂（⚠ 待归一）
+
+- **23 朝用 pinyin** `'shi'/'zhi'/'dao'`（xihan/ming/xixia/shuhan/… 及 xin 的工厂函数 `S(...)`
+  第 5 参，实测 `s.layer==='shi'`）。
+- **2 朝用汉字** `'事'/'制'/'道'`：**`qin.js`(22 条) 与 `beisong.js`(46 条)**。
+- 语义（各朝文件头一致，判据同一把尺）：
+  - **事 shi（1–50 年）**：一场仗、一次废立、一个人的死、一次亡国。绝大多数。
+  - **制 zhi（50–500 年）**：一个制度的确立/废除（官制、律、铸钱、学校、科举定式、田制…）。
+  - **道 dao（500+ / 硬测「到公元 1500 年还在起作用吗」）**：改变了此后千年且今仍运转。极吝啬。
+
+### 1.4 zaichang 形状分裂（⚠ 前端契约）
+- **array `[{wei, shuo}]`**（7 朝）：xihan xin shuhan wu liusong beiqi liao —— 每项另标 `kind:'tuiyan'`。
+- **string**（12 朝）：dongjin beiwei liang sui tang wudai beisong xixia jin nansong ming +chen(部分) —— 另有 `zaichangKind:'tuiyan'`。
+- **无 zaichang**（6 朝）：qin donghan wei xijin nanqi beizhou +chen(部分)。
+- ⇒ 这是既有的历史遗留，**不在本产品线强行迁移**（与 layer/impact 正交）。前端 `Biannian.vue`
+  必须同时处理 array / string / 缺三态（§2.4）。
+
+### 1.5 impact 现状：0，且有一个**命名撞车**（无害，但要说清）
+- 没有任何一条 **事件**带下游影响字段。102 个制/道候选全空。
+- ⚠ 全库 grep `impact:` 有 7 处命中（xin.js 1 + xixia.js 6）—— 那是 **字形/异文审计表**
+  （WITNESS 行）里的 `impact`，意思是「这个异体字**涉不涉文义**」（如 `不涉文义`），
+  **挂在 WITNESS 行对象上，不在 CHAO_SHI 事件上**。⇒ 两个不同对象命名空间，运行时不冲突。
+  但为免人读混，本设计的事件级 `impact` 语义在 §2.2 写死；老板已点名字段叫 `impact`，沿用。
+
+---
+
+## 2. Schema 设计（向后兼容，只叠加不破坏）
+
+### 2.1 `layer`（已存在，本步只做**归一**决策）
+
+**规范值 = pinyin `'shi' | 'zhi' | 'dao'`**（取 23:2 的多数派 + 与 `kind:'yuanwen'/'tuiyan'`
+的罗马化惯例一致 + xin 已用 `s.layer==='shi'` 过滤）。汉字 `事/制/道` 只作**显示 label**。
+
+> ⚠ 这一条**推翻**老板任务书草案里写的 `layer:'事'|'制'|'道'`（汉字）——
+> 草案是示意 label，不是存储值规约；把 23 个文件改成汉字，风险远大于把 2 个改成 pinyin。
+> **建议**：qin.js / beisong.js 的第二步 agent 把本文件层值 `事→shi 制→zhi 道→dao` 归一；
+> 并在 tianxia 加一行防御性 normalizer（§2.3）兜底，保证前端永远只见 pinyin。
+
+- 层是**推演**：`layer` 值本身就是「我们的读法」，无须再标 kind；**`layerWhy` 强制**给理由。
+
+### 2.2 `impact`（新字段，只加在**制/道**事件上，这是产品线正主）
+
+```js
+impact: {
+  reach: 'dangchao' | 'houshi' | 'qiannian',   // 影响半径。label：当朝/后世/千年
+  kind:  'yuanwen'  | 'tuiyan',                // 与事件级 kind 同词表：原文明引 vs 推演
+  reason: string,                              // 【强制】史学通说 / 制度史依据，说人话
+  to?: [                                       // 【可选】下游落点，可多个
+    { code?: string, year?: number, label: string }
+  ],
+  cite?: string,                               // 仅 kind:'yuanwen' 时【强制】：原文明引句
+  witnesses?: number,                          // kind:'yuanwen' 时建议≥2（双证）
+  reachWhy?: string                            // 可选：半径判据（仿 layerWhy）
+}
+```
+
+**字段规约（照史学红线，逐条硬性）**
+1. **只给 `layer==='zhi'|'dao'` 的事件加 `impact`**；`layer==='shi'` 不加（事没有下游影响链，
+   有的话它就不是"事"）。⇒ impact 天生是 102 个候选的子集。
+2. `reach` 与 layer 有对应但**不强绑**：制→常 `houshi`，道→常 `qiannian`；用**独立的下游年代**判，
+   在 `reachWhy` 写清（如「至 1905 科举废，凡 2041 年 ⇒ qiannian」）。
+3. **`kind:'tuiyan'`（推演，绝大多数）**：`reason` 强制，必须是**制度史通说 / 后世明引**，
+   ✗ **不许编造「A 导致 B」的因果**；拿不准、无据 ⇒ **不写那条 impact**，别硬连（红线）。
+4. **`kind:'yuanwen'`（原文明引后世征引，如「漢承秦制」）**：`cite` 强制、逐字、
+   `curl -sk` 双证（`witnesses>=2`），字形照录（爲/為）。
+5. **`to[].label` 强制**（人读的落点描述，如「至今农历正月仍为岁首」）；`code`/`year` 可选 ——
+   落点若在本库 25 朝之内就填（KG 可 `code→chaoId`、`code:year→evt:code:year:idx` 连边）；
+   落点在库外（清/民国/今）只填 `label`。⇒ 既支持「千年后 X 朝仍在用」，也支持「至今仍运转」。
+6. 影响链**可级联**：如 `jin 1153 改燕京为中都` → `to:[{code:'ming',year:1420,label:'永樂定北京为京师'}]`
+   → 千年（元明清至今为都）。级联在数据里天然成图，KG/前端各自渲染。
+
+### 2.3 兼容与迁移
+- **不破坏**：impact 是新可选字段；老事件无 impact，前端/ KG 判 `if (e.impact)` 即可。
+- **归一 qin/beisong**：第二步各自 agent 把 layer 汉字→pinyin（并行改不同文件，不冲突）。
+- **tianxia 可选小改（唯一允许动 tianxia 的地方）**：在 shi passthrough 处加一行
+  `layer` normalizer（`事→shi 制→zhi 道→dao`）兜底，防某朝漏改。**非必须**，归一到位就不用。
+- **KG**：零改动。`node.raw.impact` 自动可用；将来若要 impact **边**（制→后世事），那是 KG 线
+  自己的 kg.js 改动，不属于本产品线。
+
+### 2.4 前端 `Biannian.vue` 契约（第二步建，这里先定契约）
+- 主视图：**编年轴**（按 year 排）+ **层筛选**（事/制/道，pinyin→汉字 label）。
+- **影响视图**：点一个制/道事件 → 展开 `impact`（reach 徽标、reason、to 落点、cite/推演标注）；
+  `to.code`/`year` 命中本库则可跳转到下游事件（级联链）。
+- **必须两种 zaichang 都吃**：array `[{wei,shuo}]` 渲染成列表；string 直接渲染；缺则不显。
+- **诚实标注**（照本仓铁律）：层与影响**都要显式标「推演」**；`kind:'yuanwen'` 的 impact 显示 cite；
+  西夏等**源限**朝的"薄"要说清是史料所限（§3.4），不许长成和"我们没做"同一句话。
+
+---
+
+## 3. 编年覆盖审计 + 补缺清单
+
+### 3.1 全表覆盖（实测，按起年排）
+
+| 朝 | 起讫 | 跨年 | 帝 | 事件n | 事/制/道 | 每百年密度 | 判定 |
+|---|---|---:|---:|---:|---|---:|---|
+| 秦 qin | -221~-207 | 14 | 2 | 22 | 17/2/**3** | 157 | 充足（超密） |
+| 西汉 xihan | -202~8 | 210 | 12 | **18** | 10/6/2 | **8.6** | ★**最薄**（密度全表最低） |
+| 新 xin | 9~23 | 14 | 1 | 25 | 16/9/0 | 179 | 充足（制富） |
+| 东汉 donghan | 25~220 | 195 | 12 | 42 | 36/6/0 | 21.5 | 偏薄 |
+| 曹魏 wei | 220~265 | 45 | 5 | 22 | 16/6/0 | 48.9 | 充足 |
+| 蜀汉 shuhan | 221~263 | 42 | 2 | 53 | 52/1/0 | 126 | 充足（超密） |
+| 孙吴 wu | 222~280 | 58 | 4 | 26 | 23/3/0 | 44.8 | 充足 |
+| 西晋 xijin | 265~316 | 51 | 4 | 21 | 17/3/1 | 41.2 | 充足 |
+| 东晋 dongjin | 317~420 | 103 | 11 | 23 | 18/5/0 | 22.3 | 偏薄 |
+| 北魏 beiwei | 386~534 | 148 | 12 | 127 | 120/7/0 | 85.8 | 充足（超密） |
+| 刘宋 liusong | 420~479 | 59 | 8 | 128 | 126/2/0 | 217 | 充足（超密） |
+| 南齐 nanqi | 479~502 | 23 | 7 | 21 | 21/0/0 | 91 | 充足；**制/道=0** |
+| 梁 liang | 502~557 | 55 | 4 | 24 | 23/1/0 | 43.6 | 充足 |
+| 北齐 beiqi | 550~577 | 27 | 6 | 17 | 16/1/0 | 63 | 充足 |
+| 北周 beizhou | 557~581 | 24 | 5 | 28 | 27/1/0 | 117 | 充足 |
+| 陈 chen | 557~589 | 32 | 5 | 30 | 30/0/0 | 94 | 充足；**制/道=0** |
+| 隋 sui | 581~618 | 37 | 3 | 37 | 26/9/**2** | 100 | 充足（制/道极富，最佳 impact 锚朝） |
+| 唐 tang | 618~907 | 289 | 21 | **46** | 45/1/0 | **15.9** | ★**薄**（289 年只 46 事，且制仅 1） |
+| 五代 wudai | 907~960 | 53 | 14 | 42 | 40/2/0 | 79 | 充足 |
+| 辽 liao | 916~1125 | 209 | 9 | 43 | 39/4/0 | 20.6 | 偏薄 |
+| 北宋 beisong | 960~1127 | 167 | 9 | 46 | 42/4/0 | 27.5 | 尚可 |
+| 西夏 xixia | 1038~1227 | 189 | 10 | **20** | 9/11/0 | **10.6** | **源限**（无正史，别硬补，见 §3.4） |
+| 金 jin | 1115~1234 | 119 | 10 | 21 | 15/5/1 | 17.6 | 偏薄 |
+| 南宋 nansong | 1127~1279 | 152 | 10 | **22** | 21/1/0 | **14.5** | ★**薄**（且制仅 1） |
+| 明 ming | 1368~1644 | 276 | 16 | **28** | 25/2/1 | **10.1** | ★**薄**（受"抠本纪"纪律约束，见 §3.3） |
+
+**世界观地板建议（每朝至少要撑得起的）**：(a) **每位在位皇帝 ≥1 件**；(b) 该朝**所有制/道转折点**在场；
+(c) 重大战/乱/亡国节点在场。密度目标只对下面的"薄"朝加压，其余充足朝**优先做 impact，不硬加事**。
+
+### 3.2 impact 优先锚点（②的正主活，102 个候选，先做这批）
+
+**10 个「道」事件 —— 千年影响链，最高优先**（impact 必做，reach 多为 qiannian）：
+| 朝 | 年 | 事 | 建议下游落点（推演，需据） |
+|---|---:|---|---|
+| qin | -221 | 定「皇帝」号 | → 帝制沿用至 1912（label） |
+| qin | -221 | 罢分封·置郡县 | → 中国地方行政骨架至今；原文可引「漢承秦制」(yuanwen) |
+| qin | -221 | 一法度衡石丈尺·车同轨·书同文 | → 文字/度量统一至今 |
+| xihan | -136 | 置五经博士 | → 经学官学至 1905 科举废，2041 年（层已析，直接抬成 impact） |
+| xihan | -104 | 正历·以正月为岁首 | → 农历正月至今 2130 年 |
+| xijin | 268 | 泰始律令成 | → 律典体例下沿（→隋开皇律→唐律） |
+| sui | 581 | 行新律（开皇律） | → 唐律之母本（houshi/qiannian） |
+| sui | 605 | 开通济渠（大运河） | → 南北经济动脉至今 |
+| jin | 1153 | 改燕京为中都 | → **级联** ming 1420 定北京→元明清至今为都 |
+| ming | 1380 | 罢中书·废丞相 | → 无相皇权独揽至 1912（清亦不设）；层已析 |
+
+**92 个「制」事件**里的高价值链（示例，非穷举，均**推演·需制度史通说据**）：
+`beiwei 485 均田` → `sui 609 均田` → `tang 租庸调` → `tang 780 两税法`（均田制的建立→鼎盛→瓦解，
+一条可级联的赋税史主线）；`xijin 265 中正六条` → 九品中正→门阀；`beiwei 486 三长` → 隋唐乡里；
+`sui 583 罢郡`（州县二级）→ 后世地方两级制。⇒ **建议第二步优先把这几条主线连成级联链**，
+最能体现「一步制度变革，千年后还在起作用吗」。
+
+### 3.3 补事件清单（③，第三优先，逐条**双证原文**，查不实宁可不补）
+
+- **TIER A（薄 + 高权重 + 正史充足，建议多补）**
+  - **西汉 xihan（+10~14 事）**：其自身 `CHAO_COVERAGE.shi` 已自认「事層遠遠不全」——
+    高帝/惠帝/高后/文帝/昭帝/宣帝/元帝/哀帝 编年事几乎没取。补：文景削藩·推恩、武帝征匈奴/张骞、
+    昭宣中兴、霍光废立、王莽代汉铺垫。**双证《汉书》本纪 + 卷十九表**。
+  - **唐 tang（+15~20 事）**：289 年仅 46 事、制仅 1，最不撑世界观。补：玄武门、贞观、永徽律（制）、
+    武周代唐、开元、安史之乱、元和中兴、甘露之变、会昌灭佛、黄巢、朱温代唐。双证新旧唐书。
+  - **明 ming（+6~10，受约束）**：⚠ 本朝守「抠本纪」纪律，一条鞭法/隆庆开关等**在志不在纪**——
+    按红线**不硬塞进 CHAO_SHI**，或另标 `source` 单列。可补本纪确有的：土木/夺门已在；
+    可加 郑和(已)、大礼议(已)。**补量有限，别为凑数破纪律**。
+- **TIER B（薄，补制 + 关键事）**
+  - **南宋 nansong（+6~10）**：绍兴和议、秦桧擅政、隆兴/开禧北伐、端平入洛、崖山亡国；制层补科举/文官制。
+  - **金 jin（+4~8）**：大定之治、贞祐南迁、蒙金战争（海陵迁都已在）。
+  - **辽 liao（+4~6）**：承天太后摄政、头下军州制（澶渊已在）。
+  - **东汉 donghan（+4~8）**：党锢、外戚宦官更替、黄巾。
+  - **北宋 beisong**：46 尚可；**优先 impact 而非加事**（庆历新政/靖康可补）。
+- **TIER C（充足 / 源限，不加或少加）**
+  - 隋、秦、蜀汉、刘宋、北魏、新 及南北朝诸短朝：**充足，优先做 impact**。
+  - **南齐 / 陈：制道=0** —— 若逐卷本纪确有制度条（如删定律科），可补 1~2 条制；无则不硬造。
+
+### 3.4 ★ 西夏特别说明（防止有人去"补薄"）
+西夏 20 事 / 189 年看着最薄，但这是**源限不是缺工**：二十四史**无《夏史》**，只能取
+《宋史·夏国传》《辽史》《金史》外国传的转述。**照红线：查不实宁可不补。** 它的"薄"是诚实的，
+与本仓「三种没有」（②我们瞎 / ③史官没记）同理——**前端必须把它标成"源限"，不许和"我们没做完"
+长成同一句"暂无"**。且西夏 11 制 / 0 道也是老实话（西夏之制随国亡而死，无一活到 1500 年）。
+
+---
+
+## 审计口径（实跑，不手数）
+- `node src/tianxia.js` 的 `count()` = `{chao:25, di:202, shi:932}`；层分布、密度、道/制清单由
+  scratchpad 脚本 `biannian_audit.mjs` / `dao_zhi_dump.mjs` 实跑 `allChao()` 打印。
+- 层值 pinyin/hanzi 分裂由逐文件 `grep -oE "layer: ?'(shi|zhi|dao)'"` vs `'(事|制|道)'` 计数得：
+  仅 qin(22 汉字)、beisong(46 汉字)，余 23 朝 pinyin。
+- 基线：`npm test` = **601 pass**（本步只写本 .md，未动数据/代码）。