mi-assessment/.kiro/specs/admin-frontend/requirements.md

Requirements Document

Introduction

本文档定义了学业邑规划 MiAssessment 管理后台前端业务模块的需求规格。前端基于 Vue 3.5 + TypeScript 5.6 + Element Plus 2.9 技术栈，需要开发8个业务模块页面来对接已有的后端 API。系统在现有的登录、系统管理等基础功能上，扩展数据统计仪表盘、系统配置、内容管理、测评管理、用户管理、订单管理、规划师管理和分销管理等业务模块。

Glossary

• Admin_Frontend: 后台管理前端系统，基于 Vue 3 + Element Plus
• Dashboard_Page: 数据统计仪表盘页面，展示业务概览数据
• Config_Page: 系统配置管理页面，管理系统配置项
• Content_Page: 内容管理页面，包括轮播图和宣传图管理
• Assessment_Page: 测评管理页面，包括测评类型、题库、报告分类和结论管理
• User_Page: 用户管理页面，管理C端用户信息
• Order_Page: 订单管理页面，管理订单列表和退款
• Planner_Page: 规划师管理页面，管理规划师信息和预约记录
• Distribution_Page: 分销管理页面，管理邀请码、佣金和提现
• Operator: 后台运营人员，具有内容管理、订单管理、用户管理权限
• API_Service: 后端 API 服务，提供数据接口

Requirements

Requirement 1: 数据统计仪表盘

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 page, THE Dashboard_Page SHALL display today's statistics cards showing new users count, new orders count, and today's revenue
2. WHEN an Operator accesses the dashboard page, THE Dashboard_Page SHALL display cumulative statistics cards showing total users, total orders, and total revenue
3. WHEN an Operator accesses the dashboard page, THE Dashboard_Page SHALL display trend charts for user growth, order trends, and revenue trends
4. WHEN an Operator selects a date range for trend charts, THE Dashboard_Page SHALL update the charts to show data for the selected period
5. WHEN an Operator accesses the dashboard page, THE Dashboard_Page SHALL display pending items count including pending withdrawals and pending bookings
6. WHEN the API returns an error, THE Dashboard_Page SHALL display an error message and allow retry
7. WHILE data is loading, THE Dashboard_Page SHALL display loading indicators on each statistics card and chart

Requirement 2: 系统配置管理

User Story: As an Operator, I want to manage system configuration items through a user-friendly interface, so that I can dynamically adjust system parameters.

Acceptance Criteria

1. WHEN an Operator accesses the config page, THE Config_Page SHALL display all configuration items grouped by ConfigType in collapsible panels
2. WHEN an Operator clicks edit on a configuration item, THE Config_Page SHALL display an inline edit form with the current value
3. WHEN an Operator submits a configuration update, THE Config_Page SHALL validate the value format based on ConfigType before sending to API
4. IF an Operator enters an invalid price value (non-positive number), THEN THE Config_Page SHALL display a validation error message
5. IF an Operator enters an invalid commission rate (not between 0 and 1), THEN THE Config_Page SHALL display a validation error message
6. WHEN a configuration is successfully updated, THE Config_Page SHALL display a success message and refresh the configuration list
7. WHEN the API returns an error, THE Config_Page SHALL display the error message from the API response

Requirement 3: 轮播图管理

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

Acceptance Criteria

1. WHEN an Operator accesses the banner page, THE Content_Page SHALL display a paginated table with columns: image preview, title, link type, status, sort, create time, and actions
2. WHEN an Operator clicks the add button, THE Content_Page SHALL display a dialog form with fields: title, image upload, link type selector, link URL, app ID, sort, and status
3. WHEN an Operator selects link type as internal page or external link, THE Content_Page SHALL require the link URL field
4. WHEN an Operator selects link type as mini-program, THE Content_Page SHALL require both link URL and app ID fields
5. WHEN an Operator clicks edit on a banner, THE Content_Page SHALL display the edit dialog with pre-filled values
6. WHEN an Operator clicks the status switch, THE Content_Page SHALL call the API to toggle the banner status
7. WHEN an Operator clicks delete on a banner, THE Content_Page SHALL display a confirmation dialog before calling the delete API
8. WHEN an Operator drags to reorder banners, THE Content_Page SHALL call the API to update sort values
9. THE Content_Page SHALL use the ImageUpload component for banner image selection
10. THE Content_Page SHALL use DictSelect component for link type and status fields

Requirement 4: 宣传图管理

User Story: As an Operator, I want to manage promotional images through a list interface, so that I can control the promotional content at different positions.

Acceptance Criteria

