mini-starter/docs/stories/010.003.story.md

故事 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包在注册时添加完整前缀。

验收标准

功能验收

• 所有管理员路由路径不再包含 /api/v1 前缀
• 所有用户路由路径不再包含 /api/v1 前缀
• 集成测试全部通过

技术验收

• 路由路径符合后端模块开发规范
• 代码通过类型检查
• 所有测试通过

任务清单

任务1: 修复管理员广告路由路径

• 修改 unified-advertisements.admin.routes.ts
  • GET /api/v1/admin/unified-advertisements → /
  • POST /api/v1/admin/unified-advertisements → /
  • PUT /api/v1/admin/unified-advertisements/:id → /:id
  • DELETE /api/v1/admin/unified-advertisements/:id → /:id

任务2: 修复管理员广告类型路由路径

• 修改 unified-advertisement-types.admin.routes.ts
  • GET /api/v1/admin/unified-advertisement-types → /
  • POST /api/v1/admin/unified-advertisement-types → /
  • PUT /api/v1/admin/unified-advertisement-types/:id → /:id
  • DELETE /api/v1/admin/unified-advertisement-types/:id → /:id

任务3: 修复用户广告类型路由路径

• 修改 unified-advertisement-types.routes.ts
  • GET /api/v1/advertisement-types → /

任务4: 更新集成测试

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

任务5: 更新文档

• 更新史诗010文档，添加本故事说明并修复Story编号

开发笔记

修复参考

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

正确示例（delivery-address-module）:

const createDeliveryAddressRoute = createRoute({
  method: 'post',
  path: '/',  // ✅ 使用相对路径，不包含完整路径
  middleware: [authMiddleware],
  // ...
});

错误示例（修复前的unified-advertisements-module）:

const listRoute = createRoute({
  method: 'get',
  path: '/api/v1/admin/unified-advertisements',  // ❌ 包含完整路径
  middleware: [tenantAuthMiddleware] as const,
  // ...
});

正确示例（修复后的unified-advertisements-module）:

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

测试文件

1. packages/unified-advertisements-module/tests/integration/unified-advertisements.integration.test.ts

文档文件

1. docs/prd/epic-010-unified-ad-management.md

测试结果

测试执行

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丢失，已将其恢复并重新编号后续故事。

相关文档

• 后端模块包开发规范
• 史诗010: 统一广告管理系统
• 故事010.001: 创建统一广告模块