From 7254d8f9bd910ce0eed87016d389e353a933f13a Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Sun, 6 Jul 2025 02:39:04 +0800
Subject: [PATCH] =?UTF-8?q?docs(claude):=20=E6=9B=B4=E6=96=B0=E9=A1=B9?=
 =?UTF-8?q?=E7=9B=AE=E5=BC=80=E5=8F=91=E6=8C=87=E5=8D=97=E5=92=8CAPI?=
 =?UTF-8?q?=E7=BB=84=E7=BB=87=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 新增API文件组织规范
  - 强制按功能模块组织API文件
  - 禁止聚合导出，明确导入路径
  - 统一类型定义组织原则
* 更新开发注意事项
  - 完善消息提示规范
  - 明确禁止事项和最佳实践
* 新增常用命令说明
  - 开发、构建、检查命令
  - 项目架构核心说明

提升开发规范性和团队协作效率
---
 CLAUDE.md | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 53db180..7e09b83 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -263,6 +263,139 @@ coiMsgBox('确定要删除吗？', '删除确认').then(() => {
 2. 使用项目封装的alova实例
 3. 遵循统一的响应处理格式
 
+## 📁 API文件组织规范（强制要求）
+
+**API文件必须按功能模块组织，严格按模块导入，严禁聚合导出或混合不同业务模块的API**
+
+### 文件结构规范
+```
+src/service/api/
+├── auth/                 # 认证相关API
+│   └── index.ts         # 登录、注册、验证码等认证API
+├── system/              # 系统管理模块
+│   ├── user/index.ts    # 用户管理API
+│   ├── role/index.ts    # 角色管理API
+│   ├── menu/index.ts    # 菜单管理API
+│   └── ...
+└── ...
+```
+
+### API模块创建规则
+1. **模块化原则**: 每个业务功能模块必须创建独立的目录和文件
+2. **统一导出**: 每个模块目录必须有 `index.ts` 文件导出所有API
+3. **直接导入**: 必须从具体的模块路径导入API，禁止聚合导出
+4. **明确导入**: 导入路径必须明确指向具体的功能模块
+
+### 示例：正确的API组织和导入方式
+```typescript
+// src/service/api/auth/index.ts
+// 页面中的正确导入方式
+import {
+  fetchCaptchaPng,
+  fetchLogin,
+  fetchLogout
+} from '@/service/api/auth'
+
+import {
+  addUser,
+  getUserList,
+  updateUser
+} from '@/service/api/system/user'
+
+import {
+  assignUserRole,
+  getRoleList
+} from '@/service/api/system/role'
+
+import {
+  fetchUserRoutes
+} from '@/service/api/system/menu'
+
+export function fetchLogin(data: LoginRequest) { /* ... */ }
+export function fetchLogout() { /* ... */ }
+export function fetchCaptchaPng() { /* ... */ }
+
+// src/service/api/system/user/index.ts
+export interface UserQueryBo { /* ... */ }
+export interface UserVo { /* ... */ }
+export function getUserList(params: UserQueryBo) { /* ... */ }
+export function addUser(data: UserVo) { /* ... */ }
+```
+
+### 强制要求
+- ✅ 每个API模块独立维护和导入
+- ✅ 导入路径指向具体功能模块
+- ✅ 按功能拆分API到不同模块目录
+- ✅ 类型定义与API函数放在同一模块目录下
+
+### 严格禁止行为
+- ❌ 创建 `system.ts` 等聚合导出文件
+- ❌ 在单一文件中混合多个业务模块的API
+- ❌ 从聚合文件导入API (如 `from '@/service/api/system'`)
+- ❌ 创建功能不明确的API文件
+- ❌ 在页面组件中重复定义类型，应从API模块导入
+
+## 📝 类型定义组织规范（强制要求）
+
+**类型定义必须与API模块对应，按功能模块组织，禁止在页面组件中重复定义类型**
+
+### 类型文件组织原则
+1. **就近原则**: 类型定义与使用它们的API函数在同一模块
+2. **单一职责**: 每个types.ts文件只包含一个业务模块的类型
+3. **统一导出**: API模块的index.ts必须重新导出types.ts中的类型
+4. **禁止重复**: 页面组件不得重复定义已有类型
+
+### 正确的类型组织示例
+```typescript
+// src/service/api/system/user/types.ts
+// src/service/api/system/user/index.ts
+import type { UserQueryBo, UserSearchForm, UserVo } from './types'
+
+// 页面组件中的正确使用方式
+import {
+  getUserList
+
+} from '@/service/api/system/user'
+import type { UserSearchForm, UserVo } from '@/service/api/system/user'
+
+export interface UserVo {
+  userId: number
+  loginName: string
+  userName: string
+  // ...其他字段
+}
+
+export interface UserQueryBo {
+  pageNo?: number
+  pageSize?: number
+  loginName?: string
+  // ...其他查询条件
+}
+
+export interface UserSearchForm {
+  loginName?: string
+  userName?: string
+  timeRange?: [number, number] | null
+  // ...其他搜索字段
+}
+
+// 重新导出类型供外部使用
+export type { UserQueryBo, UserSearchForm, UserVo } from './types'
+
+// API函数定义
+export function getUserList(params: UserQueryBo) { /* ... */ }
+
+// 使用统一类型，不重复定义
+const tableData = ref<UserVo[]>([])
+const searchForm = ref<UserSearchForm>({})
+```
+
+### 类型命名规范
+- **请求参数类型**: `实体名QueryBo`, `实体名CreateBo`, `实体名UpdateBo`
+- **响应数据类型**: `实体名Vo`
+- **分页结果类型**: `Page实体名Vo`
+- **表单类型**: `实体名SearchForm`, `实体名Form`
+
 ### 状态管理
 1. 新增状态优先考虑使用现有store
 2. 需要持久化的状态使用pinia-plugin-persist