@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/templates/shared/rules/fec-error-handling.md

@@ -1,56 +1,56 @@
-# 错误处理规范
+# Error handling specifications
 
-本文件约定前端错误处理的常驻边界。React/Vue 组件边界细节交给对应框架 skill，API 错误映射和鉴权刷新交给 `fec-api-integration`，安全敏感错误交给 `fec-security-review`。
+This document agrees on the resident boundaries of front-end error handling. React/Vue component boundary details are handed over to the corresponding framework skill, API error mapping and authentication refresh are handed over to `fec-api-integration`, and security-sensitive errors are handed over to `fec-security-review`.
 
-## 错误分层
+## Error layering
 
-| 层级 | 错误类型 | 默认处理 |
+| Hierarchy | Error type | Default handling |
 | ---- | -------- | -------- |
-| 全局 | 未捕获异常、Promise rejection | 捕获、上报、全局降级 UI |
-| 路由 / 页面 | 页面级渲染异常 | Error Boundary / 框架错误边界 + 页面级降级 |
-| 模块 | 功能模块运行时异常 | 模块级边界 + 局部降级 |
-| 组件 / 请求 | 数据请求失败、操作失败 | 用户可理解提示 + 可恢复动作 |
-| 表单 | 校验失败 | 字段级错误提示和修正入口 |
+| Global | Uncaught exceptions, Promise rejection | Capture, reporting, global downgrade UI |
+| Routing / Page | Page-level rendering exception | Error Boundary / Frame error boundary + Page-level degradation |
+| Module | Function module runtime exception | Module-level boundary + local degradation |
+| Component/Request | Data request failure, operation failure | User-understandable prompts + recoverable actions |
+| Form | Validation failure | Field-level error prompts and correction entry |
 
-## 全局与模块边界
+## Global and module boundaries
 
-- 应在应用入口注册未捕获异常和 Promise rejection 监听，并接入项目错误上报平台。
-- React 使用项目统一的 Error Boundary 方案；业务组件保持函数式，不新增手写类组件边界。
-- Vue 使用项目统一的 `app.config.errorHandler`、`onErrorCaptured` 或框架级错误边界。
-- 独立功能模块应有局部降级能力，模块崩溃不应导致整个页面白屏。
-- Error Boundary 处理渲染异常；普通 API 失败应落到 loading/error/empty/data 状态和可恢复操作。
+- Uncaught exception and Promise rejection monitoring should be registered at the application entrance and connected to the project error reporting platform.
+- React uses the project's unified Error Boundary solution; business components remain functional and no new handwritten class component boundaries are added.
+- Vue uses project-unified `app.config.errorHandler`, `onErrorCaptured` or framework-level error boundaries.
+- Independent functional modules should have local downgrade capabilities, and module crashes should not cause the entire page to go blank.
+- Error Boundary handles rendering exceptions; normal API failures should fall into the loading/error/empty/data state and recoverable operations.
 
-## API 错误处理
+## API error handling
 
-- 请求层统一归一错误形状，组件不直接解析后端异常、token refresh 或重试策略。
-- 每类错误都应对应明确下一步：重试、重新登录、修改输入、返回上级、刷新冲突数据、联系支持或稍后再试。
-- `401`、`403`、`404`、`409`、`422`、`429`、`5xx` 和网络错误应有可区分的用户提示和日志语义。
-- UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名、密钥或敏感字段。
+- The request layer uniformly normalizes error shapes, and components do not directly parse backend exceptions, token refresh or retry strategies.
+- Each type of error should have a clear next step: retry, log in again, modify input, return to the previous level, refresh conflicting data, contact support, or try again later.
+- `401`, `403`, `404`, `409`, `422`, `429`, `5xx` and network errors should have distinguishable user prompts and log semantics.
+- The UI can display request id / trace id to facilitate support troubleshooting, but must not expose internal stacks, SQL, service names, keys or sensitive fields.
 
-## 用户体验
+## User experience
 
