HaniBlindBox/.kiro/specs/api-migration-remaining/design.md

# Design Document: API Migration Remaining

## Overview

本设计文档描述将剩余54个PHP API接口迁移到C# ASP.NET Core后端的技术方案。迁移遵循现有的Clean Architecture架构模式，复用已有的基础设施组件。

### 迁移流程

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  1. PHP源码分析  │ -> │ 2. SQL Server   │ -> │ 3. 数据表创建   │ -> │ 4. C#代码实现   │
│  查看控制器逻辑  │    │    表结构验证    │    │  (如需要)       │    │  Controller/    │
│  理解业务流程    │    │    MCP查询      │    │  Entity/        │    │  Service        │
└─────────────────┘    └─────────────────┘    │  Migration      │    └─────────────────┘
                                              └─────────────────┘
```

### 技术栈

- **后端框架**: ASP.NET Core (.NET 10)
- **ORM**: Entity Framework Core 8.0
- **数据库**: SQL Server
- **架构**: Clean Architecture (Api/Core/Infrastructure/Model)
- **依赖注入**: Autofac
- **认证**: JWT Bearer

## Architecture

### 项目结构

```
server/C#/HoneyBox/src/
├── HoneyBox.Api/           # Web API层
│   ├── Controllers/        # API控制器 (新增: AddressController, SignController等)
│   └── Filters/            # 过滤器
├── HoneyBox.Core/          # 业务逻辑层
│   ├── Services/           # 业务服务 (新增: AddressService, SignService等)
│   ├── Interfaces/         # 接口定义
│   └── Mappings/           # 对象映射配置
├── HoneyBox.Infrastructure/ # 基础设施层
│   ├── Cache/              # 缓存实现
│   └── External/           # 外部服务集成
└── HoneyBox.Model/         # 数据模型层
    ├── Entities/           # 数据库实体 (复用现有)
    ├── Models/             # DTO/ViewModel
    └── Data/               # DbContext
