create-dwy 0.5.1 → 0.6.0

package/templates/claude-global/rules/dwy-vue-api.md

@@ -0,0 +1,146 @@
+---
+description: Vue 前端网络层(ekit createRequest + 拦截器插件)
+paths:
+  - "**/api/**/*.ts"
+  - "**/api/**/*.vue"
+  - "**/api/client.ts"
+---
+
+# Vue 前端网络层规范
+
+## 六、API 请求规范
+
+### 强制规则
+
+- API 文件按**业务域拆分**（`api/user.ts`、`api/exam.ts`）
+- 每个 API 函数**独立导出**，不使用 default export
+- 请求参数和响应使用**类型标注**
+- **禁止**在组件中直接创建 axios 实例或调用 `fetch`
+
+### API 文件结构
+
+```typescript
+// api/user.ts
+import request from '@/utils/request'
+import type { UserInfo, UserCreate, UserUpdate } from '@/types/user'
+
+export function getUsers(params?: { page?: number; page_size?: number }) {
+  return request.get<{ items: UserInfo[]; total: number }>('/users', { params })
+}
+
+export function getUser(id: number) {
+  return request.get<UserInfo>(`/users/${id}`)
+}
+
+export function createUser(data: UserCreate) {
+  return request.post<UserInfo>('/users', data)
+}
+
+export function updateUser(id: number, data: UserUpdate) {
+  return request.put<UserInfo>(`/users/${id}`, data)
+}
+
+export function deleteUser(id: number) {
+  return request.delete(`/users/${id}`)
+}
+```
+
+### 请求实例配置
+
+```typescript
+// utils/request.ts
+import axios from 'axios'
+
+const request = axios.create({
+  baseURL: '/api',
+  timeout: 30000,
+})
+
+// Token 注入
+request.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token')
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+
+// 401 处理
+request.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      localStorage.removeItem('token')
+      window.location.href = '/login'
+    }
+    return Promise.reject(error)
+  },
+)
+
+export default request
+```
+
+### 禁止的写法
+
+```typescript
+// ❌ 在组件中直接调用
+const res = await axios.get('/api/users')
+
+// ✅ 通过 API 模块调用
+import { getUsers } from '@/api/user'
+const res = await getUsers()
+
+// ❌ API 函数使用 default export
+export default { getUsers, createUser }
+
+// ✅ 每个函数独立导出
+export function getUsers() { ... }
+export function createUser() { ... }
+```
+
+---
+
+## 网络层规范（ekit 统一方案）
+
+### Vue 前端
+
+**唯一方式：** ekit `createRequest()` + 插件。
+
+```typescript
+// api/client.ts
+import { createRequest } from '@dwydev/ekit'
+
+export const request = createRequest({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  plugins: [
+    tokenPlugin(),         // 注入 Authorization header
+    refreshTokenPlugin(),  // 401 自动刷新
+    unwrapPlugin(),        // 解包响应 → data
+  ],
+})
+
+// api/user.ts — 按业务域拆分
+export function getUsers(params: { page: number; page_size: number }) {
+  return request.get('/users', { params })
+}
+
+export function createUser(data: UserCreate) {
+  return request.post('/users', data)
+}
+```
+
+**禁止：** `axios.create()`、`fetch()`、`new XMLHttpRequest()`
+
+### 响应解包
+
+前端的解包逻辑必须与后端 eapi response 格式对齐：
+
+```
+后端返回: { code: "SUCCESS", message: "success", data: {...}, timestamp: ... }
+                                                      ↓ unwrap
+前端拿到: {...}  (直接是 data 的内容)
+```
+
+分页响应解包后拿到 `{ items, total, page, page_size }`（保持 snake_case 对齐后端 JSON）。
+
+业务失败时（`code !== "SUCCESS"`），unwrapPlugin 抛出的 HttpError 携带 `businessCode` 和 `apiResponse`。业务 catch 中用 `isApiBusinessError(err)` 做类型守卫后按 `err.businessCode` 分支（如 `NOT_FOUND` / `VALIDATION_ERROR` / `PERMISSION_DENIED`）；`VALIDATION_ERROR` 场景可用 `extractValidationErrors(err)` 直接给 vee-validate 的 `setErrors` 回填。

package/templates/claude-global/rules/{vue-code-style.md → dwy-vue-core.md}

@@ -1,15 +1,11 @@
 ---
+description: Vue 3 + TS + Vite + Tailwind 基础风格(组件/TS/模板/样式/反模式/错误处理)
 paths:
   - "**/*.vue"
