HaniBlindBox/.kiro/specs/user-management-migration/requirements.md

Requirements Document

Introduction

本文档定义了用户管理系统从PHP迁移到.NET 8的需求规范。用户管理系统包括用户资产管理、VIP等级系统、优惠券系统、任务系统、推荐关系管理、排行榜系统、兑换码系统和福利屋系统等功能模块。

Glossary

• User_Management_System: 用户管理系统，负责管理用户资产、等级、优惠券等功能
• Asset_Service: 资产服务，处理用户余额、积分、吧唧币等资产变更
• VIP_Service: VIP服务，处理用户VIP等级计算和升级
• Coupon_Service: 优惠券服务，处理优惠券的分享、领取、合成等功能
• Task_Service: 任务服务，处理每日/每周任务的进度计算和奖励发放
• Invitation_Service: 推荐服务，处理用户推荐关系和奖励
• Rank_Service: 排行榜服务，处理周榜和月榜排名
• Redeem_Service: 兑换码服务，处理兑换码验证和奖励发放
• Welfare_Service: 福利屋服务，处理福利活动的展示和参与

Requirements

Requirement 1: 用户资产明细查询

User Story: As a user, I want to view my asset transaction records, so that I can track my balance, integral, and score changes.

Acceptance Criteria

1. WHEN a user requests balance records with type filter, THE Asset_Service SHALL return paginated balance change records matching the filter criteria
2. WHEN a user requests integral records with type filter, THE Asset_Service SHALL return paginated integral change records matching the filter criteria
3. WHEN a user requests score records with type filter, THE Asset_Service SHALL return paginated score change records matching the filter criteria
4. WHEN a user requests payment records, THE Asset_Service SHALL return paginated payment records
5. FOR ALL asset record queries, THE Asset_Service SHALL format timestamps as "Y-m-d H:i:s" format
6. FOR ALL asset record queries, THE Asset_Service SHALL return last_page for pagination

Requirement 2: VIP等级系统

User Story: As a user, I want to view my VIP level and upgrade progress, so that I can understand my membership benefits.

Acceptance Criteria

1. WHEN a user requests VIP information, THE VIP_Service SHALL calculate current VIP level based on total order consumption
2. WHEN a user's consumption meets upgrade threshold, THE VIP_Service SHALL automatically upgrade the user's VIP level
3. WHEN a user requests VIP list, THE VIP_Service SHALL return all VIP levels with conditions and privileges
4. THE VIP_Service SHALL calculate upgrade progress percentage based on current consumption and next level threshold
5. WHEN a user reaches maximum VIP level (5), THE VIP_Service SHALL indicate no further upgrades available

Requirement 3: 优惠券列表查询

User Story: As a user, I want to view my coupons, so that I can manage and use them.

Acceptance Criteria

