makemd/archive/handover/目录结构优化方案.md

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 目录将变得更加整洁、有序，便于团队成员查找和使用文档资源。