# ptest 文档维护指南

本文档定义 `docs/` 目录的归档规则和维护要求，避免后续开发中再次出现内部文档、用户文档、开发者文档混放的情况。

## 1. 文档分类规则

### 1.1 内部文档

以下内容统一放入 `docs/plan/`：

- 当前正式产品主线文档
- 历史规划资料
- 调研报告
- 历史会话纪要
- 临时讨论与推导材料

原则：

- 不作为对外文档入口
- 可以记录过程信息、决策细节、评审痕迹
- 允许保留历史版本和阶段性结论

### 1.2 面向用户文档

以下内容统一放入 `docs/user-guide/`：

- 安装方式
- 快速开始
- 基础操作
- 常见使用路径

原则：

- 面向框架使用者
- 优先解释“怎么用”
- 避免混入研发过程和内部计划状态

### 1.3 面向开发者文档

以下内容放入公开开发者文档目录：

- `docs/architecture/`
  - 解释系统设计、模块边界、关键架构决策
- `docs/development/`
  - 解释工程规范、开发流程、质量门禁、文档规范
- `docs/guides/`
  - 解释某个具体功能或模块的专题使用方法
- `docs/api/`
  - 解释 Python API 和代码示例

### 1.4 历史文档

以下内容放入 `docs/archived/`：

- 旧版本公开文档
- 已失效但仍有参考价值的设计文档
- 只用于历史追溯的材料

## 2. 新增文档时的判断顺序

新增文档时按这个顺序判断：

1. 这是内部研发沉淀，还是对外说明？
2. 如果对外，是面向用户还是面向开发者？
3. 如果面向开发者，它属于架构、工程规范、专题指南还是 API？
4. 如果只是历史保留，直接放 `archived/`

## 3. 根目录规则

`docs/` 根目录只保留少量总览型文件：

- `README.md`
- `STRUCTURE.md`
- `PROJECT_STRUCTURE.md`

不要在根目录新增以下类型文件：

- 阶段完成报告
- 实现总结报告
- 临时调研报告
- 单次开发记录

这类文件应进入 `docs/plan/`

## 4. 链接维护规则

- 新增或移动文档后，至少检查一次同目录 README 的链接
- 公开文档尽量链接到目录入口或当前有效文档，不依赖已删除文件
- 历史文档允许保留旧链接语义，但应在索引页说明“以当前结构为准”
- 如果一个目录承担公开入口职责，必须有 `README.md`

## 5. 命名规则

- 文件名使用英文或稳定缩写
- 优先使用大写编号前缀表达顺序或计划编号
- 避免在公开文档中使用临时性命名，如 `v2-final-final.md`
- 过程性报告优先使用 `_REPORT.md` 后缀

## 6. 更新规则

当发生以下情况时，应同步更新文档索引：

- 新增公开文档目录
- 移动文档到其他目录
- 新增用户文档入口
- 新增内部计划或完成报告类别

至少同步更新：

- `docs/README.md`
- `docs/STRUCTURE.md`
- 对应目录的 `README.md`

## 7. 与 Git 的关系

当前项目约定：

- `docs/plan/` 为内部文档区
- `.gitignore` 中已忽略 `docs/plan/`

这意味着：

- 该目录默认不进入远端仓库
- 如需调整内部文档的版本控制策略，应单独评估并修改 `.gitignore`

## 8. 最小检查清单

在提交一轮文档整理前，至少确认：

- 分类是否符合本指南
- 根目录是否仍然只保留导航型文件
- 新目录是否有 `README.md`
- 是否存在明显失效链接
- 是否把内部报告误放进公开目录
