部署与开发
Docs / Product 同步指南
维护 TianGong LCA 产品行为与四语言公共文档之间的一致性。
公共文档解释用户可以完成什么；产品仓库决定系统实际上如何工作。修改用户流程、权限、路由、API 或截图说明前，必须先确认 ../platform 的当前实现。
事实来源
- 产品行为：
../platform - 中文文档源：
content/docs/**/page.mdx - 英文、德文、法文：同目录的
.en.mdx、.de.mdx、.fr.mdx - 文档路由与展示：
app/**、components/**、lib/** - 公共媒体：
public/assets/docs/**
四个语言文件表示同一个逻辑页面。结构、链接、操作步骤、约束或示例发生变化时，应在同一个提交中同步。
建议流程
- 在产品仓定位真实路由、组件、权限判断或 API 实现。
- 判断变化影响哪些用户、角色、数据空间与语言页面。
- 更新中文源和三个翻译文件。
- 使用当前产品界面验证按钮名称、顺序、状态、错误信息和角色差异。
- 运行文档站完整验证并用真实浏览器检查结果。
何时使用线上界面
以下情况不能只依赖代码阅读：
- 入口受角色或权限控制；
- 状态来自后端数据；
- 需要确认响应式布局、主题或可访问名称；
- 截图用于解释用户实际看到的界面。
不要把登录凭据、API Key、环境变量值或私有数据写入文档、截图、终端输出或提交记录。
截图原则
- 只在图片能明显降低理解成本时添加截图。
- 默认使用英文产品界面，除非主题本身是语言差异。
- 使用清晰裁切、可读字号和少量编号标注；不要在图片中堆叠长句。
- 复用同一公共资产给四个语言页面，在每种语言的正文中分别提供准确 alt 与解释。
- 将图片存入
public/assets/docs/<hash>/<slug>命名空间，并确认生成链接检查通过。
验证
pnpm lint
pnpm typecheck
node --test scripts/check-links.test.mjs
DEPLOY_ENV=ci CANONICAL_ORIGIN=http://localhost:3000 NEXT_PUBLIC_SEARCH_MODE=static pnpm build涉及视觉时，再检查 390px、1440px、超宽屏、浅色和深色主题，以及键盘焦点、搜索、语言切换和移动菜单。
无法在当前修改中完成的真实差异应立即记录到仓库根 TODO.docs-system-gaps.md 或创建可执行 Issue；不要只留在聊天中。