mta-mcp 1.0.0

package/standards/workflows/problem-diagnosis.md

@@ -0,0 +1,280 @@
+# 问题诊断与修复规范
+
+> **核心原则**：定位根因，精准修复，避免反复
+
+---
+
+## 🎯 适用场景
+
+- Bug 修复
+- 样式问题调整
+- 功能异常排查
+- 性能问题优化
+- 任何需要"修改"而非"新增"的场景
+
+---
+
+## ⚠️ 常见错误模式
+
+### 表面修复陷阱
+
+| 表面现象 | 错误做法 | 真实原因示例 |
+|----------|----------|--------------|
+| 边框缺失 | 直接加 border | overflow:hidden 裁剪、多文件样式冲突、伪元素被隐藏 |
+| 元素错位 | 调整 margin/padding | flex 布局问题、父容器约束、z-index 层级 |
+| 点击无效 | 检查事件绑定 | 透明元素遮挡、pointer-events 设置、事件冒泡被阻止 |
+| 文字截断 | 增加宽度 | white-space 设置、flex-shrink 压缩、父容器限制 |
+| 动画卡顿 | 降低帧率 | 频繁重排重绘、JavaScript 阻塞、内存泄漏 |
+| 接口超时 | 延长超时时间 | N+1 查询、缺少索引、死锁、资源竞争 |
+
+---
+
+## 📋 强制诊断流程
+
+### 第一步：复现与观察（必须）
+
+```markdown
+1. 完整复现问题，记录：
+   - 具体表现是什么？
+   - 在什么条件下出现？
+   - 是否稳定复现？
+
+2. 收集环境信息：
+   - 浏览器/运行环境版本
+   - 相关依赖版本
+   - 是否仅在特定环境出现？
+```
+
+### 第二步：根因分析（核心）
+
+**必须回答的问题**：
+
+1. **谁**定义了这个行为？
+   - 哪个文件/哪一行代码？
+   - 是否有多处定义？（样式冲突常见原因）
+
+2. **为什么**会这样表现？
+   - 这段代码的原始意图是什么？
+   - 当前表现与意图的差异在哪？
+
+3. **什么时候**开始出现？
+   - 是一直存在还是最近才有？
+   - 如果最近才有，什么改动引入的？
+
+4. **还有谁**可能受影响？
+   - 修改这里会影响其他地方吗？
+   - 是否有依赖这个行为的代码？
+
+### 第三步：验证假设
+
+```markdown
+在修改前，必须验证你的假设：
+
+✅ 正确做法：
+- 使用浏览器开发者工具检查实际生效的样式
+- 搜索全项目相关关键词，确认没有其他定义
+- 临时注释可疑代码，观察变化
+
+❌ 错误做法：
+- 看一眼代码就下结论
+- 不搜索直接修改
+- 用 !important 强行覆盖
+```
+
+### 第四步：最小化修复
+
+```markdown
+修复原则：
+1. 修改最少的代码
+2. 从源头解决，而非末端补救
+3. 不引入新的 hack 或 workaround
+4. 保持代码一致性
+```
+
+---
+
+## 🔍 诊断工具与方法
+
+### 前端样式问题
+
+```bash
+# 必做检查
+1. DevTools → Elements → Computed 查看最终生效样式
+2. DevTools → Elements → Styles 查看样式来源和覆盖关系
+3. 全项目搜索相关选择器，检查是否有冲突定义
+4. 检查父元素的 overflow、position、z-index
+```
+
+### 后端接口问题
+
+```bash
+# 必做检查
+1. 查看完整请求/响应日志
+2. 检查数据库查询执行计划（EXPLAIN）
+3. 检查是否有并发/锁问题
+4. 检查资源使用情况（内存、连接池）
+```
+
+### 通用代码问题
+
+```bash
+# 必做检查
+1. 使用 grep/ripgrep 搜索相关函数/变量的所有引用
+2. 检查 git blame 了解代码变更历史
+3. 查看相关测试用例（如果有）
+4. 检查依赖库版本和已知问题
+```
+
+---
+
+## 📝 修复报告模板
+
+每次修复问题时，应在心中（或注释中）回答：
+
+```markdown
+## 问题描述
+[具体表现]
+
+## 根因分析
+- 直接原因：[是什么导致了这个表现]
+- 根本原因：[为什么会有这个直接原因]
+- 影响范围：[这个问题还会影响哪些地方]
+
+## 解决方案
+- 修改内容：[具体改了什么]
+- 为什么这样改：[而不是其他方案]
+- 验证方法：[如何确认修复有效]
+```
+
+---
+
+## 🚫 禁止事项
+
+1. **禁止想当然修复**
+   - ❌ "边框没了？加个 border"
+   - ✅ "边框没了？先查为什么没了"
+
+2. **禁止盲目使用 !important**
+   - ❌ 用 !important 强行覆盖
+   - ✅ 找到冲突源头，提高选择器优先级或删除冲突
+
+3. **禁止不搜索就修改**
+   - ❌ 直接在当前文件修改
+   - ✅ 先搜索全项目相关定义
+
+4. **禁止只看表面不查根因**
+   - ❌ 改了能跑就行
+   - ✅ 理解为什么会出问题
+
+---
+
+## 📚 真实案例
+
+### 案例：Element Plus 表格边框问题
+
+**表面现象**：表格边框显示不全，左边粗右边细
+
+**错误修复路径**：
+1. 加 `border: 1px solid` → 左边更粗了
+2. 改 `overflow: hidden` → 右边消失了
+3. 加伪元素边框 → 还是不对
+
+**正确诊断**：
+1. 搜索全项目 `.el-table--border` 相关样式
+2. 发现 **两个文件** 都定义了表格边框：
+   - `table.css`: `border: 1px solid` + `::before { display: none }`
+   - `element-overrides.css`: `::before { background-color }`
+3. 两套互相冲突的边框机制导致渲染异常
+
+**正确修复**：
+- 删除一处定义，保持单一来源
+- 让 Element Plus 使用默认边框机制
+
+**教训**：样式问题必须搜索全项目，确认没有冲突定义
+
+---
+
+## 🎨 设计稿还原专项规范
+
+> ⚠️ **此章节基于真实案例：一个输入框居中问题反复 15+ 轮对话才修复**
+
+### 设计稿工具使用规范（Sketch/Figma）
+
+#### 强制要求：完整读取选中元素及其所有子集
+
+**问题根源**：
+- 只读取了容器属性，忽略了内部文本的精确位置
+- 每次只查询一个属性，导致信息不完整
+- 假设而非验证具体数值
+
+**正确做法**：
+
+```javascript
+// 示例：读取输入框完整信息（包含所有子集）
+function extractInputFieldComplete(inputGroup) {
+  console.log('=== 容器信息 ===');
+  console.log(`宽度: ${inputGroup.frame.width}px`);
+  console.log(`高度: ${inputGroup.frame.height}px`);
+  
+  console.log('=== 内部文本（子集）===');
+  const text = inputGroup.layers.find(l => l.type === 'Text');
+  console.log(`文本 Y 坐标: ${text.frame.y}px`);  // 关键：距容器顶部距离
+  console.log(`文本高度: ${text.frame.height}px`); // 关键：计算行高
+  console.log(`字号: ${text.style.fontSize}px`);
+  
+  console.log('=== 计算结果 ===');
+  const topSpace = text.frame.y;
+  const bottomSpace = inputGroup.frame.height - text.frame.y - text.frame.height;
+  console.log(`上边距: ${topSpace}px`);
+  console.log(`下边距: ${bottomSpace}px`);
+  console.log(`行高倍数: ${(text.frame.height / text.style.fontSize).toFixed(2)}`);
+}
+```
+
+#### 必须获取的信息清单
+
+| 元素类型 | 必须获取 | 用途 |
+|----------|----------|------|
+| 容器 | width, height, padding | 外层尺寸 |
+| 文本 | fontSize, Y坐标, height, fontWeight | 计算行高和边距 |
+| 图标/SVG | viewBox, path, fill-opacity | 完整导出 |
+| 渐变 | stops（所有节点）, from, to | 精确还原 |
+| 阴影 | x, y, blur, spread, color | 全部5个参数 |
+
+### 反复修复问题的根因分析
+
+| 导致反复的原因 | 正确做法 |
+|----------------|----------|
+| 只读取容器高度，不读内部文本 Y 坐标 | 一次性获取容器+所有子元素的完整信息 |
+| 用"试错法"调整参数 | 先计算精确值（如行高=文本高度÷字号） |
+| 修改 A 属性引发 B 问题 | 理解属性之间的相互作用关系 |
+| 假设"差不多居中" | 从设计稿获取精确像素值验证 |
+
+### 设计稿还原检查清单
+
+修复任何设计还原问题前：
+
+- [ ] 已获取目标元素的**完整信息**（容器+所有子集）
+- [ ] 已计算精确数值（行高、边距、颜色透明度）
+- [ ] 已理解框架渲染机制（如 Flutter TextField 的多属性相互作用）
+- [ ] 一次性配置完整方案，而非逐个属性调整
+- [ ] 验证所有相关元素（placeholder、光标、输入内容）都符合预期
+
+---
+
+## ✅ 检查清单
+
+修复任何问题前，确认以下检查项：
+
+- [ ] 已搜索全项目相关代码
+- [ ] 已确认没有其他文件定义相同/冲突的逻辑
+- [ ] 已理解原代码的意图
+- [ ] 修改方案从源头解决问题
+- [ ] 修改不会影响其他功能
+- [ ] 有明确的验证方法
+
+---
+
+**维护者**: MTA工作室  
+**创建日期**: 2025-01-04  
+**版本**: v1.0

