Jyotisha/docs/tasks/PROGRESS-serif-headings-20260928.md

# PROGRESS · 全站标题改用自托管宋体，正文保持黑体（2026-09-28）

任务书：`docs/tasks/TASK-serif-headings-20260928.md`。产品 2026-09-28 授权直接执行（Claude 子代理）。

- 基线：`origin/staging` = `ebcee584`（任务书写作时为 `aa33399a`，开工时已前进到任务书自身的提交）
- 分支 / 工作树：`codex/serif-headings-20260928` / `.worktrees/serif-headings-20260928`（本地两个提交，**未推送**，由 Claude 验收后推）
- 环境：Node v22.14.0（`/exec-daemon/node`）；无 `.venv`，Python 一律 `/usr/bin/python3`（3.13，含 pyswisseph）；本机临时装 `fonttools 4.65.0` + `brotli 1.2.0`（`pip --user`，不进仓库依赖）；无 Docker；有 `/usr/bin/google-chrome`（无头）。
- BUG 编号：开工时最大 BUG-1079；本单不开新 BUG，只给 BUG-737 追加说明。

## 结论

| 项 | 结果 |
| --- | --- |
| T1 切片、脚本、Python 合同测试 | 完成（提交 1） |
| T2 接入字体栈 | 完成；`serif-sc.css` 由 `site-styles.ts` 引入（偏离，见下） |
| T3 合同测试改写 | 完成；三栏见下 |
| T4 性能与截图 | 未登录页真实测量；已登录首页 / 咨询 / 报告页用构建产物搭的静态页测量（环境缺口，见下） |
| T5 文档 | DESIGN §3、BUG-737、CHANGELOG、真机清单、任务索引已改 |
| 让步 | 未动用。报告页 493 KB（≤ 900 KB），截图已做 |

## T1 · 切片

- 上游：noto-cjk `Serif2.003`（tag SHA `9b0f1436`）的 `Serif/SubsetOTF/SC/NotoSerifSC-SemiBold.otf`，11,771,476 B，sha256 `517d9736…055bf5`，许可证为同 tag 的 `Serif/LICENSE`（OFL 1.1）原样放 `OFL.txt`。完整 URL、版本、sha256、改名方式写在 `frontend/src/app/fonts/serif-sc/SOURCE.txt`。源文件不进仓，脚本校验 sha256。
- 改名：family `Jyotisha Serif SC`、PostScript / CFF 名 `JyotishaSerifSC-SemiBold`；保留版权、设计者、厂商、许可证记录，删掉 Noto 商标记录和上游本地化名。
- 字表：《通用规范汉字表》一级 3500 + 二级 3000，取自 `shengdoushi/common-standard-chinese-characters-table`（commit `d9b599a9`，与 gov.cn 公布的 PDF 同源整理），逐字节原样放 `scripts/fonts/tygfhzb-level-{1,2}.txt`，来源与 sha256 写在 `scripts/fonts/CHARSET_SOURCE.txt`。脚本断言 6500 个互不重复的单字。
- **字频顺序（偏离任务书的「按字表顺序」）**：字表是按笔画排的，不是字频，拿它排前 1000 字首页会下载一堆无关切片。改用 `scripts/fonts/char_order.txt`（进仓，脚本 `--refresh-order` 生成）：
  1. 本仓语料（git 跟踪的 `frontend/src`、`frontend/docs`、`references/`、`SKILL.md`）用得最多的 300 字排最前——星、宫、盘、运这类标题常用字；
  2. 其后按 Google Fonts 自己公开的简体中文字频分档（`googlefonts/nam-files` 的 `slices/simplified-chinese_default.txt`，commit `2a68014b`，Apache-2.0，前 20 档为 FreqRange）；
  3. 同档内按本仓语料次数，再按字表顺序。只进仓派生结果，不进仓原文件。
  只用本仓语料的第一版实测：首页问候 + 人名常落到 5～6 片、最多 495 KB，超 300 KB 上限，所以加了第 2 层。
