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

Story 010.004: 修复订单状态更新

Status

Draft

Story

As a 订单管理员 I want 能够成功更新订单状态 so that 准确跟踪订单进度

Acceptance Criteria

1. 编辑订单信息后状态能够正常更新
2. 状态变更后页面显示正确的状态信息
3. 表单验证错误能够在界面上正确显示
4. 编辑订单对话框不包含人员相关验证逻辑（人员在查看详情中编辑）

Tasks / Subtasks

• 修复编辑订单schema验证问题 (AC: 4)
  • 分析当前schema：orderFormSchema 包含 orderPersons.min(1) 验证
  • 创建独立的编辑订单schema，使 orderPersons 为可选或移除
  • 或者修改现有schema，根据模式动态调整验证规则
• 修复编辑订单提交逻辑 (AC: 1)
  • 修改 OrderForm.tsx:219-220 的编辑订单逻辑
  • 编辑订单时只传递基本信息，不包含 orderPersons
  • 确保更新API接收正确的数据格式
• 遵循UI包开发规范 (AC: 1-4)
  • 根据 ui-package-standards.md，考虑使用条件渲染两个独立的Form组件
  • 或者为创建和编辑模式使用独立的schema和默认值
  • 确保表单组件模式符合规范要求
• 检查并更新测试用例 (AC: 1-4)
  • 检查当前集成测试是否覆盖编辑订单功能
  • 如果需要，添加编辑订单表单验证测试
  • 验证编辑订单不要求人员信息
  • 确保其他字段的验证错误显示正常工作
• 进行功能测试 (AC: 1-4)
  • 手动测试编辑订单状态更新
  • 验证编辑订单不再要求人员信息
  • 确认其他字段的验证错误正确显示

Dev Notes

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

• 前端框架: React 19.1.0 + TypeScript
• 路由: React Router v7
• 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态)
• UI组件库: shadcn/ui (基于Radix UI)
• 构建工具: Vite 7.0.0
• 样式: Tailwind CSS 4.1.11
• HTTP客户端: 基于Hono Client的封装 + axios适配器

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

• 订单管理UI包路径: allin-packages/order-management-ui/
• 订单模块路径: allin-packages/order-module/
• Web应用路径: web/src/client/admin/
• 组件位置: allin-packages/order-management-ui/src/components/OrderManagement.tsx
• API客户端位置: allin-packages/order-management-ui/src/api/orderClient.ts
• 订单表单组件: allin-packages/order-management-ui/src/components/OrderForm.tsx

当前订单状态更新问题分析（基于代码分析）

根据代码分析，发现以下具体问题：

1. 不必要的人员验证（核心问题）:

   • 文件: OrderForm.tsx:70
   • 问题: orderPersons: z.array(personInfoSchema).min(1, '至少选择一名人员')
   • 编辑订单时schema仍然要求至少一名人员，但编辑订单不应该包含人员验证
   • 注意: 这个验证错误无法在界面上显示，因为表单中没有人员相关的UI元素

2. 编辑订单逻辑问题:

   • 文件: OrderForm.tsx:219-220
   • 问题: 编辑订单时传递完整的data（包含orderPersons）给更新API
   • 应该只传递订单基本信息，不包含人员数据

3. 创建和编辑模式混淆:

   • 创建订单需要人员信息（第223-247行）
   • 编辑订单不应该要求人员信息，但使用了相同的schema

4. 表单验证错误处理:

   • 文件: OrderForm.tsx:358
   • 当前: form.handleSubmit(onSubmit, (errors) => console.debug('表单验证错误:', errors))
   • 注意: 这个console.debug不是bug，是调试信息。其他字段的错误通过<FormMessage />组件显示

核心问题: 编辑订单和创建订单使用了相同的表单schema，但业务需求不同。编辑订单不应该要求人员信息。

订单模块API信息 [Source: 代码分析]

• 订单路由结构: 根据 orderClient.ts 分析，更新路由为 update[':id']['$put']
• 更新请求类型: UpdateOrderRequest = InferRequestType<typeof orderClient.update[':id']['$put']>['json']
• 更新响应类型: UpdateOrderResponse = InferResponseType<typeof orderClient.update[':id']['$put'], 200>
• 其他相关路由:
  • 创建订单: create.$post
  • 获取订单列表: list.$get
  • 获取订单详情: detail[':id']['$get']
  • 删除订单: delete[':id']['$delete']
  • 激活订单: activate[':orderId']['$post']
  • 关闭订单: close[':orderId']['$post']

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