-- 每个数据展示区域处理 Loading、Error、Empty、Success 四种状态。
-- 全局级错误页提供返回首页、刷新或重试路径；模块级降级只影响该模块；操作级错误给出下一步。
-- 重试策略要克制：用户手动重试优先，自动重试需有上限、退避和停止条件。
-- 错误提示应保留用户已输入内容，避免因失败丢失表单或上下文。
+- Each data display area handles four states: Loading, Error, Empty, and Success.
+- Global-level error pages provide paths to return to the home page, refresh or retry; module-level downgrades only affect this module; operation-level errors provide the next step.
+- The retry strategy must be restrained: users’ manual retries are given priority, and automatic retries must have upper limits, backoff and stop conditions.
+- Error prompts should retain what the user has entered to avoid losing the form or context due to failure.
 
-## 错误上报
+## Error reporting
 
-上报内容应包含错误堆栈、页面 URL、浏览器/设备信息、用户或会话标识、操作上下文、请求标识和版本信息。上报前清理 token、密码、个人敏感字段和大体积 payload。
+The reported content should include the error stack, page URL, browser/device information, user or session ID, operation context, request ID, and version information. Clean tokens, passwords, personal sensitive fields and large payloads before reporting.
 
-## 反模式
+## Anti-pattern
 
-- 空 `catch` 块吞掉错误。
-- 所有错误统一用 `alert()` 或一个模糊 toast。
-- 接口失败时 UI 无反馈，或把后端原始异常直接展示给用户。
-- Error Boundary 没有重试或返回路径。
-- 在组件中到处写重复 `try/catch`，而不是统一封装请求边界。
-- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复。
+- Empty `catch` blocks swallow errors.
+- All errors are reported with `alert()` or a vague toast.
+- When the interface fails, there is no feedback from the UI, or the original exception from the backend is directly displayed to the user.
+- Error Boundary has no retry or return path.
+- Write repeated `try/catch` everywhere in the component instead of uniformly encapsulating request boundaries.
+- Use Error Boundary to handle common API errors, making it impossible for users to understand or recover.
 
-## 检查清单
+## Checklist
 
-- [ ] 全局未捕获异常和 Promise rejection 已监听。
-- [ ] 关键页面或模块有框架错误边界和局部降级 UI。
-- [ ] API 请求有统一错误归一、分级处理和可恢复动作。
-- [ ] 数据区域覆盖 Loading / Error / Empty / Success。
-- [ ] 错误上报包含足够定位信息且不泄露敏感数据。
+- [ ] Global uncaught exceptions and Promise rejections are listened to.
+- [ ] Critical pages or modules have frame error boundaries and partially degraded UI.
+- [ ] API requests have unified error normalization, hierarchical processing and recoverable actions.
+- [ ] Data area override Loading / Error / Empty / Success.
+- [ ] Error reports contain sufficient location information and do not leak sensitive data.

package/templates/shared/rules/fec-git-conventions.md

@@ -1,8 +1,8 @@
-# Git 提交规范
+# Git commit specifications
 
-凡是创建 commit、编写 commit message 或准备提交代码时，都应用本文件。
+This file should be used whenever creating a commit, writing a commit message, or preparing to submit code.
 
-## Conventional Commits 格式
+## Conventional Commits Format
 
 ```
 <type>(<scope>): <subject>
@@ -12,62 +12,62 @@
 [footer]
 ```
 
-### type 取值
+### type value
 
-| type | 用途 |
+| type | purpose |
 |------|------|
-| `feat` | 新功能 |
-| `fix` | 修复 bug |
-| `refactor` | 重构（不改变行为） |
-| `style` | 代码格式调整（不影响逻辑） |
-| `docs` | 文档变更 |
-| `test` | 测试相关 |
-| `chore` | 构建、工具、依赖等杂项 |
-| `perf` | 性能优化 |
-| `ci` | CI/CD 配置变更 |
+| `feat` | New features |
+| `fix` | Fix bug |
+| `refactor` | Refactor (does not change behavior) |
+| `style` | Code format adjustment (does not affect logic) |
+| `docs` | Documentation changes |
+| `test` | Test related |
+| `chore` | Build, tools, dependencies and other miscellaneous items |
+| `perf` | Performance optimization |
+| `ci` | CI/CD configuration changes |
 
 ### scope
 
