BIPMaterialManager/docs

ERPAuto 文档指南

本文档是 ERPAuto 项目文档的分类指南和编写规范，用于：

• 指导文档的分类和归档
• 规范新文档的命名和格式
• 帮助开发者快速定位应创建的文档类型

---

📚 文档分类体系

一、按受众分类

分类	目录	受众	内容示例
用户文档	user/	最终用户	使用指南、配置说明、迁移指南
开发者文档	developer/	开发人员	架构设计、开发指南、模块说明
内部文档	internal/	项目维护者	分析报告、优化计划、模板

二、按内容类型分类

分类	目录	内容特点
功能特性	features/	功能说明、业务流程、重构概览
调试指南	debugging/	调试指南、快速参考、故障排查
测试文档	testing/	测试计划、测试报告、测试基础设施
模块文档	cleaner/, browser/, database/	特定模块的详细文档
计划文档	plans/	设计方案、实施计划
发布说明	releases/	版本发布记录

---

📝 文档命名规范

文件名格式

<主题>-<子主题>-<类型>.md

规则：

• 使用小写字母和连字符 (-)
• 不使用空格、下划线或大写字母
• 保持简短但有描述性

示例：

✅ user-override-match-feature.md
✅ settings-partial-save.md
✅ cleaner-validation-flow.md
✅ test-improvement-plan.md

❌ UserOverrideMatchFeature.md    # 驼峰命名
❌ user_override_match.md         # 下划线
❌ user override match.md         # 空格

类型后缀约定

后缀	用途	示例
-guide.md	指南类文档	erp-login-debug-guide.md
-quickref.md	快速参考	erp-login-debug-quickref.md
-flow.md	流程说明	settings-save-button-flow.md
-feature.md	功能特性	user-override-match-feature.md
-plan.md	计划方案	test-improvement-plan.md
-report.md	报告总结	TEST_REVIEW_REPORT.md
-template.md	模板文件	cleaner-execution-report-template.md
-overview.md	概览说明	validation-handler-refactor-overview.md

Plans 路径专用命名规范

plans/ 目录使用日期前缀命名法，便于按时间排序和管理：

<YYYY-MM-DD>-<描述>-<类型>.md

类型标识：

类型后缀	用途	内容重点
-plan.md	实施计划	任务分解、时间线、资源分配、风险评估
-design.md	设计方案	技术架构、接口设计、数据模型、决策理由

示例：

✅ 2026-04-13-cleaner-db-persistence-plan.md
✅ 2026-04-13-cleaner-db-persistence-design.md
✅ 2026-04-05-postgresql-integration-plan.md
✅ 2026-04-05-postgresql-integration-design.md

❌ cleaner-db-plan.md              # 缺少日期
❌ 2026-4-13-cleaner-db-plan.md    # 日期格式不正确（应为 2026-04-13）
❌ 2026-04-13-plan-cleaner-db.md   # 类型应在最后

相关文件对： 同一个项目通常会有配对的计划和设计文档：

• 2026-04-13-cleaner-db-persistence-plan.md - 实施计划
• 2026-04-13-cleaner-db-persistence-design.md - 设计方案

使用相同的日期和描述，便于关联查找。

---

🗂️ 分类决策流程

创建新文档时，按以下流程确定分类：

1. 文档的读者是谁？
   ├─ 最终用户 → user/
   ├─ 开发者 → developer/
   └─ 项目维护者 → internal/ 或其他专业目录

2. 文档的内容类型是什么？
   ├─ 功能说明 → features/
   ├─ 调试帮助 → debugging/
   ├─ 测试相关 → testing/
   ├─ 模块特定 → cleaner/, browser/, database/
   ├─ 设计计划 → plans/
   └─ 发布记录 → releases/

3. 是否需要快速参考？
   └─ 是 → 使用 -quickref.md 后缀，放入 debugging/

分类示例

文档主题	正确分类	理由
如何配置 ERP 连接	user/config-erp-guide.md	用户操作指南
日志系统设计	developer/architecture/logging-design.md	架构设计
登录失败排查	debugging/erp-login-quickref.md	调试快速参考
测试覆盖率分析	testing/coverage-analysis-report.md	测试报告
物料清理模块说明	cleaner/module-overview.md	模块文档
新功能实施计划	plans/2026-04-14-new-feature-implementation-plan.md	实施计划
数据库设计文档	plans/2026-04-14-database-schema-design.md	设计方案

---

📋 文档模板

指南类文档模板

# <功能> 指南

## 概述

简要说明文档目的和适用范围。

## 前置条件

列出使用该功能的前提条件。

## 操作步骤

1. 步骤一
2. 步骤二
3. 步骤三

## 常见问题

- Q: 问题描述
- A: 解决方案

## 相关文档

- [相关文档 1](link)
- [相关文档 2](link)

功能特性文档模板

# <功能名称> 特性说明

## 背景

为什么需要这个功能。

## 功能描述

功能的具体行为和预期结果。

## 用户流程

用户使用该功能的完整流程。

## 技术实现

关键实现细节（可选）。

## 影响范围

对其他模块的影响。

计划文档模板

# <项目名称> 实施计划

## 目标

项目要达成的目标。

## 范围

包含和不包含的内容。

## 任务分解

- [ ] 任务 1
- [ ] 任务 2
- [ ] 任务 3

## 时间线

预计开始和结束时间。

## 风险

可能的风险和应对措施。

---

🔧 文档维护

文档更新

• 功能变更时：同步更新相关文档
• 发现错误时：立即修正并提交
• 版本发布时：更新 releases/ 中的发布说明

文档审查

新文档创建后，应检查：

• 分类是否正确
• 命名是否符合规范
• 是否使用了模板
• 链接是否有效
• 是否添加到相关索引

废弃文档

过时的文档应：

1. 在文件顶部添加 > ⚠️ 已废弃 标记
2. 说明废弃原因和替代文档
3. 在下一个版本发布时移至 archive/ 目录

---

📖 根目录文档

docs/ 根目录仅保留跨category的项目级文档：

文档	用途
README.md	本文档 - 分类指南
build-and-release-guide.md	构建和发布流程
portable-auto-update-architecture.md	便携版更新架构

原则：如果文档不属于特定分类，且对项目整体重要，可放在根目录。

---

🔍 找不到合适的分类？

如果现有分类无法容纳你的文档：

1. 检查是否可以归入 internal/（内部文档）
2. 考虑是否应该创建新的子目录
3. 在提交 PR 时说明分类理由

---

最后更新：2026-04-14