references/discovery-and-modeling.md
discovery-and-modeling.md
发现与建模
仓库审计
编辑前检查：
领域 问题
内容来源 数据库、Markdown、CMS、本地 JSON、外部 API？
数据归属 每个字段以哪个来源为准？
路由 哪些 URL 公开、可分享、被索引或需要认证？
领域视图 哪些组件已经渲染文章、图片、记录、Demo？
写操作 有哪些表单、编辑器、发送、上传或发布操作？
运行时 哪些状态必须在窗口关闭后继续存在？
响应式 哪些工作流必须在手机、平板和桌面运行？
运营后台 哪些后台任务需要高密度表格或编辑器？
交付 构建、缓存、revalidation、canonical、sitemap、部署？
回归范围 哪些行为必须保持不变？使用仓库原生命令和结构化 API。直接核对路由代码、schema 和运行时路径，不能只相信文档。
产品问题
选择 OS 隐喻前回答：
- 谁在使用产品，他们反复执行哪些任务？
- 哪些内容适合按空间或层级浏览？
- 哪些工作流需要持久状态或命令？
- 哪些路由必须可以直接访问和分享？
- 哪些内容只读，哪些必须可编辑或有事务行为？
- 移动端是真实产品界面，还是明确不做？
- 哪个视觉年代和平台语言适合这个主题？
- 哪些现有后端契约必须保持不变？
OS 适用性测试
至少满足以下两项才使用 OS 模型：
- 用户会反复浏览异构内容；
- 多个并行上下文对用户有帮助；
- 内容有有意义的层级；
- 工作流能自然映射为应用和命令；
- 持久运行时能改善连续性；
- 产品需要有记忆点的空间身份。
如果产品只是单一线性漏斗、单篇文章或落地页，OS 外壳通常只会增加阻力。
资源分类
对每种主要内容分类：
| 内容/工作流 | 资源形式 | 默认应用 | 直接路由 | 可写 | 持久运行时 | | --- | --- | --- | --- | --- | --- | | 文章 | 文档 | 阅读器/编辑器 | 是 | 可能 | 否 | | 图片集合 | 文件夹 + 图片 | 预览 | 是 | 可能 | 否 | | 搜索 | 应用 | Finder/搜索 | 可选 | 否 | 可选 | | 联系 | 应用/资源 | Mail | 是 | 发送 | 表单状态 | | 音乐/视频 | 应用/媒体库 | 播放器 | 可选 | 否 | 播放状态 | | Demo | 资源 | Browser | 是 | 由应用决定 | 可能 | | 后台记录 | 记录 | Control Panel | 需认证 | 是 | 草稿/任务 |
不要让展示名称成为数据标识符。稳定 ID 应来自数据库 ID、canonical path 或持久外部标识符。
数据适配器契约
源数据进入 OS 运行时前先归一化：
type ResourceNode = {
id: string
parentId: string | null
kind: string
name: string
modifiedAt?: string
children?: string[]
resource?: SerializableResource
availability?: 'available' | 'unavailable'
}必须保证：
- ID 唯一；
- parent 有效；
- parent/children 双向一致；
- 值可序列化；
- 排序确定；
- 单个分类失败不会拖垮其他分类；
- 缺少可选数据时有明确 fallback。
加载器和映射函数应能脱离 UI 独立测试。