m8-codex-mcp 1.0.0

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

@@ -0,0 +1,192 @@
+# EJS API 规范
+
+> 定义 M8 框架 EJS API 的使用规范与示例。
+
+## 🚀 路由类 API
+
+### ejs.page.open - 打开新页面
+
+```javascript
+// 完整用法
+ejs.page.open({
+  pageUrl: "./detail", // 页面地址
+  pageStyle: 1,
+  orientation: 1,
+  alive: 0, // 0不保活，1保活
+  data: {
+    // 传递参数
+    id: "12345",
+  },
+  useRouter: true,
+  success: function (result) {
+    // 目标页面关闭后回调
+  },
+  error: function (error) {},
+});
+
+// 快速调用
+ejs.page.open("./detail", { id: "12345" });
+```
+
+**URL 规则**：
+
+- 同模块跳转：`'./路由名称'`
+- 跨模块跳转：`'../模块名称/路由名称'`
+
+### ejs.page.close - 关闭页面
+
+```javascript
+// 完整用法
+ejs.page.close({
+  resultData: { key: "value" },
+  success: function (result) {},
+  error: function (error) {},
+});
+
+// 快速调用
+ejs.page.close(JSON.stringify({ key: "value" }));
+ejs.page.close();
+```
+
+### ejs.page.replace - 替换页面
+
+```javascript
+ejs.page.replace({
+  url: "./new-page",
+  success: function (result) {},
+  error: function (error) {},
+});
+
+// 快速调用
+ejs.page.replace("./new-page");
+```
+
+### ejs.page.reload - 重新加载
+
+```javascript
+ejs.page.reload();
+// 注意：微信小程序请使用 uniapp API
+```
+
+## 💬 UI 类 API
+
+### ejs.ui.toast - 轻提示
+
+```javascript
+ejs.ui.toast("操作成功");
+```
+
+### ejs.ui.alert - 弹窗提示
+
+```javascript
+// 完整用法
+ejs.ui.alert({
+  title: "提示",
+  message: "操作已完成",
+  buttonName: "确定",
+  cancelable: 1,
+  h5UI: false,
+  success: function (result) {
+    // 点击按钮后回调
+  },
+});
+
+// 快速调用
+ejs.ui.alert(message, title, buttonName);
+```
+
+### ejs.ui.confirm - 确认对话框
+
+```javascript
+ejs.ui.confirm({
+  title: "确认操作",
+  message: "是否删除该记录？",
+  buttonLabels: ["取消", "确定"],
+  cancelable: 1,
+  h5UI: false,
+  success: function (result) {
+    // result.which: 0=取消, 1=确定
+    if (result.which === 1) {
+      // 确认操作
+    }
+  },
+});
+```
+
+### ejs.ui.showWaiting / closeWaiting - 加载提示
+
+```javascript
+// 显示加载
+ejs.ui.showWaiting("正在加载...");
+
+// 关闭加载
+ejs.ui.closeWaiting();
+```
+
+## 📅 选择器 API
+
+### ejs.ui.pickDate - 日期选择
+
+```javascript
+ejs.ui.pickDate({
+  title: "选择日期",
+  datetime: "2024-01-01", // 默认日期
+  minDate: "2020-01-01", // 最小日期
+  maxDate: "2030-12-31", // 最大日期
+  h5UI: false,
+  success: function (result) {
+    console.log(result.date); // '2024-01-15'
+  },
+});
+```
+
+### ejs.ui.pickTime - 时间选择
+
+```javascript
+ejs.ui.pickTime({
+  title: "选择时间",
+  datetime: "10:30",
+  minHour: 0,
+  maxHour: 23,
+  minMinute: 0,
+  maxMinute: 59,
+  h5UI: false,
+  success: function (result) {
+    console.log(result.time); // '14:30'
+  },
+});
+```
+
+### ejs.ui.pickDateTime - 日期时间选择
+
+```javascript
+ejs.ui.pickDateTime({
+  title: "选择日期时间",
+  datetime: "2024-01-01 10:30",
+  minDate: "2020-01-01",
+  maxDate: "2030-12-31",
+  h5UI: false,
+  success: function (result) {
+    console.log(result.datetime); // '2024-01-15 14:30'
+    console.log(result.week); // '周一'
+  },
+});
+```
+
+## 📌 使用优先级
+
+> **API 优先于组件使用**
+
+| 场景       | 使用方案             |
+| ---------- | -------------------- |
+| 消息提示   | `ejs.ui.toast`       |
+| 确认对话框 | `ejs.ui.confirm`     |
+| 加载提示   | `ejs.ui.showWaiting` |
+| 日期选择   | `ejs.ui.pickDate`    |
+| 时间选择   | `ejs.ui.pickTime`    |
+
+## ✅ 检查清单
+
+- [ ] 优先使用 EJS API 而非组件
+- [ ] 页面跳转使用正确的 URL 格式
+- [ ] 加载提示成对使用 show/close

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

