m8-codex-mcp 1.0.0

package/data/standards/02-vue/state-management.md

@@ -0,0 +1,293 @@
+# 状态管理规范
+
+> 定义 Vue 应用的状态管理规范，Vue2 使用 Vuex，Vue3 使用 Pinia。
+
+## 📁 文件结构
+
+```
+src/pages/[module_name]/
+├── [module_name].vue
+├── store.js          # Vue2 Vuex 定义
+└── store.ts          # Vue3 Pinia 定义
+```
+
+## 📦 Vue2 - Vuex
+
+### store.js 文件结构
+
+```javascript
+export default {
+  // 模块名称：与目录名一致
+  moduleName: "m8demo",
+
+  // 使用独立命名空间
+  namespaced: true,
+
+  // 状态数据
+  state: {
+    count: 0, // 计数器
+    userInfo: null, // 用户信息
+    orderList: [], // 订单列表
+  },
+
+  // 同步修改状态
+  mutations: {
+    /**
+     * 设置计数
+     * @param {Object} state - 状态对象
+     * @param {number} n - 增加的数量
+     */
+    increment(state, n) {
+      state.count += n;
+    },
+
+    /**
+     * 设置用户信息
+     * @param {Object} state - 状态对象
+     * @param {Object} userInfo - 用户信息
+     */
+    setUserInfo(state, userInfo) {
+      state.userInfo = userInfo;
+    },
+  },
+
+  // 异步操作
+  actions: {
+    /**
+     * 异步获取用户信息
+     * @param {Object} context - Vuex 上下文
+     * @param {string} userId - 用户ID
+     */
+    async fetchUserInfo({ commit }, userId) {
+      const result = await Util.ajax({
+        url: `${Config.serverUrl}/api/user/${userId}`,
+      });
+      commit("setUserInfo", result.data);
+    },
+  },
+
+  // 计算属性
+  getters: {
+    /**
+     * 获取格式化的用户名
+     */
+    formattedName: (state) => {
+      return state.userInfo ? `用户: ${state.userInfo.name}` : "未登录";
+    },
+  },
+};
+```
+
+### 组件中使用
+
+```vue
+<template>
+  <view>
+    <text>Count: {{ count }}</text>
+    <text>User: {{ formattedName }}</text>
+  </view>
+</template>
+
+<script>
+export default {
+  computed: {
+    // 获取状态
+    count() {
+      return this.$store.state.m8demo.count;
+    },
+    // 获取 getter
+    formattedName() {
+      return this.$store.getters["m8demo/formattedName"];
+    },
+  },
+  methods: {
+    // 提交 mutation
+    addCount() {
+      this.$store.commit("m8demo/increment", 1);
+    },
+    // 派发 action
+    loadUser(userId) {
+      this.$store.dispatch("m8demo/fetchUserInfo", userId);
+    },
+  },
+};
+</script>
+```
+
+## 📦 Vue3 - Pinia
+
+### store.ts 文件结构
+
+```typescript
+import { defineStore } from "pinia";
+
+/**
+ * 用户中心状态管理
+ * 命名规则: use + 模块名 + Store
+ */
+export const useUserCenterStore = defineStore(
+  // Store 的唯一 ID
+  "user_center",
+  {
+    // 状态数据
+    state: () => ({
+      count: 0, // 计数器
+      userInfo: null as UserInfo | null, // 用户信息
+      orderList: [] as Order[], // 订单列表
+    }),
+
+    // 计算属性
+    getters: {
+      /**
+       * 格式化用户名
+       */
+      formattedName: (state) => {
+        return state.userInfo ? `用户: ${state.userInfo.name}` : "未登录";
+      },
+
+      /**
+       * 订单总数
+       */
+      orderCount: (state) => state.orderList.length,
+    },
+
+    // 方法（支持同步和异步）
+    actions: {
+      /**
+       * 增加计数
+       * @param n - 增加的数量
+       */
+      increment(n: number) {
+        this.count += n;
+      },
+
+      /**
+       * 获取用户信息
+       * @param userId - 用户ID
+       */
+      async fetchUserInfo(userId: string) {
+        const result = await Util.ajax({
+          url: `${Config.serverUrl}/api/user/${userId}`,
+        });
+        this.userInfo = result.data;
+      },
+
+      /**
+       * 重置状态
+       */
+      reset() {
+        this.count = 0;
+        this.userInfo = null;
+        this.orderList = [];
+      },
+    },
+  }
+);
+
+// 类型定义
+interface UserInfo {
+  id: string;
+  name: string;
+  avatar: string;
+}
+
+interface Order {
+  id: string;
+  title: string;
+  amount: number;
+}
+```
+
+### 组件中使用
+
+```vue
+<template>
+  <view>
+    <text>Count: {{ store.count }}</text>
+    <text>User: {{ store.formattedName }}</text>
+  </view>
+</template>
+
+<script lang="ts" setup>
+import { useUserCenterStore } from "./store";
+
+// 获取 store 实例
+const store = useUserCenterStore();
+
+// 直接读取状态
+console.log(store.count);
+
+// 直接读取 getter
+console.log(store.formattedName);
+
+// 调用 action
+store.increment(1);
+
+// 异步 action
+store.fetchUserInfo("user123");
+
+// 重置状态
+store.reset();
+</script>
+```
+
+### 辅助函数（Options API 兼容）
+
+```vue
+<script>
+import { useUserCenterStore } from "./store";
+import { mapState, mapActions } from "pinia";
+
+export default {
+  computed: {
+    // 映射 state 和 getters
+    ...mapState(useUserCenterStore, ["count", "formattedName"]),
+  },
+  methods: {
+    // 映射 actions
+    ...mapActions(useUserCenterStore, ["increment", "fetchUserInfo"]),
+  },
+};
+</script>
+```
+
+## 📋 使用原则
+
+### 何时使用状态管理
+
+| 场景           | 推荐方案         |
+| -------------- | ---------------- |
+| 组件内部状态   | `ref` / `data`   |
+| 父子组件通信   | `props` / `emit` |
+| 跨页面共享数据 | Vuex / Pinia     |
+| 全局配置       | Vuex / Pinia     |
+
+### 最佳实践
+
+1. **避免滥用全局状态**
+
+   - 优先使用 `props` / `emit` 进行组件通信
+   - 仅在确实需要跨页面共享时使用 Store
+
+2. **使用 computed 获取派生状态**
+
+   ```typescript
+   // ✅ 使用 getter
+   const userName = computed(() => store.userInfo?.name);
+
+   // ❌ 避免在方法中直接计算
+   const getUserName = () => store.userInfo?.name;
+   ```
+
+3. **模块化状态管理**
+   - 每个模块维护自己的 Store
+   - 避免将所有状态放在一个文件中
+
+## ✅ 状态管理检查清单
+
+- [ ] Vue2 使用 Vuex，Vue3 使用 Pinia
+- [ ] Store 文件放在对应模块目录下
+- [ ] 使用独立命名空间
+- [ ] 变量和方法添加中文注释
+- [ ] 优先使用 props/emit，避免滥用全局状态
+- [ ] 使用 getter 获取派生状态

