技术文档中心

Appearance

旧项目优化流程方案 ​

这是一套专为 Vue 3 + Element Plus + Leaflet/VueFlow 老项目 (scui v1.6.9) 定制的 AI 辅助开发全流程方案。

本方案的核心创新在于**“知识库先行”**：在写代码前，先让 AI 将项目路由和业务逻辑转化为结构化的 Markdown 文档（skills/ 目录），作为后续开发的“宪法”。

🚀 scui 项目 AI 辅助开发全流程方案 ​

📋 流程概览 ​

  1. 阶段一：项目唤醒与知识库构建 (核心：生成 skills/ 文档体系)
  2. 阶段二：需求拆解与方案设计 (核心：基于知识库制定非侵入式方案)
  3. 阶段三：增量开发与编码实施 (核心：测试驱动 + 分步执行)
  4. 阶段四：重构与债务管理 (核心：局部优化 + 文档同步)
  5. 阶段五：验证与回归 (核心：自动化检查 + 模拟 Review)

🟢 阶段一：项目唤醒与知识库构建 (Project Onboarding) ​

目标：扫描项目，在根目录生成 skills/routes/ 文件夹，为每个路由生成结构化 MD 文档，并生成全局索引 PROJECT_MAP.md。

步骤 1.1：初始化结构与规划 ​

操作：在 Trae 中打开项目，发送以下提示词。

markdown
# Role

你是一位精通 Vue 3、Element Plus、Leaflet 和 VueFlow 的高级前端架构师。

# Context

项目 "scui" (v1.6.9) 是一个基于 Vue CLI 5 的老项目。
核心依赖：Vue 3.3.4, Element Plus 2.2.32, Leaflet 1.9.4 (+ Geoman), @vue-flow/core, Vuex 4.1.0。

# Goal

构建一套供 AI 阅读的“业务技能知识库”，以便后续高效开发。
我们需要在根目录创建 `skills/routes/` 文件夹，并基于现有的路由配置 (`src/router`) 为每个业务页面生成详细的 Markdown 文档。

# Task 1: 分析与规划

1. 请深入分析 `@src/router/index.js` 及 `@src/router/modules/` (如果有) 下的所有路由定义。
2. 识别出所有的**业务页面组件** (views)，忽略纯布局、重定向或外部链接路由。
3. 规划生成的文档结构：
   - 根索引：`skills/PROJECT_MAP.md`
   - 子文档：`skills/routes/[route-name].md` (每个页面对应一个文件)

# Output Requirement

请先列出你计划生成的所有文件列表（文件名对应路由 name），并简要说明每个文件将包含的核心信息（如：路径、组件、Vuex 依赖、API 推测、Leaflet/VueFlow 特殊逻辑等）。
确认列表无误后，等待我的指令开始生成。

步骤 1.2：批量生成路由技能文档 ​

操作：确认列表后，发送此指令。这将生成类似 OpenAPI/Skill 的结构化文档。

markdown
# Action

现在请开始执行生成任务。针对每一个识别出的业务路由，请在 `skills/routes/` 目录下生成对应的 `[route-name].md` 文件。

# Document Template (必须严格遵守)

每个 Markdown 文件必须包含以下章节，格式需清晰，便于 AI 检索：

## 1. 路由元数据 (Route Meta)

| 属性        | 值                  | 说明                   |
| :---------- | :------------------ | :--------------------- |
| Path        | `/xxx`              | 访问路径               |
| Component   | `src/views/xxx.vue` | 物理文件路径           |
| Name        | `xxxName`           | 路由名称               |
| Title       | `xxx`               | 菜单标题 (含 i18n key) |
| Permissions | `[]`                | 所需角色权限           |
| KeepAlive   | `bool`              | 是否缓存               |

## 2. 业务功能摘要 (Business Summary)

- **核心功能**：简练描述页面用途。
- **关键交互**：列出主要操作按钮及其行为。
- **技术特征**：特别标注是否使用了 Leaflet (地图绘制/图层)、VueFlow (流程图编辑)、Tinymce (富文本) 等重型组件。

## 3. 代码结构拆解 (Code Structure)

### 3.1 核心组件依赖

- 列出引用的关键子组件 (`@src/components/...`) 及其作用。
- 列出使用的 Element Plus 核心组件。

### 3.2 状态管理 (Vuex Connection)

- **Read**: 明确列出读取的 `state` 或 `getters` (例如：`store.state.user.token`)。
- **Write**: 明确列出触发的 `actions` 或 `mutations`。