1. WHEN a user requests coupon list with status=1, THE Coupon_Service SHALL return unused coupons ordered by id desc
2. WHEN a user requests coupon list with status=2, THE Coupon_Service SHALL return shared coupons ordered by share_time desc
3. FOR ALL coupons, THE Coupon_Service SHALL return level_text and level_img based on coupon level (1=特级赏券, 2=终极赏券, 3=高级赏券, 4=普通赏券)
4. THE Coupon_Service SHALL return y_count (today's claimed count), z_count (total limit=50), user_integral, ke_hc_count (max synthesis=20), sun_hao (loss rate=10%)

Requirement 4: 优惠券详情查询

User Story: As a user, I want to view coupon details, so that I can see who claimed my shared coupon.

Acceptance Criteria

1. WHEN a user requests coupon detail, THE Coupon_Service SHALL return coupon information including level, share_time, num, own2
2. THE Coupon_Service SHALL return yl_count (claimed count) and yl_integral_count (total claimed integral)
3. THE Coupon_Service SHALL return share_user information (nickname, headimg)
4. THE Coupon_Service SHALL return yl_list with claimer details and lucky_king flag for highest amount

Requirement 5: 优惠券分享

User Story: As a user, I want to share my coupon, so that others can claim it.

Acceptance Criteria

1. WHEN a user shares a coupon, THE Coupon_Service SHALL update coupon status to 2 (shared)
2. WHEN a user shares a coupon, THE Coupon_Service SHALL set share_time to current timestamp
3. IF the coupon does not belong to the user, THEN THE Coupon_Service SHALL return error

Requirement 6: 优惠券领取

User Story: As a user, I want to claim shared coupons, so that I can get integral rewards.

Acceptance Criteria

1. WHEN a user claims a coupon, THE Coupon_Service SHALL generate random amount from remaining pool
2. WHEN a user claims a coupon, THE Coupon_Service SHALL add integral to user's account
3. IF the user is the coupon owner, THEN THE Coupon_Service SHALL return error with code 2222
4. IF the user already claimed this coupon, THEN THE Coupon_Service SHALL return error with code 2222
5. IF the user reached daily claim limit, THEN THE Coupon_Service SHALL return error
6. IF the coupon has no remaining amount, THEN THE Coupon_Service SHALL return error with code 2222
7. WHEN a coupon is claimed, THE Coupon_Service SHALL give share reward to coupon owner

Requirement 7: 优惠券合成

User Story: As a user, I want to synthesize multiple coupons into a higher level coupon, so that I can get better rewards.

Acceptance Criteria

1. WHEN a user calculates synthesis, THE Coupon_Service SHALL return new coupon level based on total value
2. THE Coupon_Service SHALL apply 10% loss rate to synthesis
3. IF any coupon is level 1 or 2 (特级/终极), THEN THE Coupon_Service SHALL return error
4. IF coupon count exceeds 20, THEN THE Coupon_Service SHALL return error
5. WHEN synthesis is confirmed, THE Coupon_Service SHALL delete original coupons and create new coupon

Requirement 8: 任务系统

User Story: As a user, I want to complete tasks and claim rewards, so that I can earn extra benefits.

Acceptance Criteria

1. WHEN a user requests task list, THE Task_Service SHALL return tasks with completion status and progress
2. FOR daily tasks (type=1), THE Task_Service SHALL calculate progress within current day
3. FOR weekly tasks (type=2), THE Task_Service SHALL calculate progress within current week (Monday to Sunday)
4. FOR invitation tasks (cate=1), THE Task_Service SHALL count new referrals in the period
5. FOR lottery tasks (cate=2), THE Task_Service SHALL count paid orders in the period
6. WHEN a user claims task reward, THE Task_Service SHALL verify task completion and add ou_qi reward
7. IF the user already claimed the task in current period, THEN THE Task_Service SHALL return error

Requirement 9: 推荐关系管理

User Story: As a user, I want to invite friends and track my referrals, so that I can earn referral rewards.

Acceptance Criteria

1. WHEN a user requests invitation info, THE Invitation_Service SHALL return referral code and statistics
2. THE Invitation_Service SHALL return recent referrals with nickname, headimg, register_time, and reward
3. WHEN a user binds invite code, THE Invitation_Service SHALL update user's pid to inviter's id
4. IF the invite code is invalid, THEN THE Invitation_Service SHALL return error
5. IF the user already has a referrer, THEN THE Invitation_Service SHALL return error

Requirement 10: 排行榜系统

User Story: As a user, I want to view consumption rankings, so that I can see my position among other users.

Acceptance Criteria

1. WHEN a user requests week ranking, THE Rank_Service SHALL return top 30 users by weekly consumption
2. WHEN a user requests month ranking, THE Rank_Service SHALL return top 30 users by monthly consumption
3. THE Rank_Service SHALL return user's own rank and consumption amount
4. THE Rank_Service SHALL return prize information for each rank position
5. THE Rank_Service SHALL return date range and end_date for the ranking period

Requirement 11: 兑换码系统

User Story: As a user, I want to use redemption codes, so that I can get rewards.

Acceptance Criteria

1. WHEN a user submits a redemption code, THE Redeem_Service SHALL verify code validity
2. IF the code is valid, THEN THE Redeem_Service SHALL grant reward and mark code as used
3. IF the code is invalid or already used, THEN THE Redeem_Service SHALL return error
4. THE Redeem_Service SHALL return reward type and amount after successful redemption

Requirement 12: 福利屋列表

User Story: As a user, I want to view welfare house activities, so that I can participate and win prizes.

Acceptance Criteria

1. WHEN a user requests welfare list with type=1, THE Welfare_Service SHALL return ongoing activities
2. WHEN a user requests welfare list with type=3, THE Welfare_Service SHALL return completed activities ordered by open_time desc
3. THE Welfare_Service SHALL filter activities by user's unlock_amount (total consumption)
4. FOR ALL activities, THE Welfare_Service SHALL return join_count (participation count)
5. THE Welfare_Service SHALL format time fields as "Y-m-d H:i:s"

Requirement 13: 福利屋详情

User Story: As a user, I want to view welfare house details, so that I can understand the activity rules and prizes.

Acceptance Criteria

1. WHEN a user requests welfare detail, THE Welfare_Service SHALL verify user meets unlock_amount requirement
2. THE Welfare_Service SHALL return goods info, prize list, join_count, and user's participation count
3. THE Welfare_Service SHALL return user's consumption data within activity period
4. THE Welfare_Service SHALL return activity status (waiting/ongoing/ended/to_open/opened)

Requirement 14: 福利屋参与记录

User Story: As a user, I want to view welfare house participation and winning records, so that I can track my activities.

Acceptance Criteria

1. WHEN a user requests participants list, THE Welfare_Service SHALL return users who participated in the activity
2. WHEN a user requests winning records, THE Welfare_Service SHALL return users who won prizes
3. WHEN a user requests own participation records, THE Welfare_Service SHALL return user's participation history
4. WHEN a user requests own winning records, THE Welfare_Service SHALL return user's winning history

Requirement 15: API文档更新

User Story: As a developer, I want the API documentation to reflect migration status, so that I can track migration progress.

Acceptance Criteria

1. WHEN an interface is migrated, THE Documentation SHALL be updated with migration status marker
2. THE Documentation SHALL include new interface address for migrated endpoints
3. THE Documentation SHALL maintain backward compatibility information