package/data/standards/03-css/index.md

@@ -0,0 +1,165 @@
+# CSS 样式规范
+
+> 定义 M8 项目的 CSS/SCSS 编码规范与最佳实践。
+
+## 📝 命名规范
+
+### BEM 命名
+
+| 类型               | 格式               | 示例            |
+| ------------------ | ------------------ | --------------- |
+| 块（Block）        | `.block`           | `.card`         |
+| 元素（Element）    | `.block__element`  | `.card__title`  |
+| 修饰符（Modifier） | `.block--modifier` | `.card--active` |
+
+```scss
+.user-card {
+  &__avatar {
+  }
+  &__name {
+  }
+  &--vip {
+  }
+}
+```
+
+### class/id 命名规则
+
+- ✅ 使用小写字母
+- ✅ 使用中划线连接
+- ❌ 禁止使用大写或驼峰
+- ❌ 避免过度简写
+
+## 🎨 编码规范
+
+### 基本规则
+
+| 规则       | 说明                     |
+| ---------- | ------------------------ |
+| 预处理器   | 使用 SASS 编写           |
+| 颜色简写   | `#666666` → `#666`       |
+| 避免单位   | 0 值不加单位 `margin: 0` |
+| 选择器换行 | 多选择器各占一行         |
+
+### 样式穿透
+
+```scss
+// Vue2
+::v-deep .em-cell {
+  color: red;
+}
+
+// Vue3
+:deep(.em-cell) {
+  color: red;
+}
+```
+
+**穿透后禁止使用 BEM 后缀选择器**，解决方案：
+
+```scss
+// 方案1：分开写
+:deep(.em-cell) {
+}
+:deep(.em-cell__title) {
+}
+
+// 方案2：@at-root
+:deep(.em-cell) {
+  @at-root {
+    #{&}__title {
+    }
+  }
+}
+```
+
+### CSS 书写顺序
+
+1. 位置属性：`position`, `top`, `z-index`, `display`, `float`
+2. 大小属性：`width`, `height`, `padding`, `margin`
+3. 文字属性：`font`, `line-height`, `color`, `text-align`
+4. 背景边框：`background`, `border`
+5. 其他属性：`animation`, `transition`
+
+### 避免的写法
+
+```scss
+// ❌ 深层嵌套（不超过3层）
+.a {
+  .b {
+    .c {
+      .d {
+      }
+    }
+  }
+}
+
+// ❌ 标签选择器
+div.container {
+}
+
+// ❌ 通配符选择器
+* {
+  margin: 0;
+}
+
+// ❌ !important（除非覆盖第三方库）
+.text {
+  color: red !important;
+}
+```
+
+## 📁 目录结构
+
+```
+src/
+├── pages/
+│   └── [module]/
+│       └── css/
+│           └── [module].scss   # 模块样式
+└── common/
+    └── css/
+        └── common.extend       # 拓展样式
+```
+
+### 引用方式
+
+```vue
+<style lang="scss" scoped>
+@import "./css/login.scss";
+</style>
+```
+
+## 🎨 变量管理
+
+```scss
+// variables.scss
+$primary-color: #1989fa;
+$text-color: #323233;
+$border-color: #ebedf0;
+
+$font-size-sm: 12px;
+$font-size-md: 14px;
+$font-size-lg: 16px;
+
+$spacing-xs: 4px;
+$spacing-sm: 8px;
+$spacing-md: 16px;
+```
+
+## ⚡ 性能优化
+
+- 避免深层嵌套（不超过 3 层）
+- 合理使用选择器
+- 压缩和合并样式文件
+- 删除冗余代码
+
+## ✅ CSS 检查清单
+
+- [ ] 使用 BEM 命名规范
+- [ ] class 使用小写 + 中划线
+- [ ] 样式穿透语法与 Vue 版本匹配
+- [ ] 遵循 CSS 书写顺序
+- [ ] 避免使用 !important
+- [ ] 嵌套不超过 3 层
+- [ ] 删除冗余代码

