# Requirements Document

## Introduction

本文档定义了将PHP订单系统迁移到.NET 8的需求规范。订单系统是抽奖盲盒平台的核心业务模块，包括订单金额计算、订单创建支付、订单查询管理、仓库/盒柜管理等功能。

## Glossary

- **Order_System**: 订单系统，负责处理用户下单、支付、订单管理等业务
- **Order_Service**: 订单服务，提供订单相关的业务逻辑处理
- **Warehouse_Service**: 仓库服务，提供奖品回收、发货等功能
- **Order_Controller**: 订单控制器，处理订单相关的HTTP请求
- **Warehouse_Controller**: 仓库控制器，处理仓库相关的HTTP请求
- **一番赏**: 一种抽奖商品类型，有固定奖池
- **无限赏**: 一种抽奖商品类型，奖池无限
- **商城订单**: 直接购买商品的订单类型
- **盒柜**: 用户的奖品仓库，存放中奖的奖品

## Requirements

### Requirement 1: 一番赏订单金额计算

**User Story:** As a user, I want to calculate the order amount before placing an order, so that I can know the final payment amount after applying discounts.

#### Acceptance Criteria

1. WHEN a user requests order calculation with goods_id, num, prize_num, THE Order_Service SHALL return the calculated order amount
2. WHEN use_money_is is 1, THE Order_Service SHALL deduct available balance from the order total
3. WHEN use_integral_is is 1, THE Order_Service SHALL deduct available integral from the order total
4. WHEN use_money2_is is 1, THE Order_Service SHALL deduct available money2 (哈尼券) from the order total
5. WHEN a valid coupon_id is provided, THE Order_Service SHALL apply the coupon discount to the order
6. THE Order_Service SHALL return goods_info, calculation details, user_assets, and available_coupons in the response

### Requirement 2: 一番赏订单创建

**User Story:** As a user, I want to create an order and pay for it, so that I can participate in the lottery.

#### Acceptance Criteria

1. WHEN a user submits an order with valid parameters, THE Order_Service SHALL create an order record
2. WHEN the order is created successfully, THE Order_Service SHALL return order_num and payment info
3. WHEN using WeChat payment, THE Order_Service SHALL return WeChat pay parameters (appId, timeStamp, nonceStr, package, signType, paySign)
4. WHEN the order total is 0 (fully paid by balance/integral), THE Order_Service SHALL mark the order as paid immediately
5. IF the goods stock is insufficient, THEN THE Order_Service SHALL return an error message
6. IF the user exceeds purchase limits, THEN THE Order_Service SHALL return an error message

### Requirement 3: 无限赏订单金额计算

**User Story:** As a user, I want to calculate the infinite lottery order amount, so that I can know the payment details.

#### Acceptance Criteria

1. WHEN a user requests infinite order calculation, THE Order_Service SHALL return the calculated amount
2. THE Order_Service SHALL support the same discount options as regular orders (balance, integral, money2, coupon)
3. THE Order_Service SHALL validate the goods type is infinite lottery (type=2)

### Requirement 4: 无限赏订单创建

**User Story:** As a user, I want to create an infinite lottery order, so that I can participate in the infinite lottery.

#### Acceptance Criteria

1. WHEN a user submits an infinite order, THE Order_Service SHALL create the order with order_type=2
2. THE Order_Service SHALL handle the infinite lottery specific logic
3. THE Order_Service SHALL return order_num and payment info

### Requirement 5: 商城订单金额计算

**User Story:** As a user, I want to calculate the mall order amount, so that I can purchase products directly.

#### Acceptance Criteria

1. WHEN a user requests mall order calculation, THE Order_Service SHALL return the calculated amount
2. THE Order_Service SHALL support goods_num parameter for quantity
3. THE Order_Service SHALL validate the goods is available for direct purchase

### Requirement 6: 订单列表查询

**User Story:** As a user, I want to view my order list, so that I can track my purchase history.

#### Acceptance Criteria

1. WHEN a user requests order list, THE Order_Service SHALL return paginated order records
2. THE Order_Service SHALL return order details including order_num, goods_title, goods_imgurl, order_total, status, prize_num
3. THE Order_Service SHALL support pagination with page and page_size parameters
4. THE Order_Service SHALL return last_page for pagination

### Requirement 7: 订单详情查询

**User Story:** As a user, I want to view order details, so that I can see the complete order information.

#### Acceptance Criteria

1. WHEN a user requests order detail with order_num, THE Order_Service SHALL return complete order information
2. THE Order_Service SHALL return order_info, prize_list, and payment_records
3. IF the order does not exist or belong to another user, THEN THE Order_Service SHALL return an error

### Requirement 8: 抽奖结果查询（一番赏）

