# 底层必须规则（Mandatory Rules）

> 此规范由 MCP 底层自动注入，所有规范请求都会附加此内容。
> 版本: v2.0.0 | 最后更新: 2026-03-31

---

## 🚨 零容忍规则

**这些规则在任何情况下都不能违反，优先级最高：**

### 1. 结构完整性

⚡ Vue / HTML：
```html
✅ <div>...</div>
✅ <el-table>...</el-table>
❌ <div>...<div>  <!-- 缺少结束标签 -->
```

⚡ Dart / Flutter：
```dart
// ✅ 正确 — Widget 树缩进清晰、括号配对
Column(
  children: [
    Text('Hello'),
    ElevatedButton(onPressed: () {}, child: Text('OK')),
  ],
)
```

### 2. 禁止弱类型

⚡ TypeScript：
```typescript
// ❌ 禁止
const data: any = {}

// ✅ 正确
const data: Record<string, unknown> = {}
```

⚡ Dart：
```dart
// ❌ 禁止
dynamic data = fetchData();

// ✅ 正确
final User data = await fetchUser();
```

### 3. 国际化强制使用

⚡ Vue：
```vue
<!-- ✅ 正确 -->
<el-button>{{ $t('提交') }}</el-button>

<!-- ❌ 硬编码 -->
<el-button>提交</el-button>
```

⚡ Flutter（ARB）：
```dart
// ✅ 正确
Text(S.of(context).submit)
Text(S.current.enterAmount)

// ❌ 硬编码
Text('提交')
Text('请输入金额')
```

### 4. 禁止硬编码样式值

> 详细规范见 `get_standard_by_id({ id: "hardcoding-prevention" })`

所有颜色、字号、圆角、间距必须使用项目 Token / 常量系统：

```dart
// ❌ 硬编码
Container(color: Color(0xFF3B82F6), padding: EdgeInsets.all(16))

// ✅ Token
Container(color: AppColors.primary, padding: EdgeInsets.all($s.md))
```

```vue
<!-- ❌ 硬编码 -->
<div style="color: #3B82F6; padding: 16px">

<!-- ✅ Token -->
<div :style="{ color: 'var(--color-primary)', padding: 'var(--spacing-md)' }">
```

### 5. 新组件创建前必须去重

> 详细规范见 `get_standard_by_id({ id: "code-file-splitting" })`

创建新组件前，必须搜索项目中是否已存在同类组件：

```bash
# Flutter: 搜索 core/widgets/ 和 presentation/widgets/
grep -rn "class.*Widget" lib/core/widgets/ lib/**/presentation/widgets/

# Vue: 搜索 components/
grep -rn "defineComponent\|<script setup" src/components/
```

### 6. 统一错误处理 / 通知入口

> 详细规范见 `get_standard_by_id({ id: "error-handling-unification" })`

全项目使用单一通知入口，禁止直接调用底层 API：

```dart
// ❌ 禁止散落调用
Get.snackbar('Error', message);
ScaffoldMessenger.of(context).showSnackBar(...);

// ✅ 统一入口
AppToast.error(message);
```

```typescript
// ❌ 禁止散落调用
ElMessage.error(msg)

// ✅ 统一入口
useAppToast().error(msg)
```

---

## ⚠️ 强制工作流

### 问题诊断优先

当用户描述问题时（错误、样式不对、效果不符预期），必须先调用：

```
troubleshoot({ problem: "用户描述的问题" })
```

### 规范加载验证

在生成代码前，必须确认已加载相关规范：

1. **检查项目作用域** - 确认文件路径属于当前项目
2. **声明已加载** - 在响应中说明：`✅ 已加载规范: [规范名称]`

---

## 🔍 代码审查清单

**每次编辑后必检：**

### 通用
- [ ] 所有用户可见文本已国际化
- [ ] 无硬编码样式值（颜色/字号/圆角/间距）
- [ ] 新组件已去重检查
- [ ] 通知/错误提示走统一入口

### ⚡ Vue / TS
- [ ] 所有 HTML 标签正确闭合
- [ ] Vue SFC 只有一个 `<style>` 标签
- [ ] 无 `any` 类型
- [ ] Props/Emits 有完整类型定义

### ⚡ Dart / Flutter
- [ ] 无 `dynamic` 类型（除非序列化边界）
- [ ] Widget 构造函数使用 `const`
- [ ] 使用项目 Token（AppColors / DesignFontSizes / AppRadius）
- [ ] 使用 `.withValues(alpha: ...)` 而非 `.withOpacity()`

---

## 🚫 全局禁止模式

| 禁止 | 替代方案 | 适用 |
|------|----------|------|
| 弱类型 (`any` / `dynamic`) | 具体类型或 `unknown` | 全部 |
| 硬编码文本 | i18n 系统 | 全部 |
| 硬编码样式值 | Token / 常量系统 | 全部 |
| 散落通知调用 | 统一通知入口 | 全部 |
| Options API | Composition API | ⚡Vue |
| 多个 `<style>` 标签 | 合并为一个 | ⚡Vue |
| `.withOpacity()` | `.withValues(alpha: ...)` | ⚡Dart |

---

## 📋 最小改动原则

| 判断项 | 是 | 否 |
|--------|---|---|
| 修改只影响当前文件？ | 继续修改 | **停止，重新评估** |
| 存在类似模式？ | **复用现有模式** | 可新建 |
| 需要改组件类型？ | **先确认用户意图** | 继续 |
| 需要删除现有代码？ | **先确认必要性** | 继续 |

---

**此规范自动注入，无需手动加载。**
