@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/localized/zh-CN/skills/fec-validation-fix/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: fec-validation-fix
+description: 用于运行现有项目验证命令并修复代码变更后的失败，包括 lint、type-check、单元/集成测试、build、CI 或本地脚本失败。不要用于设计或编写新的组件/E2E 测试；中文触发词包括 验证、检查失败、修复失败、CI 失败。
+---
+
+# 验证并修复
+
+## 用途
+
+自动化执行已有验证命令，分析失败原因并安全修复，确保质量门禁达标。
+
+## 流程
+
+1. 从 package.json 或仓库文档中识别可用命令。
+2. 优先按以下顺序执行：
+   - lint
+   - type-check
+   - unit/integration tests
+   - build
+3. 仔细阅读失败输出。
+4. 将错误按文件、错误类型和依赖关系分组，优先处理阻塞后续诊断的根因。
+5. 一次只修复一类问题，并显示或记录关键错误上下文。
+6. 每次关键修复后重新执行受影响命令，确认错误是否减少。
+7. 如果同一错误连续三次修复仍失败，停止扩大改动并报告阻塞。
+8. 最后按“预期输出”总结执行结果、修复内容和剩余风险。
+
+## 失败分诊
+
+- 先修最早出现且会级联的错误，例如缺失类型、导入失败、配置解析失败。
+- 区分真实产品 bug、测试环境问题、快照漂移、依赖版本变化和 flaky。
+- 对 CI 专属失败记录 Node 版本、包管理器、环境变量、路径大小写和工作目录差异。
+- 修复测试时优先修产品代码或测试等待方式，不用删除断言掩盖真实回归。
+
+## 约束
+
+- 不要盲目关闭规则来消除报错
+- 除非有明确理由，不要为了通过检查而降低类型安全
+- 不要因为附近测试失败就顺手重写无关模块
+- 不要一次性修改多个无关根因
+- 不要删除失败测试来让验证通过
+- 不要只运行失败命令的片段就声称整体验证通过
+
+## 详细参考
+
+撰写验证修复报告时，加载 [references/report-template.md](references/report-template.md)。
+
+## 预期输出
+
+- lint / type-check / test / build 等验证命令全部通过
+- 失败项已修复或给出明确原因和后续行动
+- 修复报告保存为 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`

package/localized/zh-CN/skills/fec-validation-fix/references/report-template.md

@@ -0,0 +1,43 @@
+# 验证修复报告模板
+
+```markdown
+# 验证修复报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 验证范围: lint / type-check / test / build / CI
+
+## 命令状态表
+
+| 命令 | 初始状态 | 修复后状态 | 备注 |
+| --- | --- | --- | --- |
+| `npm run type-check` | 失败 / 通过 / 未运行 | 失败 / 通过 / 未运行 | ... |
+
+## 失败摘要
+
+- 最早出现且会级联的错误
+- 受影响文件、错误类型和关键日志
+- 是否属于 CI 专属、测试环境、依赖版本或 flaky 问题
+
+## 根因
+
+- 确认的根本原因
+- 支持该结论的输出、日志或复现证据
+
+## 修复内容
+
+- 修改的文件和行为
+- 为什么没有通过关闭规则、删除断言或降低类型安全来规避失败
+
+## 验证结果
+
+- 重新执行的命令
+- 命令输出摘要
+- 是否仍有失败项
+
+## 剩余风险
+
+- 未覆盖的验证命令
+- 仍需用户决策或外部环境确认的问题
+```
+
+验证修复完成后，将报告保存到 `reports/validation-fix-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/localized/zh-CN/skills/fec-vite-project-standard/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: fec-vite-project-standard
+description: 用于创建、配置、审查或调试基于 Vite 的前端项目、vite.config.ts、环境变量、dev server proxy、HMR、插件顺序、library mode、依赖预打包、bundle splitting 或 Vite 构建性能。React/Vue 组件架构请使用框架专项 skill；中文触发词包括 Vite 配置、vite.config、Vite 构建、Vite 性能。
+---
+
+# Vite 项目规范
+
+适用于 Vite 应用、组件库、开发服务器和构建配置的设计与审查。
+
+## 用途
+
+规范 Vite 配置、安全边界和构建性能，避免开发环境与生产构建的常见陷阱。
+
+## 流程
+
+1. 识别项目类型
+   - 应用项目优先检查 `root`、`base`、`server.proxy`、`envPrefix`、`build` 和框架插件。
+   - 组件库项目优先检查 `build.lib`、类型产物、peer dependencies external 和导出入口。
+   - Monorepo 额外检查 `server.fs.allow`、路径别名和包依赖边界。
+
+2. 选择插件
+   - React 默认优先 `@vitejs/plugin-react-swc`；需要 Babel 插件时才用 `@vitejs/plugin-react`。
+   - Vue 项目使用 `@vitejs/plugin-vue`，路径别名优先交给 `vite-tsconfig-paths`。
+   - TypeScript 项目必须通过 `tsc --noEmit`、CI 或 `vite-plugin-checker` 补齐类型检查。
+
+3. 管理环境变量
+   - 客户端只读取明确公开的前缀，如 `VITE_`。
+   - `loadEnv` 第三个参数使用显式前缀数组，不使用空字符串加载全部变量。
+   - 密钥、数据库地址、私有 token 必须留在服务端或构建系统，不进入客户端 bundle。
+
+4. 优化开发体验
+   - 慢启动先用 `vite --profile` 定位插件、解析或预构建瓶颈。
+   - 对 CJS/UMD 依赖用 `optimizeDeps.include` 处理互操作问题。
+   - 大项目可用 `server.warmup.clientFiles` 预热核心入口。
+
+5. 优化生产构建
+   - 发布前运行 `vite build`，并用 `vite preview` 做本地构建烟测。
+   - 手动分包使用稳定的对象形式优先，避免把每个依赖拆成独立小 chunk。
+   - 生产 sourcemap 默认关闭；若上传错误追踪平台，上传后不随站点公开。
+   - 动效、3D、图表、编辑器、地图和音视频处理库优先通过动态导入或路由级拆包隔离。
+   - 检查静态资源是否进入正确目录、是否被 hash/cache、是否存在占位 URL 或过大的未压缩媒体。
+
+## 最小配置
+
+```ts
+import { defineConfig, loadEnv } from "vite";
+import react from "@vitejs/plugin-react-swc";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), ["VITE_"]);
+
+  return {
+    plugins: [react(), tsconfigPaths()],
+    define: {
+      __PUBLIC_API_URL__: JSON.stringify(env.VITE_API_URL),
+    },
+    server: {
+      proxy: {
+        "/api": {
+          target: "http://localhost:8080",
+          changeOrigin: true,
+        },
+      },
+    },
+  };
+});
+```
+
+## 约束
+
+- `vite build` 只转译和打包，不等于类型检查；CI 必须另跑 typecheck。
+- `VITE_` 不是安全边界；任何 `VITE_` 变量都会进入客户端包。
+- 不设置 `envPrefix: ""`，不使用 `loadEnv(mode, root, "")` 后再随意 `define`。
+- 不默认引入 legacy 插件；只有真实用户数据需要时再启用。
+- 不用 `vite preview` 作为生产服务器。
+- 组件库必须 externalize peer dependencies，并单独产出 `.d.ts`。
+- 不把服务端密钥通过 `define`、`import.meta.env` 或空前缀 `loadEnv` 注入客户端。
+- 不把 GSAP、Three.js、Lottie、Monaco、地图 SDK 等重型库放进所有页面共享入口；先评估 async chunk 和首屏影响。
+
+## 预期输出
+
+输出应包含项目类型判断、关键配置变更、环境变量安全说明、构建/开发性能验证方式。完成后 Vite 配置应可类型检查、可构建、密钥不泄露，并能解释 dev 与 build 的差异。

