mta-mcp 2.17.0 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mta-mcp",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "description": "MTA - 智能项目分析与编码规范管理 MCP 服务器",
   "type": "module",
   "main": "./dist/index.js",

package/troubleshooting/flutter/component-/351/200/232/347/224/250/345/214/226/346/217/220/345/217/226.md

@@ -0,0 +1,269 @@
+# 通用组件提取与文本自适应对齐
+
+> **问题标签**: `component`, `refactor`, `text-align`, `adaptive`, `center`, `left`  
+> **框架**: Flutter  
+> **严重程度**: 中等（影响代码可维护性和 UI 一致性）
+
+---
+
+## 🔍 问题识别
+
+### 用户描述关键词
+- "这两个卡片样式很像"
+- "单行居中、多行左对齐"
+- "重复代码太多"
+- "不同状态显示不同样式"
+
+### 问题特征
+- [ ] 多个相似组件（如 Warning Card、Error Card）硬编码实现
+- [ ] 相同的布局结构重复多次
+- [ ] 文本对齐方式需要根据内容长度动态调整
+- [ ] 颜色/图标等仅通过状态切换
+
+---
+
+## 🎯 核心原理
+
+### 问题 1：硬编码重复组件
+
+**错误做法**：为每种状态创建独立的 Widget 方法
+
+```dart
+// ❌ 硬编码 - 重复代码
+Widget _buildWarningCard() { ... }
+Widget _buildErrorCard() { ... }
+Widget _buildSuccessCard() { ... }
+```
+
+**正确做法**：提取通用组件，通过参数配置样式
+
+```dart
+// ✅ 通用组件
+TipCard(
+  type: TipCardType.warning, // 或 error, success, info
+  title: '标题',
+  content: '内容',
+  buttonText: '按钮',
+  onButtonPressed: () {},
+)
+```
+
+### 问题 2：文本单行居中、多行左对齐
+
+**需求**：
+- 短文本（单行）：水平居中显示
+- 长文本（多行）：左对齐显示
+
+**解决方案**：使用 `LayoutBuilder` + `TextPainter` 动态计算
+
+```dart
+Widget _buildAdaptiveText(String content, TextStyle style) {
+  return LayoutBuilder(
+    builder: (context, constraints) {
+      // 计算文本是否超出一行
+      final textPainter = TextPainter(
+        text: TextSpan(text: content, style: style),
+        maxLines: 1,
+        textDirection: TextDirection.ltr,
+      );
+      textPainter.layout(maxWidth: constraints.maxWidth);
+
+      // 判断是否溢出
+      final isMultiLine = textPainter.didExceedMaxLines ||
+          textPainter.width >= constraints.maxWidth * 0.95;
+
+      return Container(
+        width: double.infinity,
+        alignment: isMultiLine ? Alignment.centerLeft : Alignment.center,
+        child: Text(
+          content,
+          style: style,
+          textAlign: isMultiLine ? TextAlign.left : TextAlign.center,
+          maxLines: 2,
+          overflow: TextOverflow.ellipsis,
+        ),
+      );
+    },
+  );
+}
+```
+
+---
+
+## ✅ 完整解决方案
+
+### 1. 定义配置类
+
+```dart
+/// TipCard 类型枚举
+enum TipCardType { warning, error, success, info }
+
+/// 配置类 - 所有颜色来自 Sketch
+class TipCardConfig {
+  final Color backgroundColor;
+  final Color borderColor;
+  final Color titleColor;
+  final Color contentColor;
+  final Color buttonShadowColor;
+  final String iconPath;
+
+  const TipCardConfig({...});
+
+  /// Warning: #fff8e7ff, border #ffe4b5ff
+  static const warning = TipCardConfig(
+    backgroundColor: Color(0xFFFFF8E7),
+    borderColor: Color(0xFFFFE4B5),
+    titleColor: Color(0xFFFF9800),
+    contentColor: Color(0xFFB45309),
+    buttonShadowColor: Color(0x40FF9800),
+    iconPath: 'assets/icons/warning_icon.svg',
+  );
+
+  /// Error: #f4433614 (8%透明), border #ffcacaff
+  static const error = TipCardConfig(
+    backgroundColor: Color(0x14F44336),
+    borderColor: Color(0xFFFFCACA),
+    titleColor: Color(0xFFF44336),
+    contentColor: Color(0xFFCA4F57),
+    buttonShadowColor: Color(0x40D0121B),
+    iconPath: 'assets/icons/error_icon.svg',
+  );
+
+  static TipCardConfig fromType(TipCardType type) {
+    switch (type) {
+      case TipCardType.warning: return warning;
+      case TipCardType.error: return error;
+      // ...
+    }
+  }
+}
+```
+
+### 2. 创建通用组件
+
+```dart
+class TipCard extends StatelessWidget {
+  final TipCardType type;
+  final String title;
+  final String content;
+  final String buttonText;
+  final VoidCallback? onButtonPressed;
+
+  const TipCard({
+    super.key,
+    required this.type,
+    required this.title,
+    required this.content,
+    required this.buttonText,
+    this.onButtonPressed,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final config = TipCardConfig.fromType(type);
+
+    return Container(
+      padding: const EdgeInsets.fromLTRB(23, 17, 23, 10),
+      decoration: BoxDecoration(
+        color: config.backgroundColor,
+        borderRadius: BorderRadius.circular(16),
+        border: Border.all(color: config.borderColor, width: 1),
+      ),
+      child: Column(
+        children: [
+          _buildTitleRow(config),
+          const SizedBox(height: 8),
+          _buildAdaptiveContent(config), // 自适应对齐
+          const SizedBox(height: 10),
+          _buildButton(config),
+        ],
+      ),
+    );
+  }
+}
+```
+
+### 3. 使用组件
+
+```dart
+// 替换硬编码实现
+Widget _buildWarningCard(ProfileController controller) {
+  return Obx(() {
+    final status = controller.kycStatus.value;
+
+    if (status == KycStatus.expiring) {
+      return TipCard(
+        type: TipCardType.warning,
+        title: '证件即将过期',
+        content: '您的身份证件将于30天后过期，请及时更新。',
+        buttonText: '立即更新',
+        onButtonPressed: controller.updateIdDocument,
+      );
+    } else if (status == KycStatus.rejected) {
+      return TipCard(
+        type: TipCardType.error,
+        title: '验证失败',
+        content: '证件照片不清晰，请重新上传。', // 短文本会居中
+        buttonText: '重新验证',
+        onButtonPressed: controller.resubmitVerification,
+      );
+    }
+
+    return const SizedBox.shrink();
+  });
+}
+```
+
+---
+
+## 🔑 关键公式
+
+### TextPainter 溢出检测
+
+```dart
+final isMultiLine = textPainter.didExceedMaxLines ||
+    textPainter.width >= constraints.maxWidth * 0.95;
+```
+
+- `didExceedMaxLines`：文本是否超出 maxLines
+- `width >= maxWidth * 0.95`：文本宽度接近容器宽度（留 5% 余量）
+
+### 配置类设计模式
+
+```dart
+// 枚举 + 静态配置 + fromType 工厂方法
+enum Type { a, b, c }
+
+class Config {
+  static const a = Config(...);
+  static const b = Config(...);
+  
+  static Config fromType(Type type) => switch (type) {
+    Type.a => a,
+    Type.b => b,
+    // ...
+  };
+}
+```
+
+---
+
+## ⚠️ 预防措施
+
+1. **识别相似组件**：当发现 2+ 个组件结构相同、仅样式不同时，立即提取
+2. **颜色来自设计稿**：使用 Sketch MCP 工具获取精确颜色值
+3. **文本对齐需求确认**：明确单行/多行的对齐规则
+4. **配置集中管理**：将所有变体配置放在一个类中
+
+---
+
+## 🔗 相关问题
+
+- [sketch-背景层高度.md](./sketch-背景层高度.md) - 获取精确尺寸
+- [sketch-完整提取.md](./sketch-完整提取.md) - 一次性提取样式
+
+---
+
+**创建日期**: 2026-01-20  
+**最后更新**: 2026-01-20  
+**来源**: Profile 页面 TipCard 组件重构实战