```

### PHP源码位置映射

| 模块 | PHP控制器路径 | C#控制器 |
|------|--------------|----------|
| 地址 | `server/php/app/api/controller/User.php` | `AddressController.cs` (新建) |
| 支付 | `server/php/app/api/controller/Pay.php` | `PayController.cs` (扩展) |
| 签到 | `server/php/app/api/controller/Sign.php` | `SignController.cs` (新建) |
| 福利屋 | `server/php/app/api/controller/FuLiWu.php` | `WelfareController.cs` (扩展) |
| 商品 | `server/php/app/api/controller/Goods.php` | `GoodsController.cs` (扩展) |
| 订单 | `server/php/app/api/controller/Order.php` | `OrderController.cs` (扩展) |
| 优惠券 | `server/php/app/api/controller/Coupon.php` | `CouponController.cs` (扩展) |
| 权益 | `server/php/app/api/controller/QuanYi.php` | `UserController.cs` (扩展) |
| 收藏 | `server/php/app/api/controller/Goods.php` | `CollectionController.cs` (扩展) |
| 排行榜 | `server/php/app/api/controller/Rank.php` | `RankController.cs` (扩展) |
| 兑换码 | `server/php/app/api/controller/Other.php` | `RedeemController.cs` (扩展) |
| 仓库 | `server/php/app/api/controller/Warehouse.php` | `WarehouseController.cs` (扩展) |
| 认证 | `server/php/app/api/controller/Login.php` | `AuthController.cs` (扩展) |
| 配置 | `server/php/app/api/controller/Config.php` | `ConfigController.cs` (扩展) |
| 商城 | `server/php/app/api/controller/Mall.php` | `MallController.cs` (新建) |

## Components and Interfaces

### 新增控制器

#### AddressController
```csharp
[ApiController]
[Route("api")]
[Authorize]
public class AddressController : ControllerBase
{
    // POST /addAddress - 添加收货地址
    // POST /updateAddress - 更新收货地址
    // GET /getDefaultAddress - 获取默认地址
    // GET /getAddressList - 获取地址列表
    // POST /deleteAddress - 删除地址
    // POST /setDefaultAddress - 设置默认地址
    // GET /getAddressDetail - 获取地址详情
}
```

#### SignController
```csharp
[ApiController]
[Route("api")]
[Authorize]
public class SignController : ControllerBase
{
    // GET /sign_info - 获取签到信息
    // POST /sign - 执行签到
    // POST /sign_add - 执行签到(旧版)
}
```

#### MallController
```csharp
[ApiController]
[Route("api")]
[Authorize]
public class MallController : ControllerBase
{
    // GET /get_diamond_list - 获取钻石商品列表
    // GET /createOrderProducts - 创建钻石订单
    // GET /get_diamond_order_log - 获取订单状态
}
```

### 新增服务

#### IAddressService
```csharp
public interface IAddressService
{
    Task<UserAddress> AddAddressAsync(int userId, AddAddressRequest request);
    Task<bool> UpdateAddressAsync(int userId, int addressId, UpdateAddressRequest request);
    Task<UserAddress?> GetDefaultAddressAsync(int userId);
    Task<List<UserAddress>> GetAddressListAsync(int userId);
    Task<bool> DeleteAddressAsync(int userId, int addressId);
    Task<bool> SetDefaultAddressAsync(int userId, int addressId);
    Task<UserAddress?> GetAddressDetailAsync(int userId, int addressId);
}
```

#### ISignService
```csharp
public interface ISignService
{
    Task<SignInfoResponse> GetSignInfoAsync(int userId);
    Task<SignResult> DoSignAsync(int userId);
    Task<SignResult> DoSignAddAsync(int userId);
}
```

#### IMallService
```csharp
public interface IMallService
{
    Task<List<DiamondProduct>> GetDiamondListAsync();
    Task<DiamondOrder> CreateOrderProductsAsync(int userId, CreateDiamondOrderRequest request);
    Task<DiamondOrderStatus> GetDiamondOrderLogAsync(int userId, string orderNo);
}
```

## Data Models

### 现有实体 (已存在于SQL Server)

以下实体已在 `HoneyBox.Model/Entities/` 中定义：

- `UserAddress` - 用户收货地址
- `UserSign` - 用户签到记录
- `SignConfig` - 签到配置
- `DiamondProduct` - 钻石商品
- `DiamondOrder` - 钻石订单
- `UserRecharge` - 用户充值记录
- `UserItemCard` - 用户道具卡
- `RedeemCode` - 兑换码

### 需要验证的数据表

迁移前需通过MCP SQL Server工具验证以下表是否存在：

```sql
-- 地址模块
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'user_address';

-- 签到模块
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'user_sign';
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'sign_config';

-- 钻石商城
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'diamond_product';
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'diamond_order';

