outsource/mi-assessment
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
2c7693c4e3
mi-assessment/.kiro/specs/miniapp-api/requirements.md
zpc af4b68c2dd docs: 添加小程序API开发规划文档 
- 创建 miniapp-api spec (requirements, design, tasks)
- 添加 API开发任务清单，包含页面-API对照验证
- 规划28个待开发接口，按P0/P1/P2优先级排列
2026-02-09 08:35:43 +08:00

10 KiB
Raw Blame History

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方式进行认证