@bovinphang/frontend-craft 2.7.0 → 2.8.0

package/templates/shared/rules/fec-source-driven-development.md

@@ -1,31 +1,31 @@
-# 来源驱动开发规则
+# Source-driven development rules
 
-当实现依赖框架、库、浏览器、运行时、构建工具或平台行为时，先确认事实来源，再写代码或评审结论。
+When an implementation relies on a framework, library, browser, runtime, build tool, or platform behavior, confirm the source of truth before writing code or reviewing conclusions.
 
-## 事实来源优先级
+## Fact source priority
 
-1. 项目内 README、配置、测试、模板和已有实现。
-2. 官方文档、源码、类型定义、release notes、migration guide。
-3. Web 标准、浏览器兼容数据和平台文档。
-4. Issue、讨论、博客和第三方文章仅作为线索。
+1. README, configuration, testing, templates and existing implementations within the project.
+2. Official documents, source code, type definitions, release notes, migration guide.
+3. Web standards, browser compatibility data, and platform documentation.
+4. Issues, discussions, blogs and third-party articles are only used as clues.
 
-## 使用场景
+## Usage scenarios
 
-- 框架新版本、路由、渲染模式、缓存、构建配置、浏览器 API。
-- 公共接口、组件 API、设计系统 token、CLI 命令和插件元数据。
-- 依赖升级、迁移、废弃 API 替换、跨运行时兼容。
-- 与安全、性能、可访问性相关的版本敏感判断。
+- New versions of frameworks, routing, rendering modes, caching, build configurations, browser APIs.
+- Public interfaces, component APIs, design system tokens, CLI commands, and plugin metadata.
+- Dependency upgrade, migration, obsolete API replacement, cross-runtime compatibility.
+- Version-sensitive judgments related to security, performance, and accessibility.
 
-## 输出要求
+## Output requirements
 
-- 写清来源、版本或项目事实、决策结论、影响范围和验证方式。
-- 若项目现状与官方推荐冲突，说明冲突原因和渐进迁移策略。
-- 不复制长篇外部文档；只保留必要结论、链接或项目内文件路径。
-- 无法验证时标注不确定性和需要用户/团队确认的事项。
+- Write down the source, version or project facts, decision conclusion, scope of influence and verification method.
+- If the current status of the project conflicts with official recommendations, explain the cause of the conflict and the gradual migration strategy.
+- Do not copy long external documents; only keep necessary conclusions, links or file paths within the project.
+- Mark uncertainties and matters requiring confirmation from the user/team when they cannot be verified.
 
-## 反模式
+## Anti-pattern
 
-- 凭记忆使用版本敏感 API。
-- 用过时教程替代官方文档。
-- 为追新推翻稳定项目约定。
-- 在组件里散落外部库行为假设，而不是集中到适配层。
+- Use version-sensitive APIs from memory.
+- Replace official documentation with outdated tutorials.
+- Overturn the stable project agreement in order to pursue new projects.
+- Scatter external library behavior assumptions throughout components instead of centralizing them in the adaptation layer.

package/templates/shared/rules/fec-state-management.md

@@ -1,60 +1,60 @@
-# 状态管理规范
+# Status management specifications
 
-本文件约定前端状态归属底线。状态清单、Store 形状示例、URL 状态、持久化适配器和 SSR 隔离细节交给 `fec-state-management`；请求缓存细节交给数据获取 workflow；表单字段和校验交给表单 workflow。
+This document stipulates that the front-end status belongs to the bottom line. State manifests, Store shape examples, URL states, persistence adapters, and SSR isolation details are left to `fec-state-management`; request caching details are left to the data fetch workflow; and form fields and validation are left to the form workflow.
 
-## 状态分类
+## Status classification
 
-| 类型 | 示例 | 默认归属 |
+| Type | Example | Default Attribution |
 | ---- | ---- | -------- |
