m8-codex-mcp 1.0.0

package/data/standards/02-vue/component.md

@@ -0,0 +1,299 @@
+# 组件开发规范
+
+> 定义 Vue 组件开发的标准规范与最佳实践。
+
+## 📝 组件使用原则
+
+### API 优先原则
+
+> **优先使用 EJS API，仅在 API 无法满足时才考虑使用组件形式**
+
+| 场景          | 优先使用              | 备选方案      |
+| ------------- | --------------------- | ------------- |
+| 单选/多选列表 | `ejs.ui.picker`       | `em-picker`   |
+| 日期选择      | `ejs.ui.pickDate`     | -             |
+| 时间选择      | `ejs.ui.pickTime`     | -             |
+| 日期时间选择  | `ejs.ui.pickDateTime` | -             |
+| 确认对话框    | `ejs.ui.confirm`      | `em-dialog`   |
+| 提示信息      | `ejs.ui.alert`        | -             |
+| 操作提示      | `ejs.ui.toast`        | -             |
+| 加载提示      | `ejs.ui.showWaiting`  | `em-loading`  |
+| 级联选择      | -                     | `em-cascader` |
+
+## 🏗️ 组件开发规范
+
+### 文件命名
+
+| 类型     | 命名规则      | 示例            |
+| -------- | ------------- | --------------- |
+| 通用组件 | PascalCase    | `UserCard.vue`  |
+| 页面组件 | 小写 + 下划线 | `user_list.vue` |
+
+### Vue3 组件要求
+
+**必须使用 `<script setup>` 语法**：
+
+```vue
+<template>
+  <view class="user-card">
+    <text>{{ userName }}</text>
+  </view>
+</template>
+
+<script lang="ts" setup>
+import { ref, computed } from "vue";
+
+// Props 定义
+interface Props {
+  userId: string;
+  userName?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  userName: "默认用户",
+});
+
+// Emits 定义
+const emit = defineEmits<{
+  (e: "update", value: string): void;
+  (e: "delete", id: string): void;
+}>();
+
+// 响应式数据
+const count = ref(0);
+
+// 计算属性
+const displayName = computed(() => `用户: ${props.userName}`);
+
+// 方法
+const handleClick = () => {
+  emit("update", props.userId);
+};
+</script>
+```
+
+### Props 规范
+
+**必须指定类型和默认值**：
+
+```javascript
+// Vue2
+export default {
+  props: {
+    // ✅ 正确：指定类型和默认值
+    title: {
+      type: String,
+      default: "",
+    },
+    list: {
+      type: Array,
+      default: () => [],
+    },
+    config: {
+      type: Object,
+      default: () => ({}),
+    },
+    // 必填属性
+    userId: {
+      type: String,
+      required: true,
+    },
+  },
+};
+```
+
+```typescript
+// Vue3
+interface Props {
+  title?: string;
+  list?: string[];
+  config?: Record<string, any>;
+  userId: string; // 必填
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  title: "",
+  list: () => [],
+  config: () => ({}),
+});
+```
+
+### 组件通信
+
+**禁止直接修改 props，使用 emit 通知父组件更新**：
+
+```vue
+<!-- ❌ 错误：直接修改 props -->
+<script setup>
+const props = defineProps<{ value: string }>();
+// 错误！
+props.value = 'new value';
+</script>
+
+<!-- ✅ 正确：使用 emit -->
+<script setup>
+const props = defineProps<{ value: string }>();
+const emit = defineEmits<{
+  (e: 'update:value', value: string): void;
+}>();
+
+const updateValue = (newValue: string) => {
+  emit('update:value', newValue);
+};
+</script>
+```
+
+## 📦 常用组件使用规范
+
+### em-field 输入框
+
+#### readonly 状态
+
+**必须同时添加 `is-link` 和 `clickable` 属性**：
+
+```vue
+<!-- ❌ 错误示例 -->
+<em-field v-model="date" readonly label="选择日期" />
+
+<!-- ✅ 正确示例 -->
+<em-field
+  v-model="date"
+  readonly
+  clickable
+  is-link
+  label="选择日期"
+  @click="showDatePicker"
+/>
+```
+
+#### textarea 类型
+
+**建议添加 `autosize` 属性**：
+
+```vue
+<em-field
+  v-model="content"
+  type="textarea"
+  label="内容"
+  placeholder="请输入内容"
+  autosize
+/>
+```
+
+#### 输入格式限制
+
+```vue
+<!-- 手机号：仅数字 -->
+<em-field
+  v-model="phone"
+  type="tel"
+  label="手机号"
+  placeholder="请输入手机号"
+  :rules="[
+    {
+      validator: (val) => Util.string.isMobile(val),
+      message: '请输入正确的手机号',
+    },
+  ]"
+/>
+
+<!-- 带小数位限制 -->
+<em-field
+  v-model="amount"
+  type="number"
+  label="金额"
+  placeholder="请输入金额"
+/>
+```
+
+### em-uploader 附件上传
+
+**样式上自成一行，不通过 Slots 传入 em-field**：
+
+```vue
+<!-- ✅ 正确：独立使用 -->
+<em-field label="附件">
+  <template #input>
+    <!-- 仅显示标签 -->
+  </template>
+</em-field>
+<em-uploader :after-read="afterRead" />
+
+<!-- ❌ 错误：嵌入 em-field -->
+<em-field label="附件">
+  <template #input>
+    <em-uploader :after-read="afterRead" />
+  </template>
+</em-field>
+```
+
+### em-search 搜索框
+
+```vue
+<em-search
+  v-model="keyword"
+  placeholder="请输入搜索关键词"
+  @search="onSearch"
+/>
+```
+
+### em-picker 选择器
+
+**使用注意事项**：
+
+1. 无需与 `em-popup` 绑定使用
+2. 必须添加 `show-toolbar` 属性
+
+```vue
+<!-- Vue3 示例 -->
+<template>
+  <em-picker
+    v-model="selectedValue"
+    :columns="columns"
+    show-toolbar
+    @confirm="onConfirm"
+    @cancel="onCancel"
+  />
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+
+const columns = ref(["选项1", "选项2", "选项3"]);
+const selectedValue = ref("");
+
+const onConfirm = (value: string) => {
+  selectedValue.value = value;
+};
+
+const onCancel = () => {
+  // 取消选择
+};
+</script>
+```
+
+## 🔍 响应式数据管理
+
+### Vue3 响应式原则
+
+> **不是所有数据都需要是响应式的**
+
+```typescript
+// ✅ 需要响应式：页面显示相关
+const userName = ref(""); // 需要显示
+const userList = ref([]); // 需要渲染列表
+
+// ❌ 不需要响应式：非渲染数据
+const API_URL = "/api/users"; // 常量
+let timer: number; // 定时器引用
+```
+
+## ✅ 组件检查清单
+
+- [ ] 通用组件使用 PascalCase 命名
+- [ ] Vue3 使用 `<script setup>` 语法
+- [ ] Props 指定类型和默认值
+- [ ] 使用 emit 而非直接修改 props
+- [ ] readonly 输入框添加 `is-link` 和 `clickable`
+- [ ] textarea 添加 `autosize` 属性
+- [ ] 输入框设置 placeholder

