05 实施记录（Implementation Record）

受众：工程师与 AI Agent。本册按"环境 → 入库 → 性能 → 打包 → 签名公证 → 经验"的实际施工顺序记录播客目录项目从零到可分发的全过程。 平台：macOS (darwin 25.3.0 / arm64) + Homebrew。日期：2026-06-04（脚手架）/ 2026-06-10~11（数据入库、性能、桌面端打包）。 真实性铁律：每条结论均给出 file_path:line 锚点。读不到/未实现的标注"待确认"，不臆造。

0. 一手事实速查（已核验）

1. 环境搭建（缺什么装什么）

1.1 体检结论（脚手架阶段，纯 API 子集）

hephyai-web-new-project skill 脚手架时对宿主机做体检，已装的不动，缺的本次装。来源 INSTALL-CHECKLIST.md:23-32：

Docker 运行时采用无 GUI 轻量方案：colima + docker CLI + compose 插件（INSTALL-CHECKLIST.md:36-54）：

brew install colima docker docker-compose
mkdir -p ~/.docker
# 让 docker CLI 找到 Homebrew 的 compose 插件
cat > ~/.docker/config.json <<'JSON'
{ "cliPluginsExtraDirs": ["/opt/homebrew/lib/docker/cli-plugins"] }
JSON
colima start -f       # 首次拉取 VM 镜像
docker ps && docker compose version && colima list

1.2 数据库/桌面端阶段的追加安装（2026-06-11）

来源 INSTALL-CHECKLIST.md:177-183。这一批是入库、桌面端打包阶段缺什么补什么：

CEF 落地已核验：third_party/cef/Release/Chromium Embedded Framework.framework 存在（flat 布局，见 §4/§5）。

1.3 ⚠️ colima 镜像撑满系统盘事故与外置盘符号链接处置

来源 INSTALL-CHECKLIST.md:185-188，必读事故记录：

性能测量基线就是这台重建后的 VM（4C/6G PostgreSQL 16），见 PERF-REPORT.md:4。

2. 数据入库实施

2.1 流水线总览（解压 → ETL → COPY → 索引）

入库分两条路径，复用同一套 schema.sql / finalize.sql / perf-stats.sql：

四步流水线（run-etl.sh:12-29）：

1/4 transform JSONL -> TSV   (node transform.mjs)
2/4 create staging schema    (schema.sql)
3/4 COPY into staging        (3 张 *_staging 表)
4/4 finalize                 (dedupe -> constraints -> indexes -> ANALYZE)
4b  perf stats               (预聚合统计表 + keyset 索引)

所有 psql 走容器：docker exec -i podcast-pg psql -U podcast -d podcast -v ON_ERROR_STOP=1 -q（run-etl.sh:10）。

2.2 解压与 transform（流式、不中断批次）

• 解压：dataset.7z（1.4GB）→ 6 个 shard（shard0..shard5/podcasts.jsonl），由 transform.mjs:79 读取。
• transform 策略（transform.mjs:81-150）：逐行 JSON.parse，脏行只 skip+计数、绝不中止批次（架构 §8.1）。输出 PostgreSQL COPY text 格式 TSV，转义规则在 transform.mjs:17-30（\ → \\、tab → \t、LF → \n、NULL → \N）。
• 时间戳/整数防御：toTimestamp（unix 秒 → ISO，越界/NaN 归 null，transform.mjs:33-40）、toInt（transform.mjs:42-46）。
• 背压：TsvWriter 4MiB highWaterMark + drain await（transform.mjs:48-63），保证 22.87M 行不爆内存。

2.3 COPY 与 finalize（staging → 索引）

• staging 表无约束、字段近 text（schema.sql:7-41），COPY 最快。
• finalize 用 DISTINCT ON 去重；孤儿剧集/分类（父播客缺失）由 EXISTS 子查询过滤掉（finalize.sql:52-71）。
• 索引在 bulk load 之后建（架构 §8.1 step 4，finalize.sql:97-119）——这是大表入库的关键顺序。
• 派生最新剧集字段：latest_episode_title / latest_publish_date 走 idx_episodes_podcast_pub 的 DISTINCT ON 回填（finalize.sql:98-112）。

2.4 真实统计（已核验）

来源 etl-work/etl-stats.json：

数据质量极高：293,781 行全部解析成功，0 脏行、0 无 UID 剧集。run-etl 末尾还会打印三表 count(*) 与放弃的 staging 表对账（run-etl.sh:31-35）。

3. 性能优化（三层，A/B 实测）

目标：app 端翻页毫秒级。逐层优化 DB → API → 客户端（PERF-REPORT.md:1-6）。测量环境：colima VM 4C/6G PostgreSQL 16（22.87M 剧集）+ Next.js 16 生产构建 + CEF 144。回归：381 测试全绿（PERF-REPORT.md:59）。

3.1 结果总览（基线 → 优化后）

来源 PERF-REPORT.md:9-18：

感知延迟测法：CDP 注入 MutationObserver，从点击到网格首节点内容变化的 performance.now() 差值（PERF-REPORT.md:20）。

3.2 DB 层（scripts/etl/perf-stats.sql）