package/localized/zh-CN/skills/fec-vue3-project-standard/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: fec-vue3-project-standard
+description: 用于设计或审查 Vue 3 + TypeScript 项目结构、SFC/组件边界、composables 组织、路由组合、Pinia 归属、API/错误/样式默认约定、directives 或仓库级 Vue 规范。表单、数据获取、测试、无障碍、虚拟列表、动画或安全深挖优先使用更窄的 skill；中文触发词包括 Vue 3 项目规范、Vue 组件架构。
+---
+
+# Vue 3 项目规范
+
+适用于使用 Vue 3 + TypeScript 的仓库。
+
+## 用途
+
+为 Vue 3 + TypeScript 项目提供工程结构、组件边界、Composables 和默认实现约定，确保约定式开发和类型安全。
+
+## 流程
+
+1. 识别仓库已有 Vue 约定：目录、路由、Pinia、请求层、样式体系、组件库和测试框架。
+2. 划分页面、业务组件、通用组件、composables、stores、services 和 utils 的边界。
+3. 优先沿用 `<script setup lang="ts">`、组合式 API 和仓库现有自动导入/模块出口约定。
+4. 输出时补齐状态归属、API 层、错误处理、样式隔离和专项 skill 分流。
+5. 页面和模块要有可恢复错误 UI；全局 `errorHandler`、`onErrorCaptured`、请求错误映射和路由错误页分工明确。
+6. Tailwind token/variant 或响应式布局需求应分流到对应专项 skill，避免把样式系统规则塞进 Vue 组件规范。
+7. 状态归属复杂时先做状态清单；DTO、公共 props、泛型 composable 或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约。
+8. 设计可复用 composable 时明确输入是否支持 plain value、ref、computed 或 getter；测试 Vue 组件时覆盖 Pinia、Router、Teleport、Suspense 和 async setup 的常见边界。
+
+## 详细参考
+
+按需要加载更细的参考文件：
+
+- 项目目录、组件分层、组件规范、注释和 TypeScript：加载 [references/vue3-project-structure.md](references/vue3-project-structure.md)。
+- Composables、slots、Provide/Inject 和路由组织：加载 [references/vue3-composables-routing.md](references/vue3-composables-routing.md)。
+- Pinia、API 层、错误处理、指令、样式、测试、反模式和输出检查清单：加载 [references/vue3-state-api-quality.md](references/vue3-state-api-quality.md)。
+- Vue 项目规范层面的轻量性能约定：加载 [references/vue3-performance-patterns.md](references/vue3-performance-patterns.md)。
+
+## 约束
+
+- 使用 `<script setup lang="ts">`，禁止使用 Options API 新增组件
+- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆子组件与 Composables
+- Props / Emits 必须使用 TypeScript interface 定义，禁止使用 `any`
+- Composable 返回 `readonly` 引用，防止外部意外修改
+- 不要在 store 中存放 UI 临时状态（modal 开关、表单输入等）
+- 服务端数据优先用请求库管理，而非手动存入 Pinia
+- 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
+- 禁止直接从 feature 内部深层路径导入，绕过 `index.ts`
+- 不用全局错误处理吞掉组件内可恢复的 API、表单或权限错误。
+- 不把函数型参数误当 getter 自动调用；composable 参数若可能是回调，应避免使用 getter 型输入约定。
+- 不依赖快照作为 Vue 组件唯一断言；异步组件、Teleport 和 Pinia 场景要有用户可见行为断言。
+
+## 预期输出
+
+- 组件使用 `<script setup lang="ts">`，Props / Emits 类型完整
+- 可复用逻辑已提取到 composable，返回 `readonly` 引用
+- Loading / Error / Empty / Data 状态均已处理
+- 路由组件使用动态 import 加载，状态管理符合就近原则
+- URL 状态、服务端状态、表单状态和 Pinia 全局状态边界明确
+- API 调用有类型约束和统一错误处理
+- 样式使用 scoped 隔离，关键行为有测试覆盖
+- 文件结构与项目约定一致（pages / features / components 分离）
+- 可复用 composable 的输入响应性、Pinia/Router 边界和异步组件测试策略已说明