1. WHEN an Operator accesses the promotion page, THE Content_Page SHALL display a paginated table with columns: image preview, title, position, status, sort, create time, and actions
2. WHEN an Operator clicks the add button, THE Content_Page SHALL display a dialog form with fields: title, image upload, position selector, sort, and status
3. WHEN an Operator filters by position, THE Content_Page SHALL display only promotions matching the selected position
4. WHEN an Operator clicks edit on a promotion, THE Content_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks the status switch, THE Content_Page SHALL call the API to toggle the promotion status
6. WHEN an Operator clicks delete on a promotion, THE Content_Page SHALL display a confirmation dialog before calling the delete API
7. THE Content_Page SHALL use DictSelect component for position and status fields

Requirement 5: 测评类型管理

User Story: As an Operator, I want to manage assessment types through a list interface, so that I can configure different assessment products.

Acceptance Criteria

1. WHEN an Operator accesses the assessment type page, THE Assessment_Page SHALL display a paginated table with columns: image, name, code, price, question count, status, sort, create time, and actions
2. WHEN an Operator clicks the add button, THE Assessment_Page SHALL display a dialog form with fields: name, code, image upload, price, intro content (rich text), sort, and status
3. WHEN an Operator enters a price, THE Assessment_Page SHALL validate that the value is a positive number
4. WHEN an Operator clicks edit on an assessment type, THE Assessment_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks the status switch, THE Assessment_Page SHALL call the API to toggle the status (offline/online/coming soon)
6. WHEN an Operator clicks delete on an assessment type, THE Assessment_Page SHALL display a confirmation dialog before calling the delete API
7. THE Assessment_Page SHALL use a rich text editor or image upload for the intro content field
8. THE Assessment_Page SHALL use DictSelect component for status field

Requirement 6: 题库管理

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

Acceptance Criteria

1. WHEN an Operator accesses the question page, THE Assessment_Page SHALL display a paginated table with columns: question number, content preview, assessment type, category mappings, status, and actions
2. WHEN an Operator filters by assessment type, THE Assessment_Page SHALL display only questions belonging to the selected type
3. WHEN an Operator clicks the add button, THE Assessment_Page SHALL display a dialog form with fields: assessment type selector, question number, content (rich text), and status
4. WHEN an Operator clicks edit on a question, THE Assessment_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks the category mapping button, THE Assessment_Page SHALL display a dialog with a tree selector for selecting report categories
6. WHEN an Operator clicks the batch import button, THE Assessment_Page SHALL display a dialog for uploading an Excel file with question data
7. WHEN batch import completes, THE Assessment_Page SHALL display a result summary showing success count and error details
8. WHEN an Operator clicks delete on a question, THE Assessment_Page SHALL display a confirmation dialog before calling the delete API

Requirement 7: 报告分类管理

User Story: As an Operator, I want to manage report categories through a tree interface, so that I can configure the scoring dimensions for assessment reports.

Acceptance Criteria

1. WHEN an Operator accesses the category page, THE Assessment_Page SHALL display a tree table showing the hierarchical category structure
2. WHEN an Operator selects an assessment type, THE Assessment_Page SHALL display the category tree for that assessment type
3. WHEN an Operator clicks add on a category, THE Assessment_Page SHALL display a dialog form with fields: parent category selector, name, code, category type, score rule, and sort
4. WHEN an Operator clicks edit on a category, THE Assessment_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks delete on a category with children, THE Assessment_Page SHALL display an error message preventing deletion
6. WHEN an Operator clicks delete on a leaf category, THE Assessment_Page SHALL display a confirmation dialog before calling the delete API
7. THE Assessment_Page SHALL use DictSelect component for category type and score rule fields

Requirement 8: 报告结论管理

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

Acceptance Criteria

1. WHEN an Operator accesses the conclusion page, THE Assessment_Page SHALL display a list of conclusions filtered by the selected category
2. WHEN an Operator selects a category from the tree, THE Assessment_Page SHALL display conclusions for that category
3. WHEN an Operator clicks the add button, THE Assessment_Page SHALL display a dialog form with fields: conclusion type selector, title, and content (rich text)
4. WHEN an Operator clicks edit on a conclusion, THE Assessment_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks delete on a conclusion, THE Assessment_Page SHALL display a confirmation dialog before calling the delete API
6. THE Assessment_Page SHALL use DictSelect component for conclusion type field

Requirement 9: C端用户管理

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

Acceptance Criteria

1. WHEN an Operator accesses the user page, THE User_Page SHALL display a paginated table with columns: UID, phone, nickname, avatar, user level, balance, status, create time, last login time, and actions
2. WHEN an Operator enters search criteria (UID, phone, nickname, user level, status, date range), THE User_Page SHALL filter the user list accordingly
3. WHEN an Operator clicks view on a user, THE User_Page SHALL display a detail drawer showing complete user information including parent user info, balance, income statistics, order count, and assessment count
4. WHEN an Operator clicks the status switch, THE User_Page SHALL call the API to toggle the user status (disabled/normal)
5. WHEN an Operator clicks change level on a user, THE User_Page SHALL display a dialog for selecting the new user level
6. WHEN an Operator clicks the export button, THE User_Page SHALL call the export API and download the Excel file
7. THE User_Page SHALL use DictSelect component for user level and status filter fields