-可选，标明影响范围，如模块名、组件名或功能域：
+Optional, indicate the scope of influence, such as module name, component name or functional domain:
 
-- `feat(auth): 新增手机号登录`
-- `fix(table): 修复排序列未高亮`
-- `refactor(api): 统一请求错误处理`
+- `feat(auth): add new mobile phone number to log in`
+- `fix(table): Fix sorting column not highlighted`
+- `refactor(api): unified request error handling`
 
-### subject 规范
+### subject specification
 
-- 使用祈使句（"增加 xxx" 而非 "增加了 xxx"）
-- 不超过 72 个字符
-- 不以句号结尾
-- 如果影响范围较大，在 body 中详细说明
+- Use imperative sentences ("increased xxx" instead of "increased xxx")
+- No more than 72 characters
+- does not end with a period
+- If the scope of impact is large, describe it in detail in the body
 
-## 分支命名
+## Branch naming
 
-- `feature/xxx` — 新功能
-- `fix/xxx` — 修复
-- `refactor/xxx` — 重构
-- `hotfix/xxx` — 紧急修复
+- `feature/xxx` — new features
+- `fix/xxx` — fix
+- `refactor/xxx` — Refactor
+- `hotfix/xxx` — emergency fix
 
-## 提交前检查
+## Check before submission
 
-提交前必须通过：
+Must pass before submission:
 
 1. lint
 2. type-check
-3. 与变更相关的测试
+3. Testing related to changes
 
-未经用户确认不要直接执行 `git commit`。
+Do not execute `git commit` directly without user confirmation.
 
-## 提交粒度
+## Submission granularity
 
-- 一个提交只包含一个清晰目的：功能、修复、测试、文档或清理。
-- 大型计划应拆成可验证的小批次，每批都有说明和命令结果。
-- 清理、格式化和行为变更不要混在同一提交中。
-- 推送或发 PR 前先复查 diff，确认没有本地配置、密钥、临时报告或调试输出。
+- A commit only has one clear purpose: feature, fix, test, documentation or cleanup.
+- Large programs should be broken into verifiable smaller batches, each with instructions and command results.
+- Don't mix cleanup, formatting, and behavior changes in the same commit.
+- Review the diff before pushing or sending a PR to make sure there are no local configurations, keys, temporary reports or debug output.
 
-## 反模式
+## Anti-pattern
 
-- 一个 commit 混合不相关的改动
-- commit message 过于笼统（如 "update"、"fix bug"、"wip"）
-- 在 commit 中包含调试代码、console.log 或临时 hack
-- 未说明验证命令或已知剩余风险就提交高风险改动
+- A commit that mixes unrelated changes
+- The commit message is too general (such as "update", "fix bug", "wip")
+- Include debug code, console.log, or temporary hacks in commits
+- Commit high-risk changes without specifying verification commands or knowing the remaining risk

package/templates/shared/rules/fec-i18n.md

@@ -1,64 +1,64 @@
-# 国际化 (i18n) 规则
+# Internationalization (i18n) rules
 
-凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀。
+This document applies whenever it involves user-visible copy, tooltips, form labels, error messages, or UI text. Please modify the locales path, library and key prefix according to the actual i18n solution of the project.
 
-## 适用范围
+## Scope of application
 
-- **现代栈（React / Vue / Next / Nuxt 等）**：新增或修改的用户可见文案必须走项目 i18n 方案。
-- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层遵守迁移约束，避免扩大硬编码和混乱 key。
+- **Modern stack (React/Vue/Next/Nuxt, etc.)**: New or modified user-visible copy must follow the project i18n solution.
+- **Legacy HTML/JS, progressive migration or coexistence of old and new**: The new code path must still meet the core principles; the legacy layer adheres to migration constraints to avoid expanding hard coding and confusing keys.
 