-  - "**/*.ts"
-  - "**/*.tsx"
   - "**/vite.config.*"
-  - "**/tsconfig*.json"
 ---
 
-# Vue 3 + TypeScript + Vite + Pinia 代码规范
-
-所有 Vue / TypeScript 前端项目必须遵循以下规范。AI 生成或修改代码时，必须严格按照这些规则执行。
+# Vue 3 基础风格规范
 
 ## 一、项目结构
 
@@ -36,9 +32,16 @@ frontend/
 │   ├── App.vue             # 根组件
 │   ├── main.ts             # 应用入口
 │   └── style.css           # 全局样式（Tailwind 入口）
+├── tests/                  # 测试文件（独立目录，禁止放在 src/ 内）
+│   ├── utils/              # 对应 src/utils/
+│   ├── stores/             # 对应 src/stores/
+│   ├── api/                # 对应 src/api/
+│   ├── router/             # 对应 src/router/
+│   └── components/         # 对应 src/components/
 ├── index.html
 ├── package.json
 ├── vite.config.ts
+├── vitest.config.ts        # 测试配置（独立文件）
 ├── tsconfig.json
 ├── tsconfig.app.json
 └── .npmrc
@@ -138,6 +141,37 @@ onMounted(() => {
 | 事件处理函数 | `handle` + 动作 | `handleLogin`、`handleDelete` |
 | 布尔变量 | `is/has/can/should` 前缀 | `isLoading`、`hasPermission` |
 
+### 禁止魔法字符串
+
+同一个字符串字面量在文件内出现 2 次及以上时，**必须**提取为常量。
+
+```typescript
+// ❌ 魔法字符串散落多处，改一处漏一处
+storage.set('access_token', token)
+// ...
+const t = storage.get('access_token')
+
+// ✅ 提取为常量
+const ACCESS_TOKEN_KEY = 'access_token'
+storage.set(ACCESS_TOKEN_KEY, token)
+const t = storage.get(ACCESS_TOKEN_KEY)
+
+// ❌ 事件名、路由路径、storage key 等重复字面量
+emit('update:modelValue', value)
+router.push('/dashboard')
+localStorage.getItem('theme')
+
+// ✅ 跨文件共享的 key 放到专门的常量文件
+// constants/storage-keys.ts
+export const STORAGE_KEYS = {
+  ACCESS_TOKEN: 'access_token',
+  REFRESH_TOKEN: 'refresh_token',
+  THEME: 'theme',
+} as const
+```
+
+**判断标准：** 同一字符串在同一文件出现 ≥ 2 次 → 提取为常量。跨文件使用的 key → 提取到 `constants/` 目录共享。
+
 ### 禁止的写法
 
 ```typescript
@@ -229,59 +263,6 @@ interface TableColumn {
 | `Array<string>` | `string[]` |
 | 枚举 `enum Status {}` | 联合类型 `type Status = 'active' \| 'inactive'` |
 
-## 四、Pinia 状态管理
-
-### 强制使用 Setup Store
-
-```typescript
-// ✅ Setup Store（强制）
-export const useAuthStore = defineStore('auth', () => {
-  const token = ref<string | null>(localStorage.getItem('token'))
-  const user = ref<UserInfo | null>(null)
-
-  const isLoggedIn = computed(() => !!token.value)
-
-  async function login(username: string, password: string) {
-    const res = await apiLogin(username, password)
-    token.value = res.data.access_token
-    localStorage.setItem('token', token.value)
-  }
-
-  function logout() {
-    token.value = null
-    user.value = null
-    localStorage.removeItem('token')
-  }
-
-  return { token, user, isLoggedIn, login, logout }
-})
-
-// ❌ Options Store（禁止）
-export const useAuthStore = defineStore('auth', {
-  state: () => ({ token: '' }),
-  actions: { login() {} }
-})
-```
-
-### Store 设计原则
-
-| 原则 | 说明 |
-|------|------|
-| 单一职责 | 一个 store 管理一个业务域（auth、menu、user） |
-| 不直接修改 state | 通过方法修改，不在组件中直接 `store.xxx = yyy` |
-| 异步操作放 store | API 调用封装在 store 方法中 |
-| 解构用 `storeToRefs` | 解构响应式状态必须用 `storeToRefs`，方法直接解构 |
-
-```typescript
-// ✅ 正确解构
-const store = useReportStore()
-const { report, loading } = storeToRefs(store)
-const { setReport, reset } = store
-
-// ❌ 错误解构（丢失响应性）
-const { report, loading } = store
-```
-
 ## 五、路由规范
 
 ### 强制规则
@@ -346,96 +327,6 @@ declare module 'vue-router' {
 }
 ```
 
-## 六、API 请求规范
-
-### 强制规则
-
-- API 文件按**业务域拆分**（`api/user.ts`、`api/exam.ts`）
-- 每个 API 函数**独立导出**，不使用 default export
-- 请求参数和响应使用**类型标注**
-- **禁止**在组件中直接创建 axios 实例或调用 `fetch`
-
-### API 文件结构
-
-```typescript
-// api/user.ts
-import request from '@/utils/request'
-import type { UserInfo, UserCreate, UserUpdate } from '@/types/user'
-
-export function getUsers(params?: { page?: number; page_size?: number }) {
-  return request.get<{ items: UserInfo[]; total: number }>('/users', { params })
-}
-
-export function getUser(id: number) {
-  return request.get<UserInfo>(`/users/${id}`)
-}
-
-export function createUser(data: UserCreate) {
-  return request.post<UserInfo>('/users', data)
-}
-
-export function updateUser(id: number, data: UserUpdate) {
-  return request.put<UserInfo>(`/users/${id}`, data)
-}
-
-export function deleteUser(id: number) {
-  return request.delete(`/users/${id}`)
-}
-```
-
-### 请求实例配置
-
-```typescript
-// utils/request.ts
-import axios from 'axios'
-
-const request = axios.create({
-  baseURL: '/api',
-  timeout: 30000,
-})
-
-// Token 注入
-request.interceptors.request.use((config) => {
-  const token = localStorage.getItem('token')
-  if (token) {
-    config.headers.Authorization = `Bearer ${token}`
-  }
-  return config
-})
-
-// 401 处理
-request.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 401) {
-      localStorage.removeItem('token')
-      window.location.href = '/login'
-    }
-    return Promise.reject(error)
-  },
-)
-
-export default request
-```
-
-### 禁止的写法
-
-```typescript
-// ❌ 在组件中直接调用
-const res = await axios.get('/api/users')
-
-// ✅ 通过 API 模块调用
-import { getUsers } from '@/api/user'
-const res = await getUsers()
-
-// ❌ API 函数使用 default export
-export default { getUsers, createUser }
-
-// ✅ 每个函数独立导出
-export function getUsers() { ... }
-export function createUser() { ... }
-```
-
 ## 七、组合式函数（Composables）
 
 ### 命名规范
@@ -668,8 +559,8 @@ import { useRouter, useRoute } from 'vue-router'
 import { storeToRefs } from 'pinia'
 import axios from 'axios'
 
-// 3. 内部包（@danweiyuan/*）
-import { EButton, EInput } from '@danweiyuan/eui'
+// 3. 内部包（@dwydev/*）
+import { EButton, EInput } from '@dwydev/eui'
 
 // 4. 项目内模块
 import { useAuthStore } from '@/stores/auth'
@@ -693,7 +584,193 @@ import type { UserInfo } from '@/types/user'
 import { UserInfo, getUsers } from '@/api/user'
 ```
 
-## 十三、常见反模式（禁止）
+## 十三、注释规范
+
+### 强制规则
+
+所有 `.ts` 和 `.vue` 文件必须遵循以下注释规则：
+
+1. **文件顶部必须有概述注释** — 说明文件的功能和职责
+2. **所有导出的方法/函数必须有中文注释** — 说明用途、参数、返回值
+3. **所有导出的类必须有中文注释** — 说明类的职责
+4. **所有导出的接口/类型必须有中文注释** — 说明类型含义，每个字段也需注释
+5. **复杂的内部方法必须有中文注释** — 简单的 getter/setter 可省略
+6. **注释使用中文** — 与代码保持一致的语言风格
+
+### 文件顶部注释
+
+```typescript
+/**
+ * 用户认证相关的 API 请求模块
+ * 提供登录、登出、刷新 token、获取用户信息等接口
+ */
+import { request } from '@/utils/request'
+import type { LoginParams, UserInfo } from '@/types/user'
+```
+
+```vue
+<!--
+  用户信息卡片组件
+  展示用户头像、昵称、角色标签，支持点击跳转到用户详情页
+-->
+<script setup lang="ts">
+// ...
+</script>
+```
+
+### 方法/函数注释
+
+```typescript
+/**
+ * 用户登录
+ * @param params 登录参数（用户名、密码）
+ * @returns 登录成功后返回用户信息和 token
+ */
+export async function login(params: LoginParams): Promise<LoginResult> {
+  return request.post('/auth/login', params)
+}
+
+/**
+ * 格式化金额显示
+ * @param value 金额数值（单位：分）
+ * @param currency 货币符号，默认 ¥
+ * @returns 格式化后的金额字符串，如 ¥1,234.56
+ */
+export function formatMoney(value: number, currency = '¥'): string {
+  return `${currency}${(value / 100).toLocaleString()}`
+}
+```
+
+### 类注释
+
+```typescript
+/**
+ * HTTP 请求客户端
+ * 封装 axios，提供拦截器、错误处理、token 自动刷新等能力
+ */
+export class RequestClient {
+  // ...
+}
+```
+
+### 接口/类型注释
+
+```typescript
+/**
+ * 用户基础信息
+ */
+export interface UserInfo {
+  /** 用户 ID */
+  id: number
+  /** 用户名（登录账号） */
+  username: string
+  /** 用户角色：admin=管理员，user=普通用户 */
+  role: 'admin' | 'user'
+  /** 邮箱地址（可选） */
+  email?: string
+}
+
+/**
+ * 分页查询参数
+ */
+export interface PageParams {
+  /** 当前页码，从 1 开始 */
+  page: number
+  /** 每页条数，默认 20 */
+  pageSize: number
+}
+```
+
+### 组件 Props/Emits 注释
+
+```vue
+<script setup lang="ts">
+/**
+ * 数据表格组件的 Props 定义
+ */
+interface Props {
+  /** 表格数据源 */
+  data: Record<string, unknown>[]
+  /** 列配置 */
+  columns: TableColumn[]
+  /** 是否显示加载中 */
+  loading?: boolean
+}
+
+const props = defineProps<Props>()
+
+/**
+ * 组件事件定义
+ */
+const emit = defineEmits<{
+  /** 行点击事件，参数为当前行数据 */
+  rowClick: [row: Record<string, unknown>]
+  /** 选中行变化事件，参数为选中的行数组 */
+  selectionChange: [rows: Record<string, unknown>[]]
+}>()
+</script>
+```
+
+### 组合式函数注释
+
+```typescript
+/**
+ * 列表数据管理 composable
+ * 封装列表加载、刷新、loading 状态
+ * @param fetchFn 数据获取函数
+ * @returns 列表数据、加载状态、刷新方法
+ */
+export function useList<T>(fetchFn: () => Promise<T[]>) {
+  // ...
+}
+```
+
+### 可省略注释的场景
+
+- 一目了然的 getter/setter（如 `get name() { return this._name }`）
+- 测试文件中的 `describe` / `it` 块（用例名本身就是描述）
+- 组件内部的简单辅助函数（< 5 行且逻辑清晰）
+- 私有变量的简单赋值
+
+### 禁止的写法
+
+```typescript
+// ❌ 无文件头注释
+import { ref } from 'vue'
+export function login() { ... }
+
+// ❌ 方法无注释
+export async function deleteUser(id: number) {
+  return request.delete(`/users/${id}`)
+}
+
+// ❌ 接口字段无说明
+export interface UserInfo {
+  id: number
+  username: string
+  role: 'admin' | 'user'
+}
+
+// ❌ 英文注释（与代码风格不一致）
+/** Get user info by id */
+export async function getUser(id: number) { ... }
+
+// ❌ 废话注释（只复述代码，不说明 why）
+/** 设置 count 为 0 */
+count.value = 0
+```
+
+### 注释质量要求
+
+| 要求 | 说明 |
+|------|------|
+| 说明 why 而非 what | 代码已经说明 what，注释要解释为什么这样写 |
+| 语言一致性 | 全部使用中文，不混用中英文 |
+| 描述业务含义 | 避免"获取数据"这种泛泛说法，要写"获取用户列表" |
+| 标注边界条件 | 参数范围、特殊取值、空值处理要说明 |
+| 及时更新 | 代码修改后必须同步更新注释，禁止留下过时注释 |
+
+## 十四、常见反模式（禁止）
 
 | 反模式 | 正确做法 |
 |--------|---------|
@@ -713,6 +790,67 @@ import { UserInfo, getUsers } from '@/api/user'
 | `reactive()` 用于简单值 | `ref()` 用于所有场景 |
 | 解构 store 不用 `storeToRefs` | 响应式值必须用 `storeToRefs` |
 | 手写 CSS 为主 | Tailwind 工具类为主 |
+| 测试文件放在 `src/` 内 | 放在独立 `tests/` 目录 |
+| 测试中用相对路径回溯 `../../src/` | 用 `@` 别名导入 |
+
+## 十五、代码简约原则
+
+### 核心思想
+
+代码只写**必要的逻辑**，不写"以防万一"的冗余代码。信任 TypeScript 类型系统和框架保证，只在系统边界（用户输入、外部 API）做校验。
+
+### 禁止的冗余模式
+
+```typescript
+// ❌ 不必要的 fallback — 类型已保证
+const name = props.title ?? ''       // props.title 声明为 string，不可能是 null
+const items = data.value || []       // ref<Item[]>([]) 初始就是数组
+
+// ✅ 直接使用
+const name = props.title
+const items = data.value
+
+// ❌ 不必要的可选链 — 值一定存在
+const id = user?.id                  // user 来自必传 prop，不可能是 undefined
+
+// ✅ 直接访问
+const id = user.id
+
+// ❌ 不必要的条件渲染守卫
+<div v-if="list">                    // list 是 ref<Item[]>([])，永远为真值
+  <div v-for="item in list" ...>
+
+// ✅ 直接渲染
+<div v-for="item in list" ...>
+
+// ❌ 不必要的空函数 fallback
+const onClick = props.onSubmit ?? (() => {})
+
+// ✅ 条件调用
+props.onSubmit?.()
+
+// ❌ 不必要的 try-catch 吞异常
+try {
+  await api.getUsers()
+} catch {
+  // 空 catch，bug 永远不会被发现
+}
+
+// ✅ 让异常暴露或给用户反馈
+try {
+  await api.getUsers()
+} catch {
+  toast.error('加载失败')
+}
+```
+
+### 判断标准
+
+写每一行防御代码前问自己：**这个情况在当前上下文下真的会发生吗？**
+
+- 如果**会** → 写防御，加注释说明触发条件
+- 如果**不会** → 不写，信任上游保证
+- 如果**不确定** → 查看类型定义和调用链确认，不要"以防万一"
 
 ## 代码自检（写代码时强制执行）
 
@@ -734,5 +872,53 @@ import { UserInfo, getUsers } from '@/api/user'
 | 12 | 无 `v-if` + `v-for` 同元素 | ✓ |
 | 13 | 模板无复杂表达式，已提取为 `computed` | ✓ |
 | 14 | 枚举用联合类型 `type X = 'a' | 'b'`，不用 `enum` | ✓ |
+| 15 | 测试文件在 `tests/` 目录，不在 `src/` 内 | ✓ |
+| 16 | `tsconfig.app.json` 的 include 不包含 `tests/` | ✓ |
+| 17 | 文件顶部有中文概述注释，说明文件职责 | ✓ |
+| 18 | 所有导出的方法/函数有中文注释（含参数、返回值） | ✓ |
+| 19 | 所有导出的类/接口/类型有中文注释，接口字段逐个注释 | ✓ |
+| 20 | Props/Emits 定义有中文注释说明每个字段/事件 | ✓ |
 
 **不执行自检就提交代码 = 违规。**
+
+---
+
+## 错误处理（跨栈约束）
+
+### 前端（Vue）
+
+通过 ekit request 插件统一处理：
+
+```typescript
+// 在 api/client.ts 配置拦截器后，业务代码不需要 try/catch
+// 401 → refreshToken 插件自动刷新，失败则跳登录
+// 422 → unwrap 插件抛出错误，页面级 catch 显示 message
+// 其他错误 → 全局错误提示
+```
+
+**禁止：** 每个 API 调用都包 try/catch，应在页面级或 store 级统一处理。
+
+---
+
+## 环境变量管理
+
+### 前端（Vite）
+
+```bash
+# .env.development
+VITE_API_BASE_URL=http://localhost:8000/api
+
+# .env.production
+VITE_API_BASE_URL=/api
+```
+
+代码中通过 `import.meta.env.VITE_API_BASE_URL` 访问。**只有 `VITE_` 前缀的变量会暴露给客户端。**
+
+### 强制规则
+
+| 规则 | 说明 |
+|------|------|
+| 每个项目必须有 `.env.example` | 列出所有变量名 + 注释说明，值用占位符 |
+| `.env` 文件禁止提交 git | 已在 git-security.md 约束 |
+| 禁止硬编码 | 数据库连接、密钥、API 地址等必须走环境变量 |
+| 禁止运行时读取 `.env` 文件 | 后端用 BaseSettings（启动时加载），前端用 Vite 编译注入 |