130 lines
6.6 KiB
Markdown
130 lines
6.6 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
本文档定义了抽奖系统从PHP迁移到.NET 8的需求。抽奖系统是盲盒平台的核心功能，包括一番赏抽奖、无限赏抽奖、抽奖结果查询、中奖记录展示等功能。迁移需要确保与PHP API的完全兼容性，同时保持抽奖算法的准确性和公平性。
|
||
|
||
## Glossary
|
||
|
||
- **Lottery_Engine**: 抽奖引擎，负责执行抽奖算法和概率计算
|
||
- **Prize_Service**: 奖品服务，负责奖品查询和库存管理
|
||
- **Order_Item**: 订单奖品记录，存储用户抽中的奖品信息
|
||
- **Goods_Item**: 商品奖品项，存储商品的奖品配置和库存
|
||
- **Shang_Level**: 赏品等级，如A赏、B赏等奖品分类
|
||
- **Weighted_Random**: 权重随机算法，根据库存计算概率进行抽奖
|
||
- **Prize_Log**: 中奖记录，展示用户的抽奖历史
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 一番赏抽奖结果查询
|
||
|
||
**User Story:** As a user, I want to view my lottery results after payment, so that I can see what prizes I won.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user requests lottery results with a valid order number, THE Prize_Service SHALL return the list of won prizes for that order
|
||
2. WHEN a user requests lottery results with an invalid order number, THE Prize_Service SHALL return an empty list
|
||
3. THE Prize_Service SHALL return prize details including title, image, price, recovery value, prize code, and luck number
|
||
4. THE Prize_Service SHALL format the response to match PHP API structure with snake_case field names
|
||
|
||
### Requirement 2: 无限赏抽奖结果查询
|
||
|
||
**User Story:** As a user, I want to view my infinite lottery results, so that I can see what prizes I won from infinite pool.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user requests infinite lottery results with a valid order number, THE Prize_Service SHALL return the list of won prizes
|
||
2. WHEN the order type is infinite lottery (type=2), THE Prize_Service SHALL query from infinite order items
|
||
3. THE Prize_Service SHALL return prize details consistent with the one-shot lottery format
|
||
|
||
### Requirement 3: 一番赏中奖记录查询
|
||
|
||
**User Story:** As a user, I want to view winning records for a specific product, so that I can see who won what prizes.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user requests winning records for a product, THE Prize_Service SHALL return paginated winning records
|
||
2. WHEN a shang_id filter is provided, THE Prize_Service SHALL filter records by prize level
|
||
3. THE Prize_Service SHALL return category list for filtering options
|
||
4. THE Prize_Service SHALL group records by order_id, goodslist_id, and user_id with prize count
|
||
5. THE Prize_Service SHALL mask user nicknames for privacy (show partial name with ***)
|
||
6. THE Prize_Service SHALL order records by time descending (newest first)
|
||
|
||
### Requirement 4: 无限赏中奖记录查询
|
||
|
||
**User Story:** As a user, I want to view winning records for infinite lottery products, so that I can see recent winners.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user requests infinite winning records, THE Prize_Service SHALL return paginated records for infinite lottery type
|
||
2. THE Prize_Service SHALL filter records by order_type=2 (infinite lottery)
|
||
3. THE Prize_Service SHALL return records with user info, prize info, and timestamp
|
||
|
||
### Requirement 5: 每日抽奖记录查询
|
||
|
||
**User Story:** As a user, I want to view daily lottery records for infinite products, so that I can track daily activity.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user requests daily records for a product, THE Prize_Service SHALL return today's winning records
|
||
2. THE Prize_Service SHALL filter records by current date
|
||
3. THE Prize_Service SHALL return records ordered by time descending
|
||
|
||
### Requirement 6: 道具卡抽奖
|
||
|
||
**User Story:** As a user, I want to use item cards to draw prizes, so that I can get prizes without paying.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a user uses an item card for lottery, THE Lottery_Engine SHALL validate the item card ownership
|
||
2. WHEN the item card is valid, THE Lottery_Engine SHALL execute the lottery draw
|
||
3. WHEN the item card is used, THE Lottery_Engine SHALL mark the item card as consumed
|
||
4. IF the item card is invalid or already used, THEN THE Lottery_Engine SHALL return an error message
|
||
|
||
### Requirement 7: 抽奖算法引擎
|
||
|
||
**User Story:** As a system, I want to execute fair lottery draws, so that prizes are distributed according to configured probabilities.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Lottery_Engine SHALL calculate prize probability based on remaining stock (surplus_stock / total_surplus_stock * 100)
|
||
2. THE Lottery_Engine SHALL use weighted random selection algorithm for prize selection
|
||
3. THE Lottery_Engine SHALL exclude prizes with zero remaining stock from the draw pool
|
||
4. THE Lottery_Engine SHALL deduct inventory atomically after prize selection
|
||
5. THE Lottery_Engine SHALL record draw results in order_item table
|
||
6. THE Lottery_Engine SHALL generate unique prize_code for each won prize
|
||
7. IF all prizes are depleted, THEN THE Lottery_Engine SHALL return an error indicating no available prizes
|
||
|
||
### Requirement 8: 库存管理
|
||
|
||
**User Story:** As a system, I want to manage prize inventory accurately, so that overselling is prevented.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a prize is won, THE Prize_Service SHALL decrement surplus_stock by 1 atomically
|
||
2. THE Prize_Service SHALL use database transactions to ensure inventory consistency
|
||
3. IF concurrent draws occur, THE Prize_Service SHALL use optimistic locking to prevent race conditions
|
||
4. THE Prize_Service SHALL validate stock availability before confirming the draw
|
||
|
||
### Requirement 9: 抽奖记录持久化
|
||
|
||
**User Story:** As a system, I want to persist all lottery records, so that results can be audited and queried.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a lottery draw completes, THE Prize_Service SHALL create order_item records for each prize
|
||
2. THE Prize_Service SHALL record user_id, goods_id, goodslist_id, shang_id, prize_code, and timestamp
|
||
3. THE Prize_Service SHALL set source=1 for lottery-won prizes (vs source=0 for purchased)
|
||
4. THE Prize_Service SHALL set appropriate order_type based on lottery type (1=一番赏, 2=无限赏, etc.)
|
||
|
||
### Requirement 10: API响应格式兼容
|
||
|
||
**User Story:** As a frontend developer, I want consistent API responses, so that existing frontend code works without changes.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE API SHALL return responses in format: { "status": 1, "msg": "success", "data": {...} }
|
||
2. THE API SHALL use snake_case for all field names in response
|
||
3. THE API SHALL return status=0 with error message for failures
|
||
4. THE API SHALL maintain backward compatibility with PHP API response structure
|