probably-rendering-one-more-pixel-tonight/docs/flat-notes-stage.md

扁平笔记、标签与统一资源：变更说明

本阶段保留 posts.slug（旧链接与导入去重）、cover_asset_id（明确封面）、media_jobs（异步视频处理）及 contribution_events。删除 page_key、tags.parent_id、asset_variants、page_snapshots、render_jobs；原文件不删除，旧截图和加工文件转换为普通 assets/post_assets 引用。所有笔记平等，不引入附属文档关系。

文件与目的

• apps/waterfall-wiki/db/004_flat_notes.sql：新增事务迁移。保存旧截图引用，将加工文件转换为普通资源，合并同名标签且保留笔记/资源关联，再移除旧字段和表。
• apps/waterfall-wiki/src/lib/model.ts：更新扁平标签和资源来源字段，移除代码页绑定与截图数量字段。
• apps/waterfall-wiki/src/lib/library.ts：取消递归标签查询和代码页注册过滤；从普通资源计算加工类型，允许直接保存文字笔记。
• apps/waterfall-wiki/src/lib/asset-links.ts：新增共享视频资源的加工结果关联逻辑，锁住笔记以避免并发追加占用同一位置。
• apps/waterfall-wiki/src/lib/write.ts：创建笔记不再依赖 page_key，复用视频时补齐已有加工文件引用。
• apps/waterfall-wiki/src/worker.ts：仅保留视频任务，FFmpeg 输出进入普通资源表并关联到使用该视频的笔记，继续支持重试。
• apps/waterfall-wiki/src/lib/publish-learning-series.ts：发布完整文字和扁平标签，保留已有图片和封面，不再排截图任务；同步静态文档中可见的标签名称。
• apps/waterfall-wiki/src/lib/explore.ts：直接从普通资源展示笔记，图片计数排除视频加工文件；正文中提供加工资源链接，不再读取截图状态或代码页面。
• apps/waterfall-wiki/src/lib/api.ts：移除“必须注册代码页面”的旧错误映射。
• apps/waterfall-wiki/src/pages/api/media/[id].ts、apps/waterfall-wiki/src/pages/api/preview.ts：直接读取普通加工资源，同时兼容已有 variant 媒体地址，继续提供小文件预览。
• apps/waterfall-wiki/src/pages/api/tags.ts：名称全局唯一，支持带 # 创建；同名请求复用已有标签，不需要 parentId 或手写 slug。
• apps/waterfall-wiki/src/components/TagInput.tsx：新增 #标签输入、回车创建、现有标签建议和移除交互。
• apps/waterfall-wiki/src/pages/library/import.tsx：接入标签输入，成功后直接进入 ID 地址，更新视频处理提示。
• apps/waterfall-wiki/src/components/ExploreDetail.tsx：正文链接增加小图标和轻量行内样式。
• apps/waterfall-wiki/src/styles/globals.css：新增行内链接和标签输入样式及焦点反馈。
• apps/waterfall-wiki/src/components/Feed.tsx：旧列表组件改用平级标签，不再寻找子分类。
• apps/waterfall-wiki/src/pages/p/[slug].tsx：精简为兼容旧地址的跳转，移除失效的旧详情渲染代码。
• 删除 apps/waterfall-wiki/src/lib/snapshots.ts、apps/waterfall-wiki/src/components/ArticleGallery.tsx、apps/waterfall-wiki/src/pages/api/posts/[slug]/snapshots.ts、apps/waterfall-wiki/src/pages/p/[slug]/pages/[page].tsx、apps/waterfall-wiki/scripts/wait-snapshots.mjs：移除截图执行器、轮询界面、任务 API、画布路由与部署等待脚本。
• 删除 apps/waterfall-wiki/src/content/registry.tsx：移除 Wiki 代码作品注册绑定。
• Dockerfile、apps/waterfall-wiki/Dockerfile：不再复制截图等待脚本，保留现有依赖层缓存。
• scripts/deploy.sh：停止写入后备份，迁移失败时恢复兼容旧镜像的数据库，再恢复服务；删除截图等待与共享封面假设。
• apps/waterfall-wiki/tests/flat-note-migration.ts：新增隔离数据库 schema 的真实迁移验证，覆盖旧图片、视频文件、同名标签关联及保留的视频任务。
• apps/waterfall-wiki/tests/integration.test.ts：改为验证平级标签复用、无代码绑定的文字笔记、普通视频加工资源引用及已移除的截图入口。
• docs/monorepo.md：更新存储、迁移、媒体引用与截图流程退役说明。
• docs/flat-notes-stage.md：本阶段逐文件变更说明。

验证

本地 TypeScript 检查通过，18 项单元测试通过，部署脚本语法与 diff 空白检查通过。完整 PostgreSQL/S3 迁移、视频加工、生产构建与上线验证由 Wiki CI 执行。Studio 和 Python 源码未修改。