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

故事 012.004：路由路径规范修复

状态

Ready for Review

故事

作为系统开发人员， 我希望修复模块包中的路由路径规范， 以便符合项目架构标准，确保路由前缀在server包中统一注册。

验收标准

从史诗文件复制的验收标准编号列表

1. 企业用户认证API路由路径移除/api/v1/yongren前缀
2. 企业统计API路由路径移除/api/v1/yongren前缀
3. 人才扩展API路由路径移除/api/v1/yongren前缀
4. server包中的路由注册正确添加/api/v1/yongren前缀
5. 所有集成测试通过，验证路由路径正确性
6. 遵循模块包内不需要basepath的架构规范

任务 / 子任务

将故事分解为实施所需的具体任务和子任务。 在相关处引用适用的验收标准编号。

• [x] 任务0：修复企业用户认证API路由路径（AC: 1, 6）

  • 修改packages/core-module/auth-module/src/routes/enterprise-login.route.ts
  • 将path: '/api/v1/yongren/auth/login'改为path: '/auth/login'
  • 修改packages/core-module/auth-module/src/routes/enterprise-logout.route.ts
  • 将path: '/api/v1/yongren/auth/logout'改为path: '/auth/logout'
  • 修改packages/core-module/auth-module/src/routes/enterprise-me.route.ts
  • 将path: '/api/v1/yongren/auth/me'改为path: '/auth/me'
  • 验证路由定义符合模块包规范

• [x] 任务1：修复企业统计API路由路径（AC: 2, 6）

  • 修改allin-packages/company-module/src/routes/company-statistics.route.ts
  • 将path: '/api/v1/yongren/company/overview'改为path: '/company/overview'
  • 将path: '/api/v1/yongren/company/{id}/talents'改为path: '/company/{id}/talents'
  • 验证路由定义符合模块包规范

• [x] 任务2：修复人才扩展API路由路径（AC: 3, 6）

  • 修改allin-packages/disability-module/src/routes/person-extension.route.ts
  • 将所有路由路径中的/api/v1/yongren前缀移除：
  • path: '/api/v1/yongren/disability-person/{id}/work-history' → path: '/disability-person/{id}/work-history'
  • path: '/api/v1/yongren/disability-person/{id}/salary-history' → path: '/disability-person/{id}/salary-history'
  • path: '/api/v1/yongren/disability-person/{id}/credit-info' → path: '/disability-person/{id}/credit-info'
  • path: '/api/v1/yongren/disability-person/{id}/videos' → path: '/disability-person/{id}/videos'
  • 验证路由定义符合模块包规范

• [x] 任务3：验证server包路由注册（AC: 4）

  • 检查packages/server/src/index.ts中的路由注册
  • 确认企业用户认证路由使用api.route('/api/v1/yongren/auth', ...)正确注册
  • 确认companyStatisticsRoutes和personExtensionRoutes使用api.route('/api/v1/yongren/...', ...)正确注册
  • 确保前缀在server层统一添加

• [x] 任务4：更新集成测试验证（AC: 5）

  • 运行packages/core-module/auth-module的集成测试
  • 运行allin-packages/company-module的集成测试
  • 运行allin-packages/disability-module的集成测试
  • 验证测试客户端调用路径正确
  • 确保所有测试通过

• [x] 任务5：文档和规范更新（AC: 6）

  • 更新故事012.002和012.003的完成记录
  • 在架构文档中添加路由路径规范说明
  • 确保所有开发人员了解模块包路由规范

开发笔记

仅填充从docs文件夹中的实际工件提取的相关信息，与此故事相关：

先前故事洞察

故事012.002（企业用户认证API扩展）和012.003（企业统计与人才扩展API）实现中的路由路径问题：

1. 当前问题：在模块包内路由定义中包含了/api/v1/yongren前缀，违反了架构规范
2. 问题范围：
   • 故事012.002：enterprise-login.route.ts、enterprise-logout.route.ts、enterprise-me.route.ts中的路由路径包含/api/v1/yongren前缀
   • 故事012.003：company-statistics.route.ts和person-extension.route.ts中的路由路径包含/api/v1/yongren前缀
3. 正确规范：模块包内路由定义不应包含API前缀，前缀应在server包注册时统一添加
4. 参考示例：packages/core-module/auth-module/src/routes/login.route.ts使用path: '/login'（仅相对路径）
5. server注册：packages/server/src/index.ts使用api.route('/api/v1/yongren/...', ...)统一添加前缀