-| 本地 UI 状态 | modal 开关、tab、展开行、hover 编辑态 | 组件内 state / ref |
-| 表单状态 | 输入值、脏字段、校验错误、提交中 | 表单库或表单组件 |
-| 服务端状态 | 列表、详情、分页结果、远程错误 | 请求缓存库 |
-| URL 状态 | 搜索词、筛选、排序、页码、选中 tab | 路由参数 / search params |
-| 全局客户端状态 | 登录用户、主题、权限快照、购物车草稿 | 全局 store |
-| 浏览器持久化状态 | 偏好、非敏感草稿、离线队列 | 存储层 + 状态适配器 |
-
-## 核心原则
-
-- **先归属，后选库**：不要先选 Redux、Zustand、Pinia 或 Context；先确定每个状态的唯一 owner。
-- **就近管理**：状态放在需要它的最近公共祖先。
-- **单一数据源**：同一份数据只在一个地方维护。
-- **派生优于同步**：可从 props、server state、URL 或已有 state 推导的值，不另存一份。
-- **最小全局状态**：全局 store 只保存真正跨页面、跨 feature 或需要统一动作的客户端状态。
-
-## React 状态边界
-
-- 单组件或小子树使用 `useState` / `useReducer`。
-- 低频全局配置、主题或依赖注入可用 Context；高频变化的大对象不要放 Context。
-- 中等复杂业务状态可用 Zustand、Jotai 或仓库既有方案；大型严格动作流可用 Redux Toolkit。
-- 服务端数据使用请求缓存库，不复制到全局 store。
-
-## Vue 状态边界
-
-- 局部状态使用 `ref` / `reactive` / `computed`。
-- 局部跨层级上下文使用 `provide/inject`。
-- 全局业务状态使用 Pinia 或项目既有 store。
-- 服务端数据优先使用请求库或 composable 管理，不原封不动写入 Pinia。
-
-## URL 与持久化状态
-
-- 搜索、筛选、排序、分页、选中 tab 等需要分享或刷新保留的视图状态优先放 URL。
-- 浏览器持久化只保存稳定偏好或非敏感草稿，并明确字段白名单、版本号、迁移路径、过期策略和敏感字段排除。
-- SSR 场景不要在模块顶层创建带用户数据的单例 store；每次请求需要独立实例。
-
-## 反模式
-
-- 将所有状态都放进全局 store。
-- 在 store 中存放 UI 临时状态或表单每个字段。
-- 手动同步多份相同数据，而不是从源状态派生。
-- 将服务端响应原封不动存入全局 store，而不用请求缓存库。
-- 用 Context / provide 承载高频变化大对象，导致大范围重渲染。
-- 持久化 token、权限细节、个人敏感数据或未版本化的大对象。
-
-## 检查清单
-
-- [ ] 每个状态都有明确归属：本地 / 表单 / 服务端缓存 / URL / 全局 store / 浏览器持久化。
-- [ ] 可派生的值没有被存为独立 state。
-- [ ] 全局 store 只包含真正跨边界共享的数据。
-- [ ] 服务端数据通过请求库管理，刷新、回退、权限变化和错误状态仍可恢复。
-- [ ] URL 状态与路由参数同步，刷新和分享行为符合预期。
-- [ ] 持久化状态有白名单、版本、迁移和敏感字段排除。
+| Local UI state | modal switch, tab, expand row, hover editing state | In-component state / ref |
+| Form status | Input value, dirty field, validation error, submitting | Form library or form component |
+| Server status | List, details, paging results, remote errors | Request cache library |
+| URL status | Search terms, filter, sort, page number, selected tab | Routing parameters / search params |
+| Global client status | Login users, topics, permission snapshots, shopping cart drafts | Global store |
+| Browser persistent state | Preferences, non-sensitive drafts, offline queues | Storage layer + state adapter |
+
+## Core Principles
+
+- **Own first, choose library later**: Don’t choose Redux, Zustand, Pinia or Context first; determine the unique owner of each state first.
+- **Nearest Management**: The state is placed in the nearest common ancestor that needs it.
+- **Single Data Source**: The same data is maintained in only one place.
+- **Derivation is better than synchronization**: Values that can be derived from props, server state, URL or existing state, do not save a new copy.
+- **Minimum global state**: The global store only saves client state that is truly cross-page, cross-feature, or requires unified action.
+
+## React state boundaries
+
+- Use `useState` / `useReducer` for single components or small subtrees.
+- Low-frequency global configuration, theme or dependency injection can use Context; large objects that change frequently should not be placed in Context.
+- For moderately complex business states, Zustand, Jotai or existing warehouse solutions can be used; for large and strict action flows, Redux Toolkit can be used.
+- Server-side data uses the request cache library and is not copied to the global store.
+
+## Vue state boundary
+
+- Use `ref` / `reactive` / `computed` for local state.
+- Use `provide/inject` for local cross-level context.
+- Global business status uses Pinia or the existing store of the project.
+- Server-side data is first managed using the request library or composable and is not written to Pinia intact.
+
+## URL and persistent state
+
+- When searching, filtering, sorting, paging, selecting tabs, etc., the view state that needs to be shared or refreshed should be given priority to the URL.
+- Browser persistence only saves stable preferences or non-sensitive drafts, and clearly identifies field whitelists, version numbers, migration paths, expiration policies, and sensitive field exclusions.
+- In SSR scenarios, do not create a single instance store with user data at the top level of the module; each request requires an independent instance.
+
+## Anti-pattern
+
+- Put all state into global store.
+- Store UI temporary state or each field of the form in the store.
+- Manually synchronize multiple copies of the same data instead of deriving from source state.
+- Store the server response intact in the global store without requesting the cache library.
+- Use Context / provide to carry large objects that change frequently, resulting in large-scale re-rendering.
+- Persistent tokens, permission details, personal sensitive data or unversioned large objects.
+
+## Checklist
+
+- [ ] Each state has a clear ownership: local / form / server cache / URL / global store / browser persistence.
+- [ ] Derivable values are not stored as independent state.
+- [ ] The global store only contains data that is truly shared across boundaries.
+- [ ] Server-side data is managed through the request library, and refreshes, rollbacks, permission changes, and error states can still be recovered.
+- [ ] URL state is synchronized with route parameters, and refresh and share behavior is as expected.
+- [ ] Persistence status has whitelist, version, migration and sensitive field exclusions.

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

