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

Requirements Document

Introduction

本文档定义了学业邑规划 MiAssessment 管理后台两个遗漏业务模块的需求规格：测评记录管理和业务介绍页内容管理。这两个模块是在已实现的7个核心业务模块基础上的补充，遵循相同的技术栈（.NET 10 + SQL Server 2022）和 RPC 风格接口规范。

测评记录管理模块对应数据库中已设计的 assessment_records、assessment_answers、assessment_results 三张表，提供测评记录的查询、详情查看和导出功能。

业务介绍页内容管理模块是一个新增模块，需要新建 business_pages 数据库表，用于管理小程序中从首页轮播图跳转的业务介绍详情页内容。

Glossary

• Admin_System: 后台管理系统，用于管理小程序业务数据
• AssessmentRecord_Service: 测评记录服务，管理测评记录的查询、详情和导出
• BusinessPage_Service: 业务介绍页服务，管理业务介绍页的增删改查
• Operator: 后台运营人员，具有内容管理、测评管理权限
• Assessment_Record: 测评记录实体，存储用户的测评基本信息和状态
• Assessment_Answer: 测评答案实体，存储用户对每道题的答案
• Assessment_Result: 测评结果实体，存储各分类维度的得分和星级
• Business_Page: 业务介绍页实体，存储业务介绍的长图和操作按钮配置

Requirements

Requirement 1: 测评记录列表查询

User Story: As an Operator, I want to view assessment records with filtering and pagination, so that I can monitor user assessment activities and track completion status.

Acceptance Criteria

1. WHEN an Operator requests the assessment record list, THE AssessmentRecord_Service SHALL return records with pagination support sorted by CreateTime descending
2. THE AssessmentRecord_Service SHALL support filtering records by: UserId, AssessmentTypeId, Status, CreateTime start date, CreateTime end date
3. WHEN returning the record list, THE AssessmentRecord_Service SHALL include associated user nickname, assessment type name, and order number for each record
4. THE AssessmentRecord_Service SHALL display Status as: 1 (待测评), 2 (测评中), 3 (生成中), 4 (已完成)
5. THE AssessmentRecord_Service SHALL display EducationStage as: 1 (小学及以下), 2 (初中), 3 (高中), 4 (大专), 5 (本科), 6 (研究生及以上)
6. THE AssessmentRecord_Service SHALL display Gender as: 1 (男), 2 (女)
7. WHEN filtering by Status, THE AssessmentRecord_Service SHALL return only records matching the specified status value

Requirement 2: 测评记录详情查看

User Story: As an Operator, I want to view the complete details of an assessment record, so that I can review the user's assessment information, answers, and results.

Acceptance Criteria

1. WHEN an Operator requests a record detail by Id, THE AssessmentRecord_Service SHALL return the complete record information including user info, assessment type info, and order info
2. WHEN the record has associated answers, THE AssessmentRecord_Service SHALL return all answers sorted by QuestionNo ascending
3. WHEN the record has associated results, THE AssessmentRecord_Service SHALL return all results including category name, score, max score, percentage, rank, and star level
4. IF the requested record Id does not exist or is soft-deleted, THEN THE AssessmentRecord_Service SHALL return error code 3241 with message "测评记录不存在"
5. WHEN returning answer details, THE AssessmentRecord_Service SHALL include the question content for each answer

Requirement 3: 测评报告查看

User Story: As an Operator, I want to view the assessment report for a completed record, so that I can review the scoring results across all dimensions.

Acceptance Criteria

1. WHEN an Operator requests a report by record Id, THE AssessmentRecord_Service SHALL return all assessment results grouped by category type
2. WHEN returning report data, THE AssessmentRecord_Service SHALL include category name, category type name, score, max score, percentage, and star level for each result
3. IF the record status is not 4 (已完成), THEN THE AssessmentRecord_Service SHALL return error code 3242 with message "测评报告尚未生成"
4. WHEN returning report data, THE AssessmentRecord_Service SHALL include the associated conclusion content based on star level for each category

Requirement 4: 测评记录导出

User Story: As an Operator, I want to export assessment records to a downloadable file, so that I can perform offline analysis and reporting.

Acceptance Criteria