正确性细节：podcasts.lang 单值，故跨语言 SUM 与 DISTINCT 等价（精确非估算，perf-stats.sql:6、PERF-REPORT.md:28）；category_sub_stats 排除 sub='' 链接（perf-stats.sql:29）。perf-stats 已接入 run-etl.sh:28 / reload.sh:21（步骤 4b），快照重建自动重算。

3.3 API 层（src/lib/services/catalog.service.ts + src/lib/api/memo.ts）

cursor 对客户端保持不透明契约（opaque），路由校验 cursor 与 sort 匹配（不匹配 → 错误码 1000，catalog.service.ts:139-149、PERF-REPORT.md:42）。

3.4 客户端层（public/app/app.js）

来源 PERF-REPORT.md:50-56：

净效果：翻页感知 0.5-1.0ms（PERF-REPORT.md:16-17）。

3.5 正确性保障

• 381 个既有测试全绿（含 60 档播客全字段一致性、keyset 全量翻页无重复/遗漏比对，PERF-REPORT.md:58-59）。
• 唯一测试改动：shows.test.ts 把断言 cursor 内部编码 {o:20} 的实现细节改为不透明契约断言（cursor 本就声明 opaque，PERF-REPORT.md:60）。
• 数据值零变化：all=293,781、news=38,112 与源数据对账一致（PERF-REPORT.md:61）。

4. 桌面端打包实施（desktop/package.sh）

打包流水线 7~8 步（package.sh:22-183）：fresh copy → bake server_url → macdeployqt → deep codesign → verify → DMG（→ notarize → staple）。

4.1 把 Qt 打进 bundle + 纯净 CEF framework

⚠️ 关键技巧（避免悬空符号链接）：CEF 是 flat framework（无 Versions/ 布局），macdeployqt 会尝试规范化它并造出悬空自指符号链接。处置：运行 macdeployqt 前先把 CEF framework 与 *Helper*.app 挪到 dist/cef-park/ 暂存，跑完再挪回（package.sh:40-47）。 裁剪：删 PlugIns/iconengines、imageformats——UI 在 CEF 内渲染，shell 不用；iconengines 还会拉入 macdeployqt 无法从拆分 Homebrew Qt 解析的 QtSvg（package.sh:49-51）。

构建后双重校验（package.sh:53-61）：① 主二进制不得残留 /opt/homebrew 链接；② bundle 内不得有任何悬空符号链接（否则 codesign/spctl 失败）。

4.2 深度签名（inside-out）

签名顺序由内向外（package.sh:63-107），证书 Developer ID Application: Beijing Goland Tech Co., Ltd. (5RCGYAV62A)：

entitlements（package.sh:65-76）为 Chromium/CEF 硬化运行时所需：com.apple.security.cs.allow-jit、allow-unsigned-executable-memory、disable-library-validation。

4.3 DMG 图标

build_dmg()（package.sh:120-146）：staging 目录 + /Applications 软链 + .VolumeIcon.icns；用 Swift NSWorkspace.setIcon 给挂载卷与 .dmg 文件本身打图标（resource-fork 元数据，须先于 codesign）；UDRW → UDZO 压缩后 codesign --timestamp 签 DMG。图标源 resources/AppIcon.icns（已核验存在，404KB）。

5. 签名公证踩坑实录（根因 + 修复）

三条均来自打包脚本注释与公证脚本的实战记录，每条给根因与修复。

① 27 个 Qt 依赖裸 dylib 漏签被 Apple 拒

② DMG 内 app 无装订票据 → 离线/沙盒来源机器 "can't be opened"

两次提交的原因：app zip 与 DMG 文件是两个独立公证记录，装订 DMG 需要它自己那一遍（package.sh:160-163）。

③ 微信等沙盒应用传输打特殊 quarantine → 改 HTTP 分发

5.1 服务器侧公证脚本注意事项（notarize-on-server.sh）

• 该脚本只做"上传公证 → 轮询 → 装订 → 验证"，不重签（notarize-on-server.sh:1-10）。
• ⚠️ 切勿用会重签的流程跑此 app：重签若丢失 JIT entitlements，Chromium 渲染进程在硬化运行时下会直接崩溃（notarize-on-server.sh:8-10）。
• 预检 codesign --verify "$DMG"，失败即回开发机重打包（notarize-on-server.sh:35-37）。
• 凭据：keychain profile 或 APPLE_ID + APP_PASSWORD + TEAM_ID（团队 5RCGYAV62A，与公司 StreamFab 同证书，notarize-on-server.sh:31-50）。
• 产物 <原名>_notarized.dmg，拷回即可分发（双击直开、无 Gatekeeper 警告，notarize-on-server.sh:73-80）。

6. 关键决策与经验沉淀

待确认 / 未实现

• 性能"后续可选"项（Redis 分布式缓存、episodes 列表预取、q 搜索深分页 keyset）当前规模不需要，未实现（PERF-REPORT.md:63-67）。
• 脚手架阶段版本偏差（zod 4 vs 规范 ^3.24 等）已记录待团队确认（INSTALL-CHECKLIST.md:154-171）；本项目实际栈以 §0 表为准。