@@ -1,98 +1,98 @@
-# 测试与校验规则
+# Testing and verification rules
 
-凡是新增、修改、重构或评审代码时，都应用本文件。
+This document should be used whenever code is added, modified, refactored, or reviewed.
 
-## 校验顺序
+## Verification sequence
 
-优先按以下顺序执行：
+Prioritize execution in the following order:
 
 1. lint
 2. type check
 3. unit test
 4. build
 
-优先使用仓库已有脚本。
-如果命令不确定，先检查 `package.json`。
+Priority is given to using existing scripts in the warehouse.
+If the command is uncertain, check `package.json` first.
 
-## 改动校验原则
+## Change the verification principle
 
-- 先修复范围最小且正确的问题
-- 每次关键修复后重新执行受影响的命令
-- 不要盲目压掉报错或关闭规则
-- 不要为了通过检查而降低类型安全
-- 不要因为一个局部测试失败就重写无关模块
+- Fix the smallest and correct issues first
+- Re-execute affected commands after each critical fix
+- Don’t blindly suppress error reporting or closing rules
+- Don't compromise type safety to pass checks
+- Don't rewrite unrelated modules just because a local test fails
 
-## 测试要求
+## Testing requirements
 
-新增或修改行为时，考虑是否需要覆盖以下内容：
+When adding or modifying behaviors, consider whether you need to override the following:
 
-- 组件渲染
-- 交互行为
-- 状态切换
-- 边界场景
-- loading / empty / error 状态
-- 与可访问性相关的关键交互
+- Component rendering
+- interactive behavior
+- Status switching
+- Border scenes
+- loading / empty / error status
+- Key interactions related to accessibility
 
-如果没有补测试，需要说明原因。
+If there is no supplementary test, the reason needs to be explained.
 
-## Fixture 与 Mock
+## Fixture and Mock
 
-- Fixture 表达业务场景，不使用随机、无语义或只对测试作者有意义的数据
-- 复杂对象使用 builder 填充默认值，每个测试只覆盖当前场景相关字段
-- 测试间不共享可变全局状态、fake timer、store 或 mock server handler
-- 网络 mock 应模拟公开契约和用户可见错误，不复制后端内部实现
+- Fixture expresses business scenarios without using random, meaningless or data that is meaningful only to the test author
+- Complex objects use builder to fill in default values, and each test only covers fields related to the current scenario.
+- No mutable global state, fake timers, stores or mock server handlers are shared between tests
+- Network mocks should simulate public contracts and user-visible errors and not replicate backend internal implementations
 
-## TDD 与回归测试
+## TDD and regression testing
 
-新增行为、修复 Bug 或重构关键逻辑时，优先采用 TDD：
+When adding new behaviors, fixing bugs, or refactoring key logic, TDD is preferred:
 
