m8-mcp-server 1.0.0

package/dist/data/standards/js-style.md

@@ -0,0 +1,394 @@
+# JavaScript/TypeScript 编码规范
+
+<!-- id: js-style -->
+<!-- category: javascript -->
+<!-- version: 1.0.0 -->
+<!-- lastUpdated: 2024-12-19 -->
+
+本规范定义了 M8 框架项目中 JavaScript/TypeScript 的编码标准。
+
+## 命名规范
+
+### 变量和函数使用 camelCase
+
+```javascript
+// ✅ 正确
+const userName = "John";
+const itemCount = 10;
+function getUserInfo() {}
+function handleClick() {}
+
+// ❌ 错误
+const user_name = "John";
+const ItemCount = 10;
+function GetUserInfo() {}
+```
+
+### 常量使用 UPPER_SNAKE_CASE
+
+```javascript
+// ✅ 正确
+const MAX_COUNT = 100;
+const API_BASE_URL = "/api";
+const DEFAULT_PAGE_SIZE = 20;
+
+// ❌ 错误
+const maxCount = 100;
+const apiBaseUrl = "/api";
+```
+
+### 类和组件使用 PascalCase
+
+```javascript
+// ✅ 正确
+class UserService {}
+class DataManager {}
+const UserProfile = defineComponent({});
+
+// ❌ 错误
+class userService {}
+class data_manager {}
+```
+
+## 函数规范
+
+### 函数应该只做一件事
+
+```javascript
+// ✅ 正确
+function validateEmail(email) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+function formatUserName(user) {
+  return `${user.firstName} ${user.lastName}`;
+}
+
+// ❌ 错误 - 函数做了太多事情
+function processUser(user) {
+  // 验证
+  if (!user.email.includes("@")) {
+    throw new Error("Invalid email");
+  }
+  // 格式化
+  user.fullName = user.firstName + " " + user.lastName;
+  // 保存
+  saveToDatabase(user);
+  // 发送通知
+  sendNotification(user);
+}
+```
+
+### 使用默认参数
+
+```javascript
+// ✅ 正确
+function createUser(name, role = "user", active = true) {
+  return { name, role, active };
+}
+
+// ❌ 错误
+function createUser(name, role, active) {
+  role = role || "user";
+  active = active !== undefined ? active : true;
+  return { name, role, active };
+}
+```
+
+### 使用解构参数
+
+```javascript
+// ✅ 正确
+function updateUser({ id, name, email }) {
+  // ...
+}
+
+updateUser({ id: 1, name: "John", email: "john@example.com" });
+
+// ❌ 错误
+function updateUser(id, name, email) {
+  // ...
+}
+```
+
+## 异步处理
+
+### 优先使用 async/await
+
+```javascript
+// ✅ 正确
+async function fetchUserData(userId) {
+  try {
+    const response = await Util.ajax({
+      url: `${Config.serverUrl}/api/user/${userId}`,
+      type: "GET",
+    });
+    return response.data;
+  } catch (error) {
+    console.error("获取用户数据失败:", error);
+    throw error;
+  }
+}
+
+// ❌ 不推荐 - 回调地狱
+function fetchUserData(userId, callback) {
+  Util.ajax({
+    url: `${Config.serverUrl}/api/user/${userId}`,
+    success: (response) => {
+      Util.ajax({
+        url: `${Config.serverUrl}/api/user/${response.data.id}/profile`,
+        success: (profile) => {
+          callback(null, { ...response.data, profile: profile.data });
+        },
+        error: callback,
+      });
+    },
+    error: callback,
+  });
+}
+```
+
+### 并发请求使用 Promise.all 或 Util.ajaxAll
+
+```javascript
+// ✅ 正确
+async function loadPageData() {
+  const [users, products, orders] = await Promise.all([
+    fetchUsers(),
+    fetchProducts(),
+    fetchOrders(),
+  ]);
+
+  return { users, products, orders };
+}
+
+// 或使用 Util.ajaxAll
+const ajax1 = Util.ajax({ url: "/api/users" });
+const ajax2 = Util.ajax({ url: "/api/products" });
+
+Util.ajaxAll(ajax1, ajax2).then(([users, products]) => {
+  // 处理数据
+});
+```
+
+## 错误处理
+
+### 使用 try-catch 处理异步错误
+
+```javascript
+// ✅ 正确
+async function submitForm(data) {
+  try {
+    const result = await Util.ajax({
+      url: Config.serverUrl + "/api/submit",
+      type: "POST",
+      data: { params: JSON.stringify(data) },
+    });
+
+    if (result.code === 1) {
+      return result.data;
+    } else {
+      throw new Error(result.message || "提交失败");
+    }
+  } catch (error) {
+    // 统一错误处理
+    console.error("表单提交失败:", error);
+    ejs.ui.toast({ message: error.message || "网络错误，请重试" });
+    throw error;
+  }
+}
+```
+
+### 提供有意义的错误信息
+
+```javascript
+// ✅ 正确
+function validateAge(age) {
+  if (typeof age !== "number") {
+    throw new TypeError(`年龄必须是数字，收到: ${typeof age}`);
+  }
+  if (age < 0 || age > 150) {
+    throw new RangeError(`年龄必须在 0-150 之间，收到: ${age}`);
+  }
+}
+
+// ❌ 错误
+function validateAge(age) {
+  if (typeof age !== "number" || age < 0 || age > 150) {
+    throw new Error("Invalid");
+  }
+}
+```
+
+## M8 框架最佳实践
+
+### 使用 Util.ajax 进行 HTTP 请求
+
+```javascript
+// ✅ 正确 - 使用 Util.ajax
+const result = await Util.ajax({
+  url: Config.serverUrl + "/api/data",
+  type: "POST",
+  data: { params: JSON.stringify(params) },
+  dataPath: "data",
+});
+
+// ❌ 错误 - 使用原生 fetch 或不存在的 API
+const result = await fetch("/api/data");
+const result = await ejs.http.post("/api/data"); // 不存在的 API
+```
+
+### 使用 Config 管理配置
+
+```javascript
+// ✅ 正确
+const apiUrl = Config.serverUrl + "/api/users";
+const timeout = Config.requestTimeout;
+
+// ❌ 错误 - 硬编码
+const apiUrl = "http://localhost:3000/api/users";
+```
+
+## 反模式
+
+### 避免使用 var
+
+```javascript
+// ❌ 错误
+var count = 0;
+var name = "John";
+
+// ✅ 正确
+const name = "John"; // 不会重新赋值
+let count = 0; // 会重新赋值
+```
+
+### 避免修改函数参数
+
+```javascript
+// ❌ 错误
+function updateUser(user) {
+  user.name = "New Name"; // 直接修改参数
+  return user;
+}
+
+// ✅ 正确
+function updateUser(user) {
+  return {
+    ...user,
+    name: "New Name",
+  };
+}
+```
+
+### 避免使用 == 进行比较
+
+```javascript
+// ❌ 错误
+if (value == null) {
+}
+if (count == "0") {
+}
+
+// ✅ 正确
+if (count === 0) {
+}
+```
+
+## M8 框架 JS 开发规范
+
+### 全局变量与工具类
+
+以下变量和方法在 M8 框架中已经全局注入，**严禁通过 import 导入**：
+
+- `Config`: 全局配置对象 (如 `Config.serverUrl`)
+- `Util`: 全局工具方法
+
+```javascript
+// ❌ 错误
+import { Util } from "@shared";
+import { Config } from "@config";
+
+// ✅ 正确
+Util.string.isMobile("13800000000");
+const url = Config.serverUrl + "/api/list";
+```
+
+### 字符串校验 (Util.string)
+
+优先使用 `Util.string` 提供的校验方法，而不是手写正则：
+
+- `isMobile(str)`: 手机号
+- `isTel(str)`: 固定电话
+- `isPhone(str)`: 电话 (手机或固话)
+- `isEmail(str)`: 邮箱
+- `isIdCard(str)`: 身份证
+- `isPostCode(str)`: 邮政编码
+- `isOrgCode(str)`: 组织机构代码
+
+### 页面导航 (ejs.page)
+
+使用 `ejs.page` 系列 API 进行页面跳转：
+
+```javascript
+// 打开新页面
+ejs.page.open({
+  pageUrl: "./detail", // 同模块相对路径
+  // pageUrl: '../other_module/index', // 跨模块路径
+  data: { id: "123" }, // 传递参数
+  success: (result) => {
+    // 目标页面关闭并返回数据时触发
+    console.log("Returned:", result.resultData);
+  },
+});
+
+// 关闭当前页面
+ejs.page.close({
+  resultData: { status: "success" },
+});
+```
+
+### 接收页面参数
+
+- **Vue2**: `Util.getExtraDataByKey('key')` (在 `created` 中)
+- **Vue3**: `onLoad((options) => { ... })` (在 `setup` 中)
+
+### 网络请求 (Util.ajax)
+
+必须使用 `Util.ajax` 进行网络请求，**禁止使用原生 fetch 或 axios**。
+
+```javascript
+Util.ajax({
+  url: `${Config.serverUrl}/rest/api/list`,
+  type: "POST",
+  data: {
+    params: JSON.stringify({ keyword: "test" }),
+  },
+  // dataPath: 'custom.infolist' // 可选，自动提取数据路径
+})
+  .then((res) => {
+    if (res.status.code === 1) {
+      // handle success
+    } else {
+      ejs.ui.toast(res.status.text);
+    }
+  })
+  .catch((err) => {
+    console.error(err);
+  });
+```
+
+### 日志输出规范
+
+- 禁止使用无参数的 `console.log`。
+- 必须包含日志信息描述。
+- 关键逻辑（如表单提交、接口错误）必须打日志。
+
+```javascript
+// ❌ 错误
+console.log(data);
+
+// ✅ 正确
+console.log("提交表单数据:", data);
+console.error("接口请求失败:", err);
+```

