# Light 9 库升级总蓝图

> 分析日期 2026-06-13 ｜ 基于 9 库字段级升级规划（见 [`db-upgrade/`](db-upgrade/)）汇总 ｜ 只读规划，未动任何库。
>
> 上游依据：[`databases.md`](databases.md)（库性质归类）。本文把 9 份字段级规划里的 **50 个待拍板决策点**归纳成 **6 个跨库全局原则**——定了原则，绝大多数库级决策自动有答案，不必逐库 50 次拍板。

---

## 一、关键发现：50 个决策其实是 6 个问题问了 9 遍

逐库规划各自提了 5-6 个 `decisions_needed`，但横向一看，9 个库**反复在问同样的底层问题**。把它们归并并**已与用户定稿**：

| # | 跨库原则问题 | 哪些库在问 | **✅ 已定稿（2026-06-13）** |
|---|---|---|---|
| **G1** | 薄缓存**存不存数值**？ | 7/9 | **存数值 + last_checked + 来源指针**，无网可用但永远标 stale/as-of |
| **G2** | 偏科隔离用**新字段**还是**子串**？ | 7/9 | **catch-all 子串 `domain_scope=`**（仿 db01 ai_policy，零 CI 改动）；db07 已有的 `research_field` 正式字段保留 |
| **G3** | 转实时**是否强制联网**？ | 6/9 | **按有无 API 分两类**（见下），有 API 的**默认联网实时查、快照兜底**；无网明确报"未联网核验"不蒙混 |
| **G4** | 进 **CONVENTIONS §3 统一 schema**？ | 4/9 | **进 §3 作"可选通用字段"**（`domain_scope`/`last_checked`），子串实现、不强制每卡有 |
| **G5** | B 类**没有 API**的怎么转实时？ | db01/db04/db08 | **二分**：有 API（OpenAlex/HF/npm/GitHub）→查+缓存；无 API（真 JCR/中科院分区/竞赛费用/评分权重）→**指针模型**（存快照+指向官方源+投前强制人工核，**绝不用 OpenAlex 代理值冒充真 JCR**） |
| **G6** | README 卖点缩水的**诚实口径**？ | 4/9 | **诚实写明分层**，卡数从"N 张静态库"改为"锚点+实时校验+方法论层" |

> **G3 的关键修正（诚实红线）**：用户初始倾向"一律必须联网"，但有些字段（真 JCR IF、中科院分区是 Clarivate/中科院**付费数据**；竞赛加急费/评分权重**根本无 API**）联网也查不到。若强制联网会卡死、或被迫用 OpenAlex 2yr 代理值冒充真 JCR——**那恰恰是编造，踩诚实底线**。故定稿为按"有无 API"二分：有 API 强制联网查，无 API 走指针模型让用户投前自核，两者都绝不缓存假权威值。

### 决策栈一句话总结
**有 API 的事实**（被引/APC/star/许可）→ 默认联网查、本地快照兜底+标 as-of；**无 API 的事实**（真 JCR/CAS/竞赛费）→ 指针模型、指向官方源、投前人工核、绝不冒充；**偏科判断** → `domain_scope=` 子串过滤；**通用判断** → 方法论层留本地精养；**项目状态** → db09 本地持久。所有本地数值一律带 `last_checked`，冲突默认信在线。

---

## 二、升级后的统一架构（三层）

所有库重构后落到同一个三层结构：

```
┌─ 方法论层（A-通用判断，留本地精养，几乎不过时）
│   db02 patterns_library / db03 core_assumption+优劣+指标 / db05 WCAG+栅格
│   db06 action-title+data-ink / db07 制图通识 / db08 行政程序结构 / db01 reference_style映射
│   → 这是 Light 的护城河，对任意学科成立
│
├─ 薄缓存层（B-易变事实，快照值+last_checked+来源指针，冲突信在线）
│   db01 IF/被引/APC / db03 representative_papers / db04 citation/license
│   db05/db06 工具star/许可 / db07 工具被引
│   → 有 API 的实时查(OpenAlex/HF/npm/GitHub)，无 API 的走指针模型
│
└─ 偏科隔离层（A-偏科判断，domain_scope 子串打标，非该方向用户可过滤）
│   db01 CCF/CAS(中国语境) / db02 AI样本卡 / db03 奶山羊CV(47%) / db04 CV数据集
│   db07 volcano/KM/CONSORT(领域图型,已有research_field)
│
└─ 项目状态层（C，必须本地，db09 专属）
    project_card / decision_log / version_history
```

---

## 三、扣除全局原则后，真正还需单独定的库级决策（✅ 已全部定稿 2026-06-13）

定了 G1-G6，只剩这几个**库特有、原则覆盖不到**的，已逐个拍板：

- **db01**：① 178 行真 JCR/LetPub IF（付费源人工核出，OpenAlex 查不到）→ **保留为权威快照、不被在线代理值覆盖**（G3 二分的必然结果：无 API 的真 JCR 走快照+指针，不冒充）。② subject_area 261 个碎值（233 个只出现一次，按方向筛根本筛不动）→ **归并到 ~30 个受控大方向，原值作二级标签保留**。
- **db02**：samples_real.md 的 47 处**摘要原文** → **统一降级为结构笔记**（对齐 samples_recent 已有的"不录原文"纪律，消除版权暴露 + 两文件不一致）。偏科 → 先隔离打标，补非 AI 样本作为后续 P2。
- **db03**：82 张奶山羊/家畜 CV 卡（47%）→ **物理拆到子目录 `db03-methods/cv-livestock/`**，与通用方法卡硬隔离。
- **db04**：PapersWithCode SOTA/leaderboard API 未实测 → **只做 URL 存活校验，SOTA 留手动**，不赌 PWC API。
- **db08**：B 类（竞赛费用/评分权重/页数口径）几乎无 API → **指针模型**（G5 已覆盖，确认采用：存快照+指向官方源+投前强制人工核，不缓存数值）。
- **db09**：B-fact 超期提醒阈值 → **按字段类型分档**（计量值 IF/被引 90 天 / 许可 365 天 / 不变项不催）。

## 四、动手顺序（已定）

**先重构 db01**（问题最实、最伤诚实底线的 P0）。db01 完成、跑通后作为模板推广到 db04，再到其余库。先定库架构（本蓝图已完成），动到依赖某库的技能时该库已就绪。
