HaniBlindBox/.kiro/specs/goods-system-migration/requirements.md

Requirements Document

Introduction

本文档定义了将PHP商品系统迁移到.NET 8的需求规范。商品系统是抽赏平台的核心模块，包括商品列表、详情、分类、库存管理、收藏、中奖记录等功能。迁移过程需要保持与原PHP系统的功能一致性和API兼容性。

Glossary

• Goods_Service: 商品服务，负责商品列表、详情、配置等查询功能
• Collection_Service: 收藏服务，负责用户商品收藏管理
• Prize_Service: 奖品服务，负责奖品统计和中奖记录查询
• Cache_Service: 缓存服务，负责商品数据的Redis缓存管理
• GoodsType: 商品类型，包括一番赏、无限赏、擂台赏、积分赏等
• GoodsList: 商品奖品列表，包含每个商品的奖品配置
• GoodsExtend: 商品扩展配置，包含支付方式、抵扣设置等
• BoxNumber: 箱号，商品的分箱编号
• ShangId: 赏品分类ID，如A赏、B赏、C赏等

Requirements

Requirement 1: 商品列表查询

User Story: As a user, I want to browse goods list with category filtering, so that I can find products I'm interested in.

Acceptance Criteria

1. WHEN a user requests goods list with type parameter, THE Goods_Service SHALL return paginated goods matching the specified type
2. WHEN type parameter is -1, THE Goods_Service SHALL return all available goods
3. WHEN a user requests goods list, THE Goods_Service SHALL include join_count from Redis cache or database
4. THE Goods_Service SHALL filter out goods with status != 1 (inactive goods)
5. THE Goods_Service SHALL apply unlock_amount filtering based on user's total consumption
6. THE Goods_Service SHALL return goods sorted by sort field descending, then by id descending

Requirement 2: 商品详情查询

User Story: As a user, I want to view goods details including prize list and probability, so that I can make informed decisions.

Acceptance Criteria

1. WHEN a user requests goods detail, THE Goods_Service SHALL return complete goods information including prize list
2. WHEN goods_num is 0, THE Goods_Service SHALL automatically select an available box number
3. THE Goods_Service SHALL calculate and return probability (pro) for each prize item
4. THE Goods_Service SHALL return lock_info including lock status, lock user info, and remaining time
5. THE Goods_Service SHALL return join_user list (recent participants' avatars)
6. THE Goods_Service SHALL return collection_is indicating if user has collected this goods
7. THE Goods_Service SHALL return limitInfo including daily and global purchase limits

Requirement 3: 商品子奖品查询

User Story: As a user, I want to view child prizes of a parent prize, so that I can see detailed prize breakdown.

Acceptance Criteria

1. WHEN a user requests children prizes, THE Goods_Service SHALL return all child items for the specified goods_list_id
2. THE Goods_Service SHALL calculate real_pro (real probability) for each child prize
3. THE Goods_Service SHALL include shang_info for each child prize

Requirement 4: 商品扩展配置查询

User Story: As a user, I want to know available payment methods for a goods, so that I can choose my preferred payment.

Acceptance Criteria

1. WHEN a user requests goods extend config, THE Goods_Service SHALL return payment method settings
2. IF goods has specific extend config, THE Goods_Service SHALL return goods-specific settings
3. IF goods has no specific extend config, THE Goods_Service SHALL return default settings from goods_type table

Requirement 5: 商品箱号管理

User Story: As a user, I want to browse and select different box numbers, so that I can choose my preferred box.

Acceptance Criteria

1. WHEN a user requests box list, THE Goods_Service SHALL return paginated box groups (e.g., 1-10, 11-20)
2. WHEN a user requests box detail, THE Goods_Service SHALL return boxes with surplus stock info
3. THE Goods_Service SHALL support sorting by box number (asc/desc) and surplus stock (desc)
4. THE Goods_Service SHALL include goodslist summary for each box

Requirement 6: 商品收藏功能

User Story: As a user, I want to collect/uncollect goods, so that I can easily find my favorite products.

Acceptance Criteria

1. WHEN a user adds a goods to collection, THE Collection_Service SHALL create a collection record
2. WHEN a user removes a goods from collection, THE Collection_Service SHALL delete the collection record
3. IF user already collected the goods, THE Collection_Service SHALL return error when adding again
4. WHEN a user requests collection list, THE Collection_Service SHALL return paginated collection with goods info

Requirement 7: 商品奖品统计

User Story: As a user, I want to see prize statistics, so that I can understand the prize distribution.

Acceptance Criteria

1. WHEN a user requests prize count, THE Prize_Service SHALL return total and surplus count by category
2. WHEN a user requests prize content, THE Prize_Service SHALL return detailed prize list for specified box

Requirement 8: 中奖记录查询

User Story: As a user, I want to view winning records, so that I can see who won what prizes.

Acceptance Criteria

1. WHEN a user requests prize logs, THE Prize_Service SHALL return paginated winning records
2. THE Prize_Service SHALL support filtering by shang_id (prize category)
3. THE Prize_Service SHALL return category list for filtering options
4. THE Prize_Service SHALL include user info, prize info, and winning time for each record

Requirement 9: 缓存管理

User Story: As a system, I want to cache frequently accessed data, so that I can improve response performance.

Acceptance Criteria

1. THE Cache_Service SHALL cache goods list with 30 seconds expiry
2. THE Cache_Service SHALL cache goods detail with 5 minutes expiry
3. THE Cache_Service SHALL cache join_count with 5 minutes expiry
4. WHEN goods data changes, THE Cache_Service SHALL invalidate related cache keys

Requirement 10: API兼容性

User Story: As a frontend developer, I want the new API to be compatible with existing calls, so that I don't need to modify frontend code.

Acceptance Criteria

1. THE Goods_Service SHALL maintain the same request/response format as PHP API
2. THE Goods_Service SHALL use POST method for endpoints that PHP uses POST
3. THE Goods_Service SHALL return status, msg, data structure consistent with PHP API
4. WHEN migration is complete, THE API documentation SHALL be updated with migration status