# 文档结构优化方案

## 当前问题

1. **文档分散**：根目录和 docs/ 目录都有文档，组织不清晰
2. **内容重复**：
   - BATCH_COMMAND_DESIGN.md 和 docs/batch-command-specification.md
   - TYPED_COMMANDS_SUMMARY.md 和 docs/typed-commands-guide.md
   - 多个文档包含类似的命令示例
3. **分类混乱**：设计文档、规范文档、实施指南混在一起
4. **导航困难**：缺少清晰的文档层次结构

## 新的文档结构

```
jrsoft-subway-protocol/
├── README.md                    # 项目概述和快速导航
├── CHANGELOG.md                 # 版本变更记录
├── docs/
│   ├── 01-protocol/            # 核心协议规范
│   │   ├── README.md           # 协议概述
│   │   ├── specification.md    # 完整协议规范（合并现有内容）
│   │   ├── message-types.md    # 消息类型详解
│   │   └── design-rationale.md # 设计理念和决策
│   │
│   ├── 02-commands/            # 命令系统文档
│   │   ├── README.md           # 命令系统概述
│   │   ├── simple-command.md   # Simple 命令详解
│   │   ├── batch-command.md    # Batch 命令详解（合并内容）
│   │   ├── complex-command.md  # Complex 命令详解
│   │   └── typed-commands.md   # 强类型命令系统（合并内容）
│   │
│   ├── 03-architecture/        # 架构相关文档
│   │   ├── README.md           # 架构概述
│   │   ├── edge-proxy.md       # Edge 代理架构
│   │   ├── device-protocol.md  # 设备到 Edge 协议
│   │   └── routing-flow.md     # 消息路由流程
│   │
│   ├── 04-integration/         # 集成和实施指南
│   │   ├── README.md           # 集成概述
│   │   ├── gateway-guide.md    # Gateway 集成指南
│   │   ├── backend-guide.md    # Backend 集成指南
│   │   ├── edge-guide.md       # Edge 集成指南
│   │   └── migration-guide.md  # 迁移指南
│   │
│   ├── 05-examples/            # 示例和参考
│   │   ├── README.md           # 示例概述
│   │   ├── command-examples.md # 各类命令示例
│   │   ├── flow-examples.md    # 流程示例
│   │   └── code-snippets.md    # 代码片段
│   │
│   └── 06-reference/           # 参考文档
│       ├── api.md              # API 参考
│       ├── glossary.md         # 术语表
│       └── faq.md              # 常见问题
│
├── examples/                    # 代码示例（保持不变）
└── src/                        # 源代码（保持不变）
```

## 文档合并计划

### 1. 批量命令文档合并
- 将 `BATCH_COMMAND_DESIGN.md` 和 `docs/batch-command-specification.md` 合并
- 新文件：`docs/02-commands/batch-command.md`
- 保留最新的 progress_update 设计
- 整合范围语法示例

### 2. 强类型命令文档合并
- 将 `TYPED_COMMANDS_SUMMARY.md` 和 `docs/typed-commands-guide.md` 合并
- 新文件：`docs/02-commands/typed-commands.md`
- 包含 C# 模型集成内容

### 3. 协议规范整理
- 将 `PROTOCOL_SPECIFICATION.md` 作为主要规范文档
- 移除其中的重复示例，引用专门的示例文档
- 新位置：`docs/01-protocol/specification.md`

### 4. 命令流程文档整理
- 整合 `SIMPLE_COMMAND_FLOW.md`、`COMPLEX_COMMAND_FLOW.md`
- 新位置：`docs/02-commands/` 目录下的各自文件

### 5. 架构文档整理
- `EDGE_PROXY_GUIDE.md` → `docs/03-architecture/edge-proxy.md`
- `docs/device-to-edge-protocol.md` → `docs/03-architecture/device-protocol.md`
- 添加消息路由流程文档

### 6. 集成指南整理
- `GATEWAY_INTEGRATION.md` → `docs/04-integration/gateway-guide.md`
- `MIGRATION_GUIDE.md` → `docs/04-integration/migration-guide.md`

## 实施步骤

1. 创建新的目录结构
2. 逐个合并和迁移文档
3. 更新所有内部链接
4. 删除旧文档
5. 更新 README.md 导航

## 优势

1. **清晰的层次结构**：按主题分类，易于导航
2. **避免重复**：相同主题的内容集中在一处
3. **渐进式学习**：从协议到命令，从架构到实施
4. **便于维护**：每个主题有独立的 README 索引
5. **专业性**：符合技术文档的最佳实践