-1. 先写能描述期望行为的失败测试。
-2. 运行测试并确认失败原因正确。
-3. 写最小实现让测试通过。
-4. 测试保持通过后再重构。
+1. Start by writing failing tests that describe the desired behavior.
+2. Run the test and confirm that the failure reason is correct.
+3. Write the minimum implementation to make the test pass.
+4. Refactor after the test remains passed.
 
-Bug 修复应优先保留能复现问题的回归测试。若现有项目缺少测试基础设施，不要盲目引入新框架；先给出最小测试落地建议并说明维护成本。
+Bug fixes should prioritize keeping regression tests that reproduce the problem. If the existing project lacks testing infrastructure, do not blindly introduce a new framework; first provide minimum test implementation suggestions and explain maintenance costs.
 
-## 代码评审输出风格
+## Code review output style
 
-评审代码时，返回：
+When reviewing code, return:
 
-- 总体评估
-- 必修问题
-- 建议优化
-- 可选优化项
-- 风险等级
+- Overall assessment
+- Required questions
+- Suggestions for optimization
+- Optional optimization items
+- Risk level
 
-结论要具体且可执行。
+Conclusions should be specific and actionable.
 
-## E2E 测试规则
+## E2E test rules
 
-使用 Playwright 或 Cypress 时：
+When using Playwright or Cypress:
 
-- 遵循 **Page Object**，spec 内不写裸选择器；优先 **`data-testid`**，其次 **`role` / `label`**
-- 用 **`test.describe` + `beforeEach`** 组织场景，单用例可独立运行、不依赖执行顺序
-- 禁止用固定 **`sleep`** 当主要同步手段；用 **Locator 自动等待**、`expect`、`waitForResponse` 等
-- Playwright：**`playwright.config.ts`** 中配置 `baseURL`、CI 下 `retries`/`workers`、`trace`/`screenshot`/`video`、**`webServer`** 与多 **`projects`（含移动端）**
-- 关键流程至少覆盖桌面、平板、移动端视口（或等价 device 项目）
-- **不稳定用例**：`test.fixme` / `test.skip` 需写原因与 issue；用 `--repeat-each` 辅助定位 flaky
-- 失败时保留 **截图、Trace、视频**，CI 用 **artifact** 上传 HTML 报告与产物
-- 高风险/资金类流程：**勿在生产跑真实 E2E**；staging 或 mock，必要时 `test.skip`
-- 测试数据可重复：优先 seed、测试账号或 mock 服务；随机值必须带唯一前缀并在 teardown 清理
+- Follow **Page Object**, do not write naked selectors in spec; give priority to **`data-testid`**, followed by **`role` / `label`**
+- Use **`test.describe` + `beforeEach`** to organize scenarios. A single use case can run independently and does not depend on the execution sequence.
+- It is forbidden to use fixed **`sleep`** as the main synchronization method; use **Locator to automatically wait**, `expect`, `waitForResponse`, etc.
+- Playwright: Configure `baseURL` in **`playwright.config.ts`**, `retries`/`workers`, `trace`/`screenshot`/`video`, **`webServer`** and many **`projects` (including mobile)** under CI
+- Key processes cover at least desktop, tablet, and mobile viewports (or equivalent device projects)
+- **Unstable use case**: `test.fixme` / `test.skip` needs to write the reason and issue; use `--repeat-each` to assist in locating flaky
+- Keep **Screenshots, Traces, Videos** in case of failure, CI uses **artifact** to upload HTML reports and products
+- High-risk/funding processes: **Do not run real E2E in production**; staging or mock, if necessary `test.skip`
+- Test data is repeatable: priority is seed, test account or mock service; random values must be uniquely prefixed and cleaned in teardown
 
-详细模式与示例见插件 **`fec-e2e-testing`** skill。
+For detailed modes and examples, see the plug-in **`fec-e2e-testing`** skill.
 
-## 重构规则
+## Refactoring rules
 
-进行重构时：
+When refactoring:
 
-- 除非任务明确要求改行为，否则保持行为一致
-- 说明可能的迁移风险
-- 优先做渐进式修改，而不是大范围重写
-- 总结改动文件、执行过的命令和剩余风险
+- Maintain consistent behavior unless the task specifically requires a change in behavior
+- Describe possible migration risks
+- Prioritize incremental changes over extensive rewrites
+- Summarize changed files, executed commands and remaining risks
 
-## 验证失败处理
+## Verification failure handling
 
