@bovinphang/frontend-craft 2.6.0 → 2.8.0

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,355 +1,112 @@
-# TypeScript / JavaScript 规则
+# TypeScript / JavaScript rules
 
-编写、修改或评审 `.ts`、`.tsx`、`.js`、`.jsx` 时应用本文件。注释风格另见 `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 显式、可读、可复用。
-
-### 对外导出的 API
+Use types to make external APIs, shared models, and component props explicit, readable, and reusable.
 
-- 对**导出**的函数、共享工具函数、公开类方法，写明参数与返回值类型。
-- **局部**变量在类型显而易见时交给 TypeScript 推断。
-- 重复出现的内联对象形状抽成具名 `interface` 或 `type`。
+### Externally exported API
 
-```typescript
-// 错误：导出函数缺少显式类型
-export function formatUser(user) {
-  return `${user.firstName} ${user.lastName}`;
-}
-
-// 正确：对外 API 显式标注
-interface User {
-  firstName: string;
-  lastName: string;
-}
+- 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`.
 
-export function formatUser(user: User): string {
-  return `${user.firstName} ${user.lastName}`;
-}
-```
+### `interface` and `type`
 
-### `interface` 与 `type`
+- 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.
 
-- 可能被扩展或 `implements` 的**对象形状**优先用 `interface`。
-- **联合、交叉、元组、映射类型、工具类型组合**用 `type`。
-- 优先**字符串字面量联合**；仅在互操作或团队统一要求时使用 `enum`。
-
-```typescript
-interface User {
-  id: string;
-  email: string;
-}
+### Function parameters: complex types should be named
 
-type UserRole = "admin" | "member";
-type UserWithRole = User & { role: UserRole };
-```
-
-### 函数参数：复杂类型宜具名
-
-- 参数上的**复杂联合**、**内联对象类型**、**较复杂的回调签名**等，应**优先**提取为具名 `type` / `interface`，再在函数签名中引用，便于阅读、复测与重构。
-- **仅当**类型**简单**、**短小**、一眼可读，且**明显无复用**价值时，允许在参数位置内联（如单独的 `string`、`number`、`boolean` 等）。
-
-```typescript
-// 不推荐：联合与可选散落在参数上，语义不突出
-function getUserInfo(id: string | number | undefined) {}
-
-// 推荐：具名类型表达「用户标识」语义，可选更自然
-type UserId = string | number;
-function getUserInfo(id?: UserId) {}
-```
-
-```typescript
-// 不推荐：内联联合对象冗长，难复用、难单测描述
-function send(data: string | { content: string; type: "text" | "html" }) {}
-
-// 推荐：消息载荷单一真源
-type MessagePayload =
-  | string
-  | {
-      content: string;
-      type: "text" | "html";
-    };
-
-function send(data: MessagePayload) {}
-```
-
-### 避免 `any`
-
-- 业务代码中避免 `any`。
-- 外部或不可信数据用 `unknown`，再安全收窄。
-- 类型随调用方变化时用泛型。
-
-```typescript
-// 错误：any 取消类型检查
-function getErrorMessage(error: any) {
-  return error.message;
-}
-
-// 正确：unknown 强制收窄
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return "Unexpected error";
-}
-```
-
-### React 组件 Props
-
-- 用具名 `interface` 或 `type` 定义 props。
-- 回调 props 写清参数与返回值。
-- 无特殊理由不使用 `React.FC`（避免隐式 `children` 等差异）。
-
-```typescript
-interface User {
-  id: string;
-  email: string;
-}
-
-interface UserCardProps {
-  user: User;
-  onSelect: (id: string) => void;
-}
-
-function UserCard({ user, onSelect }: UserCardProps) {
-  return <button onClick={() => onSelect(user.id)}>{user.email}</button>;
-}
-```
-
-## 单文件规模与模块拆分
-
-- `.ts` / `.tsx` / `.js` / `.jsx` 单文件建议控制在 **约 300 行以内**。该阈值是可维护性与评审效率的经验上限，不是机械的硬限制。
-- 当文件明显超过该规模且承担多重职责时，应优先按职责拆分：如数据访问、业务规则、视图渲染、适配层、常量与映射。
-- 超阈值优先提取：纯函数、子组件、自定义 Hook、`*.types.ts` 类型模块、常量表，不要仅为压行数做无意义切分。
-- 可接受例外：生成代码、极薄的 re-export 聚合文件、经团队评审确认的高内聚模块；例外建议在文件头简短注明原因。
-
-### 仍为 JavaScript 的文件
-
-- 在 `.js` / `.jsx` 中，若短期无法迁 TS，可用 **JSDoc** 补类型，并与运行时行为一致。
-
-```javascript
-/**
- * @param {{ firstName: string, lastName: string }} user
- * @returns {string}
- */
-export function formatUser(user) {
-  return `${user.firstName} ${user.lastName}`;
-}
-```
-
-## 禁止 Magic Number / Magic String
-
-- **业务代码中禁止**使用**无语义**的硬编码数字或字符串（如 `1`、`2`、`3`、`"1"`、`"2"`、`"3"`）直接表示**状态、类型、标识或业务含义**（含 `if`/`switch`/赋值与 API 字段映射等）。
-- **固定且有限的取值范围**须在单一真源处定义，并在全仓引用名称，避免裸值散落：
-  - **`enum`**（与后端或协议对齐、或团队明确约定时使用；注意字符串 enum、const enum 与打包/tree-shaking 策略）；
-  - **`as const` 常量对象**（常与 `typeof` / `keyof` 推导联合类型，适合前端主路径）；
-  - **字面量联合类型**（`type Status = "a" | "b"`）并与上面对象或 map 配套，保证调用处可收窄、可重构。
-- **不属本条**的典型例外（仍应保持可读）：纯算法下标、 obvious 的 `0`/`1` 长度判断、与业务无关的 UI 刻度若已有设计 Token 则改走 `fec-design-system.md`。
-
-```typescript
-// 不佳：业务语义依赖裸数字 / 裸字符串
-function label(status: number) {
-  if (status === 1) return "待支付";
-  if (status === 2) return "已支付";
-  return "未知";
-}
-if (user.role === "3") {
-  /* ... */
-}
-
-// 更佳：字面量联合 + as const 常量对象（或团队约定的 enum）
-type OrderStatus = "pending" | "paid" | "cancelled";
-const ORDER_STATUS = {
-  Pending: "pending",
-  Paid: "paid",
-  Cancelled: "cancelled",
-} as const satisfies Record<string, OrderStatus>;
-
-function label(status: OrderStatus) {
-  if (status === ORDER_STATUS.Pending) return "待支付";
-  if (status === ORDER_STATUS.Paid) return "已支付";
-  return "已取消";
-}
-```
-
-## 不可变更新
-
-优先用展开运算符合并新对象，避免直接改写入参。
-
-```typescript
-interface User {
-  id: string;
-  name: string;
-}
-
-// 错误：修改原对象
-function updateUser(user: User, name: string): User {
-  user.name = name;
-  return user;
-}
-
-// 正确：返回新对象
-function updateUser(user: Readonly<User>, name: string): User {
-  return { ...user, name };
-}
-```
-
-## 异步与错误处理
-
-使用 `async/await` 与 `try/catch`，在 `catch` 中将错误视为 `unknown` 再收窄。
-
-```typescript
-interface User {
-  id: string;
-  email: string;
-}
-
-declare function riskyOperation(userId: string): Promise<User>;
-
-function getErrorMessage(error: unknown): string {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return "Unexpected error";
-}
-
-const logger = {
-  error: (message: string, error: unknown) => {
-    // 替换为项目内的日志实现（如 pino、winston 等）
-  },
-};
-
-async function loadUser(userId: string): Promise<User> {
-  try {
-    return await riskyOperation(userId);
-  } catch (error: unknown) {
-    logger.error("Operation failed", error);
-    throw new Error(getErrorMessage(error));
-  }
-}
-```
-
-## 输入校验
-
-对外部输入（表单、API、URL 参数等）宜用 **Zod**（或项目选用的同类库）做模式校验，并用 `z.infer` 推导类型。
-
-```typescript
-import { z } from "zod";
-
-const userSchema = z.object({
-  email: z.string().email(),
-  age: z.number().int().min(0).max(150),
-});
-
-type UserInput = z.infer<typeof userSchema>;
-
-const validated: UserInput = userSchema.parse(input);
-```
-
-## 类型资产分层与命名
-
-- 模块或特性专属类型使用 `*.types.ts`，并与实现文件同目录或同 feature 目录放置，例如 `user.types.ts`、`billing.types.ts`。
-- 全局与环境相关声明放在 `global.d.ts`、`env.d.ts` 或 `types/*.d.ts`，仅用于真全局或 ambient 声明，不将可模块化类型放入全局。
-- 仅用于类型的导入导出优先使用 `import type` 与 `export type`，减少值空间歧义并提升编译语义清晰度。
-- 与 API DTO 同源的类型，放在对应 feature 或 API 子目录的 `*.types.ts`，避免在页面或组件实现内散落大型匿名类型。
-
-```typescript
-// user.types.ts
-export interface UserProfile {
-  id: string;
-  email: string;
-  status: "active" | "disabled";
-}
-
-// user.service.ts
-import type { UserProfile } from "./user.types";
-export type { UserProfile };
-```
-
-## 工程化与惯用法补充
-
-- 使用**判别式联合**配合 `never` 穷尽检查，确保分支新增成员时编译期可发现遗漏。
-- 需要同时满足「字面量保留」与「结构校验」时优先使用 `satisfies`，再考虑类型断言。
-- 优先使用类型收窄（`typeof` / `in` / 自定义 predicate）而非 `as` 强转；`as` 应用于边界互操作而非消错。
-- 对不应被修改的数据优先建模为 `readonly` / `Readonly<T>`，与不可变更新规则协同。
-- 新业务代码默认采用 ES Module；`namespace` 与三斜线指令仅用于声明合并或遗留互操作场景。
-- `index.ts` 聚合导出应保持浅层且按 feature 边界组织，避免深层 barrel 引发循环依赖与不必要的耦合。
-- 扩展第三方类型时使用独立声明文件（如 `types/vendor-foo.d.ts`）并通过 `declare module "pkg"` 局部扩展，避免污染全局实现文件。
-- `tsconfig` 应保持 `strict` 族能力；若为兼容遗留场景需要放宽严格项，必须在评审中明确说明范围、风险与回收计划。
-- 可在消费项目使用 lint（如 `max-lines`）辅助识别超长文件，但规则设计应服务可维护性，而非追求机械达标。
-
-## 日志与 `console.log`
-
-- 生产路径避免遗留 `console.log`；使用项目统一的日志方案。
-- 可在保存后格式化、`tsc` 检查或提交前脚本中对 `console.log` 做提示或拦截（按团队工具链配置）。
-
-## 常见模式
-
-### 统一 API 响应形状（示例）
-
-```typescript
-interface ApiResponse<T> {
-  success: boolean;
-  data?: T;
-  error?: string;
-  meta?: {
-    total: number;
-    page: number;
-    limit: number;
-  };
-}
-```
-
-### 自定义 Hook（示例）
-
-```typescript
-export function useDebounce<T>(value: T, delay: number): T {
-  const [debouncedValue, setDebouncedValue] = useState<T>(value);
-
-  useEffect(() => {
-    const handler = setTimeout(() => setDebouncedValue(value), delay);
-    return () => clearTimeout(handler);
-  }, [value, delay]);
-
-  return debouncedValue;
-}
-```
-
-### 仓储接口（示例）
-
-```typescript
-interface Repository<T> {
-  findAll(filters?: Filters): Promise<T[]>;
-  findById(id: string): Promise<T | null>;
-  create(data: CreateDto): Promise<T>;
-  update(id: string, data: UpdateDto): Promise<T>;
-  delete(id: string): Promise<void>;
-}
-```
+- **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.
 
