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

Status

Approve

Story

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

Acceptance Criteria

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

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)
- 管理后台API集成测试 (tests/integration/server/)
- 活动管理API CRUD操作测试 (P0)
- 路线管理API CRUD操作测试 (P0)
- 搜索和筛选功能测试 (P1)
- 启用/禁用功能测试 (P0)
- 活动路线关联测试 (P1)
- 管理后台页面组件测试 (tests/integration/client/)
- ActivityManagementPage组件测试 (P1)
- RouteManagementPage组件测试 (P1)
- ActivityForm组件测试 (P1)
- RouteForm组件测试 (P1)
- ActivitySelect组件测试 (P1)
- E2E测试 (tests/e2e/specs/admin/)
- 活动管理E2E测试 (P1)
- 路线管理E2E测试 (P1)
- 搜索筛选E2E测试 (P2)
- 启用禁用操作E2E测试 (P1)
实现活动选择组件 (AC: 3)
- 创建ActivitySelect组件，支持活动搜索和选择
- 在RouteForm中集成ActivitySelect组件，替换原有的数字输入框
- 实现活动搜索功能，支持按名称搜索
- 实现活动列表展示，显示活动名称和类型
- 添加活动选择验证
修复表单时间格式问题 (AC: 1, 2, 3, 4)
- 修复活动API响应schema中的时间字段类型
- 修复路线API响应schema中的时间字段类型
- 修复ActivityForm组件中的时间格式转换
- 修复RouteForm组件中的时间格式转换
- 更新管理后台开发规范，添加日期时间处理标准

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

活动选择组件设计

基于用户体验改进需求，需要实现活动选择组件来替换原有的数字ID输入框：

ActivitySelect组件功能要求：

支持活动搜索和选择，提升用户体验
显示活动名称和类型（去程/返程）
支持按活动名称搜索
集成到RouteForm中，替换原有的activityId数字输入框
遵循管理后台组件设计规范

组件位置：

src/client/admin/components/ActivitySelect.tsx

集成要求：

在RouteForm中替换现有的activityId输入字段
保持与现有表单验证的兼容性
支持活动列表的异步加载和搜索

管理后台页面设计

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

前端RPC实现规范

严格遵循 RPC Client 使用规范：

客户端导入和类型定义：

// 从统一的API模块导入客户端
import { activityClient, routeClient } from '@/client/api';
import type { InferRequestType, InferResponseType } from 'hono/client';

// 类型提取规范
type ActivityResponse = InferResponseType<typeof activityClient.$get, 200>['data'][0];
type RouteResponse = InferResponseType<typeof routeClient.$get, 200>['data'][0];
type CreateActivityRequest = InferRequestType<typeof activityClient.$post>['json'];
type UpdateActivityRequest = InferRequestType<typeof activityClient[':id']['$put']>['json'];

数据获取规范：

// 使用React Query进行数据获取
const { data, isLoading, refetch } = useQuery({
  queryKey: ['activities', searchParams],
  queryFn: async () => {
    const res = await activityClient.$get({
      query: {
        page: searchParams.page,
        pageSize: searchParams.limit,
        keyword: searchParams.keyword
      }
    });
    if (res.status !== 200) throw new Error('获取数据失败');
    return await res.json();
  },
  staleTime: 5 * 60 * 1000,  // 5分钟缓存
  cacheTime: 10 * 60 * 1000, // 10分钟缓存
});

统一错误处理：

// 统一操作处理函数
const handleOperation = async (operation: () => Promise<any>) => {
  try {
    await operation();
    toast.success('操作成功');
  } catch (error) {
    console.error('操作失败:', error);
    toast.error('操作失败，请重试');
  }
};

// 创建活动示例
const handleCreateActivity = async (data: CreateActivityRequest) => {
  await handleOperation(async () => {
    const res = await activityClient.$post({ json: data });
    if (res.status !== 201) throw new Error('创建失败');
  });
};

防抖搜索实现：

// 防抖搜索函数
const debounce = (func: Function, delay: number) => {
  let timeoutId: NodeJS.Timeout;
  return (...args: any[]) => {
    clearTimeout(timeoutId);
    timeoutId = setTimeout(() => func(...args), delay);
  };
};

const debouncedSearch = useCallback(
  debounce((keyword: string) => {
    setSearchParams(prev => ({ ...prev, keyword, page: 1 }));
  }, 300),
  []
);

活动管理页面:

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

路线管理页面:

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

种子数据要求

