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

Story 5.1: 基础数据管理和实体结构

Status

Draft

Story

As a 系统管理员 I want 能够配置活动、路线等基础数据 so that 用户能够查询和使用出行服务

Acceptance Criteria

1. 支持创建和管理活动类型（去程活动、返程活动）
2. 支持配置路线信息（出发地、目的地、上车点、下车点、出发时间、车型、价格、座位数）
3. 支持设置活动关联的路线
4. 支持启用/禁用活动、路线

Tasks / Subtasks

• 创建基础数据实体 (AC: 1, 2, 3)
  • 在 src/server/modules/routes/ 创建 route.entity.ts
  • 在 src/server/modules/activities/ 创建 activity.entity.ts
  • 在 src/share/ 创建相关类型定义
• 创建Zod Schema (AC: 1, 2, 3, 4)
  • 在 src/server/modules/routes/ 创建 route.schema.ts (创建、更新、获取、列表Schema)
  • 在 src/server/modules/activities/ 创建 activity.schema.ts (创建、更新、获取、列表Schema)
  • 验证Schema符合业务逻辑约束
• 数据库迁移和种子数据 (AC: 1, 2, 3, 4)
  • 创建数据库迁移文件，添加活动、路线相关表结构
  • 创建种子数据，添加示例活动和路线数据
  • 验证数据库迁移和种子数据正确性
• 实现管理后台API (AC: 1, 2, 3, 4)
  • 在 src/server/api/admin/activities/index.ts 使用 createCrudRoutes 创建活动管理API
  • 在 src/server/api/admin/routes/index.ts 使用 createCrudRoutes 创建路线管理API
  • 配置搜索字段、关联关系、筛选条件
  • 实现启用/禁用功能
• 实现管理后台页面 (AC: 1, 2, 3, 4)
  • 创建活动管理页面 - 活动类型配置和管理
  • 创建路线管理页面 - 路线信息配置和管理
• 编写测试 (AC: 1, 2, 3, 4)
  • 为实体编写单元测试 (tests/unit/server/)
  • 为数据库迁移编写集成测试 (tests/integration/server/)
  • 为管理后台API编写集成测试 (tests/integration/server/)

Dev Notes

数据模型设计

