docs-linking

name	docs-linking
description	MallBase 文档链接与放置规范；仅在新增、移动、删除 docs/ 或 README 文档索引时使用。

文档链接与放置规范

适用范围

• 所有项目文档的新增、移动、删除
• README.md 文档索引维护
• docs/ 目录与模块内文档组织

放置策略（混合策略）

项目级文档 → docs/

适用于跨模块、全局性质的文档：

• 安装部署指南
• 项目路线图（涉及多模块）
• 贡献指南
• 架构总览

功能级文档 → 跟随模块

适用于只与单一模块/功能相关的文档：

• 模块设计说明
• 接口契约
• 模块内测试说明
• 功能路线图（仅涉及单模块）

判断标准

条件	放置位置
文档内容涉及 >= 2 个模块	docs/
文档内容只涉及单一模块	模块目录内
部署、安装、环境相关	docs/
测试基线、触发矩阵	docs/testing/ 或 backend/tests/ 旁

README.md 索引规则

1. 所有文档必须在 README.md 的「文档」章节中以表格形式索引。
2. 表格格式固定为：

## 文档

| 文档 | 说明 |
|------|------|
| [标题](相对路径) | 一句话说明 |

3. 新增文档时必须同步更新：
   • README.md 文档索引表格
   • README.md 项目结构树中对应目录

项目结构树同步

README.md 中的项目结构树必须反映实际 docs/ 目录结构。新增或移动文档后，同步更新结构树中的 docs/ 部分。

强制规则

1. 禁止存在未被 README.md 索引的文档。
2. 禁止在 README.md 中链接不存在的文档。
3. 文档路径使用相对路径，从项目根目录起算。
4. 文档文件名使用 kebab-case（如 freight-template-roadmap.md）。
5. 文档内容使用中文（与项目整体一致）。

自检清单

• 新文档是否已按混合策略放到正确位置。
• README.md 文档索引表格是否已更新。
• README.md 项目结构树是否已同步。
• 文档链接是否可正常访问（相对路径正确）。