package/standards/workflows/textfield-centering-guide.md

@@ -0,0 +1,157 @@
+# Flutter TextField 垂直居中纠错指南
+
+> 本文档基于一次真实案例总结：修复一个简单的输入框垂直居中问题，经历了 **15+ 轮对话**，涉及多种方案反复尝试
+
+## 📋 问题总结
+
+### 问题描述
+输入框需要实现 placeholder、光标、输入内容三者在容器中垂直居中对齐。
+
+### 问题根因
+Flutter TextField 的垂直对齐涉及**多个相互作用的属性**，修改一个属性可能影响其他元素的位置，导致"改了 A 问题引发 B 问题"的循环。
+
+### 反复失败的原因
+
+| 尝试次数 | 方案 | 结果 |
+|----------|------|------|
+| 1 | contentPadding: vertical: 10 | 整体偏下 |
+| 2 | textAlignVertical: center | 只影响输入内容，placeholder 不动 |
+| 3 | 移除 contentPadding | 整体偏上 |
+| 4 | strutStyle + height: 1.0 | 文字被压缩，更难看 |
+| 5 | Container.alignment + contentPadding: 8 | 输入内容正常，placeholder 偏下 |
+| 6 | hintStyle height: 1.2 | placeholder 移动，但不够 |
+| 7 | hintStyle height: 1.0 | placeholder 过于靠上 |
+| 8-15 | 各种组合... | 来回折腾 |
+
+### 根本问题
+**没有一开始就理解 TextField 的渲染模型**，而是"试错式"调整参数。
+
+---
+
+## ✅ 正确方案（一步到位）
+
+### 设计规格（从 Sketch 获取）
+- 容器高度：36px
+- 文本 Y 坐标：8px（距顶部）
+- 文本高度：20px
+- 字号：14px
+- 行高倍数：1.43（20 ÷ 14 = 1.43）
+
+### Flutter 正确配置
+
+```dart
+Widget _buildCenteredTextField({
+  required String placeholder,
+  required TextEditingController controller,
+}) {
+  return Container(
+    height: 36,
+    decoration: BoxDecoration(
+      // ... 背景、圆角、阴影
+    ),
+    alignment: Alignment.center, // 关键：让 TextField 在容器中居中
+    child: TextField(
+      controller: controller,
+      textAlign: TextAlign.center, // 水平居中
+      // 不要使用 textAlignVertical，会导致 placeholder 和输入内容位置不一致
+      style: const TextStyle(
+        fontSize: 14,
+        height: 1.43, // 关键：与 hintStyle 保持一致
+        fontWeight: FontWeight.w600,
+      ),
+      decoration: InputDecoration(
+        hintText: placeholder,
+        hintStyle: const TextStyle(
+          fontSize: 14,
+          height: 1.43, // 关键：与 style 完全一致
+          fontWeight: FontWeight.w600,
+        ),
+        contentPadding: EdgeInsets.zero, // 关键：清除默认 padding
+        isDense: true, // 关键：移除额外空间
+        border: InputBorder.none,
+        enabledBorder: InputBorder.none,
+        focusedBorder: InputBorder.none,
+      ),
+    ),
+  );
+}
+```
+
+### 关键原则
+
+| 属性 | 作用 | 注意事项 |
+|------|------|----------|
+| `Container.alignment: Alignment.center` | 让 TextField 整体在容器中居中 | 必须配合 `contentPadding: EdgeInsets.zero` |
+| `style.height` 和 `hintStyle.height` | 控制行高 | **必须相同**，否则 placeholder 和输入内容位置不一致 |
+| `contentPadding: EdgeInsets.zero` | 清除默认间距 | 让 Container.alignment 生效 |
+| `isDense: true` | 移除 TextField 默认空间 | 减少干扰因素 |
+| `textAlignVertical` | **不推荐使用** | 只影响输入内容，不影响 placeholder |
+
+---
+
+## 📌 简版纠错指南
+
+### TextField 垂直居中三步法
+
+```dart
+// Step 1: Container 提供高度和居中
+Container(
+  height: 36,
+  alignment: Alignment.center,
+  child: TextField(
+    // Step 2: style 和 hintStyle 使用相同的 height
+    style: TextStyle(fontSize: 14, height: 1.43),
+    decoration: InputDecoration(
+      hintStyle: TextStyle(fontSize: 14, height: 1.43),
+      // Step 3: 清除 padding，启用 isDense
+      contentPadding: EdgeInsets.zero,
+      isDense: true,
+    ),
+  ),
+)
+```
+
+### 禁止事项
+
+1. ❌ **禁止 style.height 和 hintStyle.height 不一致** - 会导致 placeholder 和输入内容位置不同
+2. ❌ **禁止同时使用 textAlignVertical 和 height** - 会产生冲突
+3. ❌ **禁止 strutStyle + forceStrutHeight** - 可能压缩文字
+4. ❌ **禁止反复调整 contentPadding 试错** - 先确定行高配置
+
+### 调试顺序
+
+遇到 TextField 垂直对齐问题时，按以下顺序检查：
+
+1. **先确认设计规格** - 容器高度、文本高度、计算行高倍数
+2. **配置 height** - style 和 hintStyle 使用相同的 height
+3. **配置 Container** - alignment: Alignment.center
+4. **清除干扰** - contentPadding: EdgeInsets.zero, isDense: true
+5. **移除冲突属性** - 不要用 textAlignVertical 和 strutStyle
+
+---
+
+## 🎯 案例复盘
+
+### 为什么需要 15+ 轮对话？
+
+| 问题 | 正确做法 |
+|------|----------|
+| 没有先计算行高倍数 | 从设计稿提取：文本高度 ÷ 字号 = height |
+| 逐个尝试属性 | 一次性配置完整方案 |
+| 改了 A 引发 B | 理解属性之间的关系 |
+| 没有统一 style 和 hintStyle | 两者必须完全一致 |
+
+### 正确的工作流
+
+```
+1. 从 Sketch 获取完整规格（容器高度、文本 Y 坐标、文本高度）
+2. 计算 height = 文本高度 ÷ 字号
+3. 一次性配置完整方案（Container.alignment + 相同 height + contentPadding.zero + isDense）
+4. 验证三者（placeholder、光标、输入内容）是否对齐
+```
+
+---
+
+**创建日期**: 2026-01-19  
+**案例来源**: 汇款记录筛选弹窗金额输入框  
+**解决方案**: Container.alignment + 统一 height + contentPadding.zero

