HaniBlindBox/.kiro/specs/admin-business-migration/tasks.md

# Implementation Plan: Admin Business Migration

## Overview

本任务列表将后台业务模块迁移分为6个阶段：项目架构搭建、系统配置模块、用户管理模块、商品管理模块、订单管理模块、财务管理和仪表盘模块。每个阶段包含具体的实现任务和测试任务。

## Tasks

- [x] 1. 项目架构搭建
  - [x] 1.1 创建 HoneyBox.Admin.Business 类库项目
    - 在 `server/HoneyBox/src/` 下创建新的类库项目
    - 配置项目引用 HoneyBox.Model
    - 添加必要的 NuGet 包（Microsoft.AspNetCore.Mvc.Core, Mapster 等）
    - _Requirements: 1.1, 1.2_

  - [x] 1.2 创建项目目录结构
    - 创建 Controllers/ 目录
    - 创建 Services/Interfaces/ 目录
    - 创建 Models/ 目录
    - 创建 Extensions/ 目录
    - _Requirements: 1.6_

  - [x] 1.3 实现 ServiceCollectionExtensions 扩展方法
    - 创建 AddAdminBusiness 扩展方法
    - 实现 AddApplicationPart 加载业务控制器
    - 实现业务服务的自动注册
    - _Requirements: 1.3, 1.4, 1.5_

  - [x] 1.4 配置 HoneyBox.Admin 引用和启动
    - 在 HoneyBox.Admin.csproj 中添加对 HoneyBox.Admin.Business 的引用
    - 在 Program.cs 中调用 AddAdminBusiness()
    - 配置 HoneyBoxDbContext 的注入
    - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5_

  - [x] 1.5 创建通用响应模型和基类
    - 创建 ApiResponse<T> 通用响应模型
    - 创建 PagedRequest 和 PagedResult<T> 分页模型
    - 创建 BusinessException 业务异常类
    - 创建 BusinessControllerBase 控制器基类
    - _Requirements: 9.1, 9.2, 9.3_

  - [x] 1.6 Checkpoint - 验证项目架构
    - 确保项目编译通过
    - 确保控制器能被正确加载
    - 确保服务能被正确注入


- [x] 2. 系统配置模块迁移
  - [x] 2.1 创建配置服务接口和实现
    - 创建 IConfigService 接口
    - 实现 ConfigService，包含 GetConfigAsync 和 UpdateConfigAsync 方法
    - 实现配置的 JSON 序列化/反序列化
    - _Requirements: 3.1, 3.2, 3.3_

  - [x] 2.2 实现配置验证逻辑
    - 实现微信支付商户前缀验证（唯一性、3位字符）
    - 实现小程序配置验证（至少一个默认）
    - 实现 H5 配置验证（至少一个默认）
    - _Requirements: 3.4, 3.5, 3.6_

  - [x] 2.3 实现 Redis 缓存清理
    - 配置更新后清理相关 Redis 缓存
    - 支持按配置 key 清理特定缓存
    - _Requirements: 3.7_

  - [x] 2.4 创建 ConfigController
    - 实现 GET /api/admin/business/config/{key} 获取配置
    - 实现 PUT /api/admin/business/config/{key} 更新配置
    - 添加权限验证 [AdminPermission("config:view")] 和 [AdminPermission("config:edit")]
    - _Requirements: 3.1, 3.2, 3.8, 10.3_

  - [x] 2.5 编写配置模块单元测试
    - 测试配置读取功能
    - 测试配置更新功能
    - 测试验证逻辑
    - _Requirements: 3.1, 3.2, 3.4, 3.5, 3.6_

  - [x] 2.6 编写配置模块属性测试
    - **Property 1: Configuration Round-Trip Consistency**
    - **Validates: Requirements 3.1, 3.2**

  - [x] 2.7 编写配置验证属性测试
    - **Property 2: Merchant Prefix Uniqueness Validation**
    - **Property 3: Default App Validation**
    - **Validates: Requirements 3.4, 3.5, 3.6**

  - [x] 2.8 Checkpoint - 验证配置模块
    - 确保所有测试通过
    - 手动测试 API 端点
    - 验证 Redis 缓存清理功能

