mta-mcp 1.0.0

package/standards/workflows/design-restoration-guide.md

@@ -0,0 +1,164 @@
+# 设计稿还原通用规范
+
+> 适用于使用 Sketch、Figma 等设计工具 MCP 进行 UI 还原的所有场景
+
+## 🔴 核心问题
+
+本规范基于真实案例总结：**一个简单的输入框垂直居中问题，经历了 15+ 轮对话才修复**。
+
+### 问题根源分析
+
+| 问题 | 表现 | 后果 |
+|------|------|------|
+| **属性读取不完整** | 只读容器尺寸，忽略内部文本位置 | 无法精确计算边距和行高 |
+| **分散查询** | 每次只问一个属性 | 信息不完整，反复补充 |
+| **假设而非验证** | "应该差不多居中" | 实际偏差明显 |
+| **试错式调整** | 逐个调整参数看效果 | 改了 A 问题引发 B 问题 |
+
+---
+
+## ✅ 强制执行规范
+
+### 1. 完整读取选中元素及其所有子集
+
+**⚠️ 这是最重要的规则**
+
+```javascript
+// 正确示例：一次性获取完整信息
+function extractCompleteInfo(element) {
+  console.log('=== 容器信息 ===');
+  console.log(`尺寸: ${element.frame.width}x${element.frame.height}px`);
+  
+  console.log('=== 所有子元素 ===');
+  element.layers.forEach((child, index) => {
+    console.log(`\n子元素 ${index}: ${child.name} (${child.type})`);
+    console.log(`  X: ${child.frame.x}px, Y: ${child.frame.y}px`);
+    console.log(`  宽: ${child.frame.width}px, 高: ${child.frame.height}px`);
+    
+    if (child.type === 'Text') {
+      console.log(`  字号: ${child.style.fontSize}px`);
+      console.log(`  字重: ${child.style.fontWeight}`);
+      console.log(`  颜色: ${child.style.textColor}`);
+      console.log(`  行高倍数: ${(child.frame.height / child.style.fontSize).toFixed(2)}`);
+    }
+    
+    // 递归处理嵌套子元素
+    if (child.layers && child.layers.length > 0) {
+      child.layers.forEach(nested => {
+        console.log(`    嵌套: ${nested.name} (${nested.type})`);
+        console.log(`    位置: Y=${nested.frame.y}px`);
+      });
+    }
+  });
+  
+  console.log('=== 计算结果 ===');
+  const textChild = element.layers.find(l => l.type === 'Text');
+  if (textChild) {
+    const topSpace = textChild.frame.y;
+    const bottomSpace = element.frame.height - textChild.frame.y - textChild.frame.height;
+    console.log(`文本上边距: ${topSpace}px`);
+    console.log(`文本下边距: ${bottomSpace}px`);
+    console.log(`是否居中: ${Math.abs(topSpace - bottomSpace) < 2 ? '是' : '否'}`);
+  }
+}
+```
+
+### 2. 必须获取的完整信息清单
+
+| 元素类型 | 必须获取的属性 | 用途 |
+|----------|----------------|------|
+| **容器** | width, height, padding, 背景色/渐变 | 外层布局 |
+| **文本** | Y 坐标, height, fontSize, fontWeight, color | 计算行高和边距 |
+| **图标** | viewBox, path, fill, fill-opacity | 完整导出 SVG |
+| **渐变** | 所有 stops（颜色+位置）, from, to | 精确还原 |
+| **阴影** | x, y, blur, spread, color (全部 5 个) | 完整阴影 |
+| **边框** | color, width, position | 边框样式 |
+
+### 3. 计算而非试错
+
+**正确流程**：
+```
+1. 从设计稿获取精确数值
+2. 计算目标框架需要的参数
+3. 一次性配置完整方案
+4. 验证结果
+```
+
+**示例：TextField 行高计算**
+```
+设计稿数据:
+- 容器高度: 36px
+- 文本 Y 坐标: 8px
+- 文本高度: 20px
+- 字号: 14px
+
+计算:
+- 行高倍数 = 文本高度 ÷ 字号 = 20 ÷ 14 = 1.43
+- 上边距 = 文本 Y 坐标 = 8px
+- 下边距 = 容器高度 - Y - 文本高度 = 36 - 8 - 20 = 8px
+
+Flutter 配置:
+style: TextStyle(fontSize: 14, height: 1.43)
+Container: height=36, alignment=Alignment.center
+```
+
+---
+
+## 📋 框架特定注意事项
+
+### Flutter
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| TextField 居中 | `style.height`, `hintStyle.height` | 两者必须相同 |
+| 容器阴影 | `clipBehavior` | 设为 `Clip.none` 避免裁剪 |
+| Gap 间距 | `Gap()` vs `Gap.h()` | 默认垂直，`.h()` 水平 |
+| SVG 颜色 | `colorFilter` | 不要覆盖，保留原色 |
+
+### Vue/CSS
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| Flex 居中 | `align-items`, `justify-content` | 注意主轴方向 |
+| 文本居中 | `line-height` | 设为容器高度实现垂直居中 |
+| 边框问题 | `box-sizing` | 使用 `border-box` |
+| 阴影裁剪 | `overflow` | 避免 `hidden` 裁剪阴影 |
+
+### React Native
+
+| 问题场景 | 关键属性 | 注意事项 |
+|----------|----------|----------|
+| 文本居中 | `textAlignVertical` | 仅 Android 生效 |
+| 输入框 | `includeFontPadding` | Android 设为 false |
+| 阴影 | `elevation` vs `shadow*` | 平台差异 |
+
+---
+
+## 🚫 禁止事项
+
+1. ❌ **禁止只读容器属性** - 必须读取所有子元素
+2. ❌ **禁止分散查询** - 一次性获取完整信息
+3. ❌ **禁止假设数值** - 必须从设计稿读取精确像素
+4. ❌ **禁止试错调整** - 先计算，再编码
+5. ❌ **禁止忽略透明度** - 颜色 `#RRGGBBAA` 最后两位是透明度
+6. ❌ **禁止属性不一致** - 相关属性（如 style 和 hintStyle）必须统一配置
+
+---
+
+## ✅ 检查清单
+
+还原任何设计稿元素前：
+
+- [ ] 已获取目标元素的**容器尺寸**
+- [ ] 已获取**所有子元素**的位置和尺寸
+- [ ] 已获取文本的**Y 坐标、高度、字号**
+- [ ] 已**计算**行高倍数和边距
+- [ ] 已确认相关属性（style/hintStyle）**配置一致**
+- [ ] 已一次性配置**完整方案**
+- [ ] 已验证**所有相关元素**符合预期
+
+---
+
+**维护团队**: MTA工作室  
+**创建日期**: 2026-01-19  
+**版本**: v1.0

package/standards/workflows/large-project-split.md

@@ -0,0 +1,359 @@
+# 大型项目文档拆分规范
+
+> 适用场景：功能模块多（>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