@@ -0,0 +1,166 @@
+# Util 工具方法
+
+> M8 框架全局工具方法使用规范。`Util` 已全局注入，直接使用即可。
+
+## ⚠️ 重要提示
+
+```javascript
+// ❌ 禁止 import
+import { Util } from "@shared";
+
+// ✅ 直接使用
+Util.string.isMobile("18888888888");
+```
+
+## 📱 Util.string - 字符串验证
+
+### 手机号验证
+
+```javascript
+Util.string.isMobile("18962299766"); // true
+Util.string.isMobile("1896229976"); // false
+```
+
+### 固定电话验证
+
+```javascript
+Util.string.isTel("051258222222"); // true
+Util.string.isTel("1896229976"); // false
+```
+
+### 电话号码验证（手机+固话）
+
+```javascript
+Util.string.isPhone("18962299766"); // true
+Util.string.isPhone("051258222222"); // true
+Util.string.isPhone("1896229976"); // false
+```
+
+### 邮箱验证
+
+```javascript
+Util.string.isEmail("test@qq.com"); // true
+Util.string.isEmail("user.name@example.com"); // true
+```
+
+### 邮政编码验证
+
+```javascript
+Util.string.isPostCode("215600"); // true
+Util.string.isPostCode("21560"); // false
+```
+
+### 组织机构代码验证
+
+```javascript
+Util.string.isOrgCode("91320582704068740Y"); // true
+Util.string.isOrgCode("91320582704068740a"); // false
+```
+
+### 身份证验证
+
+```javascript
+Util.string.isIdCard("320926195511175276"); // true
+Util.string.isIdCard("320582199566666614"); // false
+```
+
+## 🔑 Util.uuid - 唯一标识生成
+
+```javascript
+const id = Util.uuid();
+// 返回: "550e8400-e29b-41d4-a716-446655440000"
+```
+
+## 🍪 Util.cookie - Cookie 操作
+
+### 设置 Cookie
+
+```javascript
+// 基础设置
+Util.cookie.set("token", "abc123");
+
+// 设置过期时间（秒）
+Util.cookie.set("token", "abc123", { "max-age": "3600" });
+```
+
+### 获取 Cookie
+
+```javascript
+const token = Util.cookie.get("token");
+```
+
+### 删除 Cookie
+
+```javascript
+// 默认路径
+Util.cookie.remove("token");
+
+// 自定义路径
+Util.cookie.remove("token", { path: "/" });
+```
+
+## 📡 Util.ajax - 网络请求
+
+```javascript
+Util.ajax({
+  url: Config.serverUrl + "/api/data",
+  data: {
+    params: JSON.stringify({ id: "123" }),
+  },
+})
+  .then((res) => {
+    console.log("成功:", res);
+  })
+  .catch((error) => {
+    console.error("失败:", error);
+  });
+```
+
+## 📤 Util.upload - 文件上传
+
+```javascript
+Util.upload({
+  url: Config.serverUrl + "/api/upload",
+  filePath: file.path,
+  name: file.name,
+  formData: { userId: "user123" },
+  success: (res) => {
+    console.log("上传成功:", res);
+  },
+});
+```
+
+## 📦 Util.getExtraDataByKey - 获取传参（Vue2）
+
+```javascript
+// Vue2 created 中获取页面传参
+created() {
+    const id = Util.getExtraDataByKey('id') || '';
+    this.loadDetail(id);
+}
+```
+
+## 📋 常用方法速查
+
+| 方法                          | 说明                  |
+| ----------------------------- | --------------------- |
+| `Util.string.isMobile(str)`   | 验证手机号            |
+| `Util.string.isTel(str)`      | 验证固定电话          |
+| `Util.string.isPhone(str)`    | 验证电话（手机+固话） |
+| `Util.string.isEmail(str)`    | 验证邮箱              |
+| `Util.string.isPostCode(str)` | 验证邮政编码          |
+| `Util.string.isIdCard(str)`   | 验证身份证            |
+| `Util.string.isOrgCode(str)`  | 验证组织机构代码      |
+| `Util.uuid()`                 | 生成 UUID             |
+| `Util.cookie.set(key, value)` | 设置 Cookie           |
+| `Util.cookie.get(key)`        | 获取 Cookie           |
+| `Util.cookie.remove(key)`     | 删除 Cookie           |
+| `Util.ajax(options)`          | 发起请求              |
+| `Util.upload(options)`        | 文件上传              |
+| `Util.getExtraDataByKey(key)` | 获取页面传参          |
+
+## ✅ 检查清单
+
+- [ ] 未通过 import 导入 Util
+- [ ] 优先使用 Util 提供的验证方法
+- [ ] 表单验证使用 Util.string 系列方法

