mi-assessment/.kiro/specs/admin-business-modules/requirements.md

Requirements Document

Introduction

本文档定义了学业邑规划 MiAssessment 管理后台业务模块的需求规格。后台管理系统基于 .NET 10 + SQL Server 2022 技术栈，采用 RPC 风格接口（仅 GET/POST 请求）。系统需要在现有的用户、角色、权限、菜单管理基础上，扩展7个核心业务模块：系统配置管理、内容管理、测评管理、用户管理、订单管理、规划师管理和分销管理。

Glossary

• Admin_System: 后台管理系统，用于管理小程序业务数据
• Config_Service: 系统配置服务，管理系统配置项的增删改查
• Content_Service: 内容管理服务，管理轮播图和宣传图
• Assessment_Service: 测评管理服务，管理测评类型、题库、报告分类和结论
• User_Service: 用户管理服务，管理C端用户信息和等级
• Order_Service: 订单管理服务，管理订单列表、详情和退款
• Planner_Service: 规划师管理服务，管理规划师信息和预约记录
• Distribution_Service: 分销管理服务，管理邀请码、佣金和提现
• Operator: 后台运营人员，具有内容管理、订单管理、用户管理权限
• Finance_Staff: 财务人员，具有订单管理、提现审核权限
• Super_Admin: 超级管理员，具有全部权限

Requirements

Requirement 1: 系统配置管理

User Story: As an Operator, I want to manage system configuration items, so that I can dynamically adjust system parameters like assessment prices, commission rates, and customer service information.

Acceptance Criteria

1. WHEN an Operator requests the configuration list, THE Config_Service SHALL return all configuration items grouped by ConfigType
2. WHEN an Operator updates a configuration value, THE Config_Service SHALL validate the value format and persist the change
3. WHEN an Operator updates a price configuration, THE Config_Service SHALL validate that the value is a positive decimal number
4. WHEN an Operator updates a commission rate configuration, THE Config_Service SHALL validate that the value is between 0 and 1
5. IF an Operator attempts to update a configuration with an invalid value, THEN THE Config_Service SHALL return a descriptive error message
6. THE Config_Service SHALL support the following configuration types: price, commission, withdraw, contact, agreement, content
7. WHEN a configuration is updated, THE Config_Service SHALL record the UpdateTime automatically

Requirement 2: 轮播图管理

User Story: As an Operator, I want to manage banner images, so that I can control the promotional content displayed on the mini-program homepage.

Acceptance Criteria

1. WHEN an Operator requests the banner list, THE Content_Service SHALL return banners sorted by Sort field in descending order
2. WHEN an Operator creates a banner, THE Content_Service SHALL validate that ImageUrl is provided and generate a unique Id
3. WHEN an Operator updates a banner, THE Content_Service SHALL validate the LinkType and corresponding LinkUrl/AppId fields
4. IF LinkType is 1 (internal page) or 2 (external link), THEN THE Content_Service SHALL require LinkUrl to be non-empty
5. IF LinkType is 3 (mini-program), THEN THE Content_Service SHALL require both LinkUrl and AppId to be non-empty
6. WHEN an Operator changes banner status, THE Content_Service SHALL update the Status field (0=disabled, 1=enabled)
7. WHEN an Operator deletes a banner, THE Content_Service SHALL perform soft delete by setting IsDeleted to 1
8. WHEN an Operator reorders banners, THE Content_Service SHALL update the Sort field for affected banners

Requirement 3: 宣传图管理

User Story: As an Operator, I want to manage promotional images, so that I can control the promotional content displayed at different positions in the mini-program.

Acceptance Criteria

1. WHEN an Operator requests the promotion list, THE Content_Service SHALL return promotions filtered by Position and sorted by Sort field
2. WHEN an Operator creates a promotion, THE Content_Service SHALL validate that ImageUrl and Position are provided
3. THE Content_Service SHALL support Position values: 1 (homepage bottom), 2 (team page)
4. WHEN an Operator updates a promotion, THE Content_Service SHALL validate the Position value is within allowed range
5. WHEN an Operator changes promotion status, THE Content_Service SHALL update the Status field (0=disabled, 1=enabled)
6. WHEN an Operator deletes a promotion, THE Content_Service SHALL perform soft delete by setting IsDeleted to 1

Requirement 4: 测评类型管理

User Story: As an Operator, I want to manage assessment types, so that I can configure different assessment products with their prices and content.

