跳到主要内容

Docs / Product 同步指南

本页面向维护者与贡献者，说明 tiangong-lca-next-docs 如何与相邻产品仓 ../tiangong-lca-next 保持同步。

核心来源边界​

请把下面三类内容明确区分：

1. 中文公开文档源​

  • docs/**

这里是中文公开文档的主源。

2. 英文镜像​

  • i18n/en/docusaurus-plugin-content-docs/current/**

这里不是“自动永远正确”的翻译产物，而是需要人工维护的英文镜像。只要中文源变了，英文镜像 就应在同一次改动中同步更新。

3. 产品真实行为​

  • ../tiangong-lca-next

凡是页面入口、按钮名称、角色显示条件、数据范围、隐藏路由、导入导出流程等产品行为，应以 产品仓代码为准，而不是以旧文档为准。

默认核对目标​

默认线上核对地址：

  • https://lca.tiangong.earth/

../tiangong-lca-next 当前是根据 main 分支提交直接发布到线上系统的，因此一般不需要把 “线上是否与 main 一致”当成单独验证步骤。默认做法是：

  • 先以 ../tiangong-lca-next 的 main 分支实现作为产品行为来源
  • 只在以下情况下再额外打开线上系统复核：
    • 需要截图
    • 需要确认隐藏入口、角色显示条件或实时文案
    • 维护者明确怀疑部署漂移、缓存问题或线上异常

秘钥与验证信息​

本 docs 仓根目录 .env 中可能存在以下变量：

  • TIANGONG_LCA_USERNAME
  • TIANGONG_LCA_PASSWORD
  • TIANGONG_LCA_API_KEY

规则只有两条：

  • 只记录变量名，不记录变量值
  • 不要把实际值写进文档、截图说明、提交信息或聊天摘要

推荐维护流程​

1. 先看 backlog​

优先查看根目录中的：

  • TODO.docs-system-gaps.md

如果发现新的文档漂移，也应先把问题记录到这里，再开始改。

2. 先查产品，再改文档​

常见核对入口包括：

  • config/routes.ts
  • src/app.tsx
  • src/components/RightContent/**
  • src/components/ImportTidasPackage/**
  • src/components/ExportTidasPackage/**
  • src/components/LcaTaskCenter/**
  • src/pages/Account/**
  • src/pages/Processes/Analysis/**
  • src/pages/Review/**
  • src/pages/ManageSystem/**

这些位置是最容易出现文档漂移的热点。

3. 中文和英文同改​

如果改动的是公开站点内容，请默认同一轮完成：

  • 中文 docs/**
  • 英文 i18n/en/**

不要只改中文或只改英文，然后把另一边留到以后。

4. 导航变化要补入口​

如果新增页面、重命名页面或改变阅读路径，请同步检查：

  • sidebars.ts
  • docs/intro.md
  • docs/user-guide/overview.md
  • 英文镜像中的对应页面

5. 完成一个 gap，就回写 TODO​

TODO.docs-system-gaps.md 不是一次性清单，而是长期维护记录。

当一个 gap 被补齐、范围变化或决策改变时，应在同一次工作会话里更新状态和说明。

截图与 Playwright 规范​

当需要新增或替换系统截图时：

  • 优先使用 Playwright 做登录与截图，而不是手工凭记忆描述
  • 截图应尽量贴近项目中已有风格
  • 除非这张图本身就是为了说明中英文界面差异，否则默认使用英文界面截图，即使当前文档页 是中文
  • 如果只需要局部图，没有必要强行做成整屏 1920x1080；应优先保证局部截图的清晰度、采样密 度和与仓库既有图片一致的导出质量
  • 如需强调入口或关键字段，应添加红色框线或标注

作图与标注细则：

  • 优先使用数字编号而不是把整句中文或英文说明直接画进图里。
  • 数字编号的解释写在正文里，不要把长文字直接压在截图上。
  • 标注不能遮住用户真正需要看的控件、图标、按钮或字段。
  • 编号圆点尽量放在目标区域外侧；必要时用引线、加留白或放大裁剪，而不是把标注压在 UI 上。
  • 如果一个区域过于密集，应扩大截图范围、提高缩放比例，或拆成两张图，而不是让多个标注互相 打架。
  • 如果确实必须在图内放文字，文字要短、要干净，并且视觉层级低于真实界面本身。
  • 对局部图，优先使用更高的采样倍率，例如 deviceScaleFactor >= 2，并保持与仓库既有截图接 近的高密度 PNG 元数据（当前仓库大量旧图约为 144 DPI）。

文档目标与截图取舍原则：

  • 本站主要是给人类读者看的，因此在入口难找、结构复杂、仅靠文字不够直观时，应优先补 高价值截图。
  • 但没有必要把每一页都做成图册；如果文字配合准确的 UI 标签已经足够清楚，就不必强行加图。
  • 优先给以下类型页面配图：
    • 顶部全局控件或隐藏入口
    • 多步弹窗流程
    • 角色差异明显的工作区
    • 现有截图已明显过时的页面

适合使用截图的场景包括：

  • 顶部控件位置明显变化
  • 审核或系统管理等隐藏入口难以仅靠文字解释
  • 现有截图已经与真实界面明显不符

如果本轮只根据代码就能准确落文档，而截图工具链暂时不稳定，可以先完成文字同步，再单独补 截图；但若该页面主要面向人类操作指导且缺图会显著影响理解，应把截图补齐作为后续高优先级工 作。

最低校验要求​

完成公开文档修改后，至少执行：

npm run lint
npm run build

如果这次同步涉及大量结构变更，也建议手动浏览本地站点，重点检查：

  • 新页面是否出现在侧边栏
  • 中英文链接是否互相对应
  • 首页与用户指南导航是否能发现新内容