-- 按文件和根因分组错误，一次修复一类问题。
-- 每次修复后重新运行最近的失败命令。
-- 不删除失败测试、不关闭规则、不降低类型安全来换取通过。
-- 同一错误多次修复仍失败时，停止扩大改动并报告阻塞。
+- Group errors by file and root cause to fix one type of problems at a time.
+- Rerun the most recent failed command after each fix.
+- Don't remove failing tests, don't close rules, don't reduce type safety in exchange for passing.
+- When the same error is repaired multiple times and still fails, the expansion of changes will be stopped and a blockage will be reported.

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

@@ -1,112 +1,112 @@
-# TypeScript / JavaScript 规则
+# TypeScript / JavaScript rules
 
-编写、修改或评审 `.ts`、`.tsx`、`.js`、`.jsx` 时应用本文件。本文只保留项目常驻硬约束；复杂类型建模、`tsconfig` 分层、声明产物、DTO / view model 边界、类型测试与发布入口设计，交给 `fec-typescript-project-standard` skill 或专项评审处理。注释风格另见 `fec-code-comments.md`；E2E 与校验流程另见 `fec-testing.md`。
+Use this file when writing, modifying or reviewing `.ts`, `.tsx`, `.js`, `.jsx`. This article only retains the permanent hard constraints of the project; complex type modeling, `tsconfig` layering, declared products, DTO / view model boundaries, type testing and release entry design are left to the `fec-typescript-project-standard` skill or special review. See also `fec-code-comments.md` for comment style; see `fec-testing.md` for E2E and verification process.
 
-## 类型与接口
+## Types and interfaces
 
-用类型让对外 API、共享模型与组件 props 显式、可读、可复用。
+Use types to make external APIs, shared models, and component props explicit, readable, and reusable.
 
-### 对外导出的 API
+### Externally exported API
 
-- 对**导出**的函数、共享工具函数、公开类方法，写明参数与返回值类型。
-- **局部**变量在类型显而易见时交给 TypeScript 推断，不为显而易见的中间变量重复标注。
-- 重复出现的内联对象形状抽成具名 `interface` 或 `type`，避免同一契约散落在多个签名中。
-- 外部数据、API DTO、路由参数、表单值与组件 props 的边界要显式命名；复杂建模分流到 `fec-typescript-project-standard`。
+- For **export** functions, shared tool functions, and public class methods, indicate the parameter and return value types.
+- **Local** variables are handed over to TypeScript for inference when the type is obvious, and obvious intermediate variables are not repeatedly annotated.
+- Recurring inline object shapes are extracted into named `interface` or `type` to avoid the same contract being scattered in multiple signatures.
+- The boundaries of external data, API DTOs, routing parameters, form values and component props must be explicitly named; complex modeling is offloaded to `fec-typescript-project-standard`.
 
-### `interface` 与 `type`
+### `interface` and `type`
 
-- 可能被扩展或 `implements` 的**对象形状**优先用 `interface`。
-- **联合、交叉、元组、映射类型、工具类型组合**用 `type`。
-- 状态、类型、角色等有限业务取值优先用字符串字面量联合；仅在互操作或团队统一要求时使用 `enum`。
+- Object shapes that may be extended or `implements` take precedence over `interface`.
+- **Union, intersection, tuple, map type, tool type combination** use `type`.
+- Limited business values such as status, type, role, etc. are first combined with string literals; `enum` is only used when interoperability or team unified requirements are met.
 
-### 函数参数：复杂类型宜具名
+### Function parameters: complex types should be named
 
-- 参数上的**复杂联合**、**内联对象类型**、**较复杂的回调签名**等，应优先提取为具名 `type` / `interface`，再在函数签名中引用。
-- 仅当类型简单、短小、一眼可读，且明显无复用价值时，允许在参数位置内联。
-- 回调参数与返回值必须表达清楚；不要用 `Function`、宽泛对象或隐式 `any` 承接业务契约。
+- **Complex unions**, **inline object types**, **more complex callback signatures**, etc. on parameters should be extracted as named `type` / `interface` first, and then referenced in the function signature.
+- Inlining in parameter positions is only allowed if the type is simple, short, readable at a glance, and has obvious no reuse value.
+- Callback parameters and return values must be expressed clearly; do not use `Function`, wide objects or implicit `any` to undertake business contracts.
 
-### 避免 `any`
+### Avoid `any`
 