- [x] 3. 用户管理模块迁移
  - [x] 3.1 创建用户服务接口和实现
    - 创建 IUserBusinessService 接口
    - 实现 UserBusinessService 基础方法
    - 实现用户列表查询（含消费统计）
    - _Requirements: 4.1, 4.2_

  - [x] 3.2 实现用户列表过滤功能
    - 支持按 user_id, mobile, nickname, last_login_ip 过滤
    - 支持按注册日期范围过滤
    - 支持按 parent_id 过滤
    - _Requirements: 4.3_

  - [x] 3.3 实现用户资金变动功能
    - 实现余额变动（增加/扣除）
    - 实现积分变动（增加/扣除）
    - 实现钻石变动（增加/扣除）
    - 记录变动到 profit 表
    - _Requirements: 4.4_

  - [x] 3.4 实现用户状态管理功能
    - 实现封号/解封功能
    - 实现测试账号设置功能
    - 实现清空手机号功能
    - 实现清空微信绑定功能
    - _Requirements: 4.5, 4.6, 4.7, 4.8, 4.9_

  - [x] 3.5 实现用户赠送功能
    - 实现赠送优惠券功能
    - 实现赠送卡牌功能
    - _Requirements: 4.10, 4.11_

  - [x] 3.6 实现 VIP 管理功能
    - 实现 VIP 等级列表查询
    - 实现 VIP 等级编辑
    - _Requirements: 4.12_

  - [x] 3.7 实现用户统计功能
    - 实现用户盈亏统计计算
    - 实现下级用户列表查询
    - _Requirements: 4.13, 4.14_

  - [x] 3.8 创建 UserController
    - 实现所有用户管理 API 端点
    - 添加权限验证
    - _Requirements: 4.1-4.14, 10.3_

  - [x] 3.9 编写用户模块单元测试
    - 测试用户列表查询
    - 测试资金变动功能
    - 测试状态管理功能
    - _Requirements: 4.1-4.14_

  - [x] 3.10 编写用户模块属性测试
    - **Property 4: User List Pagination Consistency**
    - **Property 5: User List Filter Accuracy**
    - **Property 6: User Balance Change Audit Trail**
    - **Property 7: User Status Toggle Consistency**
    - **Validates: Requirements 4.1, 4.3, 4.4, 4.5, 4.6**

  - [x] 3.11 Checkpoint - 验证用户模块
    - 确保所有测试通过
    - 手动测试 API 端点


- [x] 4. 商品管理模块迁移
  - [x] 4.1 创建商品服务接口和实现
    - 创建 IGoodsService 接口
    - 实现 GoodsService 基础方法
    - 实现商品列表查询（支持过滤）
    - _Requirements: 5.1, 5.2_

  - [x] 4.2 实现商品 CRUD 功能
    - 实现商品创建（支持9种盒子类型）
    - 实现商品编辑（防止库存减少）
    - 实现商品删除
    - 实现商品上架/下架
    - _Requirements: 5.3, 5.4, 5.5_

  - [x] 4.3 实现库存增加时奖品复制逻辑
    - 当库存增加时自动复制奖品配置
    - 处理宝箱类型的子奖品复制
    - _Requirements: 5.6_

  - [x] 4.4 实现奖品管理功能
    - 实现奖品列表查询
    - 实现奖品添加（生成唯一 prize_code）
    - 实现奖品编辑
    - 实现奖品删除
    - _Requirements: 5.7, 5.8_

  - [x] 4.5 实现盒子类型管理
    - 实现盒子类型列表查询
    - _Requirements: 5.9_

  - [x] 4.6 实现操作日志记录
    - 商品状态变更时记录日志
    - _Requirements: 5.10_

  - [x] 4.7 创建 GoodsController
    - 实现所有商品管理 API 端点
    - 添加权限验证
    - _Requirements: 5.1-5.10, 10.3_

  - [x] 4.8 编写商品模块单元测试
    - 测试商品 CRUD 功能
    - 测试奖品管理功能
    - 测试库存增加逻辑
    - _Requirements: 5.1-5.10_

  - [x] 4.9 编写商品模块属性测试
    - **Property 8: Goods Stock Increase Prize Replication** ✅ PASSED
    - **Property 9: Prize Code Uniqueness** ✅ PASSED
    - **Validates: Requirements 5.6, 5.8**

  - [x] 4.10 Checkpoint - 验证商品模块
    - 确保所有测试通过 ✅ (47 tests passed: 28 unit + 5 property + 14 related)
    - 手动测试 API 端点

