@bovinphang/frontend-craft 2.5.0

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

@@ -0,0 +1,355 @@
+# TypeScript / JavaScript 规则
+
+编写、修改或评审 `.ts`、`.tsx`、`.js`、`.jsx` 时应用本文件。注释风格另见 `fec-code-comments.md`；E2E 与校验流程另见 `fec-testing.md`。
+
+## 类型与接口
+
+用类型让对外 API、共享模型与组件 props 显式、可读、可复用。
+
+### 对外导出的 API
+
+- 对**导出**的函数、共享工具函数、公开类方法，写明参数与返回值类型。
+- **局部**变量在类型显而易见时交给 TypeScript 推断。
+- 重复出现的内联对象形状抽成具名 `interface` 或 `type`。
+
+```typescript
+// 错误：导出函数缺少显式类型
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`;
+}
+
+// 正确：对外 API 显式标注
+interface User {
+  firstName: string;
+  lastName: string;
+}
+
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`;
+}
+```
+
+### `interface` 与 `type`
+
+- 可能被扩展或 `implements` 的**对象形状**优先用 `interface`。
+- **联合、交叉、元组、映射类型、工具类型组合**用 `type`。
+- 优先**字符串字面量联合**；仅在互操作或团队统一要求时使用 `enum`。
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+}
+
+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>;
+}
+```
+
+## 密钥与敏感配置
+
+- **禁止**在源码中硬编码密钥、Token、私钥。
+- **必须**通过环境变量或构建期注入（如 `process.env.*`、`import.meta.env.*`，以项目脚手架为准），并在缺失时显式失败或降级策略清晰。
+
+```typescript
+// 错误：硬编码密钥
+const apiKey = "sk-proj-xxxxx";
+
+// 正确：环境变量（Node 示例；Vite 等请用 import.meta.env 及 VITE_ 前缀约定）
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) {
+  throw new Error("OPENAI_API_KEY not configured");
+}
+```
+
+涉及认证、支付、上传等场景时，结合项目安全规范做专项评审。
+
+## 与测试规则的关系
+
+关键用户路径的端到端覆盖方式（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` 为准。

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

@@ -0,0 +1,64 @@
+# Vue 规则
+
+当仓库或目标模块使用 Vue 时，应用本文件。
+
+## 技术栈
+
+<!-- 请根据项目实际情况修改 -->
+
+- 框架: Vue 3 + TypeScript
+- 状态管理: Pinia
+- UI 组件库: 按项目实际选择（如 Element Plus、Naive UI、Vant 或内部 Design System）
+- 版本与依赖：新建模块、补充 `package.json` 或更新本节前，优先采用彼此兼容的主流稳定版本（对齐官方文档、脚手架默认值或包管理器推荐），避免混用已停止维护或与仓库主线 major 不匹配的依赖。
+
+## Vue 组件规范
+
+- 使用 `<script setup lang="ts">`
+- 明确使用 `defineProps` 和 `defineEmits`
+- 保持模板逻辑简单、可读
+- 将可复用逻辑提取到 composables
+- 优先使用 computed，而不是大范围 watcher
+- 保持组件职责聚焦，避免上帝组件
+- props、emits、refs 和 expose 方法尽量使用强类型
+
+## Vue 实现指导
+
+创建新组件前：
+
+1. 先搜索项目中是否已有可复用组件
+2. 判断逻辑是否适合提取到 composable
+3. 检查样式是否应沿用周边现有模式
+
+编辑 Vue 组件时：
+
+- 在可能的情况下，不要把 API 调用直接放进纯展示组件
+- 不要在组件文件中内联大段业务逻辑
+- 不要重复维护可从 props 或 store 推导出的状态
+- 事件 payload 要明确且有类型约束
+
+## Vue 文件组织
+
+优先遵循项目已有约定。
+常见输出可能包括：
+
+- `ComponentName.vue`
+- `types.ts`
+- `useXxx.ts`
+- 只有在符合仓库模式时才新增本地样式文件
+
+## 组件文件规模
+
+- 单个 `.vue` 文件或同一组件模块保持**职责单一**、语义清晰、易于维护。
+- **行数参考**：优先控制在约 **300 行**以内；超过 **500 行**应视为**强烈拆分信号**。
+- **未到 500 行也应拆分**的情形：同时存在**复杂响应式状态**、**过多副作用 / watch**、**模板嵌套过深**、**`<script setup>` 内逻辑过长**、密集条件分支等，应拆为**子组件**、**Composables**、**工具模块**、**常量**与**类型定义**等（与上文「Vue 组件规范」「Vue 文件组织」一致）。
+
+## Vue 反模式
+
+避免：
+
+- 本该使用 computed 却使用大范围 watcher
+- 对 props、emits 或 refs 无理由使用 `any`
+- 模板分支层级过深却不提取
+- 在一个组件中混入无关职责
+- 单 `.vue` **逾 500 行或复杂度已高**仍拒不拆分（参见上文「组件文件规模」）
+- 用大范围全局样式覆盖去解决局部 UI 问题

package/templates/shared/rules/fec-working-modes.md

@@ -0,0 +1,50 @@
+# 工作模式规则
+
+根据任务阶段选择合适的工作模式，避免一边探索一边大改代码。
+
+## 调研模式
+
+适用于需求不清、现状复杂、需要比较方案或定位风险时。
+
+- 先阅读 README、项目规则、相关源码和最近变更。
+- 用 `rg` 查找已有模式、组件、工具函数和测试。
+- 先列发现，再给建议。
+- 在证据不足时不要下确定结论。
+- 涉及版本敏感框架、库或平台行为时，先查项目内事实和官方来源。
+
+## 计划模式
+
+适用于复杂功能、架构调整、跨文件重构和高风险修复。
+
+- 重述目标、成功标准和不做什么。
+- 标出影响范围、文件边界、依赖关系、风险和验证方式。
+- 计划应能分批执行，每批都有可验证结果。
+- 用户未确认前，不执行大范围实现。
+
+## 开发模式
+
+适用于目标明确且已有计划或范围很小的实现。
+
+- 优先复用现有模式。
+- 行为变更优先使用 TDD：先失败测试，再最小实现，再重构。
+- 每次关键修改后运行最近的验证命令。
+- 完成时总结改动、命令和剩余风险。
+- 行为、接口或性能假设必须能被类型、测试、构建、浏览器观察或文档来源支撑。
+
+## 评审模式
+
+适用于 PR、最近变更、合并前检查和专项审查。
+
+- 先通读上下文，再按严重程度列问题。
+- 优先报告会导致 bug、安全风险、回归或维护成本明显上升的问题。
+- 每个问题给出文件位置、影响、建议修复方式和置信度。
+- 无问题时明确说明剩余测试缺口。
+
+## 收尾模式
+
+适用于提交前或交付前。
+
+- 运行 lint、type-check、test、build 中与改动相关的命令。
+- 检查是否有调试代码、临时文件、未同步文档或未说明的风险。
+- 不在未经确认时提交或推送。
+- 不用“应该可以”作为交付依据；交付前报告实际运行过的命令和结果。