Acceptance Criteria

1. WHEN an Operator requests the assessment type list, THE Assessment_Service SHALL return all assessment types sorted by Sort field
2. WHEN an Operator creates an assessment type, THE Assessment_Service SHALL validate that Name, Code, and Price are provided
3. THE Assessment_Service SHALL ensure Code is unique across all assessment types
4. WHEN an Operator updates an assessment type price, THE Assessment_Service SHALL validate that Price is a positive decimal
5. WHEN an Operator changes assessment type status, THE Assessment_Service SHALL update Status (0=offline, 1=online, 2=coming soon)
6. WHEN an Operator updates IntroContent, THE Assessment_Service SHALL accept rich text or image URL content
7. WHEN an Operator deletes an assessment type, THE Assessment_Service SHALL perform soft delete by setting IsDeleted to 1

Requirement 5: 题库管理

User Story: As an Operator, I want to manage assessment questions, so that I can configure the question content for each assessment type.

Acceptance Criteria

1. WHEN an Operator requests the question list, THE Assessment_Service SHALL return questions filtered by AssessmentTypeId and sorted by QuestionNo
2. WHEN an Operator creates a question, THE Assessment_Service SHALL validate that AssessmentTypeId, QuestionNo, and Content are provided
3. THE Assessment_Service SHALL ensure QuestionNo is unique within the same AssessmentTypeId
4. WHEN an Operator updates a question, THE Assessment_Service SHALL validate Content is non-empty
5. WHEN an Operator changes question status, THE Assessment_Service SHALL update Status (0=disabled, 1=enabled)
6. WHEN an Operator deletes a question, THE Assessment_Service SHALL perform soft delete by setting IsDeleted to 1
7. WHEN an Operator imports questions in batch, THE Assessment_Service SHALL validate all questions and return detailed error information for invalid entries

Requirement 6: 报告分类管理

User Story: As an Operator, I want to manage report categories, so that I can configure the scoring dimensions and hierarchical structure for assessment reports.

Acceptance Criteria

1. WHEN an Operator requests the category list, THE Assessment_Service SHALL return categories in a hierarchical tree structure
2. WHEN an Operator creates a category, THE Assessment_Service SHALL validate that Name, Code, CategoryType, and ScoreRule are provided
3. THE Assessment_Service SHALL support CategoryType values: 1-8 (八大智能, 个人特质, 细分能力, 先天学习, 学习能力, 大脑类型, 性格类型, 未来能力)
4. THE Assessment_Service SHALL support ScoreRule values: 1 (cumulative 1-10), 2 (binary 0/1)
5. WHEN an Operator creates a sub-category, THE Assessment_Service SHALL validate that ParentId references an existing category
6. WHEN an Operator deletes a category with children, THE Assessment_Service SHALL return an error preventing deletion

Requirement 7: 题目分类映射管理

User Story: As an Operator, I want to manage question-category mappings, so that I can configure which questions contribute to which scoring categories.

Acceptance Criteria

1. WHEN an Operator requests mappings for a question, THE Assessment_Service SHALL return all associated categories
2. WHEN an Operator requests mappings for a category, THE Assessment_Service SHALL return all associated questions
3. WHEN an Operator creates a mapping, THE Assessment_Service SHALL validate that both QuestionId and CategoryId exist
4. THE Assessment_Service SHALL ensure each QuestionId-CategoryId pair is unique
5. WHEN an Operator deletes a mapping, THE Assessment_Service SHALL remove the association record
6. WHEN an Operator batch updates mappings for a question, THE Assessment_Service SHALL replace all existing mappings atomically

Requirement 8: 报告结论管理

User Story: As an Operator, I want to manage report conclusions, so that I can configure the textual conclusions displayed for different scoring results.

Acceptance Criteria

1. WHEN an Operator requests conclusions for a category, THE Assessment_Service SHALL return all conclusions sorted by ConclusionType
2. WHEN an Operator creates a conclusion, THE Assessment_Service SHALL validate that CategoryId, ConclusionType, and Content are provided
3. THE Assessment_Service SHALL support ConclusionType values: 1 (strongest), 2 (stronger), 3 (weaker), 4 (weakest)
4. WHEN an Operator updates a conclusion, THE Assessment_Service SHALL accept rich text Content
5. WHEN an Operator deletes a conclusion, THE Assessment_Service SHALL perform soft delete by setting IsDeleted to 1