Requirement 10: 订单管理

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

Acceptance Criteria

1. WHEN an Operator accesses the order page, THE Order_Page SHALL display a paginated table with columns: order number, user info, order type, product name, amount, pay amount, pay type, status, pay time, create time, and actions
2. WHEN an Operator enters search criteria (order number, user ID, order type, status, pay type, date range), THE Order_Page SHALL filter the order list accordingly
3. WHEN an Operator clicks view on an order, THE Order_Page SHALL display a detail drawer showing complete order information including user details, product details, payment details, and related records
4. WHEN an Operator clicks the export button, THE Order_Page SHALL call the export API and download the Excel file
5. THE Order_Page SHALL use DictSelect component for order type, status, and pay type filter fields
6. THE Order_Page SHALL display different status colors based on order status

Requirement 11: 退款处理

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

Acceptance Criteria

1. WHEN a Finance_Staff views an order with status paid or completed, THE Order_Page SHALL display a refund button
2. WHEN a Finance_Staff clicks the refund button, THE Order_Page SHALL display a dialog with fields: refund amount (pre-filled with pay amount) and refund reason
3. WHEN a Finance_Staff enters a refund amount greater than the pay amount, THE Order_Page SHALL display a validation error
4. WHEN a Finance_Staff submits the refund form, THE Order_Page SHALL call the refund API and display the result
5. WHEN the refund is successful, THE Order_Page SHALL refresh the order detail to show the updated status
6. THE Order_Page SHALL use v-permission directive to control refund button visibility based on user permissions

Requirement 12: 规划师管理

User Story: As an Operator, I want to manage planner information through a list interface, so that I can configure the planners available for booking.

Acceptance Criteria

1. WHEN an Operator accesses the planner page, THE Planner_Page SHALL display a paginated table with columns: avatar, name, title, price, status, sort, create time, and actions
2. WHEN an Operator clicks the add button, THE Planner_Page SHALL display a dialog form with fields: name, avatar upload, title, intro, price, sort, and status
3. WHEN an Operator enters a price, THE Planner_Page SHALL validate that the value is a positive number
4. WHEN an Operator clicks edit on a planner, THE Planner_Page SHALL display the edit dialog with pre-filled values
5. WHEN an Operator clicks the status switch, THE Planner_Page SHALL call the API to toggle the planner status
6. WHEN an Operator clicks delete on a planner, THE Planner_Page SHALL display a confirmation dialog before calling the delete API
7. WHEN an Operator drags to reorder planners, THE Planner_Page SHALL call the API to update sort values
8. THE Planner_Page SHALL use the ImageUpload component for avatar selection

Requirement 13: 预约记录管理

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

Acceptance Criteria

1. WHEN an Operator accesses the booking page, THE Planner_Page SHALL display a paginated table with columns: booking ID, user info, planner info, booking date, student info, status, create time, and actions
2. WHEN an Operator enters search criteria (planner, user, date range, status), THE Planner_Page SHALL filter the booking list accordingly
3. WHEN an Operator clicks view on a booking, THE Planner_Page SHALL display a detail drawer showing complete booking information including user details, planner details, and student information
4. WHEN an Operator clicks change status on a booking, THE Planner_Page SHALL display a dialog for selecting the new status (pending/confirmed/completed/cancelled)
5. WHEN an Operator clicks the export button, THE Planner_Page SHALL call the export API and download the Excel file
6. THE Planner_Page SHALL use DictSelect component for status filter and status change fields

Requirement 14: 邀请码管理

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

Acceptance Criteria

1. WHEN an Operator accesses the invite code page, THE Distribution_Page SHALL display a paginated table with columns: code, batch number, assigned user, assign time, used user, use time, status, create time, and actions
2. WHEN an Operator enters search criteria (code, batch number, assigned user, status), THE Distribution_Page SHALL filter the code list accordingly
3. WHEN an Operator clicks the generate button, THE Distribution_Page SHALL display a dialog for entering the count of codes to generate
4. WHEN codes are generated successfully, THE Distribution_Page SHALL display the batch number and refresh the list
5. WHEN an Operator clicks assign on unassigned codes, THE Distribution_Page SHALL display a dialog for selecting the user to assign to
6. WHEN an Operator clicks the export button, THE Distribution_Page SHALL call the export API and download the Excel file
7. THE Distribution_Page SHALL use DictSelect component for status filter field

Requirement 15: 佣金记录管理

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

