# Requirements Document

## Introduction

本文档定义了福利与任务管理模块从老项目（PHP ThinkPHP + Layui）迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）的功能需求。该模块包含奖励管理、签到配置、任务管理和权益等级四个子模块。

## Glossary

- **Admin_System**: 后台管理系统
- **Reward_Manager**: 奖励管理模块，用于配置各类奖励（优惠券/钻石/货币）
- **SignConfig_Manager**: 签到配置模块，用于配置每日签到和累计签到奖励
- **Task_Manager**: 任务管理模块，用于配置每日/每周任务
- **QyLevel_Manager**: 权益等级模块，用于配置用户权益等级和对应奖品
- **Reward_Type**: 奖励类型，包括优惠券(1)、钻石(2)、货币1/UU币(3)、货币2/达达券(4)
- **Sign_Type**: 签到类型，包括每日签到(1)、累计签到(2)
- **Task_Type**: 任务分类，包括每日任务(1)、每周任务(2)
- **QyLevel_Prize_Type**: 权益等级奖品类型，包括优惠券(1)、实物奖品(2)

## Requirements

### Requirement 1: 奖励管理列表

**User Story:** As an administrator, I want to view and manage reward configurations, so that I can control the rewards available in the system.

#### Acceptance Criteria

1. WHEN an administrator accesses the reward list page, THE Reward_Manager SHALL display a paginated list of rewards with ID, title, type, value, associated ID, creation time, and status
2. WHEN an administrator searches by reward type, THE Reward_Manager SHALL filter the list to show only rewards of the selected type
3. WHEN an administrator searches by keyword, THE Reward_Manager SHALL filter the list to show rewards with titles containing the keyword
4. WHEN an administrator clicks the status toggle, THE Reward_Manager SHALL update the reward status and persist the change
5. WHEN an administrator clicks the add button, THE Reward_Manager SHALL open a form dialog for creating a new reward
6. WHEN an administrator clicks the edit button, THE Reward_Manager SHALL open a form dialog pre-filled with the reward data
7. WHEN an administrator clicks the delete button, THE Reward_Manager SHALL show a confirmation dialog and delete the reward upon confirmation

### Requirement 2: 奖励新增/编辑

**User Story:** As an administrator, I want to create and edit rewards, so that I can configure different types of rewards for users.

#### Acceptance Criteria

1. WHEN an administrator selects reward type as coupon, THE Reward_Manager SHALL display a coupon selection dropdown
2. WHEN an administrator selects reward type as diamond/currency, THE Reward_Manager SHALL display a value input field
3. WHEN an administrator submits a coupon reward without selecting a coupon, THE Reward_Manager SHALL prevent submission and show an error message
4. WHEN an administrator submits a valid reward form, THE Reward_Manager SHALL save the reward and close the dialog
5. THE Reward_Manager SHALL validate that reward value is a positive number for non-coupon types

### Requirement 3: 签到配置列表

**User Story:** As an administrator, I want to view and manage sign-in configurations, so that I can control daily and cumulative sign-in rewards.

#### Acceptance Criteria

1. WHEN an administrator accesses the sign config page, THE SignConfig_Manager SHALL display tabs for daily sign-in and cumulative sign-in
2. WHEN an administrator switches tabs, THE SignConfig_Manager SHALL load and display the corresponding sign-in configurations
3. WHEN an administrator views the list, THE SignConfig_Manager SHALL display ID, title, icon, day number, reward information, sort order, and status
4. WHEN an administrator clicks the status toggle, THE SignConfig_Manager SHALL update the configuration status
5. WHEN an administrator edits the sort value inline, THE SignConfig_Manager SHALL update the sort order immediately
6. WHEN an administrator clicks the add button, THE SignConfig_Manager SHALL open a form dialog for creating a new configuration
7. WHEN an administrator clicks the edit button, THE SignConfig_Manager SHALL open a form dialog pre-filled with the configuration data
8. WHEN an administrator clicks the edit reward button, THE SignConfig_Manager SHALL open a reward configuration dialog
9. WHEN an administrator clicks the delete button, THE SignConfig_Manager SHALL show a confirmation dialog and delete the configuration upon confirmation

### Requirement 4: 签到配置新增/编辑

**User Story:** As an administrator, I want to create and edit sign-in configurations, so that I can set up sign-in rewards for different days.

#### Acceptance Criteria

1. WHEN an administrator creates a daily sign-in config, THE SignConfig_Manager SHALL require title, day number, and at least one reward
2. WHEN an administrator creates a cumulative sign-in config, THE SignConfig_Manager SHALL require title, cumulative day count, and at least one reward
3. WHEN an administrator configures rewards, THE SignConfig_Manager SHALL allow multiple reward types (diamond, UU coin, dada coin, coupon)
4. WHEN an administrator uploads an icon, THE SignConfig_Manager SHALL preview the uploaded image
5. WHEN an administrator submits a valid form, THE SignConfig_Manager SHALL save the configuration and associated rewards

### Requirement 5: 任务管理列表

**User Story:** As an administrator, I want to view and manage task configurations, so that I can control daily and weekly tasks for users.

#### Acceptance Criteria