- [x] 5. 订单管理模块迁移
  - [x] 5.1 创建订单服务接口和实现
    - 创建 IOrderService 接口
    - 实现 OrderService 基础方法
    - 实现订单列表查询（支持过滤）
    - _Requirements: 6.1, 6.2_

  - [x] 5.2 实现订单分类查询
    - 实现购买订单列表
    - 实现卡单列表
    - 实现兑换订单列表
    - 实现发货订单列表
    - _Requirements: 6.3_

  - [x] 5.3 实现订单详情查询
    - 实现订单详情（奖品按 prize_code 分组）
    - _Requirements: 6.4_

  - [x] 5.4 实现发货功能
    - 实现单个订单发货
    - 更新订单状态和物流信息
    - _Requirements: 6.5_

  - [x] 5.5 实现取消发货功能
    - 实现取消发货订单
    - 恢复奖品到用户盒柜
    - _Requirements: 6.6_

  - [x] 5.6 实现订单导出功能
    - 实现订单导出为 Excel
    - 包含所有必要字段
    - _Requirements: 6.9, 6.10_

  - [x] 5.7 创建 OrderController
    - 实现所有订单管理 API 端点
    - 添加权限验证
    - _Requirements: 6.1-6.10, 10.3_

  - [x] 5.8 编写订单模块单元测试
    - 测试订单列表查询
    - 测试发货功能
    - 测试取消发货功能
    - _Requirements: 6.1-6.10_

  - [x] 5.9 编写订单模块属性测试
    - **Property 10: Order List Filter Accuracy** ✅ PASSED
    - **Property 11: Order Prize Grouping** ✅ PASSED
    - **Property 12: Shipping Order Cancellation Inventory Restoration** ✅ PASSED
    - **Validates: Requirements 6.2, 6.4, 6.6**

  - [x] 5.10 Checkpoint - 验证订单模块
    - 确保所有测试通过 ✅ (27 tests passed: 19 unit + 8 property)
    - 手动测试 API 端点


- [ ] 6. 财务管理和仪表盘模块迁移
  - [x] 6.1 创建财务服务接口和实现
    - 创建 IFinanceService 接口
    - 实现 FinanceService 基础方法
    - _Requirements: 7.1-7.7_

  - [x] 6.2 实现消费排行榜功能
    - 实现按消费金额排序的用户列表
    - 包含用户信息和各类支付金额
    - _Requirements: 7.1, 7.2_

  - [x] 6.3 实现财务明细查询
    - 实现余额明细查询
    - 实现积分明细查询
    - 实现钻石明细查询
    - 实现充值记录查询
    - 支持按 user_id, mobile, 日期范围过滤
    - _Requirements: 7.3, 7.4, 7.5, 7.6, 7.7_

  - [x] 6.4 创建 FinanceController
    - 实现所有财务管理 API 端点
    - 添加权限验证 [AdminPermission("finance:view")]
    - _Requirements: 7.1-7.7, 10.3_

  - [x] 6.5 创建仪表盘服务接口和实现
    - 创建 IDashboardService 接口
    - 实现 DashboardService 基础方法
    - _Requirements: 8.1-8.5_

  - [x] 6.6 实现仪表盘统计功能
    - 实现今日注册用户数统计
    - 实现今日消费金额统计
    - 实现今日新消费用户数统计
    - 实现广告收入统计
    - _Requirements: 8.1, 8.2, 8.3, 8.4_

  - [x] 6.7 实现广告账户管理
    - 实现广告账户列表查询
    - 实现广告账户创建
    - _Requirements: 8.5_

  - [x] 6.8 创建 DashboardController
    - 实现所有仪表盘 API 端点
    - 添加权限验证 [AdminPermission("dashboard:view")]
    - _Requirements: 8.1-8.5, 10.3_

  - [x] 6.9 编写财务和仪表盘模块单元测试
    - 测试消费排行榜功能
    - 测试财务明细查询
    - 测试仪表盘统计功能
    - _Requirements: 7.1-7.7, 8.1-8.5_

  - [x] 6.10 编写财务和仪表盘模块属性测试
    - **Property 13: Consumption Ranking Sort Order**
    - **Property 14: Financial Query Filter Accuracy**
    - **Property 15: Dashboard Statistics Accuracy**
    - **Validates: Requirements 7.1, 7.7, 8.1, 8.2, 8.3**

  - [x] 6.11 Checkpoint - 验证财务和仪表盘模块
    - 确保所有测试通过
    - 手动测试 API 端点

