mini-starter/docs/stories/009.006.visit-record-optimization.story.md

Story 009.006: 回访记录优化

Status

Draft

Story

As a 残疾人信息管理员 I want 优化回访记录功能 so that 更全面地记录回访情况

Acceptance Criteria

1. 在回访类型中增加"微信回访"选项
2. "创建"按钮点击功能正常（已修复）

Tasks / Subtasks

• 修改前端VisitManagement组件，添加"微信回访"选项 (AC: 1)
  • 修改 allin-packages/disability-person-management-ui/src/components/VisitManagement.tsx
  • 在默认visitTypes数组中添加"微信回访"选项
  • 确保"微信回访"选项在Select组件中正确显示
• 验证"创建"按钮功能正常 (AC: 2)
  • 测试VisitManagement组件中的"添加回访记录"按钮功能
  • 验证点击按钮能正确添加新的回访记录表单
  • 确保表单字段验证和状态管理正常工作
• 更新相关测试文件 (AC: 1, 2)
  • 更新残疾人个人管理UI包集成测试
  • 验证"微信回访"选项在测试中可用
  • 确保所有现有测试继续通过

Dev Notes

技术栈信息 [Source: architecture/tech-stack.md]

• 运行时：Node.js 20.18.3
• 前端框架：React 19.1.0
• 样式：Tailwind CSS 4.1.11
• 状态管理：React Query 5.83.0

项目结构信息 [Source: architecture/source-tree.md]

• 残疾人个人管理UI包：allin-packages/disability-person-management-ui/
  • 组件：src/components/VisitManagement.tsx
  • 测试：tests/integration/disability-person.integration.test.tsx
• 残疾人管理模块：allin-packages/disability-module/
  • 实体：src/entities/disabled-visit.entity.ts
  • Schema：src/schemas/disabled-person.schema.ts（包含DisabledVisitSchema定义）

UI包开发规范 [Source: architecture/ui-package-standards.md]

• 组件开发规范：
  • 使用RPC推断类型，而不是直接导入schema类型
  • 为关键交互元素添加 data-testid 属性
  • 表单字段使用网格布局：grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4
• 测试规范：
  • 测试文件位置：tests/integration/
  • 使用 data-testid 进行元素查询
  • 避免使用 getByText() 查找可能重复的文本元素
• 测试选择器优化规范：
  • 必须为关键交互元素添加data-testid属性
  • 避免文本选择器冲突，使用test ID代替getByText()
  • test ID命名使用kebab-case格式：{action}-{element}-{purpose}

编码标准 [Source: architecture/coding-standards.md]

• 测试框架：Vitest + Testing Library
• 测试位置：tests/ 文件夹与源码并列
• 覆盖率目标：核心业务逻辑 > 80%
• 关键集成规则：
  • 确保现有API兼容性
  • 使用测试数据库，避免污染生产数据
  • 测试各种错误场景和边界条件

回访记录数据结构

根据现有代码分析，回访记录使用以下数据结构：

实体定义 [Source: allin-packages/disability-module/src/entities/disabled-visit.entity.ts]:

• visitType: string (varchar(50), 非空) - 回访类型
• visitDate: Date (date类型) - 回访日期
• visitContent: string (text类型) - 回访内容
• visitResult: string (varchar(50), 可为空) - 回访结果
• nextVisitDate: Date (date类型, 可为空) - 下次回访日期
• visitorId: number (int类型) - 回访人ID

Schema定义 [Source: allin-packages/disability-module/src/schemas/disabled-person.schema.ts]:

export const DisabledVisitSchema = z.object({
  visitType: z.string().max(50).openapi({
    description: '回访类型',
    example: '电话回访'
  }),
  // ... 其他字段
});

前端组件状态 [Source: allin-packages/disability-person-management-ui/src/components/VisitManagement.tsx]:

• 默认visitTypes数组：['电话回访', '上门回访', '视频回访', '其他']
• 需要添加"微信回访"选项到该数组
• 组件使用Select组件显示回访类型选项

前一个故事009.005的启示

• 这是残疾人管理模块的优化，涉及UI组件的修改
• 遵循统一的编码标准和测试要求
• 修改UI组件时需要确保向后兼容性
• 需要更新相关测试文件

项目结构对齐

• VisitManagement组件位于正确的位置：allin-packages/disability-person-management-ui/src/components/VisitManagement.tsx
• 测试文件位置正确：allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx
• 后端实体和schema定义完整，无需修改后端代码
• 这是纯前端UI优化，不涉及后端API变更

Testing

测试文件位置

• 后端：allin-packages/disability-module/tests/integration/disability.integration.test.ts
• 前端：allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx

测试标准

• 使用Vitest作为测试框架
• 集成测试验证完整工作流
• 测试覆盖率 > 80%
• 使用 data-testid 进行元素查询
• 测试边界条件和错误场景

测试框架和模式

• 前端：Testing Library + Vitest
• 使用 data-testid 进行元素查询，避免文本查找冲突

特定测试要求

• 验证"微信回访"选项在Select组件中正确显示
• 验证"添加回访记录"按钮功能正常
• 验证新添加的回访记录表单字段正常工作
• 验证现有回访类型选项不受影响
• 确保所有现有测试继续通过

Change Log

Date	Version	Description	Author
2025-12-10	1.0	初始故事创建	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results