**User Story:** As a user, I want to view my lottery results, so that I can see what prizes I won.

#### Acceptance Criteria

1. WHEN a user requests prize order log with order_num, THE Order_Service SHALL return the prize list
2. THE Order_Service SHALL return prize details including goodslist_title, goodslist_imgurl, goodslist_price, goodslist_money, status
3. THE Order_Service SHALL return luck_no for each prize

### Requirement 9: 抽奖结果查询（无限赏）

**User Story:** As a user, I want to view my infinite lottery results, so that I can see what prizes I won.

#### Acceptance Criteria

1. WHEN a user requests infinite prize order log, THE Order_Service SHALL return the prize list
2. THE Order_Service SHALL handle infinite lottery specific prize display

### Requirement 10: 仓库首页查询

**User Story:** As a user, I want to view my warehouse (盒柜), so that I can manage my prizes.

#### Acceptance Criteria

1. WHEN a user requests warehouse index, THE Warehouse_Service SHALL return paginated prize list
2. THE Warehouse_Service SHALL support status filter (0=待选择, 1=回收, 2=发货, 3=集市)
3. THE Warehouse_Service SHALL return prize details including goodslist_title, goodslist_imgurl, goodslist_price, goodslist_money, status

### Requirement 11: 奖品回收

**User Story:** As a user, I want to recycle my prizes for balance, so that I can get money back.

#### Acceptance Criteria

1. WHEN a user requests prize recovery with order_list_ids, THE Warehouse_Service SHALL process the recovery
2. THE Warehouse_Service SHALL add the recovery amount to user's balance
3. THE Warehouse_Service SHALL update the prize status to recovered
4. THE Warehouse_Service SHALL return the total recovery amount
5. IF any prize is not eligible for recovery, THEN THE Warehouse_Service SHALL return an error

### Requirement 12: 奖品发货申请

**User Story:** As a user, I want to request delivery for my prizes, so that I can receive the physical items.

#### Acceptance Criteria

1. WHEN a user requests prize delivery with order_list_ids and address info, THE Warehouse_Service SHALL create a delivery record
2. THE Warehouse_Service SHALL validate the address information (name, mobile, address)
3. THE Warehouse_Service SHALL update the prize status to pending delivery
4. THE Warehouse_Service SHALL return the delivery_id
5. IF any prize is not eligible for delivery, THEN THE Warehouse_Service SHALL return an error

### Requirement 13: 确认发货

**User Story:** As a user, I want to confirm the delivery, so that the delivery process can proceed.

#### Acceptance Criteria

1. WHEN a user confirms delivery with id, THE Warehouse_Service SHALL update the delivery status
2. IF the delivery does not exist or belong to another user, THEN THE Warehouse_Service SHALL return an error

### Requirement 14: 发货记录查询

**User Story:** As a user, I want to view my delivery records, so that I can track my shipments.

#### Acceptance Criteria

1. WHEN a user requests delivery records, THE Warehouse_Service SHALL return paginated delivery list
2. THE Warehouse_Service SHALL return delivery details including name, mobile (masked), address, status
3. THE Warehouse_Service SHALL support pagination

### Requirement 15: 发货记录详情

**User Story:** As a user, I want to view delivery details, so that I can see the complete shipment information.

#### Acceptance Criteria

1. WHEN a user requests delivery detail with id, THE Warehouse_Service SHALL return complete delivery information
2. THE Warehouse_Service SHALL return items list and logistics information
3. IF the delivery does not exist or belong to another user, THEN THE Warehouse_Service SHALL return an error

### Requirement 16: 回收记录查询

**User Story:** As a user, I want to view my recovery records, so that I can track my recycled prizes.

#### Acceptance Criteria

1. WHEN a user requests recovery records, THE Warehouse_Service SHALL return paginated recovery list
2. THE Warehouse_Service SHALL support pagination

### Requirement 17: 物流信息查询

**User Story:** As a user, I want to view logistics information, so that I can track my package.

#### Acceptance Criteria

1. WHEN a user requests logistics info with id, THE Warehouse_Service SHALL return logistics details
2. THE Warehouse_Service SHALL return company, tracking_no, status, and traces
3. IF the delivery does not exist or belong to another user, THEN THE Warehouse_Service SHALL return an error

### Requirement 18: API响应格式兼容性

**User Story:** As a developer, I want the new API to be compatible with the existing frontend, so that the migration is seamless.

#### Acceptance Criteria

1. THE Order_Controller SHALL return responses in the same format as PHP API (status, msg, data)
2. THE Order_Controller SHALL use snake_case for JSON field names
3. THE Warehouse_Controller SHALL return responses in the same format as PHP API
4. THE Warehouse_Controller SHALL use snake_case for JSON field names