package/data/standards/04-api/ajax.md

@@ -0,0 +1,178 @@
+# Ajax 请求规范
+
+> 定义 M8 项目中 Ajax 请求的使用规范与示例。
+
+## 📡 普通 Ajax 请求
+
+### 基础用法
+
+```javascript
+Util.ajax({
+  url: Config.serverUrl + "/api/user/detail",
+  data: {
+    params: JSON.stringify({
+      userId: "12345",
+    }),
+  },
+})
+  .then((res) => {
+    console.log("请求成功:", res);
+
+    // 标准响应处理
+    if (res?.status?.code === 1) {
+      const data = res.custom;
+      // 处理数据
+    }
+  })
+  .catch((error) => {
+    console.error("请求失败:", error);
+  })
+  .finally(() => {
+    // 请求完成（无论成功失败）
+    ejs.ui.closeWaiting();
+  });
+```
+
+### 带加载提示
+
+```javascript
+ejs.ui.showWaiting("加载中...");
+
+Util.ajax({
+  url: `${Config.serverUrl}/api/data`,
+  data: {
+    params: JSON.stringify({ id: "123" }),
+  },
+})
+  .then((res) => {
+    if (res?.status?.code === 1) {
+      // 处理数据
+    } else {
+      ejs.ui.toast(res?.status?.message || "请求失败");
+    }
+  })
+  .catch((error) => {
+    ejs.ui.toast("网络请求失败");
+  })
+  .finally(() => {
+    ejs.ui.closeWaiting();
+  });
+```
+
+## 📤 文件上传
+
+### 跨端上传（推荐）
+
+支持 H5、微信小程序、支付宝小程序：
+
+```javascript
+// afterRead 回调中处理上传
+const afterRead = (file) => {
+  Util.upload({
+    url: `${Config.serverUrl}/api/upload`,
+    filePath: file.path, // 文件路径
+    name: file.name, // 文件名
+    formData: {
+      userId: "user123",
+    },
+    success: (res) => {
+      console.log("上传成功:", res);
+    },
+    fail: (error) => {
+      console.error("上传失败:", error);
+    },
+  });
+};
+```
+
+### H5 专用上传
+
+```javascript
+const afterRead = (file) => {
+  Util.upload({
+    url: `${Config.serverUrl}/api/upload`,
+    files: [{ file: file }],
+    formData: {
+      userId: "user123",
+    },
+    success: (res) => {
+      console.log("上传成功:", res);
+    },
+  });
+};
+```
+
+### 小程序文件名生成
+
+```javascript
+const generateFileName = (path) => {
+  const timestamp = new Date().getTime();
+  const random = Math.floor(Math.random() * 10000);
+  const extension = path.toLowerCase().split(".").pop();
+  return `file_${timestamp}_${random}.${extension}`;
+};
+```
+
+## 📦 完整上传组件示例
+
+```vue
+<template>
+  <em-uploader :after-read="afterRead" />
+</template>
+
+<script>
+export default {
+  methods: {
+    afterRead(file) {
+      // 判断是数组还是对象（多选/单选）
+      const files = Array.isArray(file) ? file : [file];
+
+      files.forEach((f) => {
+        Util.upload({
+          url: `${Config.serverUrl}/api/upload`,
+          filePath: f.path,
+          name: f.name || this.generateFileName(f.path),
+          formData: { userId: "user123" },
+          success: (res) => {
+            console.log("上传成功:", res);
+          },
+          fail: (error) => {
+            ejs.ui.toast("上传失败");
+          },
+        });
+      });
+    },
+
+    generateFileName(path) {
+      const timestamp = new Date().getTime();
+      const random = Math.floor(Math.random() * 10000);
+      const extension = path.toLowerCase().split(".").pop();
+      return `file_${timestamp}_${random}.${extension}`;
+    },
+  },
+};
+</script>
+```
+
+## 📋 文件对象属性
+
+| 属性   | 说明     | 平台   |
+| ------ | -------- | ------ |
+| `path` | 文件路径 | 全平台 |
+| `file` | 文件对象 | 全平台 |
+| `name` | 文件名   | 仅 H5  |
+| `size` | 文件大小 | 仅 H5  |
+
+## ⚠️ 注意事项
+
+1. **跨端兼容**：小程序使用 `filePath` + `name`，H5 使用 `files`
+2. **文件名获取**：小程序环境下需手动生成文件名
+3. **多选处理**：`afterRead` 多选时返回数组，单选返回对象
+
+## ✅ 检查清单
+
+- [ ] 使用 `Util.ajax` 发起请求
+- [ ] 请求参数使用 `JSON.stringify`
+- [ ] 正确处理响应状态码
+- [ ] 添加 loading 状态
+- [ ] 文件上传区分平台