-- 业务代码中避免 `any`；已有遗留 `any` 不随手扩散。
-- 外部或不可信数据用 `unknown`，通过 `typeof`、`in`、`instanceof`、schema parse 或自定义 predicate 安全收窄。
-- 类型随调用方变化时用泛型，但不要为简单场景引入难以理解的泛型层。
-- `as` 类型断言只用于明确的边界互操作或已验证收窄后的补充表达，不用于压制类型错误。
+- Avoid `any` in business code; existing `any` should not be spread casually.
+- Use `unknown` for external or untrusted data, safely narrowed through `typeof`, `in`, `instanceof`, schema parse or custom predicate.
+- Use generics when the type changes from caller to caller, but don’t introduce an incomprehensible layer of generics for simple scenarios.
+- `as` type assertions are only used for explicit boundary interoperation or supplementary expressions after verified narrowing, and are not used to suppress type errors.
 
-### React 组件 Props
+### React Component Props
 
-- 用具名 `interface` 或 `type` 定义 props，复杂公共 props 分流到类型模块。
-- 回调 props 写清参数与返回值；事件 payload 不用裸对象长期内联。
-- 无特殊理由不使用 `React.FC`，避免隐式 `children` 等差异。
-- TSX 泛型、复杂组件 props 或外部 DTO 映射问题，交给 React 规则与 `fec-typescript-project-standard` 共同收敛。
+- Define props with named `interface` or `type`, and offload complex public props to type modules.
+- Write clear parameters and return values in callback props; event payload does not require long-term inlining of bare objects.
+- Don't use `React.FC` without special reason, avoid differences such as implicit `children`.
+- TSX generics, complex component props or external DTO mapping issues are left to React rules and `fec-typescript-project-standard` to converge together.
 
-## 单文件规模与模块拆分
+## Single file size and module splitting
 
-- `.ts` / `.tsx` / `.js` / `.jsx` 单文件建议控制在**约 300 行以内**。该阈值是可维护性与评审效率的经验上限，不是机械硬限制。
-- 当文件明显超过该规模且承担多重职责时，应优先按职责拆分：数据访问、业务规则、视图渲染、适配层、常量与映射、类型定义。
-- 超阈值优先提取纯函数、子组件、自定义 Hook、`*.types.ts` 类型模块、常量表；不要仅为压行数做无意义切分。
-- 可接受例外：生成代码、极薄的 re-export 聚合文件、经团队评审确认的高内聚模块；例外建议在文件头简短注明原因。
+- `.ts` / `.tsx` / `.js` / `.jsx` It is recommended that a single file be controlled within **about 300 lines**. This threshold is an empirical upper limit for maintainability and review efficiency, not a mechanical hard limit.
+- When the file obviously exceeds this size and bears multiple responsibilities, priority should be given to splitting it by responsibility: data access, business rules, view rendering, adaptation layer, constants and mapping, and type definition.
+- Prioritize extraction of pure functions, subcomponents, custom Hooks, `*.types.ts` type modules, and constant tables above the threshold; do not make meaningless segmentation just for the number of pressed lines.
+- Acceptable exceptions: generated code, very thin re-export aggregation files, high cohesion modules confirmed by team review; exceptions are recommended to briefly indicate the reasons in the file header.
 
-### 仍为 JavaScript 的文件
+### Still a JavaScript file
 
-- 在 `.js` / `.jsx` 中，若短期无法迁 TS，可用 JSDoc 补类型，并与运行时行为一致。
-- 不为迁移方便引入新的隐式全局、宽松对象或未验证外部输入。
+- In `.js` / `.jsx`, if TS cannot be migrated in the short term, JSDoc can be used to complement the type, and the behavior will be consistent with the runtime.
+- Do not introduce new implicit globals, loose objects, or unvalidated external inputs for migration convenience.
 
-## 禁止 Magic Number / Magic String
+## Disable Magic Number / Magic String
 