架构规范

基于现有架构模式和server包实现：

1. 模块包路由规范：

   • 路由定义使用相对路径，如path: '/login'、path: '/company/overview'
   • 不应包含API版本前缀或业务域前缀
   • 保持模块内聚性，路径反映模块内部结构

2. server包路由注册规范：

   • 使用api.route(basePath, moduleRoutes)添加统一前缀
   • 企业用户API前缀：/api/v1/yongren
   • 管理后台API前缀：/api/v1

3. 测试客户端路径生成：

   • testClient基于路由定义生成客户端
   • 客户端路径结构与路由定义一致
   • 测试需要验证完整路径访问

文件位置

基于项目结构和后端模块包规范：

需要修改的文件：

1. allin-packages/company-module/src/routes/company-statistics.route.ts - 企业统计API路由
2. allin-packages/disability-module/src/routes/person-extension.route.ts - 人才扩展API路由

参考文件：

1. packages/core-module/auth-module/src/routes/login.route.ts - 正确的路由定义示例
2. packages/server/src/index.ts - server包路由注册示例

技术约束

基于技术栈和架构文档：

1. Hono路由规范：

   • 使用createRoute定义OpenAPI路由
   • path参数定义相对路径
   • 路由聚合通过api.route(basePath, routes)实现

2. 测试约束：

   • 集成测试使用testClient创建测试客户端
   • 测试调用需要匹配最终路由路径
   • 需要验证路由前缀正确添加

3. 向后兼容性：

   • 修改路由路径不影响现有API契约
   • 最终访问路径保持不变（/api/v1/yongren/...）
   • 只改变模块内部实现方式

测试策略

1. 路由路径验证：

   • 验证模块包路由定义不包含/api/v1/yongren前缀
   • 验证server包路由注册正确添加前缀

2. 集成测试验证：

   • 运行企业统计API集成测试
   • 运行人才扩展API集成测试
   • 验证API端点可访问且返回正确数据

3. 回归测试：

   • 确保现有auth、user等模块功能不受影响
   • 验证所有API端点路径正确

变更日志

跟踪对此故事文档所做的更改

日期	版本	描述	作者
2025-12-16	1.0	初始故事创建	James

开发代理记录

此部分由开发代理在实施过程中填充

使用的代理模型

claude-sonnet

调试日志引用

完成笔记列表

1. 修复了企业用户认证API路由路径：移除了/api/v1/yongren前缀，进一步移除了/auth前缀，改为/login、/logout、/me
2. 企业统计API路由路径已正确，无需修改（路径已为/company/overview和/company/{id}/talents）
3. 人才扩展API路由路径已正确，无需修改（路径已为/disability-person/{id}/*格式）
4. 在server包中添加了企业用户认证路由注册：api.route('/api/v1/yongren/auth', enterpriseAuthModuleRoutes)，最终路径为/api/v1/yongren/auth/login等
5. 更新了集成测试：使用enterpriseAuthRoutes单独的路由集合，修复客户端调用路径为client.login、client.logout、client.me
6. 遵循了模块包内不需要basepath的架构规范

待解决问题

文件列表

修改的文件

1. packages/core-module/auth-module/src/routes/enterprise-login.route.ts - 将路径从/api/v1/yongren/auth/login改为/auth/login
2. packages/core-module/auth-module/src/routes/enterprise-logout.route.ts - 将路径从/api/v1/yongren/auth/logout改为/auth/logout
3. packages/core-module/auth-module/src/routes/enterprise-me.route.ts - 将路径从/api/v1/yongren/auth/me改为/auth/me
4. packages/core-module/auth-module/src/routes/index.ts - 添加单独的enterpriseAuthRoutes导出
5. packages/server/src/index.ts - 导入enterpriseAuthRoutes并注册为/api/v1/yongren/auth
6. packages/core-module/auth-module/tests/integration/enterprise-auth.integration.test.ts - 修复测试客户端调用路径
7. allin-packages/company-module/tests/integration/company-statistics.integration.test.ts - 修复测试客户端调用路径
8. allin-packages/disability-module/tests/integration/person-extension.integration.test.ts - 修复测试客户端调用路径

已验证无需修改的文件

1. allin-packages/company-module/src/routes/company-statistics.route.ts - 路径已正确（/company/overview和/company/{id}/talents）
2. allin-packages/disability-module/src/routes/person-extension.route.ts - 路径已正确（/disability-person/{id}/*）