-下文用 `src/locales/` 指代项目实际文案资源目录，请按仓库约定替换。
+`src/locales/` is used below to refer to the actual copywriting resource directory of the project. Please replace it according to the warehouse convention.
 
-## 核心原则
+## Core Principles
 
-- 新应用代码中的用户可见文案须使用 i18n，禁止硬编码中文或英文字符串。
-- i18n key 按模块组织，使用点分命名，例如 `order.list.empty`。
-- 相同语义的文案复用同一个 key，避免重复定义。
-- 变量、复数、日期、数字和货币使用 i18n 能力格式化，不用字符串拼接。
-- 修改文案前先检索现有资源，优先复用准确 key。
+- User-visible copy in new application code must use i18n, and hardcoding Chinese or English strings is prohibited.
+- i18n keys are organized by modules and named with dots, such as `order.list.empty`.
+- Copies with the same semantics reuse the same key to avoid repeated definitions.
+- Variables, plurals, dates, numbers and currencies are formatted using i18n capabilities without string concatenation.
+- Search existing resources before modifying the copy, and give priority to reusing accurate keys.
 
-## 文案与资源规范
+## Copywriting and resource specifications
 
-- `common.*` 用于跨模块通用文案，例如确认、取消、提交、加载中。
-- `module.component.*` 用于模块级文案。
-- `validation.*` 用于表单校验提示。
-- `error.*` 用于错误信息。
-- 每种自然语言对应独立资源文件，禁止多种语言混写在同一文件或同一顶层多语言对象内。
-- 文案文件须以 UTF-8 保存；团队有约定时优先 UTF-8 无 BOM，避免中文、日文等非 ASCII 文案乱码。
-- 新增 key 时，同步更新当前功能应覆盖的主要语言文件；若某语言暂缺，必须显式记录缺口。
+- `common.*` is used for cross-module common copywriting, such as confirm, cancel, submit, and loading.
+- `module.component.*` is used for module-level copy.
+- `validation.*` is used for form validation prompts.
+- `error.*` for error messages.
+- Each natural language corresponds to an independent resource file, and multiple languages are prohibited from being mixed in the same file or the same top-level multi-language object.
+- Copywriting files must be saved in UTF-8; when the team has an agreement, priority will be given to UTF-8 without BOM to avoid garbled non-ASCII copywriting in Chinese, Japanese and other languages.
+- When adding a key, the main language files that should be covered by the current function are updated simultaneously; if a language is temporarily missing, the gap must be explicitly recorded.
 
-## 遗留代码与迁移场景
+## Legacy code and migration scenarios
 
-- 遗留 HTML 或 JS 中不新增用户可见硬编码，除非该段为纯静态展示且仓库尚无可接入 i18n 路径。
-- React / Vue 等新代码路径新增提示、错误、按钮、表单标签时，必须走 i18n。
-- 新增子应用或模块时，与现有语言文件结构、命名空间和懒加载策略一致。
-- key 按页面、模块和语义组织，避免继续沿用历史缩写或无意义分段。
-- 旧 key 若仅“能用但不准”，优先重命名 key 并重写译文，不长期保留并行兼容。
-- 仅当旧 key 已成为对外契约（后端、埋点、外部文档、第三方集成等固定引用）时，才引入映射层或别名过渡。
+- No new user-visible hardcoding is added in legacy HTML or JS, unless the segment is purely static and the repository does not yet have access to the i18n path.
+- When new code paths such as React/Vue add prompts, errors, buttons, and form labels, i18n must be used.
+- When adding new sub-applications or modules, they should be consistent with the existing language file structure, namespace and lazy loading strategy.
+- Keys are organized by page, module and semantics to avoid continuing to use historical abbreviations or meaningless segments.
+- If the old key is only "usable but inaccurate", priority will be given to renaming the key and rewriting the translation, and parallel compatibility will not be maintained for a long time.
+- Only introduce mapping layer or alias transition when the old key has become an external contract (fixed reference in backend, buried points, external documents, third-party integration, etc.).
 
