Home Esplora Aiuto
Registrati Accedi
188-template-179
/
mini-starter
forkato da 155-template-138/mini-starter
2
0
Forka 0
File
Albero (Tree): a5815a9e2c
Rami (Branch) Tag
mini-starter
/
docs
/
stories
/
009.002.story.md

009.002.story.md 9.3 KB
Cronologia Originale

Story 009.002: 邮箱输入优化

Status

Draft

Story

As a 平台管理员 I want 邮箱字段改为非必要输入项 so that 在不需要邮箱的场景下快速完成平台相关操作

Acceptance Criteria

  1. 所有平台管理相关页面的邮箱字段改为非必填
  2. 表单验证规则更新
  3. 后端API支持邮箱为空

Tasks / Subtasks

  • 修复平台管理前端表单默认值问题 (AC: 1, 2)
    • 修改allin-packages/platform-management-ui/src/components/PlatformManagement.tsx中的表单配置
    • 将contactEmail字段的默认值从''改为undefined
    • 验证contactEmail字段的FormLabel没有红色星号标记（非必填）
    • 测试表单提交时邮箱字段可为空（不填写）
    • 测试表单提交时邮箱字段可为有效邮箱格式
    • 测试表单提交时邮箱字段为无效格式应显示验证错误
  • 修改平台模块后端schema验证 (AC: 2, 3)
    • 修改allin-packages/platform-module/src/schemas/platform.schema.ts中的CreatePlatformSchema
    • 将contactEmail字段改为：.optional().or(z.literal('')).transform(val => val === '' ? undefined : val)
    • 保留.email()验证（如果填写，必须是有效邮箱格式）
    • 同样修改UpdatePlatformSchema中的contactEmail字段验证规则
    • 确保.openapi()描述保持不变
  • 验证数据库兼容性 (AC: 3)
    • 检查allin-packages/platform-module/src/entities/platform.entity.ts中contactEmail字段为nullable: true
    • 验证现有数据可以正常读取和更新
  • 编写单元测试 (AC: 1, 2, 3)
    • 为平台schema添加测试，验证空字符串转换为undefined
    • 为平台schema添加测试，验证有效邮箱格式通过验证
    • 为平台schema添加测试，验证无效邮箱格式显示错误
    • 为平台schema添加测试，验证undefined通过验证（可选字段）
    • 为平台管理表单添加测试，验证邮箱字段可为空的表单提交
    • 为平台管理表单添加测试，验证邮箱字段为有效邮箱格式的表单提交
    • 为平台管理表单添加测试，验证邮箱字段为无效格式时显示验证错误
    • 添加集成测试验证端到端功能
  • 执行回归测试 (AC: 3)
    • 测试现有平台数据的显示和编辑功能
    • 验证API响应格式不变
    • 确保其他字段验证不受影响

Dev Notes

技术架构信息