Requirement 9: C端用户列表管理

User Story: As an Operator, I want to view and manage C-end user information, so that I can monitor user activities and manage user accounts.

Acceptance Criteria

1. WHEN an Operator requests the user list, THE User_Service SHALL return users with pagination support
2. THE User_Service SHALL support filtering users by: Uid, Phone, Nickname, UserLevel, Status, CreateTime range
3. WHEN an Operator views user details, THE User_Service SHALL return complete user information including balance and income statistics
4. WHEN an Operator changes user status, THE User_Service SHALL update Status (0=disabled, 1=normal)
5. WHEN an Operator changes user level, THE User_Service SHALL update UserLevel (1=normal, 2=partner, 3=channel partner)
6. THE User_Service SHALL display user's parent user information if ParentUserId exists
7. WHEN an Operator exports user list, THE User_Service SHALL generate a downloadable file with selected fields

Requirement 10: 订单列表管理

User Story: As an Operator, I want to view and manage orders, so that I can monitor transactions and handle customer issues.

Acceptance Criteria

1. WHEN an Operator requests the order list, THE Order_Service SHALL return orders with pagination support sorted by CreateTime descending
2. THE Order_Service SHALL support filtering orders by: OrderNo, UserId, OrderType, Status, PayType, CreateTime range
3. WHEN an Operator views order details, THE Order_Service SHALL return complete order information including user details and product information
4. THE Order_Service SHALL display OrderType as: 1 (assessment order), 2 (planning order)
5. THE Order_Service SHALL display Status as: 1 (pending payment), 2 (paid), 3 (completed), 4 (refunding), 5 (refunded), 6 (cancelled)
6. WHEN an Operator exports order list, THE Order_Service SHALL generate a downloadable file with selected fields

Requirement 11: 退款处理

User Story: As a Finance_Staff, I want to process refund requests, so that I can handle customer refund applications properly.

Acceptance Criteria

1. WHEN a Finance_Staff initiates a refund, THE Order_Service SHALL validate that the order Status is 2 (paid) or 3 (completed)
2. WHEN a Finance_Staff initiates a refund, THE Order_Service SHALL update order Status to 4 (refunding)
3. WHEN a refund is completed, THE Order_Service SHALL update order Status to 5 (refunded) and record RefundTime and RefundAmount
4. IF a refund fails, THEN THE Order_Service SHALL revert order Status and record the error reason
5. WHEN processing a refund for an assessment order, THE Order_Service SHALL check if the assessment has been completed
6. THE Order_Service SHALL record RefundReason for audit purposes

Requirement 12: 规划师信息管理

User Story: As an Operator, I want to manage planner information, so that I can configure the planners available for booking in the mini-program.

Acceptance Criteria

1. WHEN an Operator requests the planner list, THE Planner_Service SHALL return planners sorted by Sort field descending
2. WHEN an Operator creates a planner, THE Planner_Service SHALL validate that Name, Avatar, and Price are provided
3. WHEN an Operator updates a planner, THE Planner_Service SHALL validate that Price is a positive decimal
4. WHEN an Operator changes planner status, THE Planner_Service SHALL update Status (0=disabled, 1=enabled)
5. WHEN an Operator deletes a planner, THE Planner_Service SHALL perform soft delete by setting IsDeleted to 1
6. WHEN an Operator reorders planners, THE Planner_Service SHALL update the Sort field for affected planners

Requirement 13: 预约记录管理

User Story: As an Operator, I want to view and manage booking records, so that I can track planner appointments and handle scheduling issues.

Acceptance Criteria

1. WHEN an Operator requests the booking list, THE Planner_Service SHALL return bookings with pagination support
2. THE Planner_Service SHALL support filtering bookings by: PlannerId, UserId, BookingDate range, Status
3. WHEN an Operator views booking details, THE Planner_Service SHALL return complete booking information including user and planner details
4. WHEN an Operator changes booking status, THE Planner_Service SHALL update Status (1=pending, 2=confirmed, 3=completed, 4=cancelled)
5. THE Planner_Service SHALL display student grade information and scores based on Grade value
6. WHEN an Operator exports booking list, THE Planner_Service SHALL generate a downloadable file with selected fields

Requirement 14: 邀请码管理

User Story: As an Operator, I want to manage invite codes, so that I can generate and distribute free assessment codes to partners.