-## 实现约束
+## Implement constraints
 
-- Vue、React、Next、Nuxt 的具体调用方式以项目现有 i18n 库为准，例如 `vue-i18n`、`react-intl`、`react-i18next` 或框架内置方案。
-- 组件中不要直接写用户可见硬编码；测试可通过 key 或最终文案断言，但应避免与翻译细节过度耦合。
-- 懒加载语言包时，loading、fallback 和缺失 key 行为要可预期。
-- 错误、表单和空状态文案要能表达用户下一步，不只翻译技术错误。
+- The specific calling methods of Vue, React, Next, and Nuxt are subject to the existing i18n library of the project, such as `vue-i18n`, `react-intl`, `react-i18next` or the framework's built-in solution.
+- Do not directly write user-visible hard coding in components; tests can assert through key or final copywriting, but should avoid over-coupling with translation details.
+- When lazily loading language packs, loading, fallback, and missing key behaviors must be predictable.
+- Error, form, and empty state copy should express the user’s next step, not just translate technical errors.
 
-## 检查清单
+## Checklist
 
-- [ ] 所有新增用户可见文案使用 i18n key。
-- [ ] 新增 key 已添加到所有应覆盖语言文件，且各语言分文件维护。
-- [ ] 语言资源文件为 UTF-8，打开无乱码。
-- [ ] key 命名符合模块、组件、用途约定，并复用已有语义。
-- [ ] 插值、复数、日期、数字、货币使用 i18n 格式化。
-- [ ] 迁移或混合栈中未扩大用户可见硬编码。
-- [ ] 新代码未破坏现有命名空间、加载方式和子应用边界。
+- [ ] All newly added user-visible copy uses i18n key.
+- [ ] The new key has been added to all language files that should be covered, and each language is maintained in separate files.
+- [ ] The language resource file is UTF-8, and there will be no garbled characters when opened.
+- [ ] key naming conforms to module, component, and usage conventions, and reuses existing semantics.
+- [ ] Interpolation, complex numbers, dates, numbers, currencies are formatted using i18n.
+- [ ] User-visible hardcoding not expanded in migration or hybrid stacks.
+- [ ] The new code does not break existing namespaces, loading methods, and sub-app boundaries.
 
-## 反模式
+## Anti-pattern
 
-- 在模板或 JSX 中直接写用户可见中文或英文字符串。
-- 使用字符串拼接代替 i18n 插值。
-- 在 JS/TS 逻辑中硬编码 toast、错误或确认文案。
-- 不同模块为相同含义创建不同 key。
-- 多语言混写导致 diff、评审和按需加载困难。
-- 用非 UTF-8 或错误编码保存文案文件。
-- 为迁就历史缩写或劣质命名长期保留多套并行 key。
+- Write user-visible Chinese or English strings directly in templates or JSX.
+- Use string concatenation instead of i18n interpolation.
+- Hardcode toast, error or confirmation text in JS/TS logic.
+- Different modules create different keys for the same meaning.
+- Mixing multiple languages makes diffing, reviewing and on-demand loading difficult.
+- Save copy files in non-UTF-8 or incorrect encoding.
+- Long-term retention of multiple sets of parallel keys to accommodate historical abbreviations or poor naming.

package/templates/shared/rules/fec-naming-conventions.md

@@ -1,33 +1,33 @@
-# 命名规范
+# Naming convention
 
