Stooland Docs

Appearance

Docs 进一步优化方向 ​

在现有「结构清晰、易于理解、突出重点」的基础上，可逐步推进的优化方向。按优先级与投入分类，便于按需采纳。

一、补齐与沉淀类 ​

1. 业务文档（business/）充实 ​

  • 现状：business/README.md 仅说明范围，无具体领域文档。
  • 建议：
    • 从 storyboard/storyboard-business-flow.md、architecture/、api/README.md 提炼「AIGC 短视频」的领域模型与关键流程，沉淀到 business/ 下（如 aigc-storyboard-flow.md）。
    • 用 1～2 页说明核心实体、主流程与边界条件，并与 api/database 做交叉引用。

2. ADR 落地 ​

  • 现状：adr/README.md 仅有模板与约定，无编号 ADR 文件。
  • 建议：
    • 将已有重要决策（如「MCP + pybridge 分镜闭环」「FFmpeg 后备合成」「前后端响应格式约定」）整理为 ADR-0001、ADR-0002 等，便于追溯与评审。
    • 新决策按模板在 adr/ 下新增，并在 adr/README.md 或 00-INDEX 中加一栏「已采纳 ADR 列表」。

3. 术语表与缩写（Glossary） ​

  • 现状：文档中大量术语（AIGC、MCP、ICE、OSS、preset、storyboard 等）无统一释义。
  • 建议：
    • 在 docs/ 下新增 GLOSSARY.md（或 conventions/glossary.md），列出中英文术语、缩写及一句话释义。
    • 在 README/00-INDEX 中增加「术语表」入口，长文档首段可注明「术语见 GLOSSARY」。

二、可发现性与导航 ​

4. 「按问题找文档」入口 ​

  • 现状：00-INDEX 以「角色/任务」「功能名」为主，缺少「常见问题→文档」映射。
  • 建议：
    • 在 00-INDEX 或单独 docs/FAQ.md 中增加「常见问题速查」：如「本地跑不起来」「接口 401」「分镜生成失败」「FFmpeg 合成报错」等，每条对应 1～2 个文档或章节。
    • 与各 guide 文末「故障排查」相互引用。

5. 子项目入口统一 ​

  • 现状：分镜 Uni、Web、API 的「第一次运行」分散在 README、development-guide、DEVELOPMENT_CONFIG 等。
  • 建议：
    • 在 docs/README.md 或 00-INDEX「我是新人」中，用一张表列出：子项目名、本地运行命令、主要文档链接、默认端口，实现「一个表跑通所有子项目」。

6. 文档变更与版本 ​

  • 现状：文档无统一「最后更新」或版本标识，与代码演进的关系不清晰。
  • 建议：
    • 重要文档（如架构、API、产品愿景）在文首或文末增加「最后更新：YYYY-MM」或「文档版本：x.y」；大改时在 CHANGELOG 或 adr 中简述。
    • 若 OpenAPI 存在多版本，在 api/README.md 中说明版本策略与当前生效版本。

三、内容质量与一致性 ​

7. 指南类文档结构统一 ​

  • 现状：guides/、tool/、operations/ 下各文档结构不一（有的有「快速开始」有的没有，故障排查深浅不一）。
  • 建议：
    • 约定「功能/运维指南」最小结构：概述 → 快速开始（命令/配置）→ 详细说明 → 故障排查 → 相关文档；新写或大改时按此套用，旧文档逐步对齐。

8. 代码与文档的锚点 ​

  • 现状：部分文档提到「见 xxx 控制器/组件」但无具体路径或行号，重构后易失效。
  • 建议：
    • 关键说明处注明「对应代码：api/app/... / web/src/views/...」；若使用行号，注明「以当前版本为准，重构后请同步更新文档」。

9. 中英文与命名统一 ​

  • 现状：目录与文件名中英混用（如 admin-分镜布局优化.md、product-vision-and-positioning.md）。
  • 建议：
    • 新文档优先统一一种风格（如目录/文件名英文，正文中文）；历史文档可保留，在新文档与索引中保持命名风格说明，避免同一概念多种文件名混用。

四、自动化与维护 ​

10. 链接与引用校验 ​

  • 现状：文档内链、跨目录引用多为手写，易出现失效链接。
  • 建议：
    • 在 CI 或本地脚本中增加一步：扫描 docs/**/*.md 中的 ](...) 与 ](../...)，校验目标文件是否存在；可选：校验 openapi.yaml 与 api 文档中接口名是否一致。

11. 目录树与索引生成 ​

  • 现状：README 中的目录树、00-INDEX 的表为手写，新增文档时易漏。
  • 建议：
    • 用脚本根据 docs/ 目录结构生成「目录树」或「按目录列文档」的表格，在 README 或 00-INDEX 中引用生成结果；或约定「新增文档必须登记到 00-INDEX 与对应目录 README」。

12. 文档归属与责任人 ​

  • 现状：未明确谁负责更新哪类文档。
  • 建议：
    • 在 CONTRIBUTING 或团队约定中简单说明：如「架构类变更需同步 architecture/ 与 adr」「新增 API 需更新 api/README 或 openapi.yaml」「故障排查类更新需同步 FAQ/索引」。

五、优先级建议（如何选做） ​

优先级方向理由
高术语表（3）、按问题找文档（4）、子项目入口表（5）直接提升新人上手与日常排查效率
中business 充实（1）、指南结构统一（7）、ADR 落地（2）提升一致性与可追溯性
低文档版本/变更（6）、链接校验（10）、目录生成（11）长期维护与自动化，可按需逐步上

以上方向可拆成小任务分批推进，不必一次做完；每完成一类可在本文件或 README 中勾选或注明完成时间。