1. WHEN an administrator accesses the task list page, THE Task_Manager SHALL display a paginated list of tasks with ID, category, name, required count, reward value, sort order, and creation time
2. WHEN an administrator searches by task title, THE Task_Manager SHALL filter the list to show tasks with titles containing the keyword
3. WHEN an administrator filters by task category, THE Task_Manager SHALL show only tasks of the selected category (daily/weekly)
4. WHEN an administrator clicks the add button, THE Task_Manager SHALL open a form dialog for creating a new task
5. WHEN an administrator clicks the edit button, THE Task_Manager SHALL open a form dialog pre-filled with the task data
6. WHEN an administrator clicks the delete button, THE Task_Manager SHALL show a confirmation dialog and soft-delete the task upon confirmation

### Requirement 6: 任务新增/编辑

**User Story:** As an administrator, I want to create and edit tasks, so that I can configure task requirements and rewards.

#### Acceptance Criteria

1. WHEN an administrator creates a task, THE Task_Manager SHALL require title, category, required count, and reward value
2. WHEN an administrator enters a required count less than or equal to 0, THE Task_Manager SHALL show a validation error
3. WHEN an administrator enters a reward value less than or equal to 0, THE Task_Manager SHALL show a validation error
4. WHEN an administrator submits a valid form, THE Task_Manager SHALL save the task and close the dialog

### Requirement 7: 权益等级列表

**User Story:** As an administrator, I want to view and manage equity levels, so that I can configure user privilege tiers.

#### Acceptance Criteria

1. WHEN an administrator accesses the equity level page, THE QyLevel_Manager SHALL display a list of levels with ID, level number, name, required points, and creation time
2. WHEN an administrator searches by keyword, THE QyLevel_Manager SHALL filter the list to show levels with names containing the keyword
3. WHEN an administrator clicks the edit button, THE QyLevel_Manager SHALL open a form dialog pre-filled with the level data
4. WHEN an administrator clicks the prizes button, THE QyLevel_Manager SHALL open a dialog showing prizes for that level

### Requirement 8: 权益等级编辑

**User Story:** As an administrator, I want to edit equity levels, so that I can adjust level requirements and names.

#### Acceptance Criteria

1. WHEN an administrator edits a level, THE QyLevel_Manager SHALL allow modifying level number, name, and required points
2. WHEN an administrator enters a level number less than or equal to 0, THE QyLevel_Manager SHALL show a validation error
3. WHEN an administrator enters required points less than or equal to 0, THE QyLevel_Manager SHALL show a validation error
4. WHEN an administrator submits a valid form, THE QyLevel_Manager SHALL save the level and close the dialog

### Requirement 9: 权益等级奖品管理

**User Story:** As an administrator, I want to manage prizes for each equity level, so that users can receive rewards when reaching certain levels.

#### Acceptance Criteria

1. WHEN an administrator views level prizes, THE QyLevel_Manager SHALL display a list of prizes with name, type, image, value, exchange price, probability, and sort order
2. WHEN an administrator filters by prize type, THE QyLevel_Manager SHALL show only prizes of the selected type (coupon/physical)
3. WHEN an administrator adds a coupon prize, THE QyLevel_Manager SHALL require coupon selection and quantity
4. WHEN an administrator adds a physical prize, THE QyLevel_Manager SHALL require name, value, exchange price, reference price, probability, and image
5. WHEN an administrator enters a probability value, THE QyLevel_Manager SHALL validate it is between 0 and 100 with at most 2 decimal places
6. WHEN an administrator clicks the delete button, THE QyLevel_Manager SHALL show a confirmation dialog and soft-delete the prize upon confirmation

### Requirement 10: 后端API开发

**User Story:** As a developer, I want backend APIs for welfare and task management, so that the frontend can interact with the system.

#### Acceptance Criteria

1. THE Admin_System SHALL provide RESTful APIs for reward CRUD operations at `/api/business/reward`
2. THE Admin_System SHALL provide RESTful APIs for sign config CRUD operations at `/api/business/signconfig`
3. THE Admin_System SHALL provide RESTful APIs for task CRUD operations at `/api/business/task`
4. THE Admin_System SHALL provide RESTful APIs for equity level CRUD operations at `/api/business/qylevel`
5. THE Admin_System SHALL provide an API to get rewards by reward_id for sign config association
6. THE Admin_System SHALL provide an API to batch update rewards for sign config
7. THE Admin_System SHALL return consistent response format with code, message, and data fields
8. THE Admin_System SHALL validate all input parameters and return appropriate error messages

### Requirement 11: 数据库表创建

**User Story:** As a developer, I want the necessary database tables, so that the system can store equity level data.

#### Acceptance Criteria

1. THE Admin_System SHALL create `equity_levels` table with id, level, title, required_points, created_at, updated_at, deleted_at columns
2. THE Admin_System SHALL create `equity_level_prizes` table with id, level_id, type, title, coupon_id, quantity, value, exchange_price, reference_price, probability, image, prize_code, sort, created_at, updated_at, deleted_at columns
3. THE Admin_System SHALL ensure foreign key relationship between equity_level_prizes and equity_levels

### Requirement 12: 菜单和路由配置

**User Story:** As an administrator, I want to access welfare and task management pages from the menu, so that I can navigate to these features easily.

#### Acceptance Criteria

1. THE Admin_System SHALL add menu items for reward management, sign config, task management, and equity level under a "福利与任务" parent menu
2. THE Admin_System SHALL configure routes for all welfare and task management pages
3. THE Admin_System SHALL apply appropriate permission controls to menu items and routes