diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 88fb8ae..a199693 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -135,8 +135,8 @@ reading-platform-frontend/ │ ├── App.vue # 根组件 │ ├── api/ # API 接口 │ │ ├── generated/ # Orval 自动生成(禁止手改) -│ │ ├── client.ts # 统一入口 -│ │ └── *.ts # 业务适配层 +│ │ ├── index.ts # 统一入口,导出 http 方法 +│ │ └── *.ts # 业务适配层(admin.ts, school.ts, teacher.ts 等) │ ├── assets/ # 静态资源 │ ├── components/ # 公共组件 │ ├── composables/ # 组合式函数 @@ -174,9 +174,16 @@ reading-platform-frontend/ ### Controller 层规范 +**API 路径约定**: +- 超管端:`/api/v1/admin/*` +- 学校端:`/api/school/*` +- 教师端:`/api/teacher/*` +- 家长端:`/api/parent/*` +- 认证:`/api/auth/*` + ```java @RestController -@RequestMapping("/api/v1/xxx") +@RequestMapping("/api/v1/admin/xxx") // 超管端使用 /api/v1/admin/ @Tag(name = "XXX管理", description = "XXX相关接口") @RequiredArgsConstructor public class XxxController { @@ -228,23 +235,64 @@ public interface XxxMapper extends BaseMapper { ## 前端开发规范 -### API 开发规范(Orval) +### API 开发规范 1. **生成代码只读** - 不得在 `src/api/generated/` 内做任何手工修改 2. **以生成类型为准** - 参数/返回类型优先使用生成的类型 -3. **统一调用入口** - 通过 `src/api/client.ts` 访问 +3. **统一调用入口** - 通过 `src/api/index.ts` 导出的 `http` 方法 ### 推荐调用方式 +**方式一:使用 http 方法(推荐)** + ```typescript -import { readingApi } from '@/api/client'; +import { http } from '@/api'; async function loadTenant(id: number) { - const res = await readingApi.getTenant({ id }); - return res.data; + return http.get(`/v1/admin/tenants/${id}`); +} + +async function createTenant(data: CreateTenantDto) { + return http.post('/v1/admin/tenants', data); } ``` +**方式二:使用业务适配层(推荐)** + +```typescript +import { getTenant, createTenant } from '@/api/admin'; + +async function loadTenant(id: number) { + return getTenant(id); +} + +async function createNewTenant(data: CreateTenantDto) { + return createTenant(data); +} +``` + +**方式三:使用 Orval 生成的客户端(可选)** + +```typescript +import { getReadingPlatformAPI } from '@/api/generated'; + +const api = getReadingPlatformAPI(); + +async function loadTenant(id: number) { + return api.getTenant({ id }); +} +``` + +### API 路径规范 + +| 端 | 后端路径 | 前端路径 | +|----|----------|----------| +| 超管 | `/api/v1/admin/*` | `/v1/admin/*` | +| 学校 | `/api/school/*` | `/school/*` | +| 教师 | `/api/teacher/*` | `/teacher/*` | +| 家长 | `/api/parent/*` | `/parent/*` | +| 认证 | `/api/auth/*` | `/auth/*` | + ### Vue SFC 约定 - 优先使用 `