package/templates/README.md

@@ -0,0 +1,144 @@
+# 📦 项目模板代码库
+
+> 预置的可复用代码模板，支持快速生成项目基础设施
+
+---
+
+## 🤖 Agent 使用指令
+
+当用户说出以下类似指令时，Agent 应按照本文档规范执行：
+
+**触发指令示例**：
+- "将 axios 模板应用到 ht-manage 项目"
+- "把 api-layer 模板复制到 VitaSage"
+- "给 xx 项目配置 API 层"
+- "应用 vue/api-layer 模板"
+
+**Agent 执行流程**：
+
+1. **识别模板** - 根据关键词匹配模板：
+   | 关键词 | 对应模板 |
+   |--------|----------|
+   | axios / api / api-layer / 请求封装 | `vue/api-layer` |
+   | types / 类型 | `common/types` |
+
+2. **确定目标路径** - 根据项目和模板类型：
+   | 模板 | 目标路径 |
+   |------|----------|
+   | `vue/api-layer` | `{项目}/src/api/` |
+   | `common/types` | `{项目}/src/types/` |
+
+3. **复制文件** - 将模板目录下的文件（排除 `_CONFIG.md`）复制到目标路径
+
+4. **提示配置** - 告知用户需要根据 `_CONFIG.md` 调整的配置项：
+   - UI 框架适配（showMessage）
+   - 后端响应格式适配
+   - Token 传递方式
+   - 环境变量配置
+
+**执行示例**：
+
+```
+用户: 将 axios 模板应用到 ht-manage 项目
+
+Agent 执行:
+1. 模板路径: /Users/pailasi/Work/copilot-prompts/templates/vue/api-layer/
+2. 目标路径: /Users/pailasi/Work/ht-manage/src/api/
+3. 复制文件:
+   - request.ts
+   - types.ts
+   - index.ts
+   - mock/index.ts
+   - modules/index.ts
+   - modules/_template.ts
+4. 提示用户按 _CONFIG.md 配置
+```
+
+---
+
+## 目录结构
+
+```
+templates/
+├── README.md                 # 本文件（含 Agent 指令）
+├── vue/                      # Vue 项目模板
+│   ├── api-layer/            # API 层封装（axios + mock）✅
+│   ├── composables/          # 通用 Composables（预留）
+│   ├── components/           # 通用组件模板（预留）
+│   └── stores/               # 状态管理模板（预留）
+├── flutter/                  # Flutter 项目模板（预留）
+│   ├── api-layer/
+│   └── themes/
+├── react/                    # React 项目模板（预留）
+└── common/                   # 跨框架通用模板
+    └── types/                # TypeScript 类型定义 ✅
+```
+
+---
+
+## 🎯 手动使用方式
+
+1. 进入对应模板目录
+2. 复制需要的文件到项目中
+3. 根据 `_CONFIG.md` 文件说明进行配置
+
+---
+
+## 📋 可用模板
+
+### Vue 项目
+
+| 模板 | 关键词 | 说明 | 状态 |
+|------|--------|------|------|
+| `vue/api-layer` | axios, api, 请求封装 | Axios + Mock 完整封装 | ✅ 可用 |
+| `vue/composables` | composable, hook | 通用 Composables | 🚧 计划中 |
+| `vue/components` | component, 组件 | 基础组件模板 | 🚧 计划中 |
+| `vue/stores` | pinia, store, 状态 | Pinia Store 模板 | 🚧 计划中 |
+
+### Flutter 项目
+
+| 模板 | 关键词 | 说明 | 状态 |
+|------|--------|------|------|
+| `flutter/api-layer` | dio, api | Dio + 状态管理封装 | 🚧 计划中 |
+| `flutter/themes` | theme, token | Design Token 系统 | 🚧 计划中 |
+
+### 通用模板
+
+| 模板 | 关键词 | 说明 | 状态 |
+|------|--------|------|------|
+| `common/types` | types, 类型 | TypeScript 通用类型 | ✅ 可用 |
+
+---
+
+## 🔧 模板规范
+
+每个模板目录必须包含：
+
+1. **`_CONFIG.md`** - 配置说明文件
+   - 模板用途
+   - 依赖要求
+   - 配置项说明
+   - 适配指南
+
+2. **源代码文件** - 可直接复制使用的代码
+   - 保持通用性，不含业务逻辑
+   - 标注自定义点（使用 `💡` 或 `TODO` 注释）
+   - 支持多种配置方案
+
+---
+
+## 🚀 扩展模板
+
+添加新模板时：
+
+1. 在对应框架目录下创建模板文件夹
+2. 编写 `_CONFIG.md` 配置说明
+3. 添加代码文件，确保通用性
+4. 更新本 README 的模板列表
+5. 如有相关规范文档，在 `standards/patterns/` 中添加
+
+---
+
+**维护者**: MTA工作室  
+**创建日期**: 2025-12-25  
+**版本**: v1.0