创建示例活动数据：至少包含去程活动和返程活动各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/client/admin/components/ActivitySelect.tsx
数据库迁移: src/server/migrations/ 目录
种子数据: src/server/seeds/ 目录

技术栈要求

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

开发规范要求

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

测试要求

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

测试实施指导

基于测试设计分析 (docs/qa/assessments/005.001-test-design-20251016.md)，测试实施应遵循以下优先级：

P0 优先实施 (核心功能):

活动类型枚举验证
路线字段格式验证
数据库CRUD操作测试
启用/禁用状态切换测试

P1 其次实施 (重要功能):

搜索和筛选功能测试
活动路线关联测试
管理后台页面组件测试
关键E2E用户旅程测试

P2 最后实施 (辅助功能):

高级搜索筛选E2E测试
管理后台页面导航测试

测试文件位置参考:

集成测试: tests/integration/server/admin/
组件测试: tests/integration/client/admin/
E2E测试: tests/e2e/specs/admin/

Change Log

Date	Version	Description	Author
2025-10-16	2.0	修复TypeScript类型错误，提升代码质量：修复Schema定义、枚举类型、filters参数格式，移除所有any类型使用	James (Dev Agent)
2025-10-16	1.9	完成活动管理和路线管理E2E测试，实现完整的测试覆盖	James (Dev Agent)
2025-10-16	1.8	修复表单时间格式问题，补充日期时间处理规范	Winston (Architect)
2025-10-16	1.7	补充活动选择组件任务，提升用户体验	Bob (Scrum Master)
2025-10-16	1.6	完成管理后台页面所有功能：搜索筛选、创建编辑、启用/禁用	James (Dev Agent)
2025-10-16	1.5	添加前端RPC实现规范，确保符合管理后台RPC Client使用规范	Bob (Scrum Master)
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

Claude Sonnet 4.5 (2025-09-29)

Debug Log References

检查并验证了基础数据实体的实现
检查并验证了Zod Schema的实现
检查并验证了管理后台API的实现
检查并验证了管理后台页面的实现
修复TypeScript类型错误：Schema定义、枚举类型、filters参数格式、any类型使用

Completion Notes List

✅ 已完成的任务:

基础数据实体已创建并符合规范
Zod Schema已创建并包含完整验证逻辑
管理后台API已使用createCrudRoutes实现
管理后台页面已创建并集成到路由系统
活动管理页面已实现完整的搜索、筛选、创建、编辑、启用/禁用功能
路线管理页面已实现完整的搜索、筛选、创建、编辑、启用/禁用功能
所有代码遵循项目编码标准和RPC客户端使用规范
使用React Hook Form + Zod实现表单验证
使用React Query进行数据管理
实现防抖搜索优化用户体验
修复筛选参数实现（使用通用CRUD的filters参数）
创建ActivitySelect组件，提升用户体验
在RouteForm中集成ActivitySelect组件，替换原有的数字输入框
实现活动搜索功能，支持按名称搜索
实现活动列表展示，显示活动名称和类型
添加活动选择验证
完成管理后台API集成测试（活动管理和路线管理）
完成管理后台页面组件测试（ActivitiesPage和RoutesPage）
扩展TestDataFactory支持活动和路线测试数据
扩展IntegrationTestAssertions支持活动和路线断言
完成活动管理E2E测试，覆盖完整的CRUD操作流程
完成路线管理E2E测试，覆盖完整的CRUD操作流程
完成启用/禁用操作E2E测试，验证状态切换功能
在活动管理和路线管理页面添加data-testid属性，提升测试可靠性
创建活动管理和路线管理页面对象类，遵循Page Object Model模式
更新测试设置文件，集成新的页面对象

✅ 技术实现细节:

