BLD-ERPAuto/BIPMaterialManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add plans/ directory naming conventions

Browse Source 
- Add date-prefixed naming format: YYYY-MM-DD-description-type.md
- Document -plan.md and -design.md type suffixes
- Add examples from existing plan files
- Update classification examples to include plans/ naming
This commit is contained in:
Misaka_Company
2026-04-14 12:25:46 +08:00
parent 681f3ba517
commit 1f033eb315
1 changed files with 247 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

343
docs/README.md
View File

@@ -1,136 +1,287 @@
# ERPAuto 文档索引
# ERPAuto 文档指南
本文档目录包含 ERPAuto 项目的所有技术文档、用户指南和开发资料。
本文档是 ERPAuto 项目文档的**分类指南和编写规范**，用于：
## 📚 文档分类
- 指导文档的分类和归档
- 规范新文档的命名和格式
- 帮助开发者快速定位应创建的文档类型
### 👥 用户文档 (user/)
---
面向最终用户的使用指南和配置说明：
## 📚 文档分类体系
| 文档 | 说明 |
| ------------------------------------------------------- | ---------------- |
| [USER_GUIDE.md](user/USER_GUIDE.md) | 用户使用指南 |
| [MIGRATION_GUIDE.md](user/MIGRATION_GUIDE.md) | 迁移指南 |
| [CONFIG_FILE_LOCATION.md](user/CONFIG_FILE_LOCATION.md) | 配置文件位置说明 |
### 一、按受众分类
### 🎯 功能特性 (features/)
| 分类 | 目录 | 受众 | 内容示例 |
| -------------- | ------------ | ---------- | ---------------------------- |
| **用户文档** | `user/` | 最终用户 | 使用指南、配置说明、迁移指南 |
| **开发者文档** | `developer/` | 开发人员 | 架构设计、开发指南、模块说明 |
| **内部文档** | `internal/` | 项目维护者 | 分析报告、优化计划、模板 |
功能特性说明和业务流程：
### 二、按内容类型分类
| 文档 | 说明 |
| ------------------------------------------------------------------------------------------- | ------------------ |
| [user-override-match-feature.md](features/user-override-match-feature.md) | 用户覆盖匹配功能 |
| [settings-partial-save.md](features/settings-partial-save.md) | 设置部分保存功能 |
| [settings-save-button-flow.md](features/settings-save-button-flow.md) | 设置保存按钮流程 |
| [extractor-start-button-flow.md](features/extractor-start-button-flow.md) | 提取器启动流程 |
| [validation-handler-refactor-overview.md](features/validation-handler-refactor-overview.md) | 验证处理器重构概览 |
| [use-cleaner-refactor-overview.md](features/use-cleaner-refactor-overview.md) | Cleaner 重构概览 |
| 分类 | 目录 | 内容特点 |
| ------------ | ----------------------------------- | -------------------------------- |
| **功能特性** | `features/` | 功能说明、业务流程、重构概览 |
| **调试指南** | `debugging/` | 调试指南、快速参考、故障排查 |
| **测试文档** | `testing/` | 测试计划、测试报告、测试基础设施 |
| **模块文档** | `cleaner/`, `browser/`, `database/` | 特定模块的详细文档 |
| **计划文档** | `plans/` | 设计方案、实施计划 |
| **发布说明** | `releases/` | 版本发布记录 |
### 🐛 调试指南 (debugging/)
---
调试指南和快速参考：
## 📝 文档命名规范
| 文档 | 说明 |
| -------------------------------------------------------------------- | -------------------- |
| [erp-login-debug-guide.md](debugging/erp-login-debug-guide.md) | ERP 登录调试指南 |
| [erp-login-debug-quickref.md](debugging/erp-login-debug-quickref.md) | ERP 登录调试快速参考 |
### 文件名格式
### 🧪 测试文档 (testing/)
```
<主题>-<子主题>-<类型>.md
```
测试基础设施、报告、计划：
**规则：**
| 文档 | 说明 |
| ---------------------------------------------------------------------------------- | ------------------ |
| [TEST_FACTORY_USAGE.md](testing/TEST_FACTORY_USAGE.md) | 测试工厂使用指南 |
| [MOCK_LIBRARY_USAGE.md](testing/MOCK_LIBRARY_USAGE.md) | Mock 库使用指南 |
| [TEST_FIX_SUMMARY.md](testing/TEST_FIX_SUMMARY.md) | 测试修复总结 |
| [TEST_REVIEW_REPORT.md](testing/TEST_REVIEW_REPORT.md) | 测试评审报告 |
| [TEST_QUALITY_REVIEW_REPORT.md](testing/TEST_QUALITY_REVIEW_REPORT.md) | 测试质量评审报告 |
| [TEST_COVERAGE_IMPROVEMENT_PLAN.md](testing/TEST_COVERAGE_IMPROVEMENT_PLAN.md) | 测试覆盖率改进计划 |
| [test-improvement-plan.md](testing/test-improvement-plan.md) | 测试改进计划 |
| [P2_TEST_FIX_PLAN.md](testing/P2_TEST_FIX_PLAN.md) | P2 测试修复计划 |
| [P2_REFACTOR_SUMMARY.md](testing/P2_REFACTOR_SUMMARY.md) | P2 重构总结 |
| [REMAINING_TEST_FAILURES_ANALYSIS.md](testing/REMAINING_TEST_FAILURES_ANALYSIS.md) | 剩余测试失败分析 |
| [SKIPPED_TESTS_EXPLANATION.md](testing/SKIPPED_TESTS_EXPLANATION.md) | 跳过测试说明 |
- 使用**小写字母**和**连字符** (`-`)
- 不使用空格、下划线或大写字母
- 保持简短但有描述性
### 📦 模块文档
**示例：**
各功能模块的详细文档：
```
✅ user-override-match-feature.md
✅ settings-partial-save.md
✅ cleaner-validation-flow.md
✅ test-improvement-plan.md
| 目录 | 说明 |
| ---------------------- | --------------------------- |
| [cleaner/](cleaner/) | Cleaner 模块文档 |
| [database/](database/) | 数据库相关文档 |
| [browser/](browser/) | Playwright 浏览器自动化文档 |
❌ UserOverrideMatchFeature.md # 驼峰命名
❌ user_override_match.md # 下划线
❌ user override match.md # 空格
```
### 👨‍💻 开发者文档 (developer/)
### 类型后缀约定
面向开发者的技术文档：
| 后缀 | 用途 | 示例 |
| -------------- | ---------- | ----------------------------------------- |
| `-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` |
| 子目录 | 说明 |
| ---------------------------------------- | -------------- |
| [architecture/](developer/architecture/) | 架构文档 |
| [guides/](developer/guides/) | 开发指南 |
| [modules/](developer/modules/) | 模块文档 |
| [README.md](developer/README.md) | 开发者文档索引 |
### Plans 路径专用命名规范
**开发指南包括：**
`plans/` 目录使用**日期前缀**命名法，便于按时间排序和管理：
| 文档 | 说明 |
| ----------------------------------------------------------------------- | ------------ |
| [LOGGING_GUIDE.md](developer/guides/LOGGING_GUIDE.md) | 日志使用指南 |
| [LOGGING_IMPLEMENTATION.md](developer/guides/LOGGING_IMPLEMENTATION.md) | 日志实现文档 |
```
<YYYY-MM-DD>-<描述>-<类型>.md
```
### 📋 计划文档 (plans/)
**类型标识：**
设计计划和方案：
| 类型后缀 | 用途 | 内容重点 |
| ------------ | -------- | -------------------------------------- |
| `-plan.md` | 实施计划 | 任务分解、时间线、资源分配、风险评估 |
| `-design.md` | 设计方案 | 技术架构、接口设计、数据模型、决策理由 |
| 文档 | 说明 |
| ------------------------------------------------------ | -------------------- |
| [IMPLEMENTATION_PLAN.md](plans/IMPLEMENTATION_PLAN.md) | 实施计划 |
| 更多计划文件... | 按日期命名的计划文档 |
**示例：**
### 📝 发布说明 (releases/)
```
✅ 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 # 类型应在最后
```
| 文档 | 说明 |
| ------------------------------- | ---------------- |
| [README.md](releases/README.md) | 发布说明索引 |
| [1.12.0.md](releases/1.12.0.md) | v1.12.0 发布说明 |
| [1.11.1.md](releases/1.11.1.md) | v1.11.1 发布说明 |
| ... | 更多历史版本 |
**相关文件对：**
同一个项目通常会有配对的计划和设计文档：
### 🏗️ 内部文档 (internal/)
- `2026-04-13-cleaner-db-persistence-plan.md` - 实施计划
- `2026-04-13-cleaner-db-persistence-design.md` - 设计方案
内部计划、分析、模板：
使用相同的日期和描述，便于关联查找。
| 文档 | 说明 |
| ----------------------------------------------------------------------------------------- | -------------------- |
| [optimization-execution-plan.md](internal/optimization-execution-plan.md) | 优化执行计划 |
| [Configuration-Architecture-Analysis.md](internal/Configuration-Architecture-Analysis.md) | 配置架构分析 |
| [cleaner-execution-report-template.md](internal/cleaner-execution-report-template.md) | Cleaner 执行报告模板 |
---
## 📖 核心文档
## 🗂️ 分类决策流程
以下文档位于根目录，作为项目级参考：
创建新文档时，按以下流程确定分类：
| 文档 | 说明 |
| ---------------------------------------------------------------------------- | ------------------ |
| [build-and-release-guide.md](build-and-release-guide.md) | 构建和发布指南 |
| [portable-auto-update-architecture.md](portable-auto-update-architecture.md) | 便携版自动更新架构 |
```
1. 文档的读者是谁？
├─ 最终用户 → user/
├─ 开发者 → developer/
└─ 项目维护者 → internal/ 或其他专业目录
## 🔍 快速查找
2. 文档的内容类型是什么？
├─ 功能说明 → features/
├─ 调试帮助 → debugging/
├─ 测试相关 → testing/
├─ 模块特定 → cleaner/, browser/, database/
├─ 设计计划 → plans/
└─ 发布记录 → releases/
**按主题查找：**
3. 是否需要快速参考？
└─ 是 → 使用 -quickref.md 后缀，放入 debugging/
```
- 如何使用？ → [user/](user/)
- 如何调试？ → [debugging/](debugging/)
- 如何开发？ → [developer/](developer/)
- 如何测试？ → [testing/](testing/)
- 功能特性？ → [features/](features/)
- 发布历史？ → [releases/](releases/)
### 分类示例
| 文档主题 | 正确分类 | 理由 |
| ----------------- | ----------------------------------------------------- | ------------ |
| 如何配置 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` | 设计方案 |
---
## 📋 文档模板
### 指南类文档模板
```markdown
# <功能> 指南
## 概述
简要说明文档目的和适用范围。
## 前置条件
列出使用该功能的前提条件。
## 操作步骤
1. 步骤一
2. 步骤二
3. 步骤三
## 常见问题
- Q: 问题描述
- A: 解决方案
## 相关文档
- [相关文档 1](link)
- [相关文档 2](link)
```
### 功能特性文档模板
```markdown
# <功能名称> 特性说明
## 背景
为什么需要这个功能。
## 功能描述
功能的具体行为和预期结果。
## 用户流程
用户使用该功能的完整流程。
## 技术实现
关键实现细节（可选）。
## 影响范围
对其他模块的影响。
```
### 计划文档模板
```markdown
# <项目名称> 实施计划
## 目标
项目要达成的目标。
## 范围
包含和不包含的内容。
## 任务分解
- [ ] 任务 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 时说明分类理由
---