1. 必须遵循UI包开发规范，基于史诗008经验总结
2. API路径映射验证: 开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
3. 类型推断最佳实践: 必须使用RPC推断类型，而不是直接导入schema类型
4. 测试选择器优化: 必须为关键交互元素添加 data-testid 属性
5. 表单组件模式: 必须使用条件渲染两个独立的Form组件
6. API调用一致性: 必须根据实际路由名称修正API调用

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

1. 测试框架: 使用Vitest + Testing Library + hono/testing + Playwright
2. 测试位置: tests/ 文件夹与源码并列
3. 覆盖率目标: 核心业务逻辑 > 80%
4. 测试类型: 单元测试、集成测试、E2E测试

表单组件模式规范 [Source: architecture/ui-package-standards.md#表单组件模式规范]

规范: 当组件需要支持创建和编辑两种表单模式时，必须使用条件渲染两个独立的Form组件，避免在单个Form组件上动态切换props。

// ✅ 正确：条件渲染两个独立的Form组件
{isCreateForm ? (
  <Form {...createForm}>
    {/* 创建表单内容 */}
  </Form>
) : (
  <Form {...updateForm}>
    {/* 编辑表单内容 */}
  </Form>
)}

类型推断最佳实践 [Source: architecture/ui-package-standards.md#类型推断最佳实践]

规范: 必须使用RPC推断类型，而不是直接导入schema类型，避免Date/string类型不匹配问题。

// ✅ 正确：使用RPC推断类型（推荐）
export type UpdateOrderRequest = InferRequestType<typeof orderClient.update[':id']['$put']>['json'];

// ❌ 错误：直接导入schema类型（可能导致Date/string不匹配）
import type { UpdateOrderSchema } from '@d8d/allin-order-module/schemas';

测试选择器优化规范 [Source: architecture/ui-package-standards.md#测试选择器优化规范]

规范: 必须为关键交互元素添加 data-testid 属性，避免使用文本查找导致的测试冲突。

需要添加的test ID:

• data-testid="order-update-form"
• data-testid="order-update-submit-button"
• data-testid="order-status-select"
• data-testid="order-work-status-select"

需要修复的具体问题（基于代码分析）

1. 修复编辑订单schema验证:

   • 编辑订单不应该要求 orderPersons 信息
   • 需要分离创建和编辑订单的schema验证规则
   • orderPersons 验证错误无法显示是正常的（没有相关UI元素）

2. 修复编辑订单提交逻辑:

   • 编辑订单时只传递订单基本信息给更新API
   • 不传递 orderPersons 字段给更新请求

3. 遵循UI包开发规范:

   • 根据规范，应该使用条件渲染两个独立的Form组件
   • 或者为创建和编辑模式使用独立的schema

4. 检查测试覆盖:

   • 检查当前测试是否覆盖编辑订单功能
   • 确保其他字段的验证错误显示测试正常工作

文件位置

• 主要修改文件: allin-packages/order-management-ui/src/components/OrderManagement.tsx
• 表单组件文件: allin-packages/order-management-ui/src/components/OrderForm.tsx
• API客户端文件: allin-packages/order-management-ui/src/api/orderClient.ts
• 类型定义文件: allin-packages/order-management-ui/src/api/types.ts
• 测试文件: allin-packages/order-management-ui/tests/integration/order.integration.test.tsx
• 后端路由文件: allin-packages/order-module/src/routes/order-crud.routes.ts

测试

测试标准 [Source: architecture/coding-standards.md]

• 测试框架: Vitest + Testing Library
• 测试位置: tests/integration/ 文件夹
• 测试类型: 集成测试验证组件与API交互
• 覆盖率要求: 核心编辑订单功能 > 80%

具体测试要求

1. 表单验证测试: 测试编辑订单表单的验证错误显示
2. 更新功能测试: 测试订单状态更新功能
3. 错误处理测试: 测试表单提交错误处理
4. 功能分离测试: 验证编辑订单不包含人员验证逻辑

测试选择器要求

必须为相关控件添加 data-testid 属性：

• data-testid="order-edit-form"
• data-testid="order-edit-submit-button"
• data-testid="order-status-select"
• data-testid="order-work-status-select"
• data-testid="order-edit-button-{id}"
• data-testid="form-error-message"

Change Log

Date	Version	Description	Author
2025-12-12	1.0	故事创建，基于史诗010-04需求	Scrum Master Bob
2025-12-12	1.1	简化故事，专注于修复表单验证错误显示和移除不必要的人员验证	Scrum Master Bob
2025-12-12	1.2	基于代码分析更新：澄清表单验证错误显示不是bug，核心是schema设计问题	Scrum Master Bob

Dev Agent Record

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

Agent Model Used

待填写

Debug Log References

待填写

Completion Notes List

待填写

File List

待填写

QA Results

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