-## 文件与目录命名
+## File and directory naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| 页面组件 | PascalCase + `Page` 后缀 | `UserDetailPage.tsx` / `UserDetailPage.vue` |
-| 布局组件 | PascalCase + `Layout` 后缀 | `MainLayout.tsx` / `MainLayout.vue` |
-| 通用组件 | PascalCase | `DataTable.tsx` / `AppButton.vue` |
-| Hooks / Composables | camelCase + `use` 前缀 | `useAuth.ts`、`useDebounce.ts` |
-| Store 文件 | camelCase + `Store` 后缀 | `authStore.ts`、`uiStore.ts` |
-| API 文件 | camelCase | `api.ts` 或按领域命名 `userApi.ts` |
-| 工具函数 | camelCase | `format.ts`、`validators.ts` |
-| 类型文件 | camelCase | `types.ts`、`models.ts` |
-| 常量文件 | camelCase | `constants.ts`、`config.ts` |
-| 测试文件 | 与源文件同名 + `.spec` / `.test` | `Button.spec.tsx`、`useAuth.spec.ts` |
-| 样式文件 | 组件名 + `.styles` + 扩展名 | `Button.styles.css`、`DataTable.styles.scss`；使用 styled-components 时为 `ComponentName.styles.ts` |
-| 语言包 | 语言代码（BCP 47） | `zh-CN.json`、`en-US.json` |
-| 目录名 | PascalCase（组件/页面）或 kebab-case（功能模块） | `UserDetail/`、`auth/`、`order/` |
-
-## 组件命名
+| Page component | PascalCase + `Page` suffix | `UserDetailPage.tsx` / `UserDetailPage.vue` |
+| Layout component | PascalCase + `Layout` suffix | `MainLayout.tsx` / `MainLayout.vue` |
+| Common components | PascalCase | `DataTable.tsx` / `AppButton.vue` |
+| Hooks / Composables | camelCase + `use` prefix | `useAuth.ts`, `useDebounce.ts` |
+| Store file | camelCase + `Store` suffix | `authStore.ts`, `uiStore.ts` |
+| API documentation | camelCase | `api.ts` or by domain `userApi.ts` |
+| Utility functions | camelCase | `format.ts`, `validators.ts` |
+| Type files | camelCase | `types.ts`, `models.ts` |
+| Constant files | camelCase | `constants.ts`, `config.ts` |
+| Test file | Same name as source file + `.spec` / `.test` | `Button.spec.tsx`, `useAuth.spec.ts` |
+| Style file | Component name + `.styles` + extension | `Button.styles.css`, `DataTable.styles.scss`; `ComponentName.styles.ts` when using styled-components |
+| Language pack | Language code (BCP 47) | `zh-CN.json`, `en-US.json` |
+| Directory name | PascalCase (component/page) or kebab-case (function module) | `UserDetail/`, `auth/`, `order/` |
+
+## Component naming
 
 ### React
 
 ```tsx
-// 文件名与组件名一致
+//The file name is consistent with the component name
 // src/components/DataTable/DataTable.tsx
 export function DataTable({ data, columns }: DataTableProps) { ... }
 
-// 页面组件加 Page 后缀
+//Add Page suffix to page component
 // src/pages/UserDetail/UserDetailPage.tsx
 export default function UserDetailPage() { ... }
 ```
@@ -35,86 +35,86 @@ export default function UserDetailPage() { ... }
 ### Vue
 
 ```vue
-<!-- 文件名与组件名一致 -->
+<!-- The file name is consistent with the component name -->
 <!-- src/components/AppButton/AppButton.vue -->
 <script setup lang="ts">
-// 无需 defineOptions，文件名即组件名
+// No need for defineOptions, the file name is the component name
 </script>
 ```
 
-- 多词组件名（避免与 HTML 原生标签冲突）
-- Vue 全局组件推荐使用 `App` 前缀（`AppButton`、`AppModal`）
-- 模板中使用 PascalCase 引用：`<AppButton>` 而非 `<app-button>`
+- Multi-word component names (to avoid conflicts with HTML native tags)
+- Vue global components are recommended to use the `App` prefix (`AppButton`, `AppModal`)
+- Use PascalCase reference in template: `<AppButton>` instead of `<app-button>`
 
