# 命名规范（Vue3 + TypeScript）

本规范参考 Vue 官方风格与 TypeScript 主流实践，目标是统一可读性、可检索性、可维护性。

## 0) 历史代码兼容原则

- 存量代码可暂时保留历史命名，不做一次性全量改名。
- 增量从严：新增文件、目录、类型、变量、函数、组件命名必须符合本规范。
- 改动旧文件时，至少保证“新增/修改行”不引入旧命名反模式。
- 大范围改名需单独评估风险（路由、动态导入、缓存键、埋点字段），建议独立 PR 分批执行。

## 1) 目录与文件命名

- 目录名：`kebab-case`
  - 示例：`src/views/user-center/`
- 页面入口文件：`index.vue`
- 组件文件：`PascalCase.vue`
  - 示例：`UserProfileCard.vue`
- hooks/composable 文件：`useXxx.ts`
  - 示例：`useMediaEpisodePaging.ts`
- 其他 TS 文件：`kebab-case.ts`
  - 示例：`media-content-parser.ts`
- 样式文件：`kebab-case.scss`

## 2) 代码符号命名

- class/type/interface/enum：`PascalCase`
  - 示例：`UserProfileService`、`MediaListItem`、`ApiError`
- 变量/函数/方法：`camelCase`
  - 示例：`fetchMediaList`、`buildRequestParams`
- 常量：`UPPER_SNAKE_CASE`
  - 示例：`DEFAULT_PAGE_SIZE`
- 布尔变量：`is/has/can/should + PascalCase`
  - 示例：`isLoading`、`hasPermission`
- Promise 异步动作：动词开头
  - 示例：`fetchUserInfo`、`loadEpisodeList`

## 3) Vue 约定命名

- 事件处理函数统一 `handleXxx`
  - 示例：`handleSubmit`、`handleEpisodeChange`
- 事件命名（emit）使用 `kebab-case`
  - 示例：`episode-change`、`submit-success`
- props 命名在代码中使用 `camelCase`，模板中可使用 `kebab-case`。
- 计算属性命名以业务语义为主，避免 `data1`、`tempVal` 这类占位名。

## 4) 类型命名细则

- DTO/接口模型建议加语义后缀：
  - 入参：`XxxParams`
  - 返回：`XxxResp` 或 `XxxResponse`
  - 列表项：`XxxItem`
- 错误类型建议统一：`XxxError`
- 避免使用 `IUser` 这类 `I` 前缀接口命名。

## 5) 禁止项

- 禁止拼音命名（业务专有词且已有共识除外）。
- 禁止无语义缩写（如 `tmp`, `obj2`, `aaa`）。
- 禁止单字符业务变量命名（循环计数器 `i/j/k` 除外）。
- 禁止同一模块混用多种命名风格。

## 6) 快速示例

```ts
// good
const DEFAULT_RETRY_COUNT = 2;

interface QueryMediaListParams {
  pageNumber: number;
  pageSize: number;
}

async function fetchMediaList(params: QueryMediaListParams) {
  // ...
}

const isListEmpty = computed(() => state.list.length === 0);
```

```ts
// bad
const retryCountDefault = 2; // 常量未使用 UPPER_SNAKE_CASE
interface IQuery {} // 不建议 I 前缀
async function getdata(d: any) {} // 命名与类型均不规范
const temp = computed(() => state.list.length === 0); // 语义弱
```