基于 [docs/prd/epic-005-travel-service-core.md#后端数据模型] 和 [docs/architecture/data-model-schema-changes.md]，需要实现以下实体：

Route实体 (遵循 通用CRUD实体设计规范):

• 包含上车点、下车点、出发时间、车型、价格、座位数等字段
• 关联活动实体
• 支持状态管理（启用/禁用）
• 包含 createdAt 和 updatedAt 时间戳
• 使用TypeORM装饰器定义字段

Activity实体 (遵循 通用CRUD实体设计规范):

• 包含活动名称、描述、类型（去程/返程）、开始日期、结束日期等字段
• 关联路线实体
• 支持状态管理（启用/禁用）
• 包含 createdAt 和 updatedAt 时间戳
• 使用TypeORM装饰器定义字段

数据库迁移要求

• 创建 routes 表，包含必要的字段和索引
• 创建 activities 表，包含必要的字段和索引
• 创建关联关系表（如需要）
• 添加适当的约束和索引优化查询性能

管理后台API设计

基于 [docs/prd/epic-005-travel-service-core.md#管理后台API]，使用 通用CRUD规范 实现以下API端点：

活动管理API (使用 createCrudRoutes):

• GET /api/v1/admin/activities - 活动管理列表（支持分页、搜索、筛选）
• GET /api/v1/admin/activities/:id - 活动详情
• POST /api/v1/admin/activities - 创建活动
• PUT /api/v1/admin/activities/:id - 更新活动
• DELETE /api/v1/admin/activities/:id - 删除活动

活动管理API配置:

• 搜索字段: ['name', 'description']
• 关联关系: ['routes']
• 筛选字段: type (活动类型)
• 中间件: [authMiddleware]
• Zod Schema: 创建、更新、获取、列表Schema

路线管理API (使用 createCrudRoutes):

• GET /api/v1/admin/routes - 路线管理列表（支持分页、搜索、筛选）
• GET /api/v1/admin/routes/:id - 路线详情
• POST /api/v1/admin/routes - 创建路线
• PUT /api/v1/admin/routes/:id - 更新路线
• DELETE /api/v1/admin/routes/:id - 删除路线

路线管理API配置:

• 搜索字段: ['startPoint', 'endPoint', 'vehicleType']
• 关联关系: ['activity']
• 筛选字段: vehicleType, price (范围查询)
• 排序字段: price, departureTime
• 中间件: [authMiddleware]
• Zod Schema: 创建、更新、获取、列表Schema

管理后台页面设计

基于 [docs/prd/epic-005-travel-service-core.md#管理后台页面任务]，需要实现以下页面：

活动管理页面:

• 活动类型配置和管理
• 支持创建、编辑、删除活动
• 支持启用/禁用活动
• 支持设置活动关联的路线
• 遵循 管理后台页面结构标准
• 使用 数据表格规范 显示活动列表
• 实现 搜索和筛选功能
• 使用 表单处理规范 处理活动创建和编辑

路线管理页面:

• 路线信息配置和管理
• 支持创建、编辑、删除路线
• 支持启用/禁用路线
• 配置出发地、目的地、上车点、下车点、出发时间、车型、价格、座位数
• 遵循 管理后台页面结构标准
• 使用 数据表格规范 显示路线列表
• 实现 搜索和筛选功能
• 使用 表单处理规范 处理路线创建和编辑

种子数据要求

• 创建示例活动数据：至少包含去程活动和返程活动各3个
• 创建示例路线数据：关联到相应的活动
• 确保数据符合业务逻辑约束

文件位置

• 后端实体:
  • src/server/modules/routes/route.entity.ts
  • src/server/modules/activities/activity.entity.ts
• Zod Schema (遵循 Schema设计规范):
  • src/server/modules/routes/route.schema.ts
  • src/server/modules/activities/activity.schema.ts
• 共享类型:
  • src/share/route.types.ts
  • src/share/activity.types.ts
• 管理后台API (使用 createCrudRoutes):
  • src/server/api/admin/activities/index.ts
  • src/server/api/admin/routes/index.ts
• 管理后台页面 (遵循 文件组织规范):
  • mini/src/pages/admin/activities/ActivityManagementPage.tsx
  • mini/src/pages/admin/routes/RouteManagementPage.tsx
• 数据库迁移: src/server/migrations/ 目录
• 种子数据: src/server/seeds/ 目录

技术栈要求

• 后端框架: Hono + TypeORM
• 数据库: PostgreSQL 17
• 迁移工具: TypeORM Migration
• 管理后台前端: 遵循 管理后台开发规范

开发规范要求

• 实体定义: 遵循TypeORM实体规范
• 类型定义: 使用TypeScript严格类型
• 数据库约束: 添加适当的数据库级约束
• 索引优化: 为常用查询字段添加索引
• 管理后台开发: 严格遵循 管理后台开发规范
• API开发: 严格遵循 通用CRUD规范

测试要求

• 实体测试: 验证实体字段定义和关联关系
• 数据库测试: 验证迁移和种子数据正确性
• 约束测试: 验证数据库约束有效性
• API测试 (遵循 通用CRUD测试要求):
  • 验证CRUD操作的正确性
  • 测试搜索、筛选、排序功能
  • 验证关联关系查询
• 管理后台页面测试 (遵循 测试规范):
  • 组件测试：验证页面渲染和交互
  • E2E测试：验证完整的管理流程

Change Log

Date	Version	Description	Author
2025-10-16	1.4	添加通用CRUD规范引用，完善API实现细节	Bob (Scrum Master)
2025-10-16	1.3	添加管理后台开发规范引用，确保符合标准	Bob (Scrum Master)
2025-10-16	1.2	修正故事，移除班次实体，与epic005和数据模型保持一致	Bob (Scrum Master)
2025-10-16	1.1	修正故事，添加管理后台功能，完全满足epic005 US005-01需求	Bob (Scrum Master)
2025-10-16	1.0	初始故事创建，从005.002迁移基础数据实体任务	Bob (Scrum Master)

Dev Agent Record

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

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results

此部分由QA代理在审查完成后填写