# 代码规范 (模板)

## 命名规范
- **文件命名**：建议使用 kebab-case（例如：`user-profile.ts`）。
- **类名命名**：建议使用 PascalCase（例如：`UserManager`）。
- **接口命名**：建议使用以 `I` 开头的 PascalCase 或直接 PascalCase（根据团队习惯）。
- **变量与函数**：建议使用 camelCase（例如：`getUserData`）。
- **常量**：建议使用 UPPER_SNAKE_CASE（例如：`MAX_RETRY_COUNT`）。

## 类型安全
- **严禁 `any`**：除非特殊情况，否则禁止使用 `any`，优先使用 `unknown` 或定义具体接口。
- **严格模式**：代码应通过编译器的严格类型检查。
- **类型导入**：优先使用 `import type` 来导入仅作为类型使用的符号。

## 路径别名与模块导入
- **路径别名**：建议配置并使用路径别名以避免深层嵌套的相对路径（如 `../../..`）。
- **常见别名配置**：
    - `@/*` : `src` 目录
    - `@components/*` : UI 组件
    - `@hooks/*` : React Hooks (若使用 React)
    - `@utils/*` : 工具函数
    - `@services/*` : 数据接口服务

## 单元测试
- **测试文件位置**：建议与源文件同级（如 `src/utils/__tests__/`）或在根目录 `tests/` 下。
- **命名规范**：`[filename].test.ts` 或 `[filename].spec.ts`。
- **覆盖率目标**：核心逻辑建议覆盖率达到 [80%+]。

## 编程实践
- **避免魔法值**：使用常量或枚举管理配置和硬编码字符串。
- **单一职责**：函数和类应尽量保持单一职责。
- **错误处理**：统一使用 try-catch 或类似的错误处理机制，避免吞没异常。

## 规模与拆分
- **入口只做编排**：CLI、server、generator 入口负责参数解析和模块组装；领域规则、I/O、状态计算、渲染分别放入独立模块。
- **禁止规则复制**：同一状态判定、解析或校验逻辑只能有一个事实来源，由多个调用方复用。
- **控制文件长度**：手写源文件建议不超过 500 行；超过 800 行时，新增功能前必须先按职责拆分。
- **控制函数长度**：函数建议不超过 60 行；超过 100 行时必须拆出命名明确的子函数或模块。
- **组件化 UI**：页面按数据模型、视图组件、样式和浏览器交互拆分；组件只承担一个可描述的界面职责。
- **结构化目录**：按领域和职责组织文件，`index` 文件只负责导出或组装，不承载大段业务实现。
- **例外**：生成文件、vendor、固定 Schema 或受平台约束的单文件入口可例外，但必须在文件顶部说明原因，且不得继续堆叠无关职责。

## 注释规范
- **文档注释**：公开 API 和复杂逻辑应包含必要的文档注释（如 JSDoc/TSDoc）。
- **代码注释**：注释应解释“为什么”这样做，而不是“在做什么”。