-## 密钥与敏感配置
+### Avoid `any`
 
-- **禁止**在源码中硬编码密钥、Token、私钥。
-- **必须**通过环境变量或构建期注入（如 `process.env.*`、`import.meta.env.*`，以项目脚手架为准），并在缺失时显式失败或降级策略清晰。
+- 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.
 
-```typescript
-// 错误：硬编码密钥
-const apiKey = "sk-proj-xxxxx";
+### React Component Props
 
-// 正确：环境变量（Node 示例；Vite 等请用 import.meta.env 及 VITE_ 前缀约定）
-const apiKey = process.env.OPENAI_API_KEY;
-if (!apiKey) {
-  throw new Error("OPENAI_API_KEY not configured");
-}
-```
+- 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.
 
-涉及认证、支付、上传等场景时，结合项目安全规范做专项评审。
-
-## 与测试规则的关系
-
-关键用户路径的端到端覆盖方式（Playwright、Cypress、Page Object 等）以 `fec-testing.md` 为准；本文件不重复展开 E2E 细则。
-
-## 与 `typescript-reviewer` 子代理
-
-对 **`.ts` / `.tsx` / `.js` / `.jsx`** 进行专项评审（先跑 typecheck/eslint、PR 合并就绪检查、分级结论）时，可委托插件内置的 **`typescript-reviewer`** 子代理；其报告默认写入 `reports/typescript-review-YYYY-MM-DD-HHmmss.md`，规则底线仍以本文件与项目 `CLAUDE.md` 为准。
+## Single file size and module splitting
+
+- `.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.
+
+### Still a JavaScript file
+
+- 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.
+
+## Disable Magic Number / Magic String
+
+- **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
+
+- 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
+
+- 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
+
+- 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
+
+- 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
+
+- 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.
+
+## Logs and `console.log`
+
+- 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
+
+- **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
+
+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.
+
+## With the `typescript-reviewer` subagent
+
+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`.