- 切片（共 30 片，`unicode-range` 互不重叠）：
  - `00` 基本拉丁、Latin-1 符号（不含带重音字母）、× ÷、通用标点、中文与全角标点、数字与常用符号，358 字，38.5 KB；
  - `01`～`19` 有字频信号的 3635 字，按名次每片 192 字，40～62 KB；
  - `20`～`29` 无字频信号的 2865 字按码位连续切块，每块约 287 字，72～109 KB。它们的 `unicode-range` 写成「块首到块尾，扣掉 00～19 已占的码位」，这样 CSS 小一半多。代价：6500 字以外、恰好落在某块跨度里的生僻字，会让浏览器下载那一片，但片里没有它的字形，照样退回黑体。
  - 任务书写的「前 1000 字切 2～3 片、其余每片 300～400 字」按实测改细：前 1000 字 3 片时，任何有 10 个汉字的标题都会把 3 片（≈241 KB）全拉下来，加上拉丁片就碰 300 KB 上限。
  - 单片最大 109,040 B（≤ 120 KB）。
- fontTools 参数：woff2、desubroutinize（CJK CFF 的 woff2 小约 13%）、保留 hinting（Windows 渲染）、默认 layout features、不重算时间戳。**同一输入跑两遍，30 个 woff2 + CSS 的 sha256 逐一相同**。
- `tests/test_serif_font_slices.py`（8 条）：字表 6500 字；每字都被覆盖；拉丁 / 数字 / 中文标点被覆盖；各片不重叠；CSS 引用的文件都存在、是 woff2、≤ 120 KB、没有多余文件；family / 字重 / swap；OFL 与 SOURCE 在；装了 fontTools 时再核对每片字形覆盖其字表字且家族名不含 Noto。已加入 `run_quality_gate.py` 的 quick 列表（否则门禁永远不跑它；偏离，见下）。

## T2 · 接入

- `--font-display` 按硬红线第 3 条改为 `"Jyotisha Serif SC", var(--font-inter, Inter), -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif`；`--font-body` 未改。注释改写。
- **引入位置（偏离）**：任务书写「由 `layout.tsx` 引入」。根 `layout.tsx` 同时是后台 `/admin` 的根布局，`site-style-isolation-contract` 明确禁止它引站点样式；所以 `serif-sc.css` 放在 `src/app/site-styles.ts` 里、紧跟 `globals.css`——`(app)/layout.tsx` 与登录页都经它引入，后台不加载。单独文件而不并进 `globals.css`，因为 `@font-face` 的 `unicode-range` 数据 gzip 后约 22 KB，超过硬红线 5 的 +8%。
- 报告标题规则清单（改之前 grep）：

  | 规则 | 改前 | 处理 |
  | --- | --- | --- |
  | `.personal-report-cover h1` | `--font-display` | 不动 |
  | `.personal-report-section-heading h2` | `--font-display` | 不动 |
  | `.personal-report-md-article h2`（长文报告章节） | `--font-display` | 不动 |
  | `.personal-report-md-article h1`（长文报告标题，markdown `#`） | 无规则，继承正文黑体 | **新增** `font-family: var(--font-display)`，只加字体不改字号 |
  | `.personal-report-subheading h2/h3`、`.personal-report-appendix h3`、`.personal-report-disclaimer h2`、`.personal-report-state h1`、`.personal-report-facts dd`、进度标题 | `--font-display` | 不动 |
  | `.personal-report-md-article h3` / `h4` | 无规则，继承正文 | **不动，请 Claude 定** |
  | `.personal-report-theme h3` | 显式 `--font-body` | **不动，请 Claude 定**（不在任务书例外清单里，但写法是刻意的） |
  | `.personal-report-chart-card h3` | `--font-body` | 例外，保留 |

  另：`.membership-*` 标题（点数 / 订阅页）显式 `--font-body` 600，不在例外清单也未改，请 Claude 定。