Acceptance Criteria

1. WHEN a Finance_Staff accesses the commission page, THE Distribution_Page SHALL display a paginated table with columns: user info, from user info, order info, order amount, commission rate, commission amount, level, status, settle time, create time
2. WHEN a Finance_Staff enters search criteria (user, from user, order, level, status, date range), THE Distribution_Page SHALL filter the commission list accordingly
3. WHEN a Finance_Staff clicks view on a commission, THE Distribution_Page SHALL display a detail drawer showing complete commission information
4. WHEN a Finance_Staff accesses the commission page, THE Distribution_Page SHALL display statistics cards showing total amount, pending amount, and settled amount
5. WHEN a Finance_Staff clicks the export button, THE Distribution_Page SHALL call the export API and download the Excel file
6. THE Distribution_Page SHALL use DictSelect component for level and status filter fields

Requirement 16: 提现审核管理

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

Acceptance Criteria

1. WHEN a Finance_Staff accesses the withdrawal page, THE Distribution_Page SHALL display a paginated table with columns: withdrawal number, user info, amount, before balance, after balance, status, audit info, pay time, create time, and actions
2. WHEN a Finance_Staff enters search criteria (withdrawal number, user, status, date range), THE Distribution_Page SHALL filter the withdrawal list accordingly
3. WHEN a Finance_Staff clicks view on a withdrawal, THE Distribution_Page SHALL display a detail drawer showing complete withdrawal information including user balance history
4. WHEN a Finance_Staff clicks approve on a pending withdrawal, THE Distribution_Page SHALL call the approve API and refresh the list
5. WHEN a Finance_Staff clicks reject on a pending withdrawal, THE Distribution_Page SHALL display a dialog for entering the rejection reason
6. WHEN a Finance_Staff clicks complete on a processing withdrawal, THE Distribution_Page SHALL display a dialog for entering the payment transaction ID
7. WHEN a Finance_Staff clicks the export button, THE Distribution_Page SHALL call the export API and download the Excel file
8. THE Distribution_Page SHALL use v-permission directive to control approve/reject/complete button visibility based on user permissions
9. THE Distribution_Page SHALL use DictSelect component for status filter field

Requirement 17: 路由和菜单配置

User Story: As a developer, I want to configure routes and menus for business modules, so that users can navigate to the correct pages.

Acceptance Criteria

1. THE Admin_Frontend SHALL register routes for all business module pages under the /business path prefix
2. THE Admin_Frontend SHALL configure route meta information including title, icon, and permission requirements
3. WHEN a user without permission accesses a protected route, THE Admin_Frontend SHALL redirect to the 403 error page
4. THE Admin_Frontend SHALL support nested routes for modules with sub-pages (assessment, distribution)
5. THE Admin_Frontend SHALL configure keep-alive for list pages to preserve state when navigating to detail pages

Requirement 18: API 接口封装

User Story: As a developer, I want to encapsulate API calls for business modules, so that pages can easily interact with the backend.

Acceptance Criteria

1. THE Admin_Frontend SHALL create API files under src/api/business/ directory for each business module
2. THE Admin_Frontend SHALL define TypeScript interfaces for all request and response types
3. THE Admin_Frontend SHALL use the existing request utility with automatic token handling and error processing
4. THE Admin_Frontend SHALL follow RPC-style API naming convention (getList, getDetail, create, update, delete, updateStatus)
5. WHEN an API call fails, THE Admin_Frontend SHALL display the error message from the API response using Element Plus message component

Requirement 19: 权限控制

User Story: As a developer, I want to implement permission control for business module pages, so that different roles can only access their authorized functions.

Acceptance Criteria

1. THE Admin_Frontend SHALL use v-permission directive to control button visibility based on user permissions
2. THE Admin_Frontend SHALL define permission identifiers following the format: module:action (e.g., banner:create, order:refund)
3. WHEN a user clicks a button without permission, THE Admin_Frontend SHALL prevent the action and display a permission denied message
4. THE Admin_Frontend SHALL hide menu items for modules the user has no permission to access

Requirement 20: 字典数据使用

User Story: As a developer, I want to use dictionary components for status and type fields, so that the UI displays consistent labels and values.

Acceptance Criteria

1. THE Admin_Frontend SHALL use DictSelect component for all status and type selector fields
2. THE Admin_Frontend SHALL use DictRadio component for status fields in forms where appropriate
3. THE Admin_Frontend SHALL configure dictionary types in the backend for: banner_link_type, banner_status, promotion_position, assessment_status, user_level, user_status, order_type, order_status, pay_type, booking_status, invite_code_status, commission_level, commission_status, withdrawal_status, category_type, score_rule, conclusion_type
4. WHEN dictionary data is not available, THE Admin_Frontend SHALL display the raw value with a warning indicator