1. WHEN an Operator requests record export, THE AssessmentRecord_Service SHALL apply the same filters as the list query (UserId, AssessmentTypeId, Status, CreateTime range)
2. THE AssessmentRecord_Service SHALL include the following fields in the export: record Id, user nickname, assessment type name, name, phone, gender, age, education stage, province, city, district, status, start time, submit time, complete time, create time
3. WHEN the export result set exceeds 10000 records, THE AssessmentRecord_Service SHALL return error code 3243 with message "导出数据量过大，请缩小查询范围"
4. THE AssessmentRecord_Service SHALL generate the export file in Excel format

Requirement 5: 业务介绍页创建

User Story: As an Operator, I want to create business detail pages, so that I can configure the content displayed when users navigate from homepage banners.

Acceptance Criteria

1. WHEN an Operator creates a business page, THE BusinessPage_Service SHALL validate that Title and ImageUrl are provided
2. WHEN an Operator creates a business page with HasActionButton set to true, THE BusinessPage_Service SHALL validate that ActionButtonText and ActionButtonLink are provided
3. WHEN a business page is created, THE BusinessPage_Service SHALL set CreateTime and UpdateTime automatically
4. WHEN a business page is created, THE BusinessPage_Service SHALL set default Status to 1 (启用) and IsDeleted to false
5. THE BusinessPage_Service SHALL generate a unique Id for the new business page

Requirement 6: 业务介绍页列表查询

User Story: As an Operator, I want to view business detail pages with filtering and pagination, so that I can manage all configured business introduction content.

Acceptance Criteria

1. WHEN an Operator requests the business page list, THE BusinessPage_Service SHALL return pages sorted by Sort descending, then by CreateTime descending
2. THE BusinessPage_Service SHALL support filtering pages by: Title (fuzzy match), Status
3. WHEN returning the page list, THE BusinessPage_Service SHALL include all fields: Id, Title, ImageUrl, HasActionButton, ActionButtonText, ActionButtonLink, Sort, Status, CreateTime

Requirement 7: 业务介绍页更新

User Story: As an Operator, I want to update business detail pages, so that I can modify the content and configuration of existing business introduction pages.

Acceptance Criteria

1. WHEN an Operator updates a business page, THE BusinessPage_Service SHALL validate that Title and ImageUrl are provided
2. WHEN an Operator updates a business page with HasActionButton set to true, THE BusinessPage_Service SHALL validate that ActionButtonText and ActionButtonLink are provided
3. WHEN a business page is updated, THE BusinessPage_Service SHALL set UpdateTime automatically
4. IF the requested business page Id does not exist or is soft-deleted, THEN THE BusinessPage_Service SHALL return error code 3701 with message "业务介绍页不存在"

Requirement 8: 业务介绍页删除与状态管理

User Story: As an Operator, I want to delete or change the status of business detail pages, so that I can control which pages are visible in the mini-program.

Acceptance Criteria

1. WHEN an Operator deletes a business page, THE BusinessPage_Service SHALL perform soft delete by setting IsDeleted to true and UpdateTime to current time
2. WHEN an Operator changes business page status, THE BusinessPage_Service SHALL update the Status field (0=禁用, 1=启用)
3. IF the requested business page Id does not exist or is soft-deleted, THEN THE BusinessPage_Service SHALL return error code 3701 with message "业务介绍页不存在"
4. WHEN an Operator reorders business pages, THE BusinessPage_Service SHALL update the Sort field for the specified page

Requirement 9: 业务介绍页数据库迁移

User Story: As an Operator, I want the business_pages table to be created in the database, so that the business detail page data can be persisted.

Acceptance Criteria

1. THE Admin_System SHALL create a business_pages table with columns: Id (bigint, PK, auto-increment), Title (nvarchar(100), required), ImageUrl (nvarchar(500), required), HasActionButton (bit, default 0), ActionButtonText (nvarchar(50)), ActionButtonLink (nvarchar(500)), Sort (int, default 0), Status (int, default 1), CreateTime (datetime2), UpdateTime (datetime2), IsDeleted (bit, default 0)
2. THE Admin_System SHALL create an index IX_business_pages_status on the Status column

Requirement 10: 权限控制扩展

User Story: As a Super_Admin, I want the new modules to integrate with the existing permission system, so that access control is enforced consistently.

Acceptance Criteria

1. THE Admin_System SHALL register assessment record permissions: assessmentRecord:view, assessmentRecord:export
2. THE Admin_System SHALL register business page permissions: businessPage:view, businessPage:create, businessPage:update, businessPage:delete
3. WHEN a user without the required permission accesses a protected endpoint, THE Admin_System SHALL return 403 Forbidden