# 大型项目文档拆分规范

> 适用场景：功能模块多（>30页）、目录结构复杂、开发周期长的中大型项目
> 核心目标：不丢失需求细节 + 避免 Token 膨胀 + 支持独立开发

---

## 一、适用场景判断

### 触发条件（满足任一）

- 原型/设计稿页面数 > 30
- 功能模块 > 5 个
- 预估开发周期 > 2 周
- 文档内容超过 500 行

### 不适用场景

- 单页面应用或小型项目
- 功能模块 ≤ 3 个
- 页面数 ≤ 20

---

## 二、拆分流程

### Step 1: 资源盘点

```bash
# 统计原型/设计稿数量
find docs/ -type f -name "*.png" | wc -l

# 列出完整目录结构
find docs/ -type f -name "*.png" | sort
```

**输出**：确认总页面数，建立完整清单

### Step 2: 模块识别

根据目录结构识别一级模块：

```
docs/项目名/
├── 用户登录/        → 模块1
├── 交易管理/        → 模块2
├── 财务管理/        → 模块3
├── 客户管理/        → 模块4
└── ...
```

### Step 3: 创建文档结构

```
docs/
├── DEVELOPMENT_PLAN.md      # 主文档（精简版）
└── plans/                   # 模块子计划目录
    ├── 01-模块A.md
    ├── 02-模块B.md
    └── ...
```

### Step 4: 主文档内容（精简版）

主文档只包含：
1. 项目概述（技术栈、原型地址）
2. 页面统计总表（模块 + 页面数）
3. 模块子计划索引（链接到子文档）
4. 架构设计（目录结构、Mock系统）
5. 开发规范（简要）

**控制在 100-150 行以内**

### Step 5: 模块子文档内容（详细版）

每个模块文档包含：

```markdown
# 模块名称开发计划

> 模块：xxx
> 页面数：xx
> 上下文依赖：说明

---

## 页面清单

| 序号 | 页面名称 | 原型文件 | 类型 | 独立性 |
|------|----------|----------|------|--------|
| 1 | xxx | xxx.png | 列表/详情/表单/弹窗 | ✅独立 / 依赖xxx |

---

## 目录结构

src/views/main/模块名/
├── XxxList.vue
└── XxxDetail.vue

---

## 进度跟踪

- [ ] 子功能A (0/n)
- [ ] 子功能B (0/n)
```

---

## 三、页面分类标准

### 3.1 页面类型

| 类型 | 说明 | 示例 |
|------|------|------|
| 列表 | 数据表格 + 搜索 + 分页 | 用户列表、订单列表 |
| 详情 | 查看单条记录完整信息 | 订单详情、用户详情 |
| 表单 | 新增/编辑数据 | 新增用户、编辑订单 |
| 弹窗 | 轻量级交互 | 确认删除、选择项目 |
| Tab | 详情页内的子视图 | 订单详情-物流信息 |
| 仪表盘 | 数据概览 | 首页、统计页 |

### 3.2 独立性判断

| 独立性 | 说明 | 开发策略 |
|--------|------|----------|
| ✅ 独立 | 无需其他页面数据 | 可单独开发，优先处理 |
| 列表→详情 | 详情页依赖列表选中 | 通过路由参数 id 传递 |
| 表单内弹窗 | 弹窗是表单的子组件 | 随表单一起开发 |
| 流程依赖 | 需要前置步骤数据 | 通过 store/session 传递 |

---

## 四、开发顺序建议

### 4.1 整体顺序

1. **基础架构** - Mock系统、类型定义、通用组件
2. **独立列表页** - 所有无依赖的列表页（约70%）
3. **详情页** - 列表对应的详情页
4. **表单页** - 新增/编辑表单
5. **弹窗/交互** - 各种操作弹窗

### 4.2 模块内顺序

```
列表页 → 详情页 → 表单页 → 弹窗组件
```

---

## 五、Token 优化策略

### 5.1 开发时只加载当前模块

```
❌ 错误：一次性加载 DEVELOPMENT_PLAN.md（可能上千行）
✅ 正确：只加载 plans/02-交易管理模块.md（当前开发模块）
```

### 5.2 跨模块引用

如果开发当前模块需要参考其他模块：
- 只引用必要的类型定义
- 使用业务组件封装（如 CustomerSelect）
- 不加载完整的其他模块文档

### 5.3 进度更新

开发完成后，只更新：
- 当前模块文档的进度跟踪
- 主文档的完成状态（可选）

---

## 六、进度管理与中断恢复（重要）

> ⚠️ 大型项目开发过程中经常会遇到意外中断（如临时优化、Bug修复、需求变更等），必须建立进度保存机制

### 6.1 进度保存时机

**必须保存进度的场景：**