- 打印：`@media print` 里没有任何 `font-family` 覆盖，打印沿用同一条栈，屏幕上已加载的切片直接可用；没有实际打 PDF（见环境缺口）。
- 例外保留：`.conversational-narrative .message-markdown h2, h3`、`.personal-report-chart-card h3`、后台全部、四个根错误页（内联无衬线栈）。
- `var(--font-display)` 在 `globals.css` 里 40 → 41 处（多出的就是 md h1）。

## T3 · 合同测试

| 文件 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| `font-stack-loadable-contract.test.ts` `every quoted family … vendored or a system face` | 带引号 family 只能在 `SYSTEM_FACES` 里 | 也可以是 `serif-sc.css` 里 `@font-face` 声明过、且每个 `url()` 文件都存在的 family | 决策 1、3；「声明的字体必须可加载」这半条保留并扩展 |
| 同文件 `no CJK serif is reachable from the display stack` | 栈里不得有 Songti / STSong / SimSun / Noto Serif / Source Han Serif，不得以 `serif` 结尾 | **删除**，替换为 `the display stack leads with the self-hosted serif and never reaches a system 宋体`：首位是 `Jyotisha Serif SC`；不含 Songti / STSong / SimSun / Noto Serif CJK SC / Noto Serif SC / Source Han Serif；不以通用 `serif` 结尾、以 `sans-serif` 结尾；首位之后与 `--font-body` 完全相同 | 任务书 T3 明确要求删除并替换；BUG-737「不得落到系统宋体」保留 |
| 同文件 `display rank comes from weight, not from a second family` | 注释：共用一条无衬线栈 | 只改注释与报错文案；断言不变 | 字体没到时仍按无衬线显示，字重仍须承担层级 |
| `personal-report-theme-contract.test.ts` | 注释「`--font-display` 现在是无衬线」 | 注释改为历史说法并补 2026-09-28 说明；字重 500 断言不变 | T3 |
| `consultation-entrypoint.test.ts` | 同上 | 补一段注释；断言不变 | T3 |

新增 `frontend/tests/serif-headings-contract.test.ts`（7 条）：校正叙述 h2/h3 与报告分盘卡 h3 仍用 `--font-body`（精确选择器，避免被通用 `.message-markdown h2` 蒙混）；回答 h2、报告封面 / 章节 / 长文 h1 h2 用 `--font-display`；正文栈不含衬线；后台三文件不出现 heading face，`site-styles.ts` 引 `serif-sc.css` 而根 `layout.tsx` 不引；四个根错误页不引；每个 `@font-face` 是 swap、`500 700`、相对 `url()`（进 Next 打包），`layout.tsx` 无字体 preload。

测试名对比（`frontend/AGENTS.md` 的方法）：消失 1 条 = 上表被任务书要求删除的那条；新增 8 条（上面 7 条 + 替换断言 1 条）。

## 验证

| 项 | 基线 `ebcee584` | 交付 |
| --- | --- | --- |
| `tsc --noEmit` | 0 错 | 0 错 |
| `npm run lint` | 0 error / 127 warning | 0 error / 127 warning |
| `npm test` | tests 4248 · pass 4193 · fail 24 · cancelled 0 · skipped 31 | tests 4255 · pass 4200 · fail 24 · cancelled 0 · skipped 31 |
| 失败清单 | 24 条（全是需要 Docker / PostgreSQL 的数据库与部署套件） | 与基线逐条 `diff` 一致 |
| `python3 -m pytest tests/test_serif_font_slices.py` | — | 8 passed |
| `python3 scripts/run_quality_gate.py --profile quick`（Node 22 在 PATH） | — | 所有 Python 步骤通过（pytest 982 passed / 1 skipped）；最后一步 `npm test` 的 24 条失败与基线逐条一致（无 Docker）→ 退出码 1，属环境缺口。首次误用 Node 20 跑出 66 条失败（`mock.module`），已换 Node 22 重跑 |
| `python3 -m pytest tests/test_repo_privacy_markers.py -q` | — | 通过 |
| `next build`（`npm run build`，Turbopack） | `/` ○ Static | `/` ○ Static；全部路由的 ○ / ƒ 标记与基线逐行相同 |