package/localized/zh-CN/skills/fec-vue3-project-standard/references/vue3-composables-routing.md

@@ -0,0 +1,162 @@
+# Vue 3 composables 与路由模式
+
+## Composables 规范
+
+### 设计原则
+
+- 以 `use` 前缀命名
+- 返回值使用对象，明确标注类型
+- 内部处理 loading / error / data 三态
+- 支持参数响应式（接受 `Ref` 或 getter）
+- 库级 composable 要明确参数是否支持普通值、`Ref`、`computed` 或 getter，并在副作用内部解析最新值
+
+```typescript
+export function useUserList(params: MaybeRef<QueryParams>) {
+  const data = ref<User[]>([]);
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+
+  async function fetch() {
+    loading.value = true;
+    error.value = null;
+    try {
+      const res = await getUserList(toValue(params));
+      data.value = res.list;
+    } catch (e) {
+      error.value = e as Error;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  watchEffect(() => {
+    fetch();
+  });
+
+  return {
+    data: readonly(data),
+    loading: readonly(loading),
+    error: readonly(error),
+    refetch: fetch,
+  };
+}
+```
+
+### Composable 使用原则
+
+- 返回 `readonly` 引用防止外部意外修改
+- 数据请求场景优先使用 VueQuery / VueUse 等库（如项目已引入）
+- `onUnmounted` 中清理定时器、事件监听等副作用
+- 避免在 composable 中直接操作 DOM
+- 只读输入可接受普通值、ref、computed 或 getter；需要双向写入的输入只接受可写 ref 或明确的 setter。
+- 如果参数本身是回调、比较器或 predicate，不要把它设计成 getter 型输入，否则解析时可能误调用业务函数。
+
+### Vue Router / Pinia / 测试常见边界
+
+- 路由参数变化不会重新创建同一个路由组件；依赖 `route.params` 的数据要 watch 明确字段，并处理取消和竞态。
+- 导航守卫中避免旧式 `next()` 多分支重复调用；优先返回 `false`、重定向对象或抛出可处理错误。
+- Pinia store 解构会丢失响应性时使用 `storeToRefs`；setup store 必须返回需要被外部追踪的 state、getter 和 action。
+- UI 临时状态、表单输入、弹窗开关不进入全局 store；URL 查询、服务端缓存和本地组件状态先各归其位。
+- Vue Test Utils 测试优先断言用户可见行为，不把快照作为唯一证明；异步更新使用 `await`、`flushPromises` 或框架推荐的等待方式。
+- 测试使用 Pinia、Router、Teleport、Suspense、async setup 或 `defineAsyncComponent` 时，在测试夹具中显式安装插件、挂载目标容器并等待异步稳定。
+
+## Slots 与 Provide/Inject
+
+### Slots
+
+- 用 `<slot>` 实现组件组合，而非过多 props
+- 具名 slot 用于明确的布局区域
+- 作用域 slot 传递数据给父组件自定义渲染
+
+```vue
+<template>
+  <div class="card">
+    <div class="card-header">
+      <slot name="header">{{ title }}</slot>
+    </div>
+    <div class="card-body">
+      <slot :data="processedData" :loading="loading" />
+    </div>
+  </div>
+</template>
+```
+
+### Provide/Inject
+
+- 用于跨多层级的上下文共享（主题、配置、权限）
+- 提供 InjectionKey 保证类型安全
+- 不要用 provide/inject 替代 props 传递直接父子数据
+
+```typescript
+// keys.ts
+export const ThemeKey: InjectionKey<Ref<Theme>> = Symbol("theme");
+
+// Provider.vue
+provide(ThemeKey, theme);
+
+// Consumer.vue
+const theme = inject(ThemeKey);
+```
+
+## 路由规范
+
+### 路由组织
+
+```typescript
+// app/router.ts
+const routes: RouteRecordRaw[] = [
+  {
+    path: "/",
+    component: MainLayout,
+    children: [
+      {
+        path: "",
+        name: "Dashboard",
+        component: () => import("@/pages/Dashboard/DashboardPage.vue"),
+      },
+      {
+        path: "users",
+        name: "UserList",
+        component: () => import("@/pages/UserList/UserListPage.vue"),
+      },
+      {
+        path: "users/:id",
+        name: "UserDetail",
+        component: () => import("@/pages/UserDetail/UserDetailPage.vue"),
+      },
+      {
+        path: "settings",
+        name: "Settings",
+        component: () => import("@/pages/Settings/SettingsPage.vue"),
+      },
+    ],
+  },
+  {
+    path: "/login",
+    name: "Login",
+    component: () => import("@/pages/Login/LoginPage.vue"),
+  },
+  {
+    path: "/:pathMatch(.*)*",
+    name: "NotFound",
+    component: () => import("@/pages/NotFound.vue"),
+  },
+];
+```
+
+### 路由原则
+
+- 路由配置集中管理，每个路由必须有 `name`
+- 页面组件使用动态 `import()` 按需加载
+- 权限控制使用路由守卫（`beforeEach`），而非在每个页面内判断
+- URL 参数（分页、筛选、排序）与路由状态同步
+
+```typescript
+// 导航守卫
+router.beforeEach((to) => {
+  const authStore = useAuthStore();
+  if (to.meta.requiresAuth && !authStore.isLoggedIn) {
+    return { name: "Login", query: { redirect: to.fullPath } };
+  }
+});
+```