-## 变量与函数命名
+## Variable and function naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| 普通变量 | camelCase | `userName`、`isLoading`、`pageSize` |
-| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` |
-| 布尔值 | `is` / `has` / `should` / `can` 前缀 | `isVisible`、`hasPermission`、`canEdit` |
-| 事件处理（组件内） | `handle` 前缀 | `handleClick`、`handleSubmit` |
-| 回调 Props | `on` 前缀 | `onClick`、`onSubmit`、`onChange` |
-| 数组 | 复数名词 | `users`、`orderItems`、`selectedIds` |
-| Map / Record | `xxxMap` 或 `xxxByYyy` | `userMap`、`permissionsById` |
-| Ref (Vue) | 不加 `Ref` 后缀 | `count`（不用 `countRef`） |
-| 接口 | PascalCase，不加 `I` 前缀 | `UserProfile`（不用 `IUserProfile`） |
-| Props 接口 | 组件名 + `Props` | `DataTableProps`、`UserFormProps` |
-| Emits 接口 | 组件名 + `Emits` | `UserFormEmits` |
-| 枚举 | PascalCase，成员用 PascalCase | `OrderStatus.Pending` |
-| 泛型参数 | 单字母大写或语义化 | `T`、`TData`、`TItem` |
-
-## CSS 类命名
-
-- 与项目约定保持一致（BEM / CSS Modules / Tailwind / Atomic CSS）
-- 如果使用 CSS Modules，类名用 camelCase：`.headerTitle`、`.cardBody`
-- 如果使用 BEM，遵循 `block__element--modifier` 格式
-- CSS 变量使用 kebab-case：`--color-primary`、`--spacing-md`
-
-## 路由命名
-
-| 类型 | 命名风格 | 示例 |
+| Ordinary variables | camelCase | `userName`, `isLoading`, `pageSize` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
+| Boolean value | `is` / `has` / `should` / `can` prefix | `isVisible`, `hasPermission`, `canEdit` |
+| Event handling (inside component) | `handle` prefix | `handleClick`, `handleSubmit` |
+| Callback Props | `on` prefix | `onClick`, `onSubmit`, `onChange` |
+| Array | Plural noun | `users`, `orderItems`, `selectedIds` |
+| Map / Record | `xxxMap` or `xxxByYyy` | `userMap`, `permissionsById` |
+| Ref (Vue) | Without `Ref` suffix | `count` (without `countRef`) |
+| Interface | PascalCase, without `I` prefix | `UserProfile` (without `IUserProfile`) |
+| Props interface | component name + `Props` | `DataTableProps`, `UserFormProps` |
+| Emits interface | component name + `Emits` | `UserFormEmits` |
+| Enum | PascalCase, members use PascalCase | `OrderStatus.Pending` |
+| Generic parameters | Single letter capitalization or semantic | `T`, `TData`, `TItem` |
+
+## CSS class naming
+
+- Aligned with project conventions (BEM/CSS Modules/Tailwind/Atomic CSS)
+- If using CSS Modules, use camelCase for class names: `.headerTitle`, `.cardBody`
+- If using BEM, follow the `block__element--modifier` format
+- CSS variables use kebab-case: `--color-primary`, `--spacing-md`
+
+## Route naming
+
+| Type | Naming Style | Example |
 |------|----------|------|
-| 路由路径 | kebab-case | `/user-detail`、`/order-list` |
-| 路由名称 | PascalCase | `UserDetail`、`OrderList` |
-| 路由参数 | camelCase | `:userId`、`:orderId` |
-| 查询参数 | camelCase | `?pageSize=10&sortBy=name` |
-| 路径常量 | UPPER_SNAKE_CASE | `ROUTE_USER_DETAIL = '/user-detail'` |
+| routing path | kebab-case | `/user-detail`, `/order-list` |
+| Route name | PascalCase | `UserDetail`, `OrderList` |
+| Routing parameters | camelCase | `:userId`, `:orderId` |
+| Query parameters | camelCase | `?pageSize=10&sortBy=name` |
+| Path constants | UPPER_SNAKE_CASE | `ROUTE_USER_DETAIL = '/user-detail'` |
 
-## API 命名
+## API naming
 
-| 类型 | 命名风格 | 示例 |
+| Type | Naming Style | Example |
 |------|----------|------|
-| GET 列表 | `getXxxList` | `getUserList(params)` |
-| GET 单条 | `getXxxDetail` / `getXxxById` | `getUserDetail(id)` |
-| POST 创建 | `createXxx` | `createOrder(data)` |
-| PUT 更新 | `updateXxx` | `updateUser(id, data)` |
-| DELETE 删除 | `deleteXxx` | `deleteOrder(id)` |
-| DTO 类型 | 动词 + 名词 + `DTO` | `CreateOrderDTO`、`UpdateUserDTO` |
-| 响应类型 | 名词 | `User`、`Order`、`PageResult<User>` |
-
-## i18n Key 命名
-
-- 使用点分命名空间：`module.section.label`
-- 示例：`user.form.username`、`common.button.submit`、`error.network.timeout`
-- 不使用中文 / 拼音作为 key
-
-## 反模式
-
-- 文件名和组件名不一致（`user-table.tsx` 导出 `DataGrid`）
-- 同一项目混用多种命名风格（有的 kebab-case 有的 PascalCase）
-- 使用缩写或不明确的名称（`btn`、`usr`、`tmp`、`handleA`）
-- 布尔值没有语义前缀（`visible` → 应为 `isVisible`）
-- 常量不用大写（`maxRetry` → 应为 `MAX_RETRY`）
-- CSS 变量硬编码在组件中而非使用统一变量
-
-## 检查清单
-
-- [ ] 文件名与导出的组件/函数名一致
-- [ ] 页面组件有 `Page` 后缀，布局组件有 `Layout` 后缀
-- [ ] 布尔变量使用 `is` / `has` / `can` / `should` 前缀
-- [ ] 事件处理用 `handle` 前缀，回调 Props 用 `on` 前缀
-- [ ] 常量使用 UPPER_SNAKE_CASE
-- [ ] 路由路径使用 kebab-case，路由名使用 PascalCase
-- [ ] API 函数命名与 HTTP 方法语义一致
-- [ ] i18n key 使用点分命名空间，无硬编码文案
+| GET list | `getXxxList` | `getUserList(params)` |
+| GET single item | `getXxxDetail` / `getXxxById` | `getUserDetail(id)` |
+| POST Create | `createXxx` | `createOrder(data)` |
+| PUT update | `updateXxx` | `updateUser(id, data)` |
+| DELETE delete | `deleteXxx` | `deleteOrder(id)` |
+| DTO type | Verb + Noun + `DTO` | `CreateOrderDTO`, `UpdateUserDTO` |
+| Response type | Noun | `User`, `Order`, `PageResult<User>` |
+
+## i18n Key naming
+
+- Use dotted namespace: `module.section.label`
+- Examples: `user.form.username`, `common.button.submit`, `error.network.timeout`
+- Do not use Chinese/Pinyin as key
+
+## Anti-pattern
+
+- File name and component name are inconsistent (`user-table.tsx` exports `DataGrid`)
+- Mixing multiple naming styles (some kebab-case, some PascalCase) in the same project
+- Use abbreviated or ambiguous names (`btn`, `usr`, `tmp`, `handleA`)
+- Boolean values have no semantic prefix (`visible` → should be `isVisible`)
+- Constants do not need to be capitalized (`maxRetry` → should be `MAX_RETRY`)
+- CSS variables are hardcoded in components instead of using uniform variables
+
+## Checklist
+
+- [ ] The file name is consistent with the exported component/function name
+- [ ] Page components have the `Page` suffix, and layout components have the `Layout` suffix.
+- [ ] Boolean variables use `is` / `has` / `can` / `should` prefixes
+- [ ] Event handling is prefixed with `handle`, callback Props are prefixed with `on`
+- [ ] constant using UPPER_SNAKE_CASE
+- [ ] Use kebab-case for the routing path and PascalCase for the routing name.
+- [ ] API function naming is consistent with HTTP method semantics
+- [ ] i18n key uses dotted namespace, no hardcoded copy