构建备忘：Turbopack 在旧 `.next` 上增量构建时，曾输出旧的 `--font-display` 值（CSS chunk 未失效）；测量一律 `rm -rf .next` 后全量构建。

### 首屏 gzip（`index.html` 引用的全部 js / css，gzip -9 求和）

| | 基线 | 交付 | 变化 |
| --- | ---: | ---: | ---: |
| JS | 651,590 B | 651,590 B | 0（0%） |
| CSS 合计 | 43,493 B | 66,346 B | +22,853 B（+52.5%） |
| 其中 globals chunk | 42,248 B | 42,268 B | +20 B |
| 其中字体 chunk | 859 B（next/font 的 Inter / 行星符号 `@font-face`） | 23,692 B（上述 + `serif-sc.css`，Turbopack 合成一个 chunk） | +22,833 B |

CSS 超 +8%，按硬红线 5 已拆成单独文件（单独 chunk）。原因：30 片的 `unicode-range` 里 3635 个高频字只能逐个码位列出（字频顺序与码位无关，合不成区间），这是按字频切片、让首页只下 3～5 片的代价；无字频信号的 2865 字已改写成区间。宋体本身不 preload、`swap`，不阻塞首屏；这 23 KB CSS 是渲染阻塞的，4G 下约数十毫秒。

### 宋体切片流量（无头 Chrome，禁缓存，统计 `jyotisha-serif-sc-*.woff2` 的 `encodedDataLength`）

| 页面 | 测法 | 片数 | 字节 |
| --- | --- | ---: | ---: |
| `/`（未登录；本机无后端，显示「暂时无法进入 Jyotisha」卡与侧栏） | `next start` 真页面 | 5 | 226,060 |
| `/login`（未登录落地页） | `next start` 真页面 | 5 | 220,696 |
| 已登录空白首页（品牌字 + 问候「下午好，王芳」，虚构名） | 构建产物 CSS 搭的静态页 | 5 | 235,833 |
| 咨询回答（`h2`「D10 事业盘怎么读」+ `h3`） | 同上 | 4 | 171,696 |
| 完整个人报告（封面 h1 + 虚构读者 fixture `report-density-fictional-reader.json` 的全部 h1/h2，共 24 个标题；长文报告未进视口的章节也会先渲染 h2 占位，所以全部 h2 都算） | 同上 | 10 | 493,058 |

上限：首页 ≤ 300 KB、报告 ≤ 900 KB，均满足。离线估算（按切片成员与文件大小）：首页问候池 10 句 × 虚构人名为 131～309 KB，只有「周末愉快，赵磊」一句（6 片）略超 300 KB——问候随机、人名因人而异，首页会在这附近浮动；另一份 fixture `report-reader-main-fictional.json` 的报告为 7 片 ≈ 341 KB。

截图（不进仓）：`/tmp/claude-1000/-workspace-Jyotisha/d49dfa04-4e7a-47b2-80a7-8529c4c38f86/scratchpad/` 下 `shot_login.png`（登录页）、`final-home-loggedin.png`（首页问候）、`harness-consult.png`（回答 h2/h3）、`final-report.png`（报告封面与章节）。四张都确认中文标题（含同行的 `D10`、`Jyotisha`）为宋体、正文为黑体。

## T5 · 文档

- `frontend/DESIGN.md` §3：重写 Display 条目（新栈、自托管切片、Next 打包、500～700、swap 不 preload、中英混排、只许可加载字体、例外清单）；删除「CJK never takes a serif here」，改为「CJK 标题用自托管 Jyotisha Serif SC；绝不落到系统宋体」；根错误页条目补一句「标题也是刻意无衬线」；修掉表格下「Display headings use the serif stack at weight 400」。
- `docs/BUG_HISTORY.md` BUG-737：追加 2026-09-28 一行（任务书指定文字 + 实现摘要），状态仍 resolved，「最近更新」改为 2026-09-28。
- `CHANGELOG.md`：「标题改用宋体，正文仍是黑体」，Skill 不 bump，不改数据库。
- `docs/testing/serif-headings-checklist.md`：iPhone Safari、Windows Chrome / Edge、安卓 Chrome（至少一台国产机）× 首页标题 / 回答小标题 / 弹窗标题 / 报告封面 / 打印 PDF；SimSun 判别；Slow 4G 先黑体后宋体、无空白字；Network 里只有本站 `/_next/static/media/` 的小切片；生僻字退回黑体。
- `docs/tasks/README.md`：本单状态改为「已实现待验收」。