-- **业务代码中禁止**使用**无语义**的硬编码数字或字符串直接表示状态、类型、标识或业务含义，包括 `if` / `switch` / 赋值 / API 字段映射。
-- 固定且有限的取值范围须在单一真源处定义，并在全仓引用名称，避免裸值散落。
-- 前端主路径优先使用 `as const` 常量对象配合字面量联合；与后端协议或团队约定强绑定时可使用 `enum`。
-- 不属本条的典型例外仍应保持可读：纯算法下标、明显的 `0` / `1` 长度判断、与业务无关的 UI 刻度；视觉值若已有设计 Token，应改走 `fec-design-system.md`。
+- **It is prohibited** in business code to use **semantic** hard-coded numbers or strings to directly represent status, type, identity or business meaning, including `if` / `switch` / assignment / API field mapping.
+- The fixed and limited value range must be defined at a single true source, and the name must be referenced in the entire warehouse to avoid the scattering of bare values.
+- The front-end main path preferentially uses `as const` constant objects with literal unions; `enum` can be used when strongly bound to the back-end protocol or team agreement.
+- Typical exceptions that do not fall under this article should still remain readable: pure algorithm subscripts, obvious `0` / `1` length judgments, UI scales that have nothing to do with business; if the visual value already has a design token, it should be changed to `fec-design-system.md`.
 
-## 不可变更新
+## Immutable updates
 
-- 优先返回新对象或新数组，避免直接改写入参、props、store 快照或缓存对象。
-- 对不应被修改的数据优先建模为 `readonly` / `Readonly<T>`。
-- 大型嵌套更新应使用项目既有状态方案或清晰的 reducer / helper，不在组件中堆叠临时可变逻辑。
+- Prioritize returning new objects or new arrays and avoid directly modifying parameters, props, store snapshots or cache objects.
+- Data that should not be modified is first modeled as `readonly` / `Readonly<T>`.
+- Large nested updates should use the project's existing state scheme or a clear reducer/helper, without stacking temporary mutable logic in components.
 
-## 异步与错误处理
+## Asynchronous and error handling
 
-- 使用 `async` / `await` 与明确的错误边界；不要吞掉 promise rejection。
-- `catch` 中将错误视为 `unknown` 再收窄，统一映射为用户可见错误、日志错误或调用方可处理的领域错误。
-- API、认证、上传、支付等跨边界错误遵循 `fec-api-layer.md`、`fec-error-handling.md` 和安全规则，不在业务组件中散落裸处理。
+- Use `async` / `await` with clear error boundaries; don't swallow promise rejections.
+- In `catch`, errors are treated as `unknown` and then narrowed down, and uniformly mapped to user-visible errors, log errors or domain errors that can be handled by the caller.
+- Cross-border errors such as API, authentication, upload, and payment follow `fec-api-layer.md`, `fec-error-handling.md` and security rules, and are not handled nakedly in business components.
 
-## 输入校验
+## Input verification
 
-- 外部输入（表单、API、URL 参数、localStorage、postMessage、第三方 SDK 回调等）必须在边界处校验或收窄。
-- 可使用 Zod、Valibot、Yup 或项目选用的同类 schema 工具；不要把具体库作为无条件新依赖引入。
-- schema 推导类型可作为输入类型单一真源；复杂 DTO、领域模型与 UI view model 的分层交给 `fec-typescript-project-standard`。
+- External input (forms, APIs, URL parameters, localStorage, postMessage, third-party SDK callbacks, etc.) must be validated or narrowed at boundaries.
+- You can use Zod, Valibot, Yup or similar schema tools selected by the project; do not introduce specific libraries as unconditional new dependencies.
+- Schema derived types serve as a single source of truth for input types; layering of complex DTOs, domain models and UI view models is left to `fec-typescript-project-standard`.
 
-## 类型资产分层与命名
+## Type asset layering and naming
 
-- 模块或特性专属类型使用 `*.types.ts`，并与实现文件同目录或同 feature 目录放置。
-- 全局与环境相关声明放在 `global.d.ts`、`env.d.ts` 或 `types/*.d.ts`，仅用于真全局或 ambient 声明，不将可模块化类型放入全局。
-- 仅用于类型的导入导出优先使用 `import type` 与 `export type`，减少值空间歧义并提升编译语义清晰度。
-- 与 API DTO 同源的类型，放在对应 feature 或 API 子目录，避免在页面或组件实现内散落大型匿名类型。
-- `index.ts` 聚合导出应保持浅层且按 feature 边界组织，避免深层 barrel 引发循环依赖与不必要耦合。
+- Module or feature-specific types use `*.types.ts` and are placed in the same directory as the implementation file or in the same feature directory.
+- Global and environment-related declarations are placed in `global.d.ts`, `env.d.ts` or `types/*.d.ts`, only for true global or ambient declarations, and do not put modular types into globals.
+- For import and export of types only, use `import type` and `export type` first to reduce value space ambiguity and improve compilation semantic clarity.
+- Types that have the same origin as the API DTO are placed in the corresponding feature or API subdirectory to avoid scattering large anonymous types within the page or component implementation.
+- `index.ts` aggregate exports should be kept shallow and organized according to feature boundaries to avoid deep barrels causing circular dependencies and unnecessary coupling.
 