package/data/standards/02-vue/examples.md

@@ -0,0 +1,240 @@
+# Vue 典型示例
+
+> 提供 Vue2 和 Vue3 的表单页面与列表页面典型代码示例。
+
+## 📝 表单页面示例
+
+### Vue2 表单
+
+```vue
+<template>
+  <em-form @submit="onSubmit" @failed="onFailed">
+    <em-field
+      v-model="form.username"
+      label="用户名"
+      placeholder="请输入用户名"
+      :rules="[{ required: true, message: '请填写用户名' }]"
+    />
+    <em-field
+      v-model="form.password"
+      type="password"
+      label="密码"
+      placeholder="请输入密码"
+      :rules="[{ required: true, message: '请填写密码' }]"
+    />
+    <div style="margin: 16px;">
+      <em-button round block type="info" native-type="submit">提交</em-button>
+    </div>
+  </em-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      form: {
+        username: "", // 用户名
+        password: "", // 用户密码
+      },
+    };
+  },
+  computed: {},
+  watch: {},
+  created() {},
+  mounted() {},
+  methods: {
+    // 验证通过后触发
+    onSubmit(value) {
+      console.log("submit", this.form);
+    },
+    // 验证不通过后触发
+    onFailed(errorInfo) {
+      console.log("error", errorInfo);
+    },
+  },
+};
+</script>
+
+<style lang="scss" scoped>
+@import "./css/form.scss";
+</style>
+```
+
+### Vue3 表单
+
+```vue
+<template>
+  <em-form @submit="onSubmit" @failed="onFailed">
+    <em-field
+      v-model="form.username"
+      label="用户名"
+      placeholder="请输入用户名"
+      :rules="[{ required: true, message: '请填写用户名' }]"
+    />
+    <em-field
+      v-model="form.password"
+      type="password"
+      label="密码"
+      placeholder="请输入密码"
+      :rules="[{ required: true, message: '请填写密码' }]"
+    />
+    <div style="margin: 16px">
+      <em-button round block type="info" native-type="submit">提交</em-button>
+    </div>
+  </em-form>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+
+const form = ref({
+  username: "", // 用户名
+  password: "", // 用户密码
+});
+
+const onSubmit = () => {
+  console.log("onSubmit", form.value);
+};
+
+const onFailed = (errors) => {
+  console.log("onFailed", errors);
+};
+</script>
+
+<style lang="scss" scoped>
+@import "./css/form.scss";
+</style>
+```
+
+## 📋 列表页面示例
+
+### Vue2 列表
+
+```vue
+<template>
+  <view class="container">
+    <em-minirefresh
+      ref="scrollPull"
+      :initPageIndex="initPageIndex"
+      :page-size="pageSize"
+      :url="url"
+      :request-data="dataRequest"
+      :change-data="dataChange"
+    >
+      <template v-slot:default="{ listData }">
+        <em-cell
+          v-for="(item, index) in listData"
+          :key="index"
+          :title="item.title"
+          @click="itemClick(item)"
+        />
+      </template>
+    </em-minirefresh>
+  </view>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      url: `${Config.serverUrl}/rest/list`, // 请求地址
+      initPageIndex: 0, // 初始页码
+      pageSize: 10, // 每页条数
+    };
+  },
+  methods: {
+    // 请求参数函数
+    dataRequest(currPage, pageSize) {
+      return {
+        params: JSON.stringify({
+          currentpageindex: currPage,
+          pagesize: pageSize,
+        }),
+      };
+    },
+    // 数据处理函数
+    dataChange(res) {
+      if (res?.status?.code === 1) {
+        return res.custom.infolist;
+      }
+      console.error("接口返回参数错误");
+      return [];
+    },
+    // 列表项点击
+    itemClick(item) {
+      ejs.page.open({
+        pageUrl: "./detail",
+        data: { id: item.id },
+      });
+    },
+  },
+};
+</script>
+
+<style lang="scss" scoped>
+@import "./css/list.scss";
+</style>
+```
+
+### Vue3 列表
+
+```vue
+<template>
+  <view class="container">
+    <em-minirefresh
+      ref="scrollPull"
+      :page-size="pageSize"
+      :url="url"
+      :request-data="dataRequest"
+      :change-data="dataChange"
+      @update:listData="(val) => (listData = val)"
+    >
+      <em-cell
+        v-for="(item, index) in listData"
+        :key="index"
+        :title="item.title"
+        @click="itemClick(item)"
+      />
+    </em-minirefresh>
+  </view>
+</template>
+
+<script lang="ts" setup>
+import { ref } from "vue";
+
+const url = `${Config.serverUrl}/rest/list`; // 请求地址
+const pageSize = ref(15); // 每页条数
+const listData = ref([]); // 列表数据
+
+// 请求参数函数
+const dataRequest = (currPage, pageSize) => {
+  return {
+    params: JSON.stringify({
+      currentpageindex: currPage,
+      pagesize: pageSize,
+    }),
+  };
+};
+
+// 数据处理函数
+const dataChange = (res) => {
+  if (res.status.code === 1) {
+    return res.custom.infolist;
+  }
+  console.error("接口返回参数错误");
+  return [];
+};
+
+// 列表项点击
+const itemClick = (item) => {
+  ejs.page.open({
+    pageUrl: "./detail",
+    data: { id: item.id },
+  });
+};
+</script>
+
+<style lang="scss" scoped>
+@import "./css/list.scss";
+</style>
+```

