af4b68c2dd
- 创建 miniapp-api spec (requirements, design, tasks) - 添加 API开发任务清单，包含页面-API对照验证 - 规划28个待开发接口，按P0/P1/P2优先级排列
201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
本文档定义了学业邑规划（MiAssessment）微信小程序后端API的开发需求。系统基于多元智能理论，提供学业规划测评服务，包含首页展示、测评流程、订单管理、学业规划预约、分销系统等核心功能模块。
|
||
|
||
技术栈：.NET 10 Web API (C#) + SQL Server 2022 + Entity Framework Core + Redis
|
||
|
||
## Glossary
|
||
|
||
- **API_System**: 小程序后端API系统，负责处理所有小程序端的请求
|
||
- **Home_Module**: 首页模块，提供Banner、测评入口、宣传图等首页内容
|
||
- **Assessment_Module**: 测评模块，处理测评介绍、题目获取、答案提交、结果查询等
|
||
- **Order_Module**: 订单模块，处理订单创建、支付、查询等
|
||
- **Planner_Module**: 规划师模块，提供规划师列表和预约功能
|
||
- **Invite_Module**: 分销模块，处理邀请、佣金、提现等分销业务
|
||
- **System_Module**: 系统模块，提供协议、隐私政策、关于我们等系统配置
|
||
- **Team_Module**: 团队模块，提供团队介绍内容
|
||
- **Business_Module**: 业务详情模块，提供业务介绍页内容
|
||
- **User**: 小程序用户
|
||
- **Partner**: 合伙人用户，拥有邀请下级和获取佣金的权限
|
||
- **Invite_Code**: 邀请码，合伙人用于免费测评的凭证
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 首页模块 (Home_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看首页内容, so that I can 了解平台信息并快速进入测评流程。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求Banner列表 THEN THE Home_Module SHALL 返回所有启用状态的Banner记录，按Sort降序排列
|
||
2. WHEN 用户请求测评入口列表 THEN THE Home_Module SHALL 返回所有未删除的测评类型，包含状态信息（已上线/即将上线）
|
||
3. WHEN 用户请求宣传图列表 THEN THE Home_Module SHALL 返回首页位置（Position=1）且启用状态的宣传图
|
||
4. THE Home_Module SHALL 对所有首页接口不要求用户登录认证
|
||
|
||
### Requirement 2: 业务详情模块 (Business_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看业务详情页, so that I can 了解具体业务介绍并参与业务流程。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求业务详情 THEN THE Business_Module SHALL 根据ID返回业务页面内容，包含背景图和参与按钮配置
|
||
2. THE Business_Module SHALL 对业务详情接口不要求用户登录认证
|
||
|
||
### Requirement 3: 测评模块 - 测评介绍与题目 (Assessment_Module)
|
||
|
||
**User Story:** As a 用户, I want to 获取测评介绍和题目, so that I can 了解测评内容并完成答题。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求测评介绍 THEN THE Assessment_Module SHALL 根据typeId返回测评类型的介绍内容和价格
|
||
2. WHEN 已登录用户请求题目列表 THEN THE Assessment_Module SHALL 根据typeId返回所有启用的题目，按QuestionNo排序
|
||
3. THE Assessment_Module SHALL 对测评介绍接口不要求登录，对题目列表接口要求登录认证
|
||
|
||
### Requirement 4: 测评模块 - 答案提交与结果 (Assessment_Module)
|
||
|
||
**User Story:** As a 用户, I want to 提交测评答案并查看结果, so that I can 获得测评报告。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 已登录用户提交测评答案 THEN THE Assessment_Module SHALL 验证记录归属当前用户，保存答案并更新记录状态为"生成中"
|
||
2. WHEN 已登录用户查询报告状态 THEN THE Assessment_Module SHALL 返回测评记录的当前状态和是否完成标识
|
||
3. WHEN 已登录用户请求测评结果 THEN THE Assessment_Module SHALL 验证记录归属且已完成，返回完整的报告数据结构
|
||
4. IF 用户提交的答案数量与题目数量不匹配 THEN THE Assessment_Module SHALL 返回错误提示
|
||
5. IF 用户请求的测评记录不属于当前用户 THEN THE Assessment_Module SHALL 返回无权限错误
|
||
|
||
### Requirement 5: 测评模块 - 邀请码验证 (Assessment_Module)
|
||
|
||
**User Story:** As a 用户, I want to 使用邀请码免费测评, so that I can 无需支付即可完成测评。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户提交邀请码验证请求 THEN THE Assessment_Module SHALL 检查邀请码是否存在且未使用
|
||
2. IF 邀请码不存在 THEN THE Assessment_Module SHALL 返回"邀请码有误，请重新输入"
|
||
3. IF 邀请码已被使用 THEN THE Assessment_Module SHALL 返回"邀请码已被使用"
|
||
4. WHEN 邀请码验证通过 THEN THE Assessment_Module SHALL 返回邀请码ID供后续订单使用
|
||
|
||
### Requirement 6: 测评模块 - 往期测评 (Assessment_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看往期测评记录, so that I can 回顾历史测评结果。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 已登录用户请求往期测评列表 THEN THE Assessment_Module SHALL 返回该用户的测评记录，支持分页
|
||
2. THE Assessment_Module SHALL 返回测评记录的状态（生成中/已完成）和基本信息
|
||
|
||
### Requirement 7: 订单模块 - 订单查询 (Order_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看我的订单, so that I can 了解订单状态和详情。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 已登录用户请求订单列表 THEN THE Order_Module SHALL 返回该用户的订单，支持按类型筛选和分页
|
||
2. WHEN 已登录用户请求订单详情 THEN THE Order_Module SHALL 返回订单完整信息，包含关联的测评记录或规划预约
|
||
3. IF 用户请求的订单不属于当前用户 THEN THE Order_Module SHALL 返回无权限错误
|
||
|
||
### Requirement 8: 订单模块 - 订单创建 (Order_Module)
|
||
|
||
**User Story:** As a 用户, I want to 创建测评或规划订单, so that I can 购买服务。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户创建测评订单 THEN THE Order_Module SHALL 创建订单记录和测评记录，关联用户基本信息
|
||
2. WHEN 用户创建规划订单 THEN THE Order_Module SHALL 创建订单记录和规划预约记录
|
||
3. WHEN 用户使用邀请码创建订单 THEN THE Order_Module SHALL 将订单金额设为0并标记邀请码已使用
|
||
4. IF 创建订单过程中发生错误 THEN THE Order_Module SHALL 回滚所有数据库操作
|
||
5. THE Order_Module SHALL 使用数据库事务确保多表操作的数据一致性
|
||
|
||
### Requirement 9: 订单模块 - 支付流程 (Order_Module)
|
||
|
||
**User Story:** As a 用户, I want to 支付订单, so that I can 完成购买流程。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户发起支付请求 THEN THE Order_Module SHALL 调用微信支付统一下单接口并返回支付参数
|
||
2. WHEN 用户查询支付结果 THEN THE Order_Module SHALL 返回订单的支付状态
|
||
3. IF 订单已支付或已取消 THEN THE Order_Module SHALL 拒绝重复支付请求
|
||
|
||
### Requirement 10: 规划师模块 (Planner_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看规划师并预约, so that I can 获得学业规划服务。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求规划师列表 THEN THE Planner_Module SHALL 返回所有启用的规划师，按Sort排序
|
||
2. THE Planner_Module SHALL 对规划师列表接口不要求用户登录认证
|
||
3. WHEN 用户预约规划师 THEN THE Planner_Module SHALL 复用订单创建流程（orderType=2）
|
||
|
||
### Requirement 11: 分销模块 - 邀请信息 (Invite_Module)
|
||
|
||
**User Story:** As a 合伙人, I want to 查看邀请信息和生成二维码, so that I can 邀请新用户。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 合伙人请求邀请信息 THEN THE Invite_Module SHALL 返回用户邀请码、余额、邀请人数等信息
|
||
2. WHEN 合伙人请求生成二维码 THEN THE Invite_Module SHALL 调用微信小程序码接口生成带参数二维码
|
||
3. THE Invite_Module SHALL 对所有分销接口要求用户登录认证
|
||
|
||
### Requirement 12: 分销模块 - 邀请记录与佣金 (Invite_Module)
|
||
|
||
**User Story:** As a 合伙人, I want to 查看邀请记录和佣金, so that I can 了解分销收益。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 合伙人请求邀请记录 THEN THE Invite_Module SHALL 返回直属下级用户列表及贡献佣金，支持分页
|
||
2. WHEN 合伙人请求佣金信息 THEN THE Invite_Module SHALL 返回累计收益、已提现、待提现金额
|
||
|
||
### Requirement 13: 分销模块 - 提现功能 (Invite_Module)
|
||
|
||
**User Story:** As a 合伙人, I want to 申请提现, so that I can 获得佣金收益。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 合伙人申请提现 THEN THE Invite_Module SHALL 验证余额充足后创建提现记录并扣减用户余额
|
||
2. IF 提现金额超过可提现余额 THEN THE Invite_Module SHALL 返回"超出待提现金额"错误
|
||
3. IF 提现金额小于最低限额（1元） THEN THE Invite_Module SHALL 返回错误提示
|
||
4. IF 提现金额不是整数 THEN THE Invite_Module SHALL 返回错误提示
|
||
5. WHEN 合伙人请求提现记录 THEN THE Invite_Module SHALL 返回提现记录列表，支持分页
|
||
|
||
### Requirement 14: 系统模块 (System_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看系统配置内容, so that I can 了解用户协议、隐私政策等信息。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求用户协议 THEN THE System_Module SHALL 从配置表读取并返回用户协议内容
|
||
2. WHEN 用户请求隐私政策 THEN THE System_Module SHALL 从配置表读取并返回隐私政策内容
|
||
3. WHEN 用户请求关于我们 THEN THE System_Module SHALL 从配置表读取并返回关于我们内容和版本号
|
||
4. THE System_Module SHALL 对所有系统配置接口不要求用户登录认证
|
||
|
||
### Requirement 15: 团队模块 (Team_Module)
|
||
|
||
**User Story:** As a 用户, I want to 查看团队介绍, so that I can 了解团队信息。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户请求团队介绍 THEN THE Team_Module SHALL 返回团队位置（Position=2）的宣传图列表
|
||
2. THE Team_Module SHALL 对团队介绍接口不要求用户登录认证
|
||
|
||
### Requirement 16: API响应规范
|
||
|
||
**User Story:** As a 开发者, I want to 统一的API响应格式, so that I can 方便地处理接口返回。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE API_System SHALL 对所有接口返回统一的JSON响应格式：{code, message, data}
|
||
2. WHEN 请求成功 THEN THE API_System SHALL 返回code=0
|
||
3. WHEN 请求失败 THEN THE API_System SHALL 返回非0错误码和错误信息
|
||
4. THE API_System SHALL 对分页接口返回统一的分页响应格式：{list, total, page, pageSize, totalPages}
|
||
|
||
### Requirement 17: 认证与授权
|
||
|
||
**User Story:** As a 系统管理员, I want to 保护需要登录的接口, so that I can 确保数据安全。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 未登录用户访问需要认证的接口 THEN THE API_System SHALL 返回未授权错误（code=-1或1002）
|
||
2. WHEN 用户Token过期 THEN THE API_System SHALL 返回登录过期错误（code=1003）
|
||
3. THE API_System SHALL 使用Bearer Token方式进行认证
|