---
name: code-ts
description: Vue 3 + TypeScript 命名、导入顺序、显式 import 与目录组织。编写或修改 .ts/.js 代码、新增 composable 或工具函数时加载本技能。
---

# TypeScript 规范（Vue 3 + Naive UI）

Vue SFC 见 [code-vue](../code-vue/SKILL.md)，样式见 [code-css](../code-css/SKILL.md)。

## 命名

- 组件文件：**PascalCase**（`AppIcon.vue`、`AuditDetailDrawer.vue`）；工具/接口模块：**kebab-case 或小写**（`export-task.ts`、`acting-tenant.ts`）。
- 变量 / 函数：**camelCase**；事件处理用 `handle` 前缀；Composables 用 `use` 前缀。
- 常量：`UPPER_SNAKE_CASE`（如 `TENANT_STATUS`）；展示映射放在 `src/apis/xt/<域>.ts` 里与接口同处。
- 样式 class：kebab-case（见 [code-css](../code-css/SKILL.md)）。

## TypeScript

- `import type { ... }` 与值导入**分开写**（ESLint `@antfu` 会强制）。
- 对象结构优先 `interface`；联合/工具类型用 `type`。
- Props 默认值：`withDefaults(defineProps<Type>(), { ... })`；避免 `any`。
- **接口出入参类型直接复用 `src/apis/xt/` 里的契约类型**，不要手写一份字段。

## 导入顺序（ESLint 会排）

1. 类型导入（`import type`） → 2. 第三方（`vue` / `naive-ui` / `axios`） → 3. 项目内部（`@/apis`、`@/stores`、`@/utils`、`@/icons`、`@/composables`）

⚠️ **本仓库没有 auto-import**：naive-ui 组件、Vue API（`ref`/`computed`/`h`…）、工具函数**必须显式 import**。
不要写"为已自动导入的 API 写冗余 import"这类旧规范 —— 那是上一版（Gi 模板）的约定，现在写了才不报错。

## 常用内部模块

| 模块 | 用途 |
|---|---|
| `@/utils/http.ts` | axios 实例：成功直接 resolve `data`、失败弹提示、带 `Authorization` 与 `X-Tenant-Id` |
| `@/utils/naive.ts` | 全局 `message`（在组件外用，如 http 拦截器） |
| `@/utils/tag.ts` | `tagOf()`：状态色词 → `n-tag` 的 `type`（**必须过这一层**） |
| `@/utils/format.ts` | `fmtDate` 等格式化 |
| `@/composables/pagination.ts` | `listPagination()`：列表页分页器统一参数 |
| `@/stores/user.ts` | `useUserStore()`：`has('码')` / `hasAny(...)` / `menus` / `isPlatform` |
| `@/stores/acting-tenant.ts` | 平台运营的「当前学校」（请求头 `X-Tenant-Id`） |