### 3.3 外部接口 (API Integration)

- 列出该页面调用的 API 函数 (参考 `@src/api`)。
- 简述关键请求的参数和返回结构。

## 4. AI 开发指南 (AI Dev Guide)

- **修改建议**：若需增加功能，建议优先修改哪个函数或模块？
- **避坑指南**：(重要) 指出已知的复杂逻辑、硬编码、或 Leaflet/VueFlow 实例销毁的特殊要求。
- **测试重点**：建议覆盖的核心场景。

## 5. 源代码关键片段 (Key Snippets)

```javascript
// 摘录核心的 setup() 逻辑、重要的 watch/computed 或地图初始化代码
```

Execution Rule ​

  • 必须深入阅读对应的 .vue 文件源码，禁止凭空猜测。
  • 对于涉及 Leaflet 或 VueFlow 的页面，必须详细记录实例初始化和销毁逻辑 (onBeforeUnmount)。
  • 逐个生成文件，每完成一个简要确认。
  • 开始执行...

### 步骤 1.3：生成全局索引文件
**操作**：子文档生成完毕后，发送此指令。
```markdown
# Task: 生成全局索引
所有子路由文档已生成。现在请创建 `skills/PROJECT_MAP.md`。

# Content Requirements
这份文档是 AI 理解项目的“入口”，必须包含：

1. **项目概览**
   - 技术栈版本清单 (Vue, Element Plus, Leaflet, etc.)。
   - 核心业务模块划分 (如：GIS 地图模块、流程引擎模块、系统管理模块)。

2. **路由导航树 (Route Tree)**
   - 以树状结构展示路由层级。
   - 每个节点必须带上相对链接：`- [页面名称](./routes/[filename].md)`。

3. **跨模块依赖矩阵**
   - 总结哪些页面强依赖特定的 Vuex Module。
   - 总结高频复用的公共组件 (`@src/components`)。

4. **AI 协作协议 (Collaboration Protocol)**
   - **规则 1**：回答具体业务问题时，必须优先引用 `skills/routes/` 下的对应文档。
   - **规则 2**：修改代码前，必须检查文档中的“避坑指南” (特别是地图/流程图实例管理)。
   - **规则 3**：涉及多页面联动时，先列出受影响的文档列表。

5. **快速启动指引**
   - 示例：“若要修改地图功能，请先阅读 ./routes/map-editor.md”。

请生成这份高质量的索引文件。

步骤 1.4：激活验证 ​

操作：发送此指令测试 AI 是否真正理解了知识库。

markdown
# Verification Test

假设我要在“地图轨迹管理”页面（请根据 `@skills/PROJECT_MAP.md` 找到对应文档）增加一个“导出视频”的功能。

请依据知识库文档：

1. 定位并引用相关的 `.md` 文件。
2. 总结该页面的当前架构、Vuex 依赖和 API 情况。
3. 给出一个初步的实现思路，明确指出需要修改的文件（严格基于文档指引）。
4. 暂时不要写代码，先展示你对文档的理解。

🔵 阶段二：需求拆解与方案设计 ​

目标：基于知识库，制定安全、兼容的新需求方案。

步骤 2.1：方案设计与风险评估 ​

操作：输入具体新需求。

markdown
# New Requirement

[在此处详细描述新需求，例如：在地图编辑器中支持导入 GeoJSON 文件并自动拟合视图]

# Constraints

1. 必须兼容现有的 Leaflet 封装逻辑 (参考 @skills/routes/[对应页面].md)。
2. 遵循 Vuex 4 模块规范，不直接修改 State。
3. UI 风格严格匹配 Element Plus 2.2.32。
4. 确保不破坏现有的地图初始化及销毁流程。

# Task

基于 @skills/PROJECT_MAP.md 和相关路由文档，提供 3 种技术方案：

1. **保守方案**：最小化改动，直接在现有组件追加。
2. **重构方案**：抽取通用逻辑到 Hook/Util。
3. **隔离方案**：新建独立组件集成。

对每种方案分析：

- 需修改的文件列表。
- 对现有功能（如原有的绘图、测距）的潜在影响。
- 推荐指数及理由。

最后，选择最佳方案，并将其拆解为 5-8 个原子任务步骤 (Task List)。

🟠 阶段三：增量开发与编码实施 ​

目标：按任务列表执行，测试驱动，小步快跑。

步骤 3.1：编写/更新测试用例 ​

操作：

markdown
任务执行：步骤 1 - 测试准备
依据设计方案。

1. 检查项目现有的测试框架 (Jest/Mocha)。
2. 为受影响的 Vuex Module 或工具函数编写/补充单元测试，确保现有逻辑未被破坏。
3. 为新功能编写测试桩 (Stub) 和预期行为描述。
   先输出测试代码策略，暂不修改业务逻辑。

步骤 3.2：核心逻辑开发 (分步执行) ​

操作：针对具体任务（如 Store 扩展）。

markdown
任务执行：步骤 X - [具体任务名，如：扩展轨迹 Store]
依据设计方案，修改或创建文件。
要求：

1. 严格遵循 @skills/routes/[对应页面].md 中记录的 Vuex 规范。
2. 代码风格与项目中现有文件 (如 @src/store/modules/map.js) 保持一致。
3. 若涉及 Leaflet/VueFlow 操作，务必注意实例的生命周期管理。
4. 使用 Trae 编辑功能直接修改，并在完成后列出变更摘要。

操作：针对 UI 组件开发。

markdown
任务执行：步骤 X - [具体任务名，如：开发导入控件]
创建新组件 `@src/components/xxx/ImportControl.vue`。
要求：

1. 语法：沿用目标页面现有的 API 风格 (Setup 或 Options)。
2. UI：使用 Element Plus 组件，样式使用项目配置的预处理器 (Less/Sass)。
3. 逻辑：通过 Props/Emits 与父组件通信，参考 @skills/routes/[对应页面].md 中的组件交互模式。
4. 自我审查：确保无未安装依赖，符合 ESLint/Prettier 规则。

步骤 3.3：集成与联调 ​

操作：

markdown
任务执行：步骤 X - 集成到新页面
修改 `@src/views/[对应页面].vue`。

1. 引入新组件/逻辑。
2. 绑定事件与数据。
3. 确保新逻辑不阻塞原有加载流程。
4. 添加适当的 Loading 状态 (Element Plus v-loading)。
   修改前，请先列出计划插入的代码位置和逻辑伪代码，确认后再执行。

🟣 阶段四：重构与债务管理 ​

目标：利用新需求机会，安全地清理技术债务。

步骤 4.1：局部重构 ​

操作：

markdown
代码审查与重构：
在开发中发现 `@src/views/[A]` 和 `@src/views/[B]` 存在重复逻辑 (如地图初始化)。
请提取公共逻辑到 `@src/hooks/useMapCore.js` (Composition API)。
要求：

1. 保持功能完全一致。
2. 兼容 Leaflet 1.9.4 和 Geoman 插件。
3. 更新原文件以引用新 Hook。
4. 添加详细 JSDoc 注释。

步骤 4.2：文档同步 ​

操作：

markdown
文档更新：
根据本次开发变更，更新 `@skills/routes/[对应页面].md`。
内容包括：

1. 新增的 Vuex 字段/Actions。
2. 新组件的 Props/Events。
3. 更新的“AI 开发指南”或“避坑指南”。
   保持文档结构与模板一致。

🔴 阶段五：验证与回归 ​

目标：确保上线安全，无回归错误。

步骤 5.1：自动化检查与修复 ​

操作：

markdown
最终验证：

1. 模拟运行 `npm run lint`，修复所有 ESLint/Prettier 问题。
2. 移除所有 `console.log`，保留必要错误日志。
3. 检查 import 路径，确保无循环依赖，别名使用正确。
4. 生成“变更自查清单”，列出所有修改文件及变动点。

步骤 5.2：模拟 Code Review ​

操作：

markdown
角色扮演：
请扮演挑剔的技术负责人，对本次代码变更进行 Code Review。
重点检查：

- 内存泄漏 (Leaflet/VueFlow 实例是否在 onBeforeUnmount 销毁)。
- 异步竞态 (Axios 请求处理)。
- 样式污染 (Less/Sass 作用域)。
- 浏览器兼容性 (Vue 3.3.4 + Browserslist)。

列出所有问题并给出修复代码。

💡 核心使用技巧 ​

  • 随时引用知识库：在任何后续对话中，习惯性地加上 参考 @skills/PROJECT_MAP.md 和 @skills/routes/[相关页面].md。
  • 警惕地图/流程图：由于项目重度依赖 Leaflet 和 VueFlow，任何涉及 DOM 操作或实例创建的代码，都要让 AI 二次确认生命周期管理。
  • 小步提交：每完成一个原子任务，就 Git Commit 一次，方便回滚。