-- 权益模块
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'user_vip_reward';
SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = 'vip_level_reward';
```

### DTO模型

#### AddAddressRequest
```csharp
public class AddAddressRequest
{
    public string Name { get; set; }        // 收货人姓名
    public string Phone { get; set; }       // 手机号
    public string Province { get; set; }    // 省
    public string City { get; set; }        // 市
    public string District { get; set; }    // 区
    public string Address { get; set; }     // 详细地址
    public bool IsDefault { get; set; }     // 是否默认
}
```

#### SignInfoResponse
```csharp
public class SignInfoResponse
{
    public bool IsSignedToday { get; set; }     // 今日是否已签到
    public int ContinuousDays { get; set; }     // 连续签到天数
    public int TotalDays { get; set; }          // 累计签到天数
    public List<SignReward> Rewards { get; set; } // 签到奖励配置
}
```

## Correctness Properties

*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*

### Property 1: 地址操作一致性
*For any* 用户和地址操作序列，添加地址后通过getAddressList应能查询到该地址，删除后应查询不到
**Validates: Requirements 1.1, 1.4, 1.5**

### Property 2: 默认地址唯一性
*For any* 用户，设置某地址为默认后，该用户只能有一个默认地址，其他地址的默认标记应为false
**Validates: Requirements 1.3, 1.6**

### Property 3: 余额支付扣减正确性
*For any* 余额支付操作，支付后用户余额应等于支付前余额减去支付金额
**Validates: Requirements 2.2**

### Property 4: 签到幂等性
*For any* 用户在同一天内多次调用签到接口，只有第一次应成功，后续调用应返回已签到状态
**Validates: Requirements 3.1, 3.2**

### Property 5: 签到连续天数计算
*For any* 用户签到序列，连续签到天数应正确反映实际连续签到情况
**Validates: Requirements 3.1**

### Property 6: 福利屋积分扣减
*For any* 福利屋购买操作，购买后用户积分应等于购买前积分减去消耗积分
**Validates: Requirements 4.2**

### Property 7: 收藏状态一致性
*For any* 商品收藏操作，添加收藏后collect_status应返回已收藏，取消后应返回未收藏
**Validates: Requirements 9.1, 9.2, 9.3**

### Property 8: 兑换码使用唯一性
*For any* 兑换码，使用后不能再次使用，应返回已使用错误
**Validates: Requirements 11.1**

### Property 9: 保险柜移入移出一致性
*For any* 奖品，移入保险柜后应在保险柜列表中可见，移出后应不在保险柜列表中
**Validates: Requirements 12.1, 12.2**

## Error Handling

### 通用错误码

| 错误码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 未授权/Token无效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

### 业务错误码

| 错误码 | 说明 |
|--------|------|
| 1001 | 地址不存在 |
| 1002 | 地址数量超过限制 |
| 2001 | 余额不足 |
| 2002 | 支付订单不存在 |
| 3001 | 今日已签到 |
| 3002 | 签到配置不存在 |
| 4001 | 积分不足 |
| 4002 | 福利屋活动已结束 |
| 5001 | 兑换码无效 |
| 5002 | 兑换码已使用 |

### 响应格式

```json
{
    "code": 0,
    "msg": "success",
    "data": { ... }
}
```

错误响应：
```json
{
    "code": 1001,
    "msg": "地址不存在",
    "data": null
}
```

## Testing Strategy

### 单元测试

- 使用 xUnit 作为测试框架
- 使用 Moq 进行依赖模拟
- 测试覆盖所有Service方法
- 测试边界条件和异常情况

### 属性测试

- 使用 FsCheck 进行属性测试
- 每个属性测试运行100次迭代
- 测试标签格式: **Feature: api-migration-remaining, Property {number}: {property_text}**

### 集成测试

- 使用 WebApplicationFactory 进行API集成测试
- 使用内存数据库进行测试隔离
- 测试完整的请求-响应流程

### 测试文件结构

```
server/C#/HoneyBox/tests/
├── HoneyBox.Api.Tests/
│   ├── Controllers/
│   │   ├── AddressControllerTests.cs
│   │   ├── SignControllerTests.cs
│   │   └── MallControllerTests.cs
│   └── Integration/
│       └── ApiIntegrationTests.cs
└── HoneyBox.Core.Tests/
    └── Services/
        ├── AddressServiceTests.cs
        ├── SignServiceTests.cs
        └── MallServiceTests.cs
```

## Migration Checklist

每个接口迁移需完成以下步骤：

- [ ] 1. 在PHP源码中找到对应控制器方法
- [ ] 2. 分析业务逻辑和数据库操作
- [ ] 3. 使用MCP查询SQL Server表结构
- [ ] 4. 如缺少表，创建Entity和Migration
- [ ] 5. 实现Service层业务逻辑
- [ ] 6. 实现Controller层API端点
- [ ] 7. 添加DTO映射配置
- [ ] 8. 编写单元测试
- [ ] 9. 进行API测试验证
- [ ] 10. 更新API接口清单状态