📝 docs(story): 新增银行卡管理优化故事文档

- 创建故事文档 009.004.bank-card-management-optimization.story.md
- 定义用户故事：作为残疾人信息管理员，需要优化银行卡管理功能
- 明确验收标准：【功能】银行名称改为选项式并支持自定义、【修复】解决银行卡照片上传问题、【功能】增加银行卡类型选择项、【优化】简化表单验证规则
- 详细规划开发任务、技术栈、项目结构、数据模型和测试策略
- 提供组件架构、编码标准和测试环境配置指导

docs/stories/009.004.bank-card-management-optimization.story.md

@@ -0,0 +1,179 @@
+# Story 009.004: 银行卡管理优化
+
+## Status
+Draft
+
+## Story
+**As a** 残疾人信息管理员
+**I want** 优化银行卡管理功能
+**so that** 更便捷地管理残疾人的银行卡信息
+
+## Acceptance Criteria
+1. 银行名称改为选项式，支持用户自行添加（参考省份选择逻辑）
+2. 修复银行卡照片无法上传的问题
+3. 增加银行卡类型选择项（一类卡/二类卡）
+4. 仅保留"公司名字"为必填项，其他字段设为非必填
+
+## Tasks / Subtasks
+- [ ] 修改银行选择组件为选项式 (AC: 1)
+  - [ ] 创建银行选择组件，支持选项选择和用户自定义输入
+  - [ ] 参考AreaSelect组件的省份选择逻辑实现
+  - [ ] 添加银行选项数据管理（可配置的银行列表）
+- [ ] 修复银行卡照片上传功能 (AC: 2)
+  - [ ] 检查FileSelector组件的集成问题
+  - [ ] 修复文件ID绑定逻辑
+  - [ ] 验证照片上传和预览功能
+- [ ] 添加银行卡类型选择字段 (AC: 3)
+  - [ ] 在BankCardManagement组件中添加银行卡类型字段
+  - [ ] 创建银行卡类型枚举（一类卡/二类卡）
+  - [ ] 更新相关schema和类型定义
+- [ ] 优化表单验证规则 (AC: 4)
+  - [ ] 修改BankCardManagement组件的表单验证
+  - [ ] 仅保留必要字段为必填，其他设为可选
+  - [ ] 更新前端验证逻辑和后端schema
+- [ ] 更新测试用例 (AC: 1, 2, 3, 4)
+  - [ ] 更新BankCardManagement组件的集成测试
+  - [ ] 添加银行卡类型选择测试
+  - [ ] 验证照片上传功能测试
+  - [ ] 验证表单验证规则更新
+
+## Dev Notes
+
+### 技术栈信息 [Source: architecture/tech-stack.md]
+- **前端框架**: React 19.1.0 + TypeScript
+- **UI组件库**: shadcn/ui (基于Radix UI)
+- **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态)
+- **表单处理**: react-hook-form + zodResolver
+- **HTTP客户端**: 基于Hono Client的RPC封装
+- **样式**: Tailwind CSS 4.1.11
+- **构建工具**: Vite 7.0.0
+
+### 项目结构信息 [Source: architecture/source-tree.md]
+- **UI包位置**: `allin-packages/disability-person-management-ui/`
+- **组件文件**: `src/components/BankCardManagement.tsx`
+- **API客户端**: `src/api/disabilityClient.ts`
+- **测试文件**: `tests/integration/disability-person.integration.test.tsx`
+- **后端模块**: `allin-packages/disability-module/`
+- **Schema文件**: `allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
+
+### 数据模型信息 [Source: architecture/data-model-schema-changes.md]
+**银行卡实体Schema** (来自disabled-person.schema.ts:268-319):
+```typescript
+export const DisabledBankCardSchema = z.object({
+  id: z.number().int().positive(),
+  personId: z.number().int().positive(),
+  subBankName: z.string().max(100),      // 发卡支行
+  bankName: z.string().max(50),          // 银行名称
+  cardNumber: z.string().max(50),        // 卡号
+  cardholderName: z.string().max(50),    // 持卡人姓名
+  fileId: z.number().int().positive(),   // 银行卡照片文件ID
+  file: FileSchema.nullable().optional(), // 银行卡照片文件实体
+  isDefault: z.number().int().min(0).max(1).default(0) // 是否默认
+});
+```
+
+**当前BankCardManagement组件字段**:
+- `subBankName`: 发卡支行（当前为必填）
+- `bankName`: 银行名称（当前为必填，需要改为选项式）
+- `cardNumber`: 银行卡号（当前为必填）
+- `cardholderName`: 持卡人姓名（当前为必填）
+- `fileId`: 银行卡照片文件ID（当前可选，但上传有问题）
+- `isDefault`: 是否默认银行卡（当前可选）
+
+**需要新增字段**:
+- `cardType`: 银行卡类型（一类卡/二类卡）
+
+### UI包开发规范 [Source: architecture/ui-package-standards.md]
+**必须遵循的规范**:
+1. **API路径映射验证**: 开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
+2. **类型推断最佳实践**: 必须使用RPC推断类型，而不是直接导入schema类型
+3. **测试选择器优化**: 必须为关键交互元素添加`data-testid`属性
+4. **表单组件模式**: 必须使用条件渲染两个独立的Form组件
+5. **API调用一致性**: 必须根据实际路由名称修正API调用
+
+**参考现有组件模式**:
+- **AreaSelect组件**: 参考省份选择逻辑实现银行选择组件
+- **PlatformManagement组件**: 参考表单处理模式，确保一致性
+- **广告管理UI包**: `packages/advertisement-management-ui` 作为参考实现
+
+### 组件架构信息 [Source: architecture/component-architecture.md]
+**前端组件架构**:
+- 使用React 19.1.0 + TypeScript
+- 路由: React Router v7
+- 状态管理: @tanstack/react-query + Context
+- UI组件库: shadcn/ui (基于Radix UI)
+
+**文件管理服务**:
+- 已实现完整功能，支持分段上传、预签名URL生成
+- 核心功能: 单文件上传（≤5MB）、多部分分段上传（>5MB大文件）
+- 预签名URL生成（支持下载和直接访问）
+
+### 编码标准和测试策略 [Source: architecture/coding-standards.md]
+**测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
+**测试位置**: `tests/` 文件夹与源码并列
+**覆盖率目标**: 核心业务逻辑 > 80%
+**测试类型**: 单元测试、集成测试、E2E测试
+
+**关键集成规则**:
+- 现有API兼容性: 确保测试不破坏现有API契约
+- 数据库集成: 使用测试数据库，避免污染生产数据
+- 错误处理: 测试各种错误场景和边界条件
+- 日志一致性: 测试日志格式和错误信息
+
+### 测试
+**测试文件位置**: `allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx`
+
+**测试标准**:
+- 使用Vitest作为测试框架
+- 使用Testing Library进行React组件测试
+- 集成测试验证组件与API的交互
+- 必须添加`data-testid`属性用于测试选择器
+- 参考现有集成测试模式进行测试编写
+
+**测试要求**:
+1. 验证银行选择组件功能（选项选择、自定义输入）
+2. 验证银行卡照片上传功能修复
+3. 验证银行卡类型选择功能
+4. 验证表单验证规则更新（仅必要字段必填）
+5. 确保现有功能不受影响
+
+**Radix UI组件测试环境修复** (基于故事008.007经验):
+- 在测试环境中使用Radix UI组件时，必须添加必要的DOM API mock
+- 特别是Select、DropdownMenu等组件需要`scrollIntoView` mock
+- 在测试setup文件中添加: `Element.prototype.scrollIntoView = vi.fn();`
+
+### 项目结构对齐检查
+**当前结构**:
+- `allin-packages/disability-person-management-ui/src/components/BankCardManagement.tsx`
+- `allin-packages/disability-module/src/schemas/disabled-person.schema.ts`
+- `allin-packages/disability-person-management-ui/tests/integration/disability-person.integration.test.tsx`
+
+**需要创建/修改的文件**:
+1. 银行选择组件（新组件）
+2. BankCardManagement.tsx（修改现有组件）
+3. 相关类型定义文件
+4. 集成测试文件更新
+
+**结构一致性**: 符合现有UI包结构规范，无需调整项目结构。
+
+## 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
+*待QA代理填写*