134 lines
9.6 KiB
Markdown
134 lines
9.6 KiB
Markdown
# 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
|