-## 工程化与惯用法补充
+## Engineering and idiom additions
 
-- 需要同时满足字面量保留与结构校验时优先使用 `satisfies`，再考虑类型断言。
-- 使用判别式联合表达清晰状态；关键分支需要穷尽性时用 `never` 检查。
-- 新业务代码默认采用 ES Module；`namespace` 与三斜线指令仅用于声明合并或遗留互操作场景。
-- 扩展第三方类型时使用独立声明文件并通过局部 `declare module` 扩展，避免污染全局实现文件。
-- `tsconfig`、package exports、声明文件、路径别名和 public API 类型属于 TypeScript 项目规范深水区，不在本规则内展开。
+- When both literal preservation and structure verification need to be met, use `satisfies` first, and then consider type assertions.
+- Use discriminant unions to express clear states; use `never` checks when exhaustiveness is required for critical branches.
+- New business code uses ES Module by default; `namespace` and triple slash directives are only used to declare merge or legacy interop scenarios.
+- When extending third-party types, use independent declaration files and extend them through local `declare module` to avoid polluting the global implementation file.
+- `tsconfig`, package exports, declaration files, path aliases and public API types belong to the deep water area of TypeScript project specifications and are not expanded within this rule.
 
-## 日志与 `console.log`
+## Logs and `console.log`
 
-- 生产路径避免遗留 `console.log`；使用项目统一的日志方案。
-- 调试日志提交前应删除，或按团队工具链通过 lint / hook / CI 提示。
+- Avoid legacy `console.log` in the production path; use the project's unified logging scheme.
+- Debug logs should be deleted before submission, or prompted by the team toolchain via lint/hook/CI.
 
-## 密钥与敏感配置
+## Keys and sensitive configurations
 
-- **禁止**在源码中硬编码密钥、Token、私钥或真实凭证示例。
-- 必须通过环境变量或构建期注入读取配置，并在缺失时显式失败或提供清晰降级策略。
-- 涉及认证、支付、上传、第三方脚本或敏感数据处理时，结合项目安全规范做专项评审。
+- **Prohibited** Hardcoding keys, tokens, private keys, or real credential examples in source code.
+- Configuration must be read via environment variables or build-time injection, and fail explicitly if missing or provide a clear downgrade strategy.
+- When authentication, payment, uploading, third-party scripts or sensitive data processing are involved, special reviews will be conducted in conjunction with project security specifications.
 
-## 与测试规则的关系
+## Relationship with test rules
 
-类型改动影响 public API、DTO、外部输入收窄或关键业务分支时，应补充 typecheck、类型测试、组件测试或消费方 fixture。关键用户路径的端到端覆盖方式（Playwright、Cypress、Page Object 等）以 `fec-testing.md` 为准；本文件不重复展开 E2E 细则。
+When type changes affect public APIs, DTOs, external input narrowing, or business-critical branches, typechecks, type tests, component tests, or consumer fixtures should be supplemented. The end-to-end coverage method of key user paths (Playwright, Cypress, Page Object, etc.) is subject to `fec-testing.md`; this document does not repeat the E2E details.
 
-## 与 `typescript-reviewer` 子代理
+## With the `typescript-reviewer` subagent
 
-对 **`.ts` / `.tsx` / `.js` / `.jsx`** 进行专项评审（先跑 typecheck / eslint、PR 合并就绪检查、分级结论）时，可委托插件内置的 **`typescript-reviewer`** 子代理；其报告默认写入 `reports/typescript-review-YYYY-MM-DD-HHmmss.md`，规则底线仍以本文件与项目 `CLAUDE.md` 为准。
+When conducting a special review of **`.ts` / `.tsx` / `.js` / `.jsx`** (run typecheck / eslint first, PR merge readiness check, graded conclusion), you can entrust the plug-in's built-in **`typescript-reviewer`** subagent; its report is written by default `reports/typescript-review-YYYY-MM-DD-HHmmss.md`, the bottom line of the rules is still based on this file and the project `CLAUDE.md`.