package/data/standards/02-vue/performance.md

@@ -0,0 +1,74 @@
+# 性能优化规范
+
+> 定义 Vue 应用的性能优化策略与最佳实践。
+
+## 🎯 核心性能指标
+
+| 指标    | 说明         | 目标    |
+| ------- | ------------ | ------- |
+| **LCP** | 最大内容绘制 | < 2.5s  |
+| **FID** | 首次输入延迟 | < 100ms |
+| **CLS** | 累计布局偏移 | < 0.1   |
+
+**检测工具**：Lighthouse、WebPageTest
+
+## ⚡ 渲染优化
+
+### v-show vs v-if
+
+| 指令     | 特点          | 适用场景     |
+| -------- | ------------- | ------------ |
+| `v-show` | CSS 切换显示  | 频繁切换     |
+| `v-if`   | 完全销毁/创建 | 条件很少改变 |
+
+### 合理使用 computed
+
+```javascript
+// ✅ 使用 computed：有缓存
+const filteredList = computed(() => list.value.filter((item) => item.active));
+
+// ❌ 避免 methods：每次渲染都重新计算
+```
+
+### keep-alive 缓存
+
+```vue
+<keep-alive include="UserList,OrderList">
+  <router-view />
+</keep-alive>
+```
+
+## 📦 代码分割
+
+### Vue3 异步组件
+
+```typescript
+import { defineAsyncComponent } from "vue";
+const AsyncComponent = defineAsyncComponent(
+  () => import("./HeavyComponent.vue")
+);
+```
+
+### Suspense 包裹
+
+```vue
+<Suspense>
+  <template #default><AsyncComponent /></template>
+  <template #fallback><div>加载中...</div></template>
+</Suspense>
+```
+
+## 🖼️ 图片优化
+
+- 使用 WebP 格式
+- 设置尺寸属性（避免 CLS）
+- 启用懒加载 `lazy-load`
+- 压缩图片 < 100KB
+
+## ✅ 性能检查清单
+
+- [ ] 频繁切换使用 `v-show`
+- [ ] 使用 `computed` 替代方法调用
+- [ ] 适当使用 `keep-alive` 缓存
+- [ ] 非关键组件动态加载
+- [ ] 图片使用 WebP 格式并懒加载