Podcast Catalog 项目交付文档
内网播客目录服务 + Qt/CEF 桌面客户端 —— 完整交付文档树。 生成日期：2026-06-11 ｜ 文档语言：简体中文（技术标识符保留英文）。 真实性原则：全部内容以仓库代码与活库实测为准，关键事实带
file_path:line锚点，不臆造。
一分钟了解项目
只读播客目录服务：把 ~7.8GB 源 JSONL（293,781 档播客 / 22,867,469 集剧集）入库 PostgreSQL，经 Next.js 16 REST API 暴露，由 Qt6 + CEF 桌面客户端（内嵌 Web UI）浏览、搜索、播放。本机作为内网服务端，客户端经 HTTP API 取数。
| 维度 | 现状 |
|---|---|
| 数据库 | PostgreSQL 16，8 表 / 17 索引 / 293,781 播客 + 22,867,469 剧集 + 354,508 分类关联 |
| API | Next.js 16 Route Handlers，13 个端点，381 测试全绿 / 覆盖率 94.7% |
| 客户端 | Qt6 + CEF 144 桌面端（macOS arm64），已签名 + 公证，500 轮压测 0 崩溃 |
| 翻页性能 | DB keyset + 预聚合 + 客户端预取，感知延迟 ~1ms |
| 交付物 | PodcastDesktop.dmg（159MB，公证完成），内网 HTTP 下载链接 |
文档树（阅读导航）
docs/delivery/
├── README.md ← 你在这里（总索引）
├── 01-architecture.md 系统架构设计
├── 02-database.md 数据库设计
├── 03-api-reference.md API 接口详细设计（供其他 Agent 集成）★
├── 04-modules.md 各模块代码设计
├── 05-implementation.md 实施记录
├── 06-testing.md 测试报告
├── 07-operations.md 运维与交付手册
└── 08-status-roadmap.md 项目进度与 P0/P1 路线图
| # | 文档 | 内容概要 | 主要读者 |
|---|---|---|---|
| 01 | 系统架构设计 | 三端架构图、技术栈裁决、部署拓扑、端到端数据流、与 v4 设计文档的落地对照 | 架构师 / 新人 |
| 02 | 数据库设计 | 8 表完整 DDL、17 索引、tsvector 全文检索、ETL 管线、一致性保证 | 后端 / DBA |
| 03 | API 接口详细设计 ★ | 13 端点逐个规格（参数/响应/错误/curl）、envelope、错误码、游标分页、字段映射、偏差登记 | 集成方 / 其他 Agent |
| 04 | 模块代码设计 | 服务端分层、Web UI SPA、桌面端 Qt+CEF（启动/消息泵/关闭握手/服务地址解析） | 全栈 / C++ |
| 05 | 实施记录 | 环境搭建、数据入库、三层性能优化（A/B 数据）、打包签名公证踩坑实录 | 工程 / 运维 |
| 06 | 测试报告 | 381 单测 + 一致性 0 差异、500 轮压测、性能基线、缺陷修复 | QA / 验收 |
| 07 | 运维与交付手册 | 服务启停、状态检查、客户端分发、quarantine 处理、故障排查 | 运维 / 支持 |
| 08 | 进度与 P0/P1 路线图 | 已完成清单、PRD 能力矩阵、P0/P1/P2 待办分级、风险登记 | 管理者 / 决策 |
按角色快速入口
- 要集成 API 的 Agent / 客户端工程师 → 直接看 03 API 接口详细设计（自包含，含 curl 示例与字段映射）。
- 要部署/运维这套服务 → 07 运维手册 + 05 实施记录。
- 要评估项目进度、排下一步 → 08 进度与 P0/P1。
- 要改代码 → 01 架构 → 04 模块 → 02 数据库。
- 要做验收 → 06 测试报告。
当前待办速览（详见 08）
P0（阻塞正式交付）
- Git 版本控制未落地 —— 代码几乎全部未纳入版本管理，误删即不可恢复
- 数据库无
pg_dump容灾备份 —— 数据单点 - 服务器常驻（launchd 未装 + 未防睡眠）—— Mac 睡眠即断服
- 内容版权法务确认 —— 音频/封面来自第三方 CDN
P1（重要增强）：真实多用户鉴权（JWT，当前固定 token）、限流（OWASP，未实装）、订阅/收藏（表已设计未实现）、下载队列 UI、Intel 双架构、Redis 缓存层。
源文档与代码索引（本交付树之外的一手材料）
| 类型 | 路径 |
|---|---|
| 原始需求 | 07_Podcasts_下载功能_PRD.md |
| 架构调研真源 | deepresearch_podcast-catalog-api-architecture_20260604_v4.md |
| API 契约（实现侧） | podcast-api/docs/API-DESIGN.md |
| 测试计划 | podcast-api/docs/TEST-PLAN.md |
| 性能报告 | podcast-api/docs/PERF-REPORT.md |
| 压测报告 | desktop/tests/STRESS-REPORT.md |
| 服务运维 | docs/SERVICE-OPS.md |
| 客户端分发 | DELIVERY.md |
| 环境安装清单 | INSTALL-CHECKLIST.md |
| 服务端代码 | podcast-api/src/（lib/services·lib/api·lib/db·app/api·validations） |
| ETL 脚本 | podcast-api/scripts/etl/ |
| 桌面端代码 | desktop/src/ + desktop/CMakeLists.txt |
| 打包/公证 | desktop/package.sh · desktop/notarize-on-server.sh |