前端技术栈:

  • React 19.1.0 + TypeScript [Source: architecture/tech-stack.md#前端框架]
  • UI组件库: shadcn/ui (基于Radix UI) [Source: architecture/component-architecture.md#技术栈配置]
  • 状态管理: @tanstack/react-query (服务端状态) + Context (本地状态) [Source: architecture/component-architecture.md#技术栈配置]
  • 构建工具: Vite 7.0.0 [Source: architecture/tech-stack.md#构建工具]

项目结构:

  • 平台管理UI包: allin-packages/platform-management-ui [Source: 实际项目结构检查]
  • 平台模块: allin-packages/platform-module [Source: 实际项目结构检查]

组件规范

UI包开发规范:

  • 必须遵循UI包开发规范 [Source: architecture/coding-standards.md#UI包开发提示]
  • API路径映射验证：开发前必须验证故事中的API路径映射与实际后端路由定义的一致性 [Source: architecture/coding-standards.md#关键检查点]
  • 类型推断最佳实践：必须使用RPC推断类型，而不是直接导入schema类型 [Source: architecture/coding-standards.md#关键检查点]
  • 测试选择器优化：必须为关键交互元素添加data-testid属性 [Source: architecture/coding-standards.md#关键检查点]

现有实现分析

平台管理表单现状:

  • 文件位置: allin-packages/platform-management-ui/src/components/PlatformManagement.tsx:395-406
  • 当前表单字段：contactEmail字段有FormLabel但没有红色星号标记
  • 表单验证：使用CreatePlatformSchema和UpdatePlatformSchema进行验证

平台schema现状:

  • 创建DTO: allin-packages/platform-module/src/schemas/platform.schema.ts:53 - contactEmail字段有.email()验证和.optional()
  • 更新DTO: allin-packages/platform-module/src/schemas/platform.schema.ts:77 - contactEmail字段有.email()验证和.optional()
  • 数据库实体: allin-packages/platform-module/src/entities/platform.entity.ts:47 - contactEmail字段为nullable: true

问题分析: 当前schema中contactEmail字段有.optional()和.email()验证，这意味着：

  1. 字段是可选的（可以是undefined）✅ 符合"非必要输入项"要求
  2. 如果填写了，必须是有效的邮箱格式 ⚠️ 当前有.email()验证

关键问题发现: 前端表单默认值设置有问题：

  • 文件位置：allin-packages/platform-management-ui/src/components/PlatformManagement.tsx:42
  • 当前默认值：contactEmail: ''（空字符串）
  • 问题：空字符串''不是有效的邮箱格式，会导致Zod验证失败
  • 正确做法：默认值应该是undefined

技术细节:

  • Zod schema：.optional()允许undefined，但不允许无效的邮箱格式
  • React Hook Form：defaultValues中可以使用undefined，但输入框清空后值是''
  • 当前所有字段都设置为''，但只有contactEmail需要特殊处理，因为它是可选但需要邮箱验证的字段

解决方案选项：

  1. 推荐方案：修改schema，使用.or(z.literal(''))允许空字符串，然后转换

    contactEmail: z.string().email().max(100).optional()
 .or(z.literal(''))  // 允许空字符串
 .transform(val => val === '' ? undefined : val)  // 将空字符串转为undefined

  2. 备选方案：前端在提交前将空字符串转换为undefined

  3. 简单方案：只修改默认值为undefined，但用户清空输入框后还是''

根据故事需求，推荐使用方案1，因为它：

  • 保持邮箱验证（如果填写了）
  • 允许空字符串（用户清空输入框）
  • 在API层面将空字符串转为undefined

根据故事"邮箱字段改为非必要输入项"的要求，需要：

  1. 修改schema，允许空字符串并转换为undefined
  2. 可选：将前端表单默认值从''改为undefined
  3. 确保字段支持空值（不填写）
  4. 如果用户选择填写，验证邮箱格式

文件位置参考

  1. 平台管理组件: allin-packages/platform-management-ui/src/components/PlatformManagement.tsx
  2. 平台schema: allin-packages/platform-module/src/schemas/platform.schema.ts
  3. 平台实体: allin-packages/platform-module/src/entities/platform.entity.ts

技术约束

  • 保持向后兼容性：现有数据必须能正常显示和编辑
  • API兼容性：不能修改现有API的请求/响应格式
  • 数据库兼容性：contactEmail字段已经是nullable: true，无需修改数据库结构

测试

测试策略:

  • 单元测试：使用Vitest框架 [Source: architecture/testing-strategy.md#单元测试]
  • 组件测试：使用Testing Library [Source: architecture/testing-strategy.md#单元测试]
  • 测试位置：tests/文件夹与源码并列 [Source: 实际项目结构检查]

测试要求:

  • 覆盖率目标：核心业务逻辑 > 80% [Source: architecture/coding-standards.md#覆盖率目标]
  • 测试类型：单元测试、集成测试 [Source: architecture/coding-standards.md#测试类型]
  • 错误处理：测试各种错误场景和边界条件 [Source: architecture/coding-standards.md#错误处理]

具体测试场景:

  1. schema验证：空字符串''转换为undefined通过验证
  2. schema验证：undefined通过验证（可选字段）
  3. schema验证：有效邮箱格式通过验证
  4. schema验证：无效邮箱格式显示验证错误
  5. 平台表单：验证提交时邮箱字段可为空（不填写）
  6. 平台表单：验证提交时邮箱字段可为有效邮箱格式
  7. 平台表单：验证提交时邮箱字段为无效格式应显示验证错误
  8. 数据兼容性：验证现有含邮箱数据的显示和编辑

Testing

测试标准

  • 测试框架: Vitest + Testing Library [Source: architecture/tech-stack.md#新技术添加]
  • 测试位置: tests/文件夹与源码并列 [Source: 实际项目结构检查]
  • 覆盖率要求: 核心业务逻辑 > 80% [Source: architecture/coding-standards.md#覆盖率目标]

组件测试要求

  • 必须为关键交互元素添加data-testid属性 [Source: architecture/coding-standards.md#关键检查点]
  • 测试平台管理表单在邮箱字段为空时的提交行为
  • 测试平台管理表单在邮箱字段为有效邮箱格式时的提交行为
  • 测试平台管理表单在邮箱字段为无效格式时的验证错误显示

集成测试要求

  • 测试平台管理表单的完整提交流程
  • 验证邮箱字段为空的表单提交
  • 验证邮箱字段为有效邮箱格式的表单提交
  • 验证邮箱字段为无效格式的表单提交应显示验证错误
  • 测试现有数据的兼容性

测试文件位置

  1. 平台管理测试: allin-packages/platform-management-ui/tests/integration/platform-management.integration.test.tsx

Change Log

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

Dev Agent Record

此部分由开发代理在实施期间填写

QA Results

此部分由QA代理在审查期间填写