fmode-app/rules/13-TypeScript工程基线.md

TypeScript 工程基线

定位:TS 严格模式/类型收窄/枚举/路径别名/ESLint 门禁等工程基线。TS 工程方法论见技能 .claude/skills/dev-expert。

负面清单(Do Not)

• [禁止] 使用 any(用 unknown 收窄或明确类型);确有需要时须说明理由
• [禁止] 深层相对路径引用(超过两层必须用路径别名)
• [禁止] 运行时 enum(用 const 对象 + 联合类型,避免体积与双向映射问题)
• [禁止] 引入 NgRx/Redux 等重型状态库(规模不到不引入)
• [禁止] lint 未通过的代码进入提交

必须规则

1. [必须] 严格模式:tsconfig 开启 strict(含 noImplicitAny、strictNullChecks 等全部严格项);后端同样开启。
2. [必须] 类型命名:接口/类型用 XxxModel/XxxDto/XxxResponse 后缀;泛型参数单大写字母(T/K/V);禁止 I 前缀。
3. [必须] 类型收窄:函数返回联合类型时用类型守卫收窄;禁止 as any 强转绕过类型检查(确需时注释理由)。
4. [必须] 类型集中在 models:数据接口类型集中在 *.model.ts;前后端共享类型走 packages/shared,前端私有类型放 core/models;禁止在组件内定义重复数据结构。
5. [必须] 枚举规范:用 const OBJECT = {...} as const + 联合类型 type X = typeof OBJECT[keyof typeof OBJECT];取值变化时同步登记文档。
6. [必须] 路径别名:统一别名表(@shared/@core/@features/@server 等,以项目 tsconfig/jest 配置为准);引用超过两层相对路径必须改用别名。
7. [必须] ESLint/Prettier 门禁:项目必须配置 ESLint(typescript-eslint + @angular-eslint + rxjs 规则)与 Prettier;配置收敛到 packages/config 共享包,各应用继承;提交前 lint 通过,CI 检查(若配置)。
8. [必须] 状态管理选型:业务状态用 service + signal 即可;禁止引入 NgRx/Redux 等重型状态库(项目规模未达到引入阈值)。
9. [必须] 异步类型安全:Promise/async 返回值显式标注;rxjs 类型完整(操作符与 subscribe 泛型正确)。
10. [必须] 错误类型化:自定义错误类(AppError/ApiError)携带 code/message 类型,禁止 throw '字符串'。

建议规则

• [建议] 工具函数类型完备:shared/utils 下工具函数必须带完整参数与返回类型 + 简短 JSDoc(中文);通用逻辑才入 utils(≥2 处复用)。