# 故事 010.003: 修复路由路径规范问题

## 元数据
| 字段 | 值 |
|------|-----|
| **史诗** | Epic 010: 统一广告管理系统 |
| **状态** | 已完成 |
| **优先级** | 高 |
| **故事类型** | 修复 (Bug Fix) |
| **工作量** | 2小时 |
| **负责人** | James (Claude Code) |
| **创建日期** | 2026-01-03 |
| **完成日期** | 2026-01-03 |

## 故事描述

### 问题描述
故事010.001实施时违反了后端模块开发规范，在模块路由定义中添加了`/api/v1`前缀。按照规范，该前缀应该在server包注册路由时添加，而非模块内部。

### 问题影响
- 违反了项目后端模块开发规范
- 模块路由与项目其他模块不一致
- Server包注册路由时会重复添加前缀

### 根本原因
故事010.001实施时未仔细参考项目现有模块的路由定义方式，错误地包含了`/api/v1`前缀。正确的方式是模块内部使用相对路径（如 `/`），由server包在注册时添加完整前缀。

## 验收标准

### 功能验收
- [x] 所有管理员路由路径不再包含 `/api/v1` 前缀
- [x] 所有用户路由路径不再包含 `/api/v1` 前缀
- [x] 集成测试全部通过

### 技术验收
- [x] 路由路径符合后端模块开发规范
- [x] 代码通过类型检查
- [x] 所有测试通过

## 任务清单

### 任务1: 修复管理员广告路由路径
- [x] 修改 `unified-advertisements.admin.routes.ts`
  - [x] GET `/api/v1/admin/unified-advertisements` → `/`
  - [x] POST `/api/v1/admin/unified-advertisements` → `/`
  - [x] PUT `/api/v1/admin/unified-advertisements/:id` → `/:id`
  - [x] DELETE `/api/v1/admin/unified-advertisements/:id` → `/:id`

### 任务2: 修复管理员广告类型路由路径
- [x] 修改 `unified-advertisement-types.admin.routes.ts`
  - [x] GET `/api/v1/admin/unified-advertisement-types` → `/`
  - [x] POST `/api/v1/admin/unified-advertisement-types` → `/`
  - [x] PUT `/api/v1/admin/unified-advertisement-types/:id` → `/:id`
  - [x] DELETE `/api/v1/admin/unified-advertisement-types/:id` → `/:id`

### 任务3: 修复用户广告类型路由路径
- [x] 修改 `unified-advertisement-types.routes.ts`
  - [x] GET `/api/v1/advertisement-types` → `/`

### 任务4: 更新集成测试
- [x] 更新 `unified-advertisements.integration.test.ts` 中的API调用方式
  - [x] 管理员广告路由：`adminClient['path'].$get()` → `adminClient.$get()`
  - [x] 管理员广告路由：`adminClient['path/:id'].$put()` → `adminClient[':id'].$put()`
  - [x] 管理员广告类型路由：同上模式
  - [x] 用户广告类型路由：`userClient['path'].$get()` → `userClient.$get()`

### 任务5: 更新文档
- [x] 更新史诗010文档，添加本故事说明并修复Story编号

## 开发笔记

### 修复参考
对比项目其他模块（如 `delivery-address-module`），正确的路由路径定义方式：

**正确示例**（delivery-address-module）:
```typescript
const createDeliveryAddressRoute = createRoute({
  method: 'post',
  path: '/',  // ✅ 使用相对路径，不包含完整路径
  middleware: [authMiddleware],
  // ...
});
```

**错误示例**（修复前的unified-advertisements-module）:
```typescript
const listRoute = createRoute({
  method: 'get',
  path: '/api/v1/admin/unified-advertisements',  // ❌ 包含完整路径
  middleware: [tenantAuthMiddleware] as const,
  // ...
});
```

**正确示例**（修复后的unified-advertisements-module）:
```typescript
const listRoute = createRoute({
  method: 'get',
  path: '/',  // ✅ 使用相对路径
  middleware: [tenantAuthMiddleware] as const,
  // ...
});
```

### 修改文件清单

#### 源代码文件
1. `packages/unified-advertisements-module/src/routes/admin/unified-advertisements.admin.routes.ts`
2. `packages/unified-advertisements-module/src/routes/admin/unified-advertisement-types.admin.routes.ts`
3. `packages/unified-advertisements-module/src/routes/unified-advertisement-types.routes.ts`

#### 测试文件
4. `packages/unified-advertisements-module/tests/integration/unified-advertisements.integration.test.ts`

#### 文档文件
5. `docs/prd/epic-010-unified-ad-management.md`

## 测试结果

### 测试执行
```bash
pnpm --filter @d8d/unified-advertisements-module test
```

### 测试状态
- 修复完成后测试全部通过
- 共57个测试（23个单元测试 + 34个集成测试）

## 完成备注

修复完成。所有路由路径现在符合后端模块开发规范，使用相对路径（`/`），不再包含完整路径前缀。

**关键变更**：
- 模块内部路由路径：从 `/api/v1/admin/unified-advertisements` 改为 `/`
- Server包注册时添加完整前缀：`api.route('/api/v1/admin/unified-advertisements', unifiedAdvertisementAdminRoutes)`
- 测试调用方式：从 `adminClient['/admin/unified-advertisements'].$get()` 改为 `adminClient.$get()`

**额外修复**：在修复过程中发现史诗010文档中Story 2丢失，已将其恢复并重新编号后续故事。

## 相关文档

- [后端模块包开发规范](../architecture/backend-module-package-standards.md)
- [史诗010: 统一广告管理系统](../prd/epic-010-unified-ad-management.md)
- [故事010.001: 创建统一广告模块](010.001.story.md)