📋 古籍通平台更新日志 (Changelog)
记录古籍通开源公益数字人文项目的功能迭代、学术工具升级与版本演进历程。
v1.30.82当前版本
数据来源页 · 全量上游 URL
- **数据来源页补齐所有数据来源的官方 URL**(`/[lang]/data-source`,外链均经 `safeHttpUrl` 白名单过滤):
- 古籍原文(殆知阁 v20):上游仓库 `github.com/garychowcmu/daizhigev20`,并注明在线阅读经 `raw.githubusercontent.com` 与 CDN 镜像(jsDelivr / statically)按需拉取、本站不入库;
- 人物数据(哈佛 CBDB):官方主页 `projects.iq.harvard.edu/cbdb`、官方数据包仓库 `github.com/cbdb-project/cbdb_sqlite`(原有 How to Cite 规范页外链保留);
- 学术数据集:中研院史语所(`www.ihp.sinica.edu.tw`)与北京大学(`www.pku.edu.cn`)主页。
- **i18n**:新增 7 个词条 ×4 语言(zhTW/en/ja/ko),机构名独立成键便于链接文案;`i18n-verify` 0 缺失。
- **页脚文案精简与口径统一**:站点简介「公益古籍文献检索阅读与考据平台」→「公益古籍文献检索与阅读平台」(去掉已并入人物库的「考据」、补齐连词);数据说明后半句「原始数据 4.9GB 托管于上游仓库,本仓库零复制,阅读时按需加载」→「约 4.9GB 原文托管上游、按需加载,本站零复制」(保留真实部数、数据规模与零复制托管三项事实,去掉重复主语);`Footer.tsx` 的 `license` 兜底文案由过时的「开源协议」修正为「版权与授权」,与现行专有软件口径一致。
- 五语字典(`en` / `zhTW` / `ja` / `ko` 的 `core.ts`)同步替换两组词条键与译文;原型首页 `prototype/pages/index.html` 页脚简介同步;版本行格式 `V{版本号} · build {yymmddhhmm}` 保持不变。
v1.30.81
修复
- **IDE 内嵌预览注入脚本报错**:`src/app/layout.tsx` 在 `#app-container` 外补一层真实根容器 `#__next`(App Router 默认不生成该 id,而部分外部预览 / 检测脚本按 Next.js 传统约定查找该容器并调用 `getBoundingClientRect()`),消除 `Cannot read properties of null (reading 'getBoundingClientRect')`;新容器为无样式块级包装,CSS 依赖 `.app-container` 类选择器、不受影响,原有语义化 id 全部保留。
- 同批清理预览环境:此前两个 dev server(3000 与 3457)共写同一 `.next` 导致 `/_next/static/*` 批量 404,已收敛为单一 3457 server 并重建缓存(Playwright 多场景验证页面 0 运行时错误、静态资源 200)。
v1.30.80
热榜页全面审查与功能补全
- **数据加载**:本机数据(`useLocalRanking.ts`)与全站榜(`useGlobalRank.ts`)彻底解耦;目录有内存缓存,页面重新可见 / 跨标签页 `storage` 变更时静默重刷本机数据(不闪骨架);`mounted` 守卫避免卸载后 setState。
- **刷新**:同周期在途请求去重、跨周期 `seq` 丢弃旧响应;`lastRefreshAt` 仅在成功时写入,失败可立即重试;5 分钟定时刷新 + 页面重新可见且数据过期时立即补刷;手动刷新 30 秒冷却,在途请求视为已受理;刷新失败保留上次成功数据并顶部提示。
- **排序/筛选**:新增 `rankingSort.ts` 纯函数,四种排序(名次 / 阅读次数 / 书名 / 趋势,名次列始终显示真实名次);部类下拉按本期榜单真实部类动态生成并带条数;关键词繁简归一化;筛选、排序、周期切换均重置到第 1 页,失败/空态下仍保留已选部类以便清除。
- **分页/加载更多**:`RankingPager.tsx` 提供首页 / 上一页 / 页码窗口(省略号折叠)/ 下一页 / 末页,每页 10 / 20 / 50 条可切;显示「显示 x–y / 共 N 条」;越界页码夹紧;切页后列表滚回视口;`pageWindow` 纯函数可测。
- **趋势**:快照升级 `rank:snapshot:v2` 的 `current + previous` 双期结构,兼容 v1;同期刷新基线固定为 `previous`(趋势稳定),跨期自动推进;无基线仍显示「—」不误报「新上榜」。
- **状态处理**:全站榜加载骨架、刷新中 `aria-busy` + 「正在更新榜单…」、空数据 / 筛选空结果 / 四类异常 / 刷新失败 / 数据过期 各态独立;本机数据与馆藏分布各自骨架、局部错误与重试,不再阻塞整页;`MAX_ITEMS` 截断时提示「仅展示前 100 名」。
- **可访问性**:Tabs 支持 ← / → / Home / End 并移交焦点;分页按钮 `aria-current` 与页码标签;`role="tabpanel"` 带 `aria-busy`;状态区 `role="status"` / `aria-live`。
- **健壮性**:`parseRankResponse` 按 rank 重排,服务端乱序仍正确展示;`paginate` 返回 `start/end`;i18n 新增 22 键 × 4 语。
- **验证**:`tsc --noEmit` 0 错误、`next lint` 0 告警、`i18n-verify` 五语缺失键 0、单测全绿;新增 `tests/rankingSort.test.ts` 覆盖排序、动态部类、页码窗口、分页范围、双期快照、v1 兼容、脏数据归一化。
v1.30.80
热榜排序 / 分页 / 趋势与局部降级完善
- 新增 `src/lib/rankingSort.ts`(榜单名次 / 热度升 / 热度降,按 `bookId` 稳定打破平手)与 `RankingPager.tsx`(分页 + 每页条数选择)。
- 新增 `src/lib/rankingSnapshot.ts`:双期快照趋势,保存上一期名次快照(localStorage `rank:snapshot:v1`),计算 ↑N / ↓N / 持平 / 新上榜;首访无基线显示「—」。
- 数据层拆分:`useGlobalRank.ts`(全站榜,接口异常时局部降级回退本机热读 + 馆藏分布,不阻断阅读)+ `useLocalRanking.ts`(本机热读)+ `useRankingData.ts`(编排、5 分钟自动刷新、手动 30s 冷却、状态细分)。
- `useRankingData.ts` 重构瘦身;`RankingToolbar.tsx` 整合搜索 / 部类 / 排序 / 每页条数 / 刷新 / 分页。
- 注:本版本漏写 CHANGELOG 条目,于此随 v1.30.83 整理时回填。
v1.30.83
热榜 R91 剩余增强推进(单日体积闸 + 口径澄清)
- **R91② 单日写入体积闸实现**:`edge-functions/api/track.js` 按单 `clientId` 单日 **5 MB** 持久配额(`rank/quotas/<day>/<clientId>.json`,Blob 计数,跨实例/冷启动有效)拒绝超限写入(429 `quota_exceeded` + 服务端告警);抽 `enforceDailyQuota` 纯函数并补 `tests/rankQuota.test.ts`。
- **R91④ 核查澄清**:`scripts/sync-to-object-storage.mjs` 为同步 `public/index/` 静态索引到 CDN 的独立脚本、被 `deploy.yml` 的 `npm run sync:storage` 依赖,与热榜 Makers Blob 链路后端不同、无重复代码口径,**不删除**,仅文档澄清。
- **R91①③ 标注待平台/人工**:① 跨实例强限流需平台 KV(Makers Blob 非 KV);③ 榜单精度与 GA4 PV 对照验收待 GA4 数据(本机无法验收)。
- 推进 `docs/tasks.md` R91 条目状态;源码行数守约(均 ≤200)。
v1.30.79
热榜功能完善:核心范围、交互、条目信息与状态
- **核心范围明确(口径见 `docs/06-部署与迭代/项目部署上线规范.md` §5.5)**:热度指标**只采用匿名阅读次数 `views`**;PV / 互动量(点赞·评论·收藏)/ 分享量因需扩展写接口字段白名单与用户行为追踪,违反 AGENTS §2 禁止画像埋点与 §8 数据最小化,**明确不纳入**;分类维度为全站榜 + 本机按十大部类筛选的分类榜 + 纯本地的本机热读,**不做个性化推荐榜**(需用户画像)。站内 GA4 仅匿名聚合,不回灌榜单。
- **时间范围与排名规则**:新增 `1d` 聚合窗口,UI 四档「今日 / 本周 / 本月 / 总榜」,明确为**截至上次聚合时刻的滚动窗口**(近 24h / 7d / 30d / 全留存),非自然日/周/月;每日 00:10(UTC+8)由 CI 聚合,排名 `views↓ → bookId↑`(无并列、无加权、无衰减,可复现可审计);`generatedAt` 展示绝对 + 相对时间,超过 48h 标「数据可能已过期」。
- **交互**:关键词检索(复用 `toSimplified` 繁简归一化,匹配书名/部类/子类/id)、部类下拉、分页(10 条/页)、手动刷新(30 秒冷却,规避边缘限流)、自动刷新(5 分钟,与 CDN `max-age=300` 对齐,页面不可见时暂停);`requestSeq` 防慢响应覆盖。
- **条目信息**:书名直达链接 + 真实子类路径缩略内容 + 一级馆藏来源与卷帙规模(目录 size 换算)+ 阅读次数 + **较上一期名次趋势**(localStorage `rank:snapshot:v1` 快照,↑N / ↓N / 持平 / 新上榜;首次访问无基线显示「—」不误报)。产物仍只存 `bookId + views`,不扩展数据契约。
- **状态补齐**:区分「该时间范围暂无阅读记录」空数据、「没有符合条件的书目」筛选空结果、四类异常(404 不可用 / 429 请求过频 / 8 秒超时 / 数据格式异常)与刷新失败保留上次数据提示;接口不可用仍展示本机热读与馆藏分布。
- **后端契约(向后兼容)**:`aggregate-rank.mjs` 与 `--demo` 窗口改 `[1,7,30,0]`;`edge-functions/api/rank.js` 放行 `1d`;`verify-rank-deploy.mjs` 纳入 `1d` 但设为可选产物(旧站点缺失仅 WARN 不阻断验收);`rankingApi.ts` 返回带原因的结果并让空榜成为合法数据。
- **新增/拆分**:`src/lib/rankingView.ts`(检索归一化 / 筛选 / 分页 / 趋势 / 更新时间纯函数)、`RankingToolbar.tsx`(工具栏)、`src/app/styles/ranking-toolbar.css`,各源码文件均守 ≤200 行;`tests/rankingView.test.ts` 8 组单测纳入 `npm test`。
- i18n:30 个新键补入 en/ja/ko/zhTW 四语 `ranking.ts`;文档同步部署规范 §5.4/§5.5、`docs/README.md` 索引、`docs/tasks.md` R91 条目。
v1.30.78
修复:全站榜聚合作业从未运行(job 级 if 引用 secrets 上下文无效)
- **问题定位**:生产 `/api/rank` 对 7d / all 榜均返回 `404 rank_unavailable`,Blob 中不存在任何 `rank/<period>.json` 聚合产物,前端热榜页永久降级为「全站榜暂不可用」。根因是 `aggregate-rank.yml` 在 **job 级 `if` 中引用 `secrets` 上下文**——GitHub Actions 的 `secrets` 上下文在 job 级 `if` 中不可用(官方 Contexts 文档明确 job 级 `if` 仅支持 `github` / `needs` / `vars` / `inputs`),导致跳过条件失效、聚合作业从未按预期执行。
- **修复**:改为 job 级 `env.RANK_HAS_TOKEN` 中转(`jobs.<job_id>.env` 允许 secrets),判断移至 step 级 `if: env.RANK_HAS_TOKEN == 'true'`;未配置 `MAKERS_API_TOKEN` 时行为不变(整步跳过)。
- **后续动作**:推送后在 Actions 手动触发 `Aggregate Rank`(workflow_dispatch)验证首轮聚合;确认仓库 Secrets `MAKERS_API_TOKEN` / `MAKERS_PROJECT_ID` 已配置。注意零事件且零快照时聚合脚本按设计退出 1 不写产物(保护既有榜单),需先有真实阅读事件入库。
v1.30.77
热榜存储后端迁移:COS 直连签名 → Makers Blob SDK
- **存储层替换**:边缘函数 `edge-functions/api/track.js`(写)与 `edge-functions/api/rank.js`(读)改用 `@edgeone/pages-blob` 的 `getStore("rank")`,**免密钥**(平台自动注入命名空间,首次写入即创建),移除 `edge-functions/lib/cos.js` 的 WebCrypto COS V5 签名与 4 个 `COS_*` Secrets。
- **部署方式变更**:Makers 目录约定式部署(仓库 `edge-functions/api/*.js` → 路由 `/api/*`,随 Git 推送自动生效),不再需在控制台手动建函数或配触发规则;Makers Blob 命名空间 `rank` 由首次 SDK 调用自动创建(控制台仅只读浏览)。
- **CI 聚合客户端**:`scripts/lib/cosClient.mjs` 抽换为 `scripts/lib/blobClient.mjs`(接口对齐 `listKeys` / `getText` / `getJson` / `putJson` / `deleteKey`),`scripts/aggregate-rank.mjs` 与 `scripts/verify-rank-deploy.mjs` 零逻辑改动仅换配置来源;CI Secrets 由 4 项 `COS_*` 收敛为 1 项 `MAKERS_API_TOKEN`(+ 可选 `MAKERS_PROJECT_ID`)。
- **文档同步**:AGENTS.md §3 / §8 / §9、部署规范 §5.4、R91 方案落地状态与实现要点同步为 Makers Blob 口径;`aggregate-rank.yml` 跳过条件与 Secrets 注入同步。
- **安全**:消除边缘侧密钥泄露面(免密钥)、减少 CI Secrets 数量;采集与降级链路不变。
- **全量静态审查** `src/`(259 文件 / 23,855 行):严重 **0** / 一般 **0** / 优化 433(267 行过长 + 166 React PascalCase 文件名误报,非缺陷)。工具「硬编码敏感信息」判级 0/0,统一以直接源码核验为准——真实密钥硬编码 0 处、`dangerouslySetInnerHTML` 仅 `layout.tsx:77` JSON-LD 常量(安全)/`eval`/`innerHTML`/`new Function`/`catch(...:any)`/`console.log` 0 命中。
- **安全专项逐条实测**:serve-out 三道闸(L49 `decodeURIComponent` → L55 `[\x00-\x1f]` → L58 `path.resolve` 前缀白名单 + L108 仅 127.0.0.1)、url 双重防御(L15/L28)、download 净化、catalogSources 原型污染白名单(L9/L57–62)+ `Promise.all` 容错(L95–96)全完好;**v1.30.77 新增 Makers Blob 边缘函数全量核验**——`track.js` 字段白名单/同源校验/双重限流/≤1024B/一事件一对象/免密钥,`rank.js` 周期+limit 校验/缺失降级 404,`blobClient.mjs` 凭证仅环境变量;全部 0 安全缺陷。
- **质量门禁**:`tsc --noEmit` 0 错误;`i18n-verify` 五语 0 缺失(zhTW=785/en=ja=ko=805/UNION=805);单测 108/109(仅 `catalog.test.ts` 离线环境性失败);`node --check` 边缘函数+聚合脚本 6/6 通过。
- 详 `docs/09-项目审查/2026-11-13-R94/{代码审查报告-2026-11-13-R94.md, 安全审查与修复报告-2026-11-13-R94.md, review_results.json}`。
v1.30.76
热榜(R91 阶段三):全站统计的存储生命周期治理与部署验收
- **保留期真正生效**:`RANK_RETENTION_DAYS` 原仅被读取与打印、从未驱动任何行为(审查 C1)。现由 `scripts/lib/rankLifecycle.mjs` 的 `normalizeRetention()` 夹紧到 ≥30 天(不得小于最长滚动窗口),`planRetention()` 只清理边界日之前的完整 UTC 日,保证 7d/30d 榜零损失。
- **归档而非丢弃(审查 D2)**:超期日期目录先按 `(clientId, bookId, day)` 生成去重计数日快照 `rank/state/daily/<day>.json`(只存 bookId→views,隐私最小化),再删除该日源事件对象;`all` 榜改由「全部日快照 + 未快照日期的留存事件」合成,清理后总榜不失真、重跑幂等。快照不可解析时任务中止以保护既有榜单;删除失败仅告警、下轮自动补删;非事件格式对象一律不删。
- **代码结构**:Node 侧 COS V5 客户端抽为 `scripts/lib/cosClient.mjs`(列举/读/写/删/JSON,404 降级为 null),聚合编排 `scripts/aggregate-rank.mjs` 精简为纯编排;新增纯函数 `scripts/lib/rankLifecycle.mjs`;所有脚本 ≤200 行。边缘运行时仍用独立的 WebCrypto 版 `edge-functions/lib/cos.js`,两侧不耦合。
- **部署自检(推进 D4)**:新增只读脚本 `scripts/verify-rank-deploy.mjs`(`npm run verify:rank`),逐项输出 PASS/WARN/FAIL——对象存储连通与签名、事件量与日快照数、`rank/{7d,30d,all}.json` 结构及 48h 新鲜度、`/api/rank` 端到端返回、`/api/track` OPTIONS 预检;不写对象存储、不上报阅读事件(避免自检污染真实榜单),FAIL 退出 1。`--site` / `RANK_SITE_URL` 省略时只检查存储侧。
- **CI 与工作流**:`.github/workflows/ci.yml` 增加「热榜脚本自检」步骤(8 个文件 `node --check` + `aggregate-rank.mjs --demo`),弥补边缘函数/聚合脚本不参与 Next 构建的门禁盲区;`aggregate-rank.yml` 的 `workflow_dispatch` 新增 `retention_days` 入参(默认 30),并把生命周期口径写入注释;`package.json` 新增 `aggregate:rank` / `verify:rank` 脚本。
- **测试**:新增 `tests/rankLifecycle.test.ts` 8 组用例(保留期夹紧、key 严格解析、边界日不清理、已有快照不重复归档、日快照去重、脏快照剔除、all 榜叠加排序、全链路幂等),纳入 `npm test`。
- **文档同步**:R91 方案第〇节落地状态表补「阶段三 / 部署验收工具」两行与实现要点第 6 条;部署规范 §5.4 组件表、部署步骤、验证与运维段同步(含一键自检用法);`docs/tasks.md` R91 闭环 C1/D2、更新剩余增强清单。
- **门禁**:`npm run ci` 全绿(根目录清洁度 + lint + typecheck + 109/109 单测)、`node --check` 8/8、聚合 `--demo` 演练通过。**注意**:本轮改动全在 CI 侧脚本与文档,腾讯云真实桶未连接,DELETE / 签名 / 端到端探测需平台 Secrets 配好后由 `npm run verify:rank` 实测。
v1.30.75
根目录临时文件治理(固定子目录 + 清洁度门禁)
- **统一落盘位置**:所有一次性脚本 / 探针 / 运行日志 / 中间产物一律写入仓库根 `.tmp/`(已 gitignore、用完即清);根目录只保留工程清单、配置与社区惯例文档。历史散落的 16 个 `.tmp-*` 与 1 个 `review_results.json` 已统一移入 `.tmp/legacy-root-20261112/`(保留可再生产物、未直接删除)。
- **新增根目录清洁度门禁** `scripts/check-root-clean.mjs`(白名单制):校验顶层目录与根级文件白名单、`.tmp/` 必须为目录、`.gitignore` 必须保留 `/.tmp/` 规则;违规时输出改道指引并 `exit 1`。挂在 `npm run ci` 首步与 CI(`.github/workflows/ci.yml`)首个检查步骤,防止临时文件重新堆积。
- **不污染门禁**:`.eslintrc.json` 的 `ignorePatterns` 与 `tsconfig.json` 的 `exclude` 均加入 `.tmp/`,临时脚本不会被 Lint / 类型检查误扫。
- **忽略规则整理**:`.gitignore` 按依赖 / 构建产物 / 环境 / 数据产物 / 根目录清洁度分组,保留全部既有条目并补 `audit-*.json`、`*-result.json` 兜底;明确注释「禁止再往根目录写新文件」。
- **测试**:新增 `tests/rootClean.test.ts` 6 组用例(白名单放行、临时文件 / 未登记目录 / `.tmp` 类型 / 忽略规则校验),已纳入 `npm test`。
v1.30.74
设置面板宽度与选项排布修复
- **面板放宽**:`settings-panel` 的 `max-width` 由 420px 提升至 520px(移动端仍为 100% 宽自适应),四列 / 五列选项组得以单行排布;同步把窄屏断点由 480px 上调至 560px,使面板收缩与列数回退同时生效。
- **列数随选项数量自适应**:`SettingsOptionGroup` 新增 `data-cols`(按 `options.length` 收敛在 2–5 之间),`settings-options.css` 对应支持 2/4/5 列;正文字号 4 档、朗读语速 4 档不再折成「3+1」孤行,界面语言 5 语由 3+2 改为一行五列。
- **窄屏回退**:≤560px 时四列回退两列(2+2)、五列回退三列(3+2),避免列宽过窄挤压「简体中文」等四字标签。
- 门禁:`tsc --noEmit` 0 错误、`next lint` 0 告警、`i18n-verify` 五语 0 缺失。
v1.30.73
排行榜边缘函数加固(限流 + 事件校验)+ 周期审查 R93
- **边缘函数(track.js / rank.js)安全加固**:新增单实例内存近似限流——track 按 `clientId` 10 次/分 + IP 哈希 60 次/分双重计数,rank 按 IP 哈希 60 次/分;限流键只存哈希、不落盘、不含明文 IP;按时间窗口淘汰过期键,避免一次性 `clear()` 被大量随机 `clientId` 击穿。track 新增 `clientId` UUID 格式校验、声明 `content-length` 与解码后字节双重 ≤1024B 校验、未知字段拒绝(`bad_book_id`/`bad_dwell`/`bad_client_id`/`unknown_field` 细分错误码);rank 周期(`7d`/`30d`/`all`)与 `limit`(默认 50、上限 100、截断取整)严格校验,缺失产物一律 404 `rank_unavailable` 降级。密钥仅平台环境变量(`COS_SECRET_ID`/`COS_SECRET_KEY`/`COS_BUCKET`/`COS_REGION`),不入库、不落日志、不进响应体。
- **`CollectionsClient.tsx` 等超限文件拆分落地**:`CollectionDetail`(176→84 行)、`RankingClient`(173→74 行)按职责拆分为 `CollectionDetailParts`(191)、`RankingBoard`(88)、`useRankingData`(101)等子组件/纯函数,全部 ≤200 行;`collections.ts`(152)、`collectionsImport.ts`(83)、`collectionsStore.ts`(40)、`CatalogCategoryChips`(162)等新模块归位,组件层无明显引用死代码。
- **周期审查 R93(2026-11-12,验证 + 加固轮)**:`code-reviewer` 原生工具全量审查 `src/`(257 文件 / 23,855 行):严重 0 / 一般 0 / 优化 431(267 行过长 + 164 命名规范误报,非缺陷);安全专项逐条核验不变量全部完好(serve-out 三道闸、url 双重防御闭环、download 净化、track.js/rank.js 限流 + 校验 + 同源 + 密钥不入库、cos.js 环境变量签名、isSafeSurnameFile 穿越防御、catalogSources 原型污染白名单 + Promise.all 容错)。质量门禁:`tsc --noEmit` 0 错误、`i18n-verify` 五语 0 缺失、单测 94/95(仅 `catalog.test.ts` 离线环境性失败)、`node --check` 边缘函数/聚合脚本 6/6 通过。
- **版本纪律修复**:提交 `5ae3eaf` 已将全部被改 `src/` 文件头注释与三处边缘函数头注释升至 `v1.30.73`,但 `package.json` 与 `AGENTS.md` 遗忘仍为 `1.30.72`,本运行补 bump 至 `1.30.73` 以对齐代码实际状态。详 `docs/09-项目审查/2026-11-12-R93/`。