package/data/standards/05-typescript/index.md

@@ -0,0 +1,166 @@
+# TypeScript 规范
+
+> 定义 M8 项目中 TypeScript 的使用规范。
+
+## 📝 类型声明规范
+
+### 必须显式声明类型
+
+```typescript
+// ✅ 正确：显式声明
+const userName: string = "admin";
+const userAge: number = 25;
+const isActive: boolean = true;
+
+// ❌ 错误：依赖推断的复杂类型
+const userData = fetchUserData(); // 类型不明确
+```
+
+### 禁止使用 any
+
+```typescript
+// ❌ 禁止
+const data: any = response.data;
+function process(item: any) {}
+
+// ✅ 正确：使用具体类型或 unknown
+const data: UserInfo = response.data;
+function process(item: unknown) {
+  if (isUserInfo(item)) {
+    // 类型收窄后使用
+  }
+}
+```
+
+## 📦 接口与类型定义
+
+### 命名规范
+
+| 类型     | 规则                | 示例          |
+| -------- | ------------------- | ------------- |
+| 接口     | PascalCase + I 前缀 | `IUserInfo`   |
+| 类型     | PascalCase + T 前缀 | `TStatus`     |
+| 枚举替代 | 常量对象            | `USER_STATUS` |
+
+### 优先使用接口
+
+```typescript
+// ✅ 推荐：接口（支持扩展和合并）
+interface IUserInfo {
+  id: string;
+  name: string;
+  age: number;
+}
+
+interface IUserInfo {
+  avatar?: string; // 接口合并
+}
+
+// ⚠️ 次选：类型别名
+type TUserInfo = {
+  id: string;
+  name: string;
+};
+```
+
+### 避免使用枚举
+
+```typescript
+// ❌ 避免：枚举
+enum UserStatus {
+  Active = 1,
+  Inactive = 0,
+}
+
+// ✅ 推荐：常量对象
+const USER_STATUS = {
+  ACTIVE: 1,
+  INACTIVE: 0,
+} as const;
+
+type TUserStatus = (typeof USER_STATUS)[keyof typeof USER_STATUS];
+```
+
+## 🧩 组件 Props 定义
+
+```typescript
+// Vue3 组件 Props
+interface IProps {
+  userId: string; // 必填
+  userName?: string; // 可选
+  userAge?: number; // 可选
+}
+
+const props = withDefaults(defineProps<IProps>(), {
+  userName: "默认用户",
+  userAge: 0,
+});
+```
+
+## 📋 常用类型定义
+
+### API 响应类型
+
+```typescript
+// 通用响应结构
+interface IApiResponse<T> {
+  status: {
+    code: number;
+    message: string;
+  };
+  custom: T;
+}
+
+// 列表响应
+interface IListResponse<T> {
+  infolist: T[];
+  total: number;
+}
+
+// 使用示例
+type TUserListResponse = IApiResponse<IListResponse<IUserInfo>>;
+```
+
+### 表单数据类型
+
+```typescript
+interface ILoginForm {
+  username: string;
+  password: string;
+  remember?: boolean;
+}
+
+const form = ref<ILoginForm>({
+  username: "",
+  password: "",
+  remember: false,
+});
+```
+
+## ⚡ 类型工具
+
+```typescript
+// Partial - 所有属性可选
+type TPartialUser = Partial<IUserInfo>;
+
+// Required - 所有属性必填
+type TRequiredUser = Required<IUserInfo>;
+
+// Pick - 选取部分属性
+type TUserBasic = Pick<IUserInfo, "id" | "name">;
+
+// Omit - 排除部分属性
+type TUserWithoutId = Omit<IUserInfo, "id">;
+
+// Record - 键值对类型
+type TUserMap = Record<string, IUserInfo>;
+```
+
+## ✅ TypeScript 检查清单
+
+- [ ] 显式声明变量类型
+- [ ] 未使用 any 类型
+- [ ] 接口使用 I 前缀
+- [ ] 类型使用 T 前缀
+- [ ] 使用常量对象替代枚举
+- [ ] Props 配合接口定义