严格遵循RPC客户端使用规范
使用TypeScript确保类型安全
- 修复Schema定义不完整问题，确保API返回完整对象
- 使用枚举类型替代字符串字面量，提升类型安全性
- 移除所有any类型使用，遵循TypeScript最佳实践
- 确保测试代码具有完整的类型推断
实现组件化表单设计
支持活动类型筛选（去程/返程）
支持车型筛选（大巴/中巴/小车）
实现状态切换确认对话框
所有单元测试通过验证
创建Combobox组件，基于Command和Popover组件
实现ActivitySelect组件，支持活动搜索和选择
集成React Query进行异步数据获取
实现防抖搜索优化性能
显示活动名称和类型信息
修复活动API响应schema中的时间字段类型问题
修复路线API响应schema中的时间字段类型问题
在ActivityForm和RouteForm中添加时间格式转换函数
使用date-fns库进行时间格式化
更新管理后台开发规范，添加日期时间处理标准
扩展测试基础设施支持活动和路线实体
实现全面的API集成测试覆盖CRUD、搜索、筛选、状态切换
实现组件集成测试覆盖页面渲染、表单交互、错误处理
修复测试数据字段映射问题（status vs isDisabled, seats vs seatCount）
实现完整的E2E测试覆盖活动管理和路线管理功能
使用data-testid属性提升测试可靠性，避免基于文本的定位器
遵循Page Object Model设计模式，创建专业的页面对象类
使用Playwright进行E2E测试，确保端到端流程正确性
实现活动CRUD操作E2E测试：创建、编辑、删除、启用/禁用
实现路线CRUD操作E2E测试：创建、编辑、删除、启用/禁用
验证状态切换功能在E2E测试中的正确性
修复TypeScript类型错误，提升代码质量
- 修复Schema定义不完整问题：扩展活动获取Schema和路线获取Schema为完整对象定义
- 修复枚举类型使用错误：使用ActivityType枚举值替代字符串字面量
- 修复filters参数格式错误：使用JSON.stringify传递筛选条件
- 移除测试代码中的所有any类型使用，提升类型安全性

File List

已创建/修改的文件:

src/server/modules/activities/activity.entity.ts
src/server/modules/routes/route.entity.ts
src/server/modules/activities/activity.schema.ts
src/server/modules/routes/route.schema.ts
src/share/activity.types.ts
src/share/route.types.ts
src/server/api/admin/activities/index.ts
src/server/api/admin/routes/index.ts
src/client/admin/pages/Activities.tsx
src/client/admin/pages/Routes.tsx
src/client/admin/components/ActivityForm.tsx
src/client/admin/components/RouteForm.tsx
src/client/admin/routes.tsx
src/server/api.ts
src/client/components/ui/combobox.tsx
src/client/admin/components/ActivitySelect.tsx
src/server/modules/activities/activity.schema.ts - 修复时间字段类型
src/server/modules/routes/route.schema.ts - 修复时间字段类型
src/client/admin/components/ActivityForm.tsx - 添加时间格式转换
src/client/admin/components/RouteForm.tsx - 添加时间格式转换
docs/architecture/admin-dashboard-standards.md - 添加日期时间处理规范
tests/utils/server/integration-test-db.ts - 扩展TestDataFactory支持活动和路线
tests/utils/server/integration-test-utils.ts - 扩展IntegrationTestAssertions
tests/integration/server/admin/activities.integration.test.ts - 活动管理API集成测试
tests/integration/server/admin/routes.integration.test.ts - 路线管理API集成测试
tests/integration/client/admin/activities.test.tsx - ActivitiesPage组件测试
tests/integration/client/admin/routes.test.tsx - RoutesPage组件测试
src/client/admin/pages/Activities.tsx - 添加data-testid属性
src/client/admin/pages/Routes.tsx - 添加data-testid属性
tests/e2e/pages/admin/activity-management.page.ts - 活动管理页面对象
tests/e2e/pages/admin/route-management.page.ts - 路线管理页面对象
tests/e2e/utils/test-setup.ts - 更新测试夹具，添加页面对象
tests/e2e/specs/admin/activities.spec.ts - 活动管理E2E测试规范
tests/e2e/specs/admin/routes.spec.ts - 路线管理E2E测试规范
src/server/modules/activities/activity.schema.ts - 修复获取Schema定义，扩展为完整对象
src/server/modules/routes/route.schema.ts - 修复获取Schema定义，扩展为完整对象
tests/integration/server/admin/activities.integration.test.ts - 修复类型错误，移除any类型使用
tests/integration/server/admin/routes.integration.test.ts - 修复类型错误，移除any类型使用

QA Results

测试设计审查 (2025-10-16)

审查人: Quinn (Test Architect)

测试策略:

总测试场景: 24个
单元测试: 8个 (33%)
集成测试: 10个 (42%)
E2E测试: 6个 (25%)
优先级分布: P0: 10个, P1: 8个, P2: 6个

质量门控状态: ✅ 测试设计通过

每个验收标准都有适当的测试覆盖
测试级别分配合理
优先级与业务风险对齐
无重复覆盖问题

实施建议: 开发团队应按P0→P1→P2优先级顺序实施测试

005.001.story.md 24 KB Histórico Em bruto