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

本阶段保留 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 源码未修改。