package/data/standards/06-mock/index.md

@@ -0,0 +1,154 @@
+# Mock 数据规范
+
+> 定义 M8 项目中 Mock 数据的使用规范。
+
+## 📁 文件位置
+
+```
+src/pages/[module_name]/
+├── [module_name].vue
+├── router.js
+├── store.js
+└── mock.js          # Mock 数据定义
+```
+
+框架会自动引入模块下的 `mock.js` 文件。
+
+## 📝 基础结构
+
+```javascript
+import Mock from "@mock";
+
+const resultData = [
+  {
+    methodUrl: "/rest/api/endpoint", // 接口地址
+    input: {}, // 入参（可选）
+    output: {}, // 出参（Mock 数据）
+  },
+];
+
+export default resultData;
+```
+
+## 📋 列表数据示例
+
+```javascript
+import Mock from "@mock";
+
+const resultData = [
+  {
+    methodUrl: "/rest/mock/list",
+    input: {
+      keyword: "",
+      currentpageindex: "",
+      pagesize: "",
+    },
+    output: Mock.mock({
+      "infolist|10-20": [
+        {
+          title: () => Mock.Random.csentence(10),
+          date: () => Mock.Random.date(),
+          id: () => Mock.Random.guid(),
+          content: "来源：综合",
+          photo: () => Mock.Random.image("114x83", "#00405d", "#FFF", "Mock"),
+        },
+      ],
+    }),
+  },
+];
+
+export default resultData;
+```
+
+## 📄 详情数据示例
+
+```javascript
+import Mock from "@mock";
+
+const resultData = [
+  {
+    methodUrl: "/rest/mock/detail",
+    input: {
+      guid: "",
+    },
+    output: Mock.mock({
+      info: {
+        title: Mock.Random.csentence(5, 10),
+        content: Mock.Random.cparagraph(3, 5),
+        author: Mock.Random.cname(),
+        date: Mock.Random.date(),
+        views: Mock.Random.integer(100, 10000),
+      },
+    }),
+  },
+];
+
+export default resultData;
+```
+
+## 🎲 Mock.js 常用方法
+
+| 方法                            | 说明       | 示例             |
+| ------------------------------- | ---------- | ---------------- |
+| `Mock.Random.guid()`            | 生成 GUID  | `"550e8400-..."` |
+| `Mock.Random.date()`            | 随机日期   | `"2024-01-15"`   |
+| `Mock.Random.cname()`           | 随机中文名 | `"张三"`         |
+| `Mock.Random.csentence(n)`      | 中文句子   | `"这是一段..."`  |
+| `Mock.Random.cparagraph()`      | 中文段落   | 多句话           |
+| `Mock.Random.integer(min, max)` | 随机整数   | `256`            |
+| `Mock.Random.image(size)`       | 随机图片   | URL              |
+
+### 数组生成语法
+
+```javascript
+// 生成 10-20 个元素的数组
+'infolist|10-20': [{ ... }]
+
+// 固定生成 5 个元素
+'items|5': [{ ... }]
+
+// 随机选择一个
+'status|1': ['待处理', '处理中', '已完成']
+```
+
+## 📡 请求调用示例
+
+```javascript
+Util.ajax({
+  url: `${Config.serverUrl}/rest/mock/list`,
+  data: {
+    params: JSON.stringify({
+      currentpageindex: 0,
+      pagesize: 10,
+    }),
+  },
+})
+  .then((result) => {
+    if (result?.status?.code === 1) {
+      // 获取 mock 数据
+      console.log(result.custom.infolist);
+    }
+  })
+  .catch((err) => {
+    console.error(err);
+  });
+```
+
+## ⚠️ 注意事项
+
+1. **扁平结构**：直接导出 `info` 或 `infolist`，无需嵌套 `custom`/`status`
+2. **数组导出**：`resultData` 必须是数组
+3. **接口匹配**：`methodUrl` 用于匹配请求地址
+4. **错误处理**：所有 mock 接口应包含错误处理
+
+## 🔄 与真实接口切换
+
+使用 `sdoc-mcp` 服务时，可检索真实接口替换 Mock。
+
+## ✅ 检查清单
+
+- [ ] mock.js 放在模块目录下
+- [ ] resultData 为数组格式
+- [ ] 包含 methodUrl、input、output
+- [ ] 数据结构为扁平格式
+- [ ] 使用 Mock.Random 生成随机数据