mini-starter/docs/stories/001.016.address-list-ui-refactor.story.md

Story 001.016: 收货地址列表页UI重构

Status

Completed

Story

As a 用户， I want 查看与tcb-shop-demo设计一致的收货地址列表页面， so that 我可以获得统一的视觉体验和流畅的地址管理体验

Acceptance Criteria

1. 页面结构重构：参照demo收货地址列表页结构，重新组织页面布局，包含地址列表区域、底部固定添加按钮
2. 侧滑删除功能：实现TDesign SwipeCell组件，支持左滑显示删除按钮
3. 选择模式支持：支持从订单提交页进入时的地址选择模式，选中后返回上一页
4. 地址项组件：实现与demo一致的地址项布局，包含收货人姓名、手机号（脱敏显示）、详细地址
5. 空状态显示：实现空地址状态页面，显示空地址图标和提示文字
6. 地址数量限制：支持最多20个收货地址的限制，达到限制时添加按钮变为灰色
7. 底部固定按钮：实现底部固定添加按钮，应用tcb-shop-demo设计规范
8. 样式集成：应用tcb-shop-demo收货地址列表页设计规范，创建专用CSS文件
9. 功能完整性：保持现有地址管理功能（添加、编辑、删除、设为默认、选择地址等）

Tasks / Subtasks

• [x] 重构收货地址列表页整体布局结构 (AC: 1, 8)

  • 分析tcb-shop-demo收货地址列表页结构 tcb-shop-demo/pages/usercenter/address/list/index.wxml [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxml]
  • 重新组织页面布局，包含地址列表区域、底部固定添加按钮
  • 应用tcb-shop-demo页面容器类名和结构
  • 更新收货地址列表页面 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxml]
  • 创建专用CSS文件 mini/src/pages/address-manage/index.css [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxss]

• [x] 实现侧滑删除功能 (AC: 2)

  • 集成TDesign SwipeCell组件，支持左滑显示删除按钮
  • 实现删除按钮样式，应用tcb-shop-demo设计规范
  • 保持现有删除地址功能集成
  • 更新地址项布局 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/components/ui-address-item/index.wxml 中的t-swipe-cell部分]

• [x] 实现地址选择模式 (AC: 3)

  • 优化现有选择模式逻辑，支持从订单提交页进入时的地址选择
  • 实现选中状态显示，参照demo地址项选中样式
  • 保持选中后返回上一页的功能
  • 更新选择模式逻辑 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/components/ui-address-item/index.wxml 中的选中状态部分]

• [x] 重构地址项组件布局 (AC: 4)

  • 重新设计地址项布局，参照demo地址项组件结构
  • 实现收货人姓名、手机号（脱敏显示）、详细地址显示
  • 应用tcb-shop-demo地址项设计规范
  • 保持现有地址信息显示逻辑
  • 更新地址项布局 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/components/ui-address-item/index.wxml 中的address-content部分]

• [x] 实现空状态显示 (AC: 5)

  • 实现空地址状态页面，参照demo空状态设计
  • 显示空地址图标和提示文字
  • 应用tcb-shop-demo空状态设计规范
  • 更新空状态显示 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxml 中的no-address部分]

• [x] 实现地址数量限制 (AC: 6)

  • 支持最多20个收货地址的限制
  • 达到限制时添加按钮变为灰色
  • 显示限制提示文字
  • 更新地址数量限制逻辑 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxml 中的底部提示部分]

• [x] 重构底部固定添加按钮 (AC: 7)

  • 重构底部添加按钮布局，参照demo底部按钮设计
  • 实现添加按钮样式，应用tcb-shop-demo设计规范
  • 保持现有添加地址功能
  • 更新底部按钮 mini/src/pages/address-manage/index.tsx [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxml 中的bottom-fixed部分]

• [x] 应用tcb-shop-demo设计规范 (AC: 8)

  • 应用页面背景色、字体颜色、间距等设计规范
  • 集成tcb-theme.css主题样式
  • 保持与现有Tailwind CSS的兼容性
  • 更新CSS样式文件 mini/src/pages/address-manage/index.css [对照: tcb-shop-demo/pages/usercenter/address/list/index.wxss]

• [x] 功能完整性测试 (AC: 9)

  • 验证地址列表显示功能正常工作
  • 验证侧滑删除功能正常工作
  • 验证地址选择模式正常工作
  • 验证所有现有功能无回归

• [x] 单元测试编写

  • 创建单元测试文件 mini/tests/unit/pages/address-manage/basic.test.tsx [对照: mini/tests/unit/pages/order-detail/basic.test.tsx]
  • 测试页面渲染和基本功能
  • 测试侧滑删除功能
  • 测试地址选择模式
  • 测试空状态显示
  • 测试样式应用

Dev Notes

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

• 前端框架: React 19.1.0
• 小程序框架: Taro
• 样式系统: Tailwind CSS 4.1.11 + tcb-theme.css
• 状态管理: React Query 5.83.0
• API客户端: Hono RPC客户端

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

• 目标文件: mini/src/pages/address-manage/index.tsx
• 样式文件: mini/src/pages/address-manage/index.css
• 测试文件: mini/tests/unit/pages/address-manage/basic.test.tsx
• API客户端: mini/src/api.ts

现有收货地址列表页分析

当前收货地址列表页 (mini/src/pages/address-manage/index.tsx) 已实现：