Acceptance Criteria

1. WHEN an Operator requests the invite code list, THE Distribution_Service SHALL return codes with pagination support
2. THE Distribution_Service SHALL support filtering codes by: Code, BatchNo, AssignUserId, Status
3. WHEN an Operator generates invite codes in batch, THE Distribution_Service SHALL create unique 5-character uppercase letter codes
4. WHEN an Operator generates invite codes, THE Distribution_Service SHALL assign the same BatchNo to all codes in the batch
5. WHEN an Operator assigns codes to a user, THE Distribution_Service SHALL update AssignUserId, AssignTime, and Status to 2 (assigned)
6. THE Distribution_Service SHALL display code usage information: UseUserId, UseOrderId, UseTime when Status is 3 (used)
7. WHEN an Operator exports invite code list, THE Distribution_Service SHALL generate a downloadable file with selected fields

Requirement 15: 佣金记录管理

User Story: As a Finance_Staff, I want to view commission records, so that I can monitor the distribution earnings and verify commission calculations.

Acceptance Criteria

1. WHEN a Finance_Staff requests the commission list, THE Distribution_Service SHALL return records with pagination support
2. THE Distribution_Service SHALL support filtering commissions by: UserId, FromUserId, OrderId, Level, Status, CreateTime range
3. WHEN a Finance_Staff views commission details, THE Distribution_Service SHALL return complete information including user and order details
4. THE Distribution_Service SHALL display Level as: 1 (direct subordinate), 2 (indirect subordinate)
5. THE Distribution_Service SHALL display Status as: 1 (pending settlement), 2 (settled)
6. THE Distribution_Service SHALL calculate and display commission statistics: total amount, pending amount, settled amount
7. WHEN a Finance_Staff exports commission list, THE Distribution_Service SHALL generate a downloadable file with selected fields

Requirement 16: 提现审核管理

User Story: As a Finance_Staff, I want to review and process withdrawal requests, so that I can approve or reject user withdrawal applications.

Acceptance Criteria

1. WHEN a Finance_Staff requests the withdrawal list, THE Distribution_Service SHALL return records with pagination support sorted by CreateTime descending
2. THE Distribution_Service SHALL support filtering withdrawals by: WithdrawalNo, UserId, Status, CreateTime range
3. WHEN a Finance_Staff views withdrawal details, THE Distribution_Service SHALL return complete information including user balance history
4. WHEN a Finance_Staff approves a withdrawal, THE Distribution_Service SHALL update Status to 2 (processing) and record AuditUserId and AuditTime
5. WHEN a Finance_Staff rejects a withdrawal, THE Distribution_Service SHALL update Status to 4 (cancelled) and record AuditRemark
6. WHEN a withdrawal payment is completed, THE Distribution_Service SHALL update Status to 3 (completed) and record PayTime and PayTransactionId
7. IF a withdrawal payment fails, THEN THE Distribution_Service SHALL revert user balance and record the error reason
8. THE Distribution_Service SHALL display Status as: 1 (pending), 2 (processing), 3 (completed), 4 (cancelled)

Requirement 17: 数据统计仪表盘

User Story: As an Operator, I want to view business statistics on a dashboard, so that I can monitor key business metrics at a glance.

Acceptance Criteria

1. WHEN an Operator accesses the dashboard, THE Admin_System SHALL display today's statistics: new users, new orders, revenue
2. THE Admin_System SHALL display cumulative statistics: total users, total orders, total revenue
3. THE Admin_System SHALL display recent trends: user growth chart, order trend chart, revenue trend chart
4. THE Admin_System SHALL support date range selection for trend charts
5. THE Admin_System SHALL display pending items: pending withdrawals count, pending bookings count
6. WHEN statistics data is requested, THE Admin_System SHALL return cached data if available and refresh in background

Requirement 18: 权限控制

User Story: As a Super_Admin, I want to control access to business modules, so that different roles can only access their authorized functions.

Acceptance Criteria

1. THE Admin_System SHALL integrate with the existing role-permission system
2. WHEN a user without permission accesses a protected endpoint, THE Admin_System SHALL return 403 Forbidden
3. THE Admin_System SHALL define business permissions for each module: config, content, assessment, user, order, planner, distribution
4. THE Admin_System SHALL support permission granularity: view, create, update, delete for each module
5. WHEN a new business module is added, THE Admin_System SHALL register its permissions in the permission system