package/localized/zh-CN/skills/fec-vue3-project-standard/references/vue3-performance-patterns.md

@@ -0,0 +1,13 @@
+# Vue 3 性能模式
+
+本文件保留轻量级 Vue 项目规范性能指导。当任务需要指标、trace、profile、包体分析、网络证据或正式性能报告时，使用前端性能工作流。
+
+## 性能
+
+- 使用 `shallowRef` / `shallowReactive` 优化大型对象
+- 大列表使用虚拟滚动
+- 避免在 `v-for` 中使用 `v-if`（提取为 computed 过滤）
+- 使用 `defineAsyncComponent` 懒加载重型组件
+- `v-for` 必须有稳定的 `:key`
+- 路由组件使用动态 `import()` 按需加载
+

package/localized/zh-CN/skills/fec-vue3-project-standard/references/vue3-project-structure.md

@@ -0,0 +1,176 @@
+# Vue 3 项目结构与组件规范
+
+## 项目结构
+
+以下为中大型 Vue 3 项目的业界最佳实践结构，按项目实际情况裁剪：
+
+```
+src/
+├── app/                        # 应用入口与全局配置
+│   ├── App.vue                 # 根组件
+│   ├── main.ts                 # 应用启动入口
+│   └── router.ts               # 路由实例与配置
+│
+├── pages/                      # 页面组件（与路由一一对应）
+│   ├── Dashboard/
+│   │   ├── DashboardPage.vue
+│   │   ├── components/         # 页面私有组件
+│   │   └── composables/        # 页面私有 composables
+│   ├── UserList/
+│   └── Settings/
+│
+├── layouts/                    # 布局组件
+│   ├── MainLayout.vue          # 主布局（侧边栏 + 顶栏 + 内容区）
+│   ├── AuthLayout.vue          # 登录/注册页布局
+│   └── BlankLayout.vue         # 空白布局（错误页等）
+│
+├── features/                   # 功能模块（按业务领域划分）
+│   ├── auth/
+│   │   ├── components/         # 模块组件
+│   │   ├── composables/        # 模块 composables
+│   │   ├── api.ts              # 模块 API 调用
+│   │   ├── types.ts            # 模块类型定义
+│   │   ├── constants.ts        # 模块常量
+│   │   └── index.ts            # 模块公开导出
+│   └── order/
+│
+├── components/                 # 全局共享 UI 组件
+│   ├── AppButton/
+│   │   ├── AppButton.vue
+│   │   └── __tests__/
+│   ├── AppModal/
+│   ├── AppForm/
+│   └── AppErrorBoundary/
+│
+├── composables/                # 全局共享 composables
+│   ├── useAuth.ts
+│   ├── useDebounce.ts
+│   └── useMediaQuery.ts
+│
+├── services/                   # API 基础层
+│   ├── request.ts              # Axios/fetch 实例与拦截器
+│   └── endpoints/              # API 端点定义（如按领域拆分）
+│
+├── stores/                     # Pinia 状态管理
+│   ├── authStore.ts
+│   └── uiStore.ts
+│
+├── locales/                    # 国际化语言包
+│   ├── zh-CN.json              # 中文
+│   ├── en-US.json              # 英文
+│   └── index.ts                # i18n 实例初始化（vue-i18n）
+│
+├── assets/                     # 静态资源
+│   ├── images/                 # 图片（PNG、JPG、WebP）
+│   ├── icons/                  # SVG 图标
+│   └── fonts/                  # 自定义字体
+│
+├── config/                     # 应用配置
+│   ├── env.ts                  # 环境变量类型化封装
+│   └── features.ts             # Feature Flags 管理
+│
+├── types/                      # 全局共享类型
+│   ├── api.ts                  # API 响应/请求通用类型
+│   ├── models.ts               # 业务实体类型
+│   └── global.d.ts             # 全局类型扩展（组件类型、模块声明等）
+│
+├── utils/                      # 纯工具函数
+│   ├── format.ts               # 日期、数字、货币格式化
+│   ├── validators.ts           # 表单校验规则
+│   └── storage.ts              # LocalStorage / SessionStorage 封装
+│
+├── directives/                 # 自定义指令
+│   ├── vPermission.ts          # 权限指令
+│   └── vClickOutside.ts        # 点击外部关闭
+│
+├── plugins/                    # Vue 插件注册
+│   ├── i18n.ts                 # vue-i18n 插件配置
+│   └── index.ts                # 插件统一注册入口
+│
+├── styles/                     # 全局样式与主题
+│   ├── global.css              # 全局基础样式（reset / normalize）
+│   ├── variables.css           # CSS 变量（颜色、间距、字号）
+│   ├── breakpoints.ts          # 响应式断点常量
+│   └── themes/                 # 主题定义
+│       ├── light.css           # 亮色主题变量
+│       ├── dark.css            # 暗色主题变量
+│       └── index.ts            # 主题切换逻辑
+│
+└── constants/                  # 全局常量
+    ├── routes.ts               # 路由路径常量
+    └── config.ts               # 业务常量（分页大小、超时时间等）
+```
+
+### 关键原则
+
+- `pages/` 做路由映射和布局组合，不放业务逻辑
+- `layouts/` 定义页面骨架（侧边栏、顶栏、面包屑），由路由配置的 `component` 引用
+- `features/` 按业务领域划分，模块内自包含（components + composables + api + types）
+- `components/` 仅放无业务耦合的通用组件，可跨项目复用
+- `composables/` 仅放通用逻辑（防抖、媒体查询等），业务 composables 放到对应 feature 中
+- `locales/` 存放语言包 JSON 文件，模板中使用 `$t('key')` 而非硬编码文案
+- `assets/` 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF
+- `config/` 封装环境变量和 Feature Flags，禁止组件中直接读取 `import.meta.env`
+- `styles/themes/` 通过 CSS 变量实现主题切换，组件中引用变量而非硬编码颜色
+- 每个模块通过 `index.ts` 管控公开 API，避免深层路径导入
+
+## 组件设计规范
+
+- 使用 `<script setup lang="ts">`
+- 明确使用 `defineProps` / `defineEmits` 并附带类型
+- 可复用逻辑优先提取到 composables
+- 保持 template 可读，避免过深条件嵌套
+- 优先使用计算属性，而不是重复维护状态
+- 避免构建大型单体组件；**单文件规模**见 `templates/shared/rules/fec-vue.md`「**组件文件规模**」（约 300 行内为佳，逾 500 行或复杂度过高拆子组件与 Composables）
+- 优先使用强类型的 props、emits 和暴露方法
+- 遵循仓库的文件与目录命名规范
+- 优先复用现有 UI 组件和 Token
+
+### 组件分层
+
+```
+页面组件 (Pages)          → 路由映射、布局组合
+  └── 容器组件 (Containers)  → 数据获取、状态编排
+       └── 业务组件 (Features) → 领域逻辑展示
+            └── 通用组件 (UI)   → 纯展示，无业务耦合
+```
+
+## 注释规范
+
+- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。
+- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。
+- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。
+- **公开 API**：composable 或模块的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。
+
+## TypeScript 规范
+
+通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+
+Vue 规范只补充 SFC、Props / Emits、暴露方法、Provide / Inject 和 composable 响应性类型；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+
+### Vue 3 项目补充约定
+
+```vue
+<script setup lang="ts">
+interface Props {
+  title: string;
+  items: Item[];
+  loading?: boolean;
+}
+
+interface Emits {
+  (e: "select", item: Item): void;
+  (e: "delete", id: string): void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+});
+
+const emit = defineEmits<Emits>();
+</script>
+```
+
+- Props 和 Emits 使用 TypeScript interface 定义
+- 使用 `withDefaults` 设置默认值
+- `defineExpose` 暴露的方法需有类型约束