## 偏离任务书

1. `serif-sc.css` 由 `site-styles.ts` 引入，不在根 `layout.tsx`（理由见 T2：根布局也管后台）。
2. 字频顺序不用字表顺序，用「本仓语料前 300 + Google Fonts 字频分档」（理由见 T1）；因此多引用了一份 Apache-2.0 的派生数据，来源已记录。
3. 切片粒度比任务书建议的细：高频 19 片 × 192 字，低频 10 片 × ~287 字（理由见 T1，为满足首页 300 KB）。
4. 拉丁片不收 Latin-1 带重音字母（À–ÿ），只收 Latin-1 符号与 × ÷；任务书要求的「基本拉丁、中文与全角标点、数字与常用符号」都在。
5. 新增 `.personal-report-md-article h1` 用 `--font-display`（长文报告的标题行就是它的「封面」）。
6. `tests/test_serif_font_slices.py` 加进 quick 门禁列表（`scripts/run_quality_gate.py` +2 行）。

## 请 Claude 定

- `.personal-report-md-article h3`（长文报告小节，现继承黑体）、`.personal-report-theme h3`（显式黑体）、`.membership-*` 标题（显式黑体 600）是否跟随改宋体。本单均未改。

## 环境缺口

- 已登录首页、咨询回答、报告页没有登录态与数据库，无法在真页面上测；改用「同一次构建的 CSS chunk + 真实类名 + 虚构内容」的静态页测流量与截图。真页面的最终数字要在 staging 登录后用 DevTools 复核（真机清单第 7 条）。
- 打印 PDF 未实际导出：`@media print` 无字体覆盖，理论上沿用宋体；留给真机清单。
- 真机（iPhone / Windows / 安卓）与 Slow 4G 观感：`docs/testing/serif-headings-checklist.md`。
- 无 Docker：数据库 / 部署 24 条前端测试与基线同样失败；quick 门禁因此退出码 1。
- 未推送：按指示不推 staging、不推分支；部署核对由 Claude 做。

## Claude 独立验收（2026-09-28）

| 项 | 结论 | 证据 |
| --- | --- | --- |
| T1 切片 | 通过 | `tests/test_serif_font_slices.py` 8 passed；字体 name 表 ID1/16 = `Jyotisha Serif SC`，OFL 与 SOURCE 齐全 |
| T2 字体栈 | 通过 | `--font-display` 与硬红线 3 逐字一致；`--font-body` 未动 |
| T3 合同测试 | 通过 | Node 22：tests 4255 / pass 4200 / fail 24 / cancelled 0；24 条均为需 Docker 的数据库/部署套件，与 PROGRESS 基线一致 |
| tsc / lint | 通过 | tsc 0 错；lint 0 error / 127 warning（同基线） |
| `/` Static | 通过 | 干净 `rm -rf .next` 后 `next build`：`○ /` |
| 首屏 CSS gzip | **接受偏离** | +22.9 KB gzip（+52.5%），来自 3,635 个高频字逐字写进 unicode-range；已按任务书拆成独立 CSS。产品要的是全设备一致的宋体标题，这是它的直接成本，不再压缩 |
| 视觉 | 通过（静态） | 回答 h2/h3 与报告标题为宋体、正文黑体（执行方截图）；真机清单 `docs/testing/serif-headings-checklist.md` 欠 |
| 执行方提问：`.personal-report-md-article h3`、`.personal-report-theme h3`、`.membership-*` | 维持黑体 | 这些规则本来就不走 `--font-display`，不在任务书范围；产品看真机后再定 |