mta-mcp 1.0.0

package/standards/core/code-style.md

@@ -0,0 +1,308 @@
+# 核心代码规范
+
+## 基本原则
+
+1. **代码可读性优先** - 清晰 > 简洁
+2. **类型安全** - 使用严格的类型系统
+3. **一致性** - 遵循统一的代码风格
+4. **可维护性** - 编写易于理解和修改的代码
+5. **注释充分** - 重要逻辑必须添加注释说明
+6. **专注代码** - 生成代码时不创建 Markdown 文档
+
+## 命名规范
+
+### 变量命名
+```typescript
+// ✅ 好 - 使用驼峰命名法
+const userName = 'John'
+const isActive = true
+const itemCount = 10
+
+// ❌ 坏
+const user_name = 'John'
+const UserName = 'John'
+```
+
+### 常量命名
+```typescript
+// ✅ 好 - 使用大写字母和下划线
+const MAX_RETRY_COUNT = 3
+const API_BASE_URL = 'https://api.example.com'
+
+// ❌ 坏
+const maxRetryCount = 3
+```
+
+### 函数命名
+```typescript
+// ✅ 好 - 使用动词开头
+function getUserData() { }
+function validateForm() { }
+function handleClick() { }
+
+// ❌ 坏
+function user() { }
+function data() { }
+```
+
+### 类/接口命名
+```typescript
+// ✅ 好 - 使用 PascalCase
+interface UserProfile { }
+class DataService { }
+type StatusType = 'pending' | 'success'
+
+// ❌ 坏
+interface userProfile { }
+class dataService { }
+```
+
+## 代码组织
+
+### 导入顺序
+```typescript
+// 1. Node 内置模块
+import * as path from 'path'
+
+// 2. 第三方库
+import { ref, computed } from 'vue'
+import { defineStore } from 'pinia'
+
+// 3. 项目内部模块
+import { useUserStore } from '@/stores/user'
+import MyComponent from '@/components/MyComponent.vue'
+
+// 4. 类型导入（分组）
+import type { User, Profile } from '@/types'
+```
+
+### 文件结构
+```typescript
+// 1. 类型定义
+interface Props { }
+interface Emits { }
+
+// 2. 常量
+const DEFAULT_PAGE_SIZE = 10
+
+// 3. 状态
+const isLoading = ref(false)
+
+// 4. 计算属性
+const filteredData = computed(() => {})
+
+// 5. 方法
+function handleSubmit() {}
+
+// 6. 生命周期
+onMounted(() => {})
+```
+
+## 注释规范
+
+### 核心要求（v1.3.0 强制规则）
+
+1. **重要代码必须注释** - 复杂逻辑、算法、业务规则需要清晰说明
+2. **去 AI 化** - 避免使用表情符号、过度热情的语气
+3. **专业简洁** - 使用平实的技术语言，避免口语化表达
+4. **⚠️ 单行注释使用 `//`** - TypeScript/JavaScript 中，单行注释必须使用 `//`，不使用 `/** */`
+5. **注释内容有意义** - 说明为什么而非做什么，避免废话注释
+
+### 注释格式规范
+
+```typescript
+// ✅ 正确：单行注释使用 //
+// 使用二分查找提高性能
+function binarySearch() {}
+
+// ✅ 正确：多行注释使用 /** */ 
+/**
+ * 获取用户信息
+ * @param userId 用户ID
+ * @returns 用户信息对象
+ */
+function getUserInfo(userId: number) {}
+
+// ❌ 错误：单行注释不要使用 /** */
+/** 使用二分查找提高性能 */
+function binarySearch() {}
+
+// ❌ 错误：无意义的注释
+// 创建变量
+const count = 0
+```
+
+### 好的注释风格
+
+```typescript
+// 使用二分查找提高性能
+function binarySearch(arr: number[], target: number): number {
+  let left = 0
+  let right = arr.length - 1
+  
+  // 当搜索范围有效时继续查找
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2)
+    
+    if (arr[mid] === target) {
+      return mid
+    } else if (arr[mid] < target) {
+      left = mid + 1
+    } else {
+      right = mid - 1
+    }
+  }
+  
+  return -1
+}
+
+// 缓存计算结果避免重复请求
+const memoizedFetch = (() => {
+  const cache = new Map()
+  
+  return async (url: string) => {
+    if (cache.has(url)) {
+      return cache.get(url)
+    }
+    
+    const data = await fetch(url).then(r => r.json())
+    cache.set(url, data)
+    return data
+  }
+})()
+```
+
+### 避免的注释风格
+
+```typescript
+// ❌ 不自然 - 使用表情符号
+// 🎉 太棒了！这个函数超级好用！
+// ✨ 神奇的算法来啦～
+
+// ❌ 过度热情
+// 哇！这里使用了超酷的技巧！
+// 注意啦！这里很重要哦～
+
+// ❌ 只重复代码
+// 创建用户
+function createUser() {}
+
+// ❌ 废话连篇
+// 这个函数非常非常重要，请一定要仔细阅读
+// 它做了很多很多事情，真的很厉害
+```
+
+### 正确的注释示例
+
+```typescript
+// 正确：说明为什么，而非做什么
+// 使用 Set 去重，避免 O(n²) 复杂度
+const uniqueIds = [...new Set(ids)]
+
+// 正确：说明业务规则
+// 管理员用户跳过权限检查
+if (user.role === 'admin') {
+  return true
+}
+
+// 正确：说明技术决策
+// 使用 WeakMap 避免内存泄漏
+const cache = new WeakMap()
+
+// 正确：警告潜在问题
+// 注意：此方法会修改原数组
+function sortInPlace(arr: number[]) {
+  return arr.sort((a, b) => a - b)
+}
+```
+
+### 函数注释
+```typescript
+/**
+ * 获取用户信息
+ * @param userId 用户ID
+ * @returns 用户信息对象，如果不存在返回 null
+ */
+function getUserInfo(userId: number): User | null {
+  // 实现逻辑...
+}
+
+// 对于简单函数，单行注释即可
+// 验证邮箱格式
+function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+```
+
+## 文档创建规范（v1.3.0 强制规则）
+
+### ⚠️ 禁止行为
+
+**生成代码时不要创建 Markdown 文档**
+
+```typescript
+// ❌ 错误：自动创建额外的文档文件
+// 不要生成：USAGE.md, GUIDE.md, CHANGES.md, NOTES.md 等
+
+// ✅ 正确：在代码中添加充分的注释
+/**
+ * UserService 类
+ * 
+ * 提供用户相关的业务逻辑处理
+ * 包括用户注册、登录、信息更新等功能
+ */
+class UserService {
+  // 实现...
+}
+```
+
+### 何时可以创建文档
+
+**仅在以下情况创建文档：**
+1. ✅ 用户明确要求创建说明文档、配置文档等
+2. ✅ 项目初始化需要 README.md
+3. ✅ 修改现有文档文件
+4. ✅ 用户明确说"生成文档"、"创建说明"等
+
+**默认行为：**
+- ❌ 不要主动创建文档
+- ✅ 在代码中添加详细注释说明
+- ✅ 使用 JSDoc 或 TypeDoc 格式的注释
+
+### 复杂逻辑注释
+
+```typescript
+// 使用 Set 去重，提高性能（避免 O(n²) 复杂度）
+const uniqueIds = [...new Set(ids)]
+
+// ❌ 坏 - 只是重复代码
+// 创建 Set 去重
+const uniqueIds = [...new Set(ids)]
+```
+
+## 错误处理
+
+```typescript
+// ✅ 好 - 明确的错误处理
+try {
+  const data = await fetchData()
+  return data
+} catch (error) {
+  console.error('Failed to fetch data:', error)
+  throw new Error(`Data fetch failed: ${error.message}`)
+}
+
+// ❌ 坏 - 吞掉错误
+try {
+  const data = await fetchData()
+} catch (error) {
+  // 什么都不做
+}
+```
+
+## 性能优化原则
+
+1. **避免不必要的计算** - 使用 computed 缓存
+2. **按需加载** - 使用动态导入
+3. **防抖节流** - 高频事件使用防抖/节流
+4. **列表渲染** - 使用 key 优化