1. **每完成一个阶段/任务** - 主动保存当前状态
2. **被临时任务打断时** - 保存后再切换
3. **发现需要优化/重构时** - 先记录再执行
4. **长时间暂停前** - 如下班、会议等

### 6.2 进度记录格式

在项目根目录或 docs/ 下维护 `PROGRESS.md`：

```markdown
# 项目开发进度

## 当前状态

- **阶段**: Phase 3 - 用户登录模块
- **进度**: 2/8 页面完成
- **最后更新**: 2025-12-25 15:30

## 任务清单

### ✅ 已完成
1. [x] Phase 1: 基础设施 - Mock系统、类型定义、composables、通用组件
2. [x] Phase 2: API封装 - request.ts、各业务模块API

### 🔄 进行中
3. [ ] Phase 3: 用户登录模块 (2/8)
   - [x] Login.vue 完善
   - [x] 路由配置
   - [ ] TwoFactorAuth.vue
   - [ ] ResetPassword.vue
   - ...

### ⏳ 待开始
4. [ ] Phase 4: 交易管理模块
5. [ ] Phase 5: 其他业务模块

## 变更记录

### 2025-12-25
- **临时任务**: 优化 API 封装，结合 VitaSage 的 wrap 函数
- **影响范围**: src/api/request.ts, src/api/modules/*
- **状态**: ✅ 已完成
- **备注**: 新增 wrap 函数、文件上传下载、Mock 集成

### 2025-12-24
- **完成**: Phase 1 基础设施搭建
- **产出**: Mock系统、8个类型定义文件、3个composables、5个通用组件
```

### 6.3 中断处理流程

```
发现需要中断
    ↓
1. 保存当前文件
    ↓
2. 更新 PROGRESS.md
   - 当前进度
   - 中断原因
   - 待办事项
    ↓
3. 执行临时任务
    ↓
4. 完成后记录变更
    ↓
5. 恢复原任务
```

### 6.4 恢复开发流程

```
打开项目
    ↓
1. 阅读 PROGRESS.md
   - 确认当前阶段
   - 查看待办事项
   - 了解近期变更
    ↓
2. 加载相关模块文档
   - plans/xx-当前模块.md
    ↓
3. 继续开发
```

### 6.5 Todo List 工具使用

**推荐使用 `manage_todo_list` 工具跟踪任务：**

```typescript
// 创建任务列表
manage_todo_list({
  todoList: [
    { id: 1, title: "Phase 1: 基础设施", status: "completed", description: "..." },
    { id: 2, title: "Phase 2: API封装", status: "completed", description: "..." },
    { id: 3, title: "Phase 3: 用户登录", status: "in-progress", description: "..." },
    { id: 4, title: "Phase 4: 交易管理", status: "not-started", description: "..." },
  ]
})
```

**工具使用原则：**
- 开始新项目时创建完整任务列表
- 每完成一个任务立即更新状态
- 被打断时保存当前状态

---

## 七、质量检查清单

### 拆分完成后检查

- [ ] 所有原型页面都已记录（数量一致）
- [ ] 每个页面有明确的类型和独立性标注
- [ ] 主文档精简（< 150行）
- [ ] 模块子文档完整（含页面清单、目录结构、进度跟踪）
- [ ] 子文档之间无重复内容

### 开发过程检查

- [ ] 开发前只加载当前模块文档
- [ ] 完成后及时更新进度
- [ ] 复用组件及时提取到 common/business

---

## 七、示例项目结构

以「汇通管理后台」为例：

```
docs/
├── DEVELOPMENT_PLAN.md           # 主文档（~100行）
├── plans/
│   ├── 01-用户登录模块.md         # 8页
│   ├── 02-交易管理模块.md         # 29页（含8个子模块）
│   ├── 03-财务管理模块.md         # 17页
│   ├── 04-客户管理模块.md         # 18页
│   ├── 05-收款人管理模块.md       # 5页
│   ├── 06-推广管理模块.md         # 14页
│   ├── 07-促销管理模块.md         # 9页
│   ├── 08-风险管理模块.md         # 10页
│   ├── 09-系统设置模块.md         # 14页
│   ├── 10-消息与广告模块.md       # 9页
│   └── 11-其他页面.md             # 2页
└── 汇通管理后台/                  # 原型截图（143个.png）
```

---

## 八、MCP 工具调用

开发大型项目时，建议的工作流：

```typescript
// 1. 项目分析阶段
analyze_project({ projectPath: "/path/to/project" })

// 2. 加载当前模块规范
get_relevant_standards({ 
  scenario: "大型项目文档拆分",
  fileType: "md"
})

// 3. 开发具体模块时
get_relevant_standards({ 
  fileType: "vue",
  imports: ["element-plus"]  // 根据实际技术栈
})
```

---

**维护者**: MTA工作室
**创建日期**: 2025-12-25
**适用版本**: v1.0