wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
123 lines
6.1 KiB
Markdown
123 lines
6.1 KiB
Markdown
# Docs 目录结构优化方案
|
||
|
||
## 当前结构分析
|
||
|
||
当前 `docs` 目录结构存在以下问题：
|
||
|
||
1. **根目录文件过多**：根目录下存在多个零散文件（如 `AI_CONTEXT.md`、`API_MAP.md` 等），缺乏统一分类
|
||
2. **目录层次不够清晰**：部分文档可以进一步归类到更具体的子目录中
|
||
3. **命名规范不一致**：部分文件名使用中文，部分使用英文
|
||
4. **缺少统一的文档结构标准**：不同类型文档的组织方式不够统一
|
||
|
||
## 优化目标
|
||
|
||
1. **清晰的层级结构**：按功能和类型对文档进行分类
|
||
2. **统一的命名规范**：采用一致的文件命名方式
|
||
3. **便于维护和查找**：使文档结构更直观，易于导航
|
||
4. **符合项目规范**：遵循项目的整体架构和组织原则
|
||
|
||
## 优化方案
|
||
|
||
### 建议的目录结构
|
||
|
||
```
|
||
docs/
|
||
├── 01-overview/ # 项目概览和总览文档
|
||
│ ├── README.md # 文档总索引
|
||
│ ├── business-overview.md # 业务梳理（重命名自 business梳理.md）
|
||
│ └── project-map.md # 项目结构映射
|
||
├── 02-architecture/ # 架构相关文档
|
||
│ ├── global-blueprint.md # 全局业务蓝图（重命名自 global-business-blueprint.md）
|
||
│ ├── backend-arch.md # 后端架构（重命名自 arch-overview-v30.md）
|
||
│ ├── frontend-arch.md # 前端架构（重命名自 frontend-architecture.md）
|
||
│ ├── extension-arch.md # 插件架构
|
||
│ └── archive/ # 架构历史文档
|
||
├── 03-api/ # API 相关文档
|
||
│ ├── api-map.md # API 端点映射
|
||
│ ├── data-schema.md # 数据模型 schema
|
||
│ └── workflow.md # 业务流程
|
||
├── 04-development/ # 开发相关文档
|
||
│ ├── backend/ # 后端开发
|
||
│ │ └── server-readme.md
|
||
│ ├── frontend/ # 前端开发
|
||
│ │ └── frontend-dev-plan.md
|
||
│ └── extension/ # 插件开发
|
||
│ ├── extension-business.md
|
||
│ └── extension-initiation.md
|
||
├── 05-blueprints/ # 蓝图和集成方案
|
||
│ ├── frontend-integration/ # 前端集成蓝图
|
||
│ │ ├── TEMPLATE.md
|
||
│ │ ├── approval-center.md
|
||
│ │ ├── crm-hub.md
|
||
│ │ ├── finance-recon.md
|
||
│ │ ├── inventory-aging-ui.md
|
||
│ │ ├── inventory-forecast-replenishment.md
|
||
│ │ ├── logistics-health-ui.md
|
||
│ │ ├── multi-currency-recon.md
|
||
│ │ ├── oms-workbench.md
|
||
│ │ ├── order-profit-analysis.md
|
||
│ │ ├── platform-fee-watcher-ui.md
|
||
│ │ ├── stock-planner-ui.md
|
||
│ │ └── supplier-capacity-watch.md
|
||
│ └── archive/ # 蓝图历史文档
|
||
├── 06-guides/ # 指南和手册
|
||
│ ├── ai-friendly.md # AI 友好指南（重命名自 ai-friendly-guidelines.md）
|
||
│ ├── non-saas-multi-tenant.md # 非 SaaS 多租户指南
|
||
│ └── toc-early-stage.md # ToC 早期阶段指南
|
||
├── 07-quality/ # 质量保障
|
||
│ ├── frontend-delivery.md # 前端交付标准
|
||
│ ├── golive-checklist.md # 上线前检查清单
|
||
│ └── ux-acceptance.md # UX 验收清单
|
||
├── 08-governance/ # 治理和协作
|
||
│ ├── collaboration-board.md # 协作看板
|
||
│ ├── console-collaboration.md # Console 协作看板
|
||
│ ├── doc-maintenance.md # 文档维护计划
|
||
│ ├── task-specifications.md # 任务规格说明
|
||
│ └── archive/ # 治理历史文档
|
||
├── 09-benchmarks/ # 行业标杆
|
||
│ └── industry-benchmarks.md # 行业标杆综合分析
|
||
├── 10-design/ # 设计相关
|
||
│ ├── console-pipeline.md # 控制台流水线设计
|
||
│ ├── extension-collection.md # 插件采集设计
|
||
│ └── risk-registry.md # 风险注册表
|
||
└── 11-ai-context/ # AI 上下文文件
|
||
├── ai-context.md # AI 上下文入口
|
||
├── module-index.md # 模块索引
|
||
├── dependency-map.md # 依赖映射
|
||
├── code-style.md # 代码风格指南
|
||
└── repo-prompt.md # 仓库提示
|
||
```
|
||
|
||
## 优化说明
|
||
|
||
1. **按数字前缀排序**：使用数字前缀确保目录按逻辑顺序排列
|
||
2. **统一命名规范**：所有文件名使用小写短横线命名法
|
||
3. **中文文件名转英文**：将中文文件名转换为英文，提高国际化可读性
|
||
4. **分类更细致**：将根目录文件归类到相应的子目录中
|
||
5. **保持原有内容**：优化仅涉及目录结构和文件名，不改变文档内容
|
||
|
||
## 迁移步骤
|
||
|
||
1. **创建新目录结构**：按照建议的目录结构创建新的目录
|
||
2. **移动文件**：将现有文件移动到对应的新目录中
|
||
3. **重命名文件**：按照新的命名规范重命名文件
|
||
4. **更新引用**：更新所有文档中的交叉引用和链接
|
||
5. **更新文档索引**：更新 `README.md` 作为新的文档总索引
|
||
|
||
## 优势
|
||
|
||
1. **更清晰的结构**：按功能和类型分类，便于查找和维护
|
||
2. **更好的可扩展性**：新文档可以轻松归类到相应的目录中
|
||
3. **提高可读性**：统一的命名规范和目录结构使文档更易于理解
|
||
4. **符合最佳实践**：遵循标准的文档组织方式
|
||
|
||
## 注意事项
|
||
|
||
1. **保持兼容性**：确保所有现有链接和引用在迁移后仍然有效
|
||
2. **逐步实施**：可以分阶段实施迁移，避免一次性大规模变更
|
||
3. **更新导航**：确保文档导航和索引及时更新
|
||
4. **通知团队**：迁移完成后通知团队成员新的文档结构
|
||
|
||
---
|
||
|
||
通过以上优化方案，`docs` 目录将变得更加整洁、有序，便于团队成员查找和使用文档资源。 |