package/dist/data/standards/project-structure.md

@@ -0,0 +1,325 @@
+# 项目结构规范
+
+<!-- id: project-structure -->
+<!-- category: project -->
+<!-- version: 1.0.0 -->
+<!-- lastUpdated: 2024-12-19 -->
+
+本规范定义了 M8 框架项目的目录结构和文件组织标准。
+
+## 目录结构
+
+### 标准项目结构
+
+```
+project/
+├── src/
+│   ├── api/              # API 接口定义
+│   │   ├── index.js      # API 统一导出
+│   │   ├── user.js       # 用户相关接口
+│   │   └── order.js      # 订单相关接口
+│   ├── assets/           # 静态资源
+│   │   ├── images/       # 图片资源
+│   │   ├── styles/       # 全局样式
+│   │   └── fonts/        # 字体文件
+│   ├── components/       # 公共组件
+│   │   ├── common/       # 通用组件
+│   │   └── business/     # 业务组件
+│   ├── composables/      # Vue3 组合式函数 (M8.4)
+│   ├── hooks/            # 自定义 hooks
+│   ├── pages/            # 页面组件
+│   ├── router/           # 路由配置
+│   ├── store/            # 状态管理
+│   │   ├── index.js
+│   │   └── modules/
+│   ├── utils/            # 工具函数
+│   ├── App.vue           # 根组件
+│   └── main.js           # 入口文件
+├── public/               # 公共资源（不经过构建）
+├── config/               # 项目配置
+├── tests/                # 测试文件
+├── package.json
+└── README.md
+```
+
+## 文件命名
+
+### 组件文件
+
+组件文件使用 PascalCase 命名。
+
+```
+// ✅ 正确
+components/
+├── UserProfile.vue
+├── TodoList.vue
+├── SearchInput.vue
+└── common/
+    ├── BaseButton.vue
+    └── BaseInput.vue
+
+// ❌ 错误
+components/
+├── userProfile.vue
+├── todo-list.vue
+└── searchinput.vue
+```
+
+### 页面文件
+
+页面文件应严格按照模块划分，每个模块对应一个文件夹。文件名应与模块名保持一致（m8 规范），或使用 kebab-case（通用规范）。
+
+```
+// ✅ 正确
+pages/
+├── home/
+│   └── index.vue
+├── user/
+│   ├── index.vue
+│   ├── profile.vue
+│   └── settings.vue
+└── order/
+    ├── list.vue
+    └── detail.vue
+```
+
+### 工具函数文件
+
+工具函数文件使用 kebab-case 命名。
+
+```
+// ✅ 正确
+utils/
+├── date-format.js
+├── string-utils.js
+├── validate.js
+└── index.js
+
+// ❌ 错误
+utils/
+├── dateFormat.js
+├── StringUtils.js
+```
+
+## API 组织
+
+### 按模块组织 API
+
+```javascript
+// api/user.js
+import { request } from "./request";
+
+/**
+ * 获取用户信息
+ */
+export function getUserInfo(userId) {
+  return request({
+    url: `/api/user/${userId}`,
+    method: "GET",
+  });
+}
+
+/**
+ * 更新用户信息
+ */
+export function updateUserInfo(data) {
+  return request({
+    url: "/api/user/update",
+    method: "POST",
+    data,
+  });
+}
+
+// api/index.js - 统一导出
+export * from "./user";
+export * from "./order";
+export * from "./product";
+```
+
+### 请求封装
+
+```javascript
+// api/request.js
+/**
+ * 统一请求封装
+ */
+export function request(options) {
+  return Util.ajax({
+    url: Config.serverUrl + options.url,
+    type: options.method || "POST",
+    data: options.data ? { params: JSON.stringify(options.data) } : undefined,
+    dataPath: options.dataPath || "data",
+    ...options,
+  });
+}
+```
+
+## 组件组织
+
+### 公共组件
+
+公共组件放在 `components/common/` 目录下，使用 `Base` 或 `Ne` 前缀。
+
+```
+components/
+├── common/
+│   ├── BaseButton.vue      # 基础按钮
+│   ├── BaseInput.vue       # 基础输入框
+│   ├── BaseModal.vue       # 基础弹窗
+│   └── index.js            # 统一导出
+└── business/
+    ├── UserCard.vue        # 用户卡片
+    ├── OrderItem.vue       # 订单项
+    └── index.js
+```
+
+### 页面级组件
+
+页面特有的组件放在页面目录下的 `components/` 子目录中。
+
+```
+pages/
+└── order/
+    ├── index.vue
+    ├── detail.vue
+    └── components/
+        ├── OrderHeader.vue
+        ├── OrderItems.vue
+        └── OrderFooter.vue
+```
+
+## 状态管理
+
+### Vuex 模块化 (M8.3)
+
+```
+store/
+├── index.js
+└── modules/
+    ├── user.js
+    ├── cart.js
+    └── order.js
+```
+
+```javascript
+// store/modules/user.js
+export default {
+  namespaced: true,
+  state: () => ({
+    userInfo: null,
+    token: "",
+  }),
+  mutations: {
+    SET_USER_INFO(state, info) {
+      state.userInfo = info;
+    },
+  },
+  actions: {
+    async fetchUserInfo({ commit }) {
+      const result = await getUserInfo();
+      commit("SET_USER_INFO", result);
+    },
+  },
+};
+```
+
+### Pinia 模块化 (M8.4)
+
+```
+store/
+├── index.js
+└── modules/
+    ├── useUserStore.js
+    ├── useCartStore.js
+    └── useOrderStore.js
+```
+
+```javascript
+// store/modules/useUserStore.js
+import { defineStore } from "pinia";
+
+export const useUserStore = defineStore("user", {
+  state: () => ({
+    userInfo: null,
+    token: "",
+  }),
+  actions: {
+    async fetchUserInfo() {
+      const result = await getUserInfo();
+      this.userInfo = result;
+    },
+  },
+});
+```
+
+## 样式组织
+
+### 全局样式
+
+```
+assets/
+└── styles/
+    ├── index.scss          # 样式入口
+    ├── variables.scss      # 变量定义
+    ├── mixins.scss         # 混入
+    ├── reset.scss          # 重置样式
+    └── utils.scss          # 工具类
+```
+
+### 组件样式
+
+组件样式使用 scoped 或 CSS Modules。
+
+```vue
+<!-- 使用 scoped -->
+<style scoped lang="scss">
+.user-card {
+  // ...
+}
+</style>
+
+<!-- 或使用 CSS Modules -->
+<style module lang="scss">
+.userCard {
+  // ...
+}
+</style>
+```
+
+## 反模式
+
+### 避免过深的目录嵌套
+
+```
+// ❌ 错误 - 嵌套过深
+src/modules/user/pages/profile/components/header/UserAvatar.vue
+
+// ✅ 正确 - 扁平化
+src/pages/user/profile.vue
+src/components/UserAvatar.vue
+```
+
+### 避免循环依赖
+
+```javascript
+// ❌ 错误 - 循环依赖
+// a.js
+import { b } from "./b";
+export const a = b + 1;
+
+// b.js
+import { a } from "./a";
+export const b = a + 1;
+
+// ✅ 正确 - 提取公共依赖
+// constants.js
+export const BASE = 1;
+
+// a.js
+import { BASE } from "./constants";
+export const a = BASE + 1;
+
+// b.js
+import { BASE } from "./constants";
+export const b = BASE + 2;
+```