package/templates/common/types/_CONFIG.md

@@ -0,0 +1,12 @@
+# 通用 TypeScript 类型模板
+
+> 跨框架通用的类型定义
+
+## 📦 包含文件
+
+- `api.ts` - API 响应相关类型
+- `common.ts` - 通用业务类型
+
+## 🚀 使用方式
+
+复制到项目的 `src/types/` 目录

package/templates/common/types/api.ts

@@ -0,0 +1,39 @@
+/**
+ * API 相关类型定义
+ */
+
+/** API 响应基础结构 */
+export interface ApiResponse<T = any> {
+  code: number
+  data: T
+  message: string
+}
+
+/** 分页参数 */
+export interface PageParams {
+  page: number
+  pageSize: number
+}
+
+/** 分页数据 */
+export interface PageData<T> {
+  list: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+/** 分页响应 */
+export type PageResponse<T> = ApiResponse<PageData<T>>
+
+/** 排序参数 */
+export interface SortParams {
+  sortField?: string
+  sortOrder?: 'asc' | 'desc'
+}
+
+/** 时间范围 */
+export interface DateRange {
+  startDate?: string
+  endDate?: string
+}

package/templates/common/types/common.ts

@@ -0,0 +1,70 @@
+/**
+ * 通用业务类型定义
+ */
+
+/** 通用 ID 类型 */
+export type ID = string | number
+
+/** 通用状态 */
+export type Status = 'active' | 'inactive' | 'pending' | 'deleted'
+
+/** 启用状态 */
+export type EnableStatus = 0 | 1
+
+/** 审核状态 */
+export type AuditStatus = 'pending' | 'approved' | 'rejected'
+
+/** 性别 */
+export type Gender = 'male' | 'female' | 'unknown'
+
+/** 键值对 */
+export interface KeyValue<T = any> {
+  key: string
+  value: T
+}
+
+/** 选项项（下拉框等） */
+export interface OptionItem<T = string | number> {
+  label: string
+  value: T
+  disabled?: boolean
+  children?: OptionItem<T>[]
+}
+
+/** 树形节点 */
+export interface TreeNode<T = any> {
+  id: ID
+  label: string
+  children?: TreeNode<T>[]
+  data?: T
+}
+
+/** 表格列配置 */
+export interface TableColumn {
+  prop: string
+  label: string
+  width?: number | string
+  minWidth?: number | string
+  fixed?: 'left' | 'right'
+  sortable?: boolean
+  align?: 'left' | 'center' | 'right'
+}
+
+/** 用户基础信息 */
+export interface UserBase {
+  id: ID
+  username: string
+  nickname?: string
+  avatar?: string
+  email?: string
+  phone?: string
+}
+
+/** 带时间戳的基础实体 */
+export interface BaseEntity {
+  id: ID
+  createdAt: string
+  updatedAt: string
+  createdBy?: ID
+  updatedBy?: ID
+}

package/templates/config-templates/agents-section.md

@@ -0,0 +1,9 @@
+## 📚 配置的 Agents
+
+本项目使用以下 Agents（规范内容由 MCP 工具实时加载）：
+
+{{AGENTS_LIST}}
+
+> 💡 **工作原理**: Copilot 在编写代码时会自动调用 MCP 工具加载对应 Agent 的规范内容，无需在此文件中嵌入完整规范。
+
+---