- [x] 7. 权限和响应格式验证
  - [x] 7.1 实现权限验证过滤器
    - AdminPermissionAttribute 特性已在 HoneyBox.Admin/Filters/ 中实现
    - 权限检查逻辑已完成（检查 JWT 认证、用户权限）
    - BusinessPermissionFilter 已实现，处理 BusinessPermissionAttribute
    - _Requirements: 10.1, 10.2, 10.3, 10.4_

  - [x] 7.2 为业务控制器启用权限特性
    - ConfigController 已添加 [BusinessPermission("config:view")] 和 [BusinessPermission("config:edit")]
    - UserController 已添加所有权限特性 (user:list, user:view, user:money, user:status, user:test, user:clear, user:gift)
    - GoodsController 已添加所有权限特性 (goods:list, goods:view, goods:add, goods:edit, goods:delete, goods:status)
    - OrderController 已添加所有权限特性 (order:list, order:view, order:ship, order:export)
    - VipController 已添加权限特性 (vip:list, vip:edit)
    - PrizesController 已添加权限特性 (goods:edit)
    - GoodsTypesController 已添加权限特性 (goods:view)
    - FinanceController 已添加权限特性 (finance:view)
    - DashboardController 已添加权限特性 (dashboard:view, dashboard:edit)
    - _Requirements: 10.3, 10.5_

  - [x] 7.3 在数据库中初始化业务模块权限数据
    - 已更新 DataSeeder.cs 添加业务模块权限
    - 已创建 SQL 脚本 scripts/seed_business_permissions.sql 用于现有数据库
    - 添加 config:view, config:edit 权限
    - 添加 user:list, user:view, user:money, user:status, user:test, user:clear, user:gift 权限
    - 添加 goods:list, goods:view, goods:add, goods:edit, goods:delete, goods:status 权限
    - 添加 order:list, order:view, order:ship, order:export 权限
    - 添加 finance:view, dashboard:view, dashboard:edit 权限
    - 添加 vip:list, vip:edit 权限
    - _Requirements: 10.5_

  - [x] 7.4 编写权限验证属性测试
    - **Property 18: Authentication Enforcement** ✅ PASSED
    - **Property 19: Permission Enforcement** ✅ PASSED
    - 测试文件: PermissionPropertyTests.cs
    - **Validates: Requirements 10.1, 10.2, 10.4**

  - [x] 7.5 编写响应格式属性测试
    - **Property 16: API Response Format Consistency** ✅ PASSED
    - **Property 17: Paginated Response Format** ✅ PASSED
    - 测试文件: ResponseFormatPropertyTests.cs
    - **Validates: Requirements 9.1, 9.2, 9.3**

  - [x] 7.6 Final Checkpoint - 完整验证
    - 所有测试通过 ✅
    - 所有 API 端点已实现权限控制
    - 响应格式一致性已验证

## Notes

- All tasks are required for complete implementation
- Each task references specific requirements for traceability
- Checkpoints ensure incremental validation
- Property tests validate universal correctness properties
- Unit tests validate specific examples and edge cases
- 建议按阶段顺序执行，每个阶段完成后进行验证
- AdminPermissionAttribute 已在 HoneyBox.Admin 项目中实现，业务控制器只需取消注释即可启用