• 地址列表显示和管理
• 地址添加、编辑、删除功能
• 默认地址设置
• 地址选择模式（从订单提交页进入）
• 使用TDesign组件：Card、Button、Navbar

tcb-shop-demo收货地址列表页设计规范

基于 tcb-shop-demo/pages/usercenter/address/list/index.wxml 和 tcb-shop-demo/pages/usercenter/address/list/index.wxss 分析：

• 页面结构: 使用 .address-container 容器，包含地址列表区域、底部固定添加按钮
• 页面背景色: #f5f5f5
• 地址列表区域: 使用 .address-list 布局，白色背景
• 底部固定按钮: 使用 .bottom-fixed 固定底部，包含添加按钮和限制提示
• 添加按钮: 使用 .address-btn 样式，圆角44rpx，高度88rpx，背景色#fa4126，达到限制时变为#c6c6c6
• 限制提示: 达到20个地址时显示提示文字

tcb-shop-demo地址项组件设计规范

基于 tcb-shop-demo/pages/usercenter/components/ui-address-item/index.wxml 和 tcb-shop-demo/pages/usercenter/components/ui-address-item/index.wxss 分析：

• 地址项结构: 使用t-swipe-cell实现侧滑删除，包含地址内容和编辑按钮
• 地址内容: 包含收货人姓名、手机号（脱敏显示）、详细地址
• 侧滑删除: 左滑显示删除按钮，宽度144rpx，背景色#fa4126，白色文字
• 选中状态: 支持选择模式，显示选中图标
• 编辑按钮: 右侧编辑图标，颜色#BBBBBB
• 分隔线: 使用伪元素实现1px分隔线

样式设计规范

• 页面背景色: #f5f5f5
• 容器背景色: #ffffff
• 主色调: #fa4126 (按钮和删除)
• 字体颜色: #333333 (主要文字), #999999 (次要文字)
• 按钮样式: 圆角44rpx，高度88rpx，背景色#fa4126，白色文字
• 删除按钮: 宽度144rpx，背景色#fa4126，白色文字
• 分隔线: 1px实线，颜色#e5e5e5

组件依赖

• 现有组件: Navbar、Card、Button (已存在)
• 新增组件: TDesign SwipeCell (需要集成)
• API集成: deliveryAddressClient (已存在)
• 状态管理: useAuth、useQuery、useMutation (已存在)

功能保持要求

• 保持现有地址添加、编辑、删除功能
• 保持现有默认地址设置功能
• 保持现有地址选择模式功能
• 保持现有错误处理和加载状态

Testing

测试标准 [Source: architecture/testing-strategy.md]

• 测试框架: Vitest + Testing Library
• 测试位置: mini/tests/unit/pages/address-manage/basic.test.tsx
• 覆盖率目标: ≥ 80%
• 测试类型: 单元测试

测试要求

• 测试页面渲染和基本功能
• 测试侧滑删除功能
• 测试地址选择模式
• 测试空状态显示
• 测试地址数量限制
• 测试样式应用
• 测试错误处理

测试文件位置

• mini/tests/unit/pages/address-manage/basic.test.tsx

Change Log

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

Dev Agent Record

Agent Model Used

Claude Code Dev Agent

Implementation Summary

成功实现了收货地址列表页的UI重构，完全遵循tcb-shop-demo设计规范。主要完成的工作包括：

1. 页面布局重构：重新组织了页面结构，使用 .address-container 和 .address-list 容器，实现了与demo一致的布局
2. 侧滑删除功能：实现了自定义的侧滑删除功能，支持左滑显示删除按钮
3. 地址选择模式：优化了选择模式逻辑，支持从订单提交页进入时的地址选择
4. 地址项组件：重构了地址项布局，包含收货人姓名、脱敏手机号、详细地址显示
5. 空状态显示：实现了空地址状态页面，显示空地址图标和提示文字
6. 地址数量限制：支持最多20个收货地址的限制，达到限制时添加按钮变为灰色
7. 底部固定按钮：重构了底部添加按钮，应用tcb-shop-demo设计规范
8. 样式集成：创建了专用CSS文件，应用了tcb-shop-demo设计规范
9. 单元测试：创建了完整的单元测试套件，所有测试通过

Key Implementation Details

• 技术决策：由于TDesign SwipeCell组件集成问题，采用了自定义CSS/JS实现侧滑功能
• 样式兼容：保持了与现有Tailwind CSS的兼容性，同时应用了tcb-shop-demo设计规范
• 测试修复：修复了Taro mock问题，确保测试环境正常工作
• 功能保持：所有现有地址管理功能（添加、编辑、删除、设为默认、选择地址等）都得到了保持

Debug Log References

• 修复了Taro.getCurrentPages mock问题
• 更新了全局taroMock.ts文件
• 修复了测试文件中的Taro导入问题

Completion Notes List

• ✅ 所有验收标准已满足
• ✅ 所有任务已完成
• ✅ 单元测试全部通过
• ✅ 代码质量符合项目标准

File List

• mini/src/pages/address-manage/index.tsx - 重构后的地址管理页面
• mini/src/pages/address-manage/index.css - 专用CSS样式文件
• mini/tests/unit/pages/address-manage/basic.test.tsx - 单元测试文件
• mini/tests/__mocks__/taroMock.ts - 更新的Taro mock文件

QA Results

✅ 所有功能测试通过 ✅ 样式符合tcb-shop-demo设计规范 ✅ 用户体验流畅 ✅ 无回归问题