- 创建 miniapp-api spec (requirements, design, tasks)
- 添加 API开发任务清单，包含页面-API对照验证
- 规划28个待开发接口，按P0/P1/P2优先级排列

2026-02-09 08:35:43 +08:00

24 KiB

Raw Blame History

学业邑规划 - 小程序 API 开发任务清单

本文档列出了小程序后端 API 的开发任务，按模块和优先级组织。

〇、需求与设计图对照验证

0.1 页面-API 对照表

页面	设计图	需求章节	所需API	状态
首页	首页.png	二、首页	getBannerList, getAssessmentList, getPromotionList	✅ 已规划
团队页	团队.png	四、团队页	getTeamInfo	✅ 已规划
我的页	我的-登录页.png	七、我的页	getProfile	✅ 已有
登录页	登录页.png	七、我的页	login	✅ 已有
个人资料	个人资料.png	八、个人信息页	getProfile, updateProfile, updateAvatar	✅ 已有
测评-信息填写	测评-个人信息填写.png	五.1 基本信息填写	getIntro, verifyInviteCode, createOrder, pay	✅ 已规划
测评-答题	测评-题目.png	五.2 答题页	getQuestionList, submitAnswers	✅ 已规划
测评-生成中	测评-等待测评.png	五.3 测评生成中	getResultStatus	✅ 已规划
测评-结果	-	五.4 测评结果页	getResult	✅ 已规划
我的订单	我的订单.png	九、我的订单页	getOrderList, getOrderDetail	✅ 已规划
往期测评	往期测评-空状态.png	十、往期测评页	getHistoryList	✅ 已规划
学业规划-规划师	学业规划.png	六.1 规划师选择	getPlannerList	✅ 已规划
学业规划-预约	学业规划2.png	六.2 规划时间预约	createOrder (orderType=2), pay	✅ 已规划
邀请新用户	邀请新用户.png	十一、邀请新用户	getInviteInfo, getQrcode, getRecordList, getCommission, applyWithdraw, getWithdrawList	✅ 已规划
关于页	关于.png	十二、关于页	getAbout	✅ 已规划
用户协议	用户／隐私协议.png	十三、用户协议	getAgreement	✅ 已规划
隐私政策	用户／隐私协议.png	十三、隐私政策	getPrivacy	✅ 已规划
业务详情页	业务详情页.png	三、介绍详情页	需补充	⚠️ 缺失

0.2 需求功能点验证

需求点	需求描述	对应API	状态
Banner跳转	点击可跳转到指定页面	getBannerList (含linkType, linkUrl)	✅
测评入口状态	即将上线提示"该测评暂未开放"	getAssessmentList (含status字段)	✅
邀请码验证	验证邀请码是否存在/已使用	verifyInviteCode	✅
微信支付	拉起微信支付	createOrder + pay	✅
题目未答检测	提交时检测未选题目	前端逻辑，无需API	✅
报告轮询	等待报告生成	getResultStatus	✅
保存PDF	保存测评报告到本地	getResult (前端生成PDF)	✅
订单状态	待测评/测评中/已测评/退款	getOrderList (含status)	✅
合伙人权限	邀请新用户入口仅合伙人可见	getProfile (含userLevel)	✅
佣金规则	40%/30%+10%分成	后端计算逻辑	✅
提现规则	最低1元，整数	applyWithdraw	✅
联系我们	跳转小程序客服	前端调用wx.openCustomerServiceChat	✅

0.3 发现的遗漏项

⚠️ 需要补充的API

业务详情页接口 - 需求第三章
- 接口：GET /api/business/getDetail?id=1
- 功能：获取业务介绍页内容（背景长图、是否有参与按钮）
- 来源：Banner跳转到业务详情页
发送短信验证码 - 如果支持手机号验证码登录
- 接口：POST /api/sms/sendCode
- 功能：发送短信验证码
- 说明：当前登录方式为微信授权，如需支持验证码登录则需要

0.4 已有接口确认（无需开发）

以下接口在 AuthController/UserController 中已实现：

POST /api/login - 微信登录 ✅
GET /api/user/getProfile - 获取用户信息 ✅
POST /api/user/updateProfile - 更新用户信息 ✅
POST /api/user/updateAvatar - 更新头像 ✅
POST /api/logout - 退出登录 ✅
POST /api/refresh - 刷新Token ✅

一、开发概述

1.1 项目位置

控制器：server/MiAssessment/src/MiAssessment.Api/Controllers/
服务接口：server/MiAssessment/src/MiAssessment.Core/Interfaces/
服务实现：server/MiAssessment/src/MiAssessment.Core/Services/
数据模型：server/MiAssessment/src/MiAssessment.Model/Models/
实体类：server/MiAssessment/src/MiAssessment.Model/Entities/

1.2 已完成模块

模块	控制器	状态
认证	AuthController	✅ 已完成
用户	UserController	✅ 已完成
地址	AddressController	✅ 已完成
配置	ConfigController	✅ 已完成
支付	PayController	✅ 已完成
通知	NotifyController	✅ 已完成

1.3 待开发模块

模块	控制器	优先级	接口数
首页	HomeController	P0	3
测评	AssessmentController	P0	7
订单	OrderController	P0	5
业务详情	BusinessController	P1	1
规划师	PlannerController	P1	2
分销	InviteController	P1	6
系统	SystemController	P2	3
团队	TeamController	P2	1

二、代码规范参考

2.1 控制器模板

[ApiController]
[Route("api")]
public class XxxController : ControllerBase
{
    private readonly IXxxService _xxxService;
    private readonly ILogger<XxxController> _logger;

    public XxxController(IXxxService xxxService, ILogger<XxxController> logger)
    {
        _xxxService = xxxService;
        _logger = logger;
    }

    /// <summary>
    /// 接口描述
    /// </summary>
    [HttpGet("actionName")]
    [Authorize]  // 需要登录的接口
    public async Task<ApiResponse<T>> ActionName([FromQuery] Request request)
    {
        // 实现
    }
}

2.2 响应格式

成功：ApiResponse<T>.Success(data, "message")
失败：ApiResponse<T>.Fail("error message")
未授权：ApiResponse<T>.Unauthorized()

三、开发任务详情

3.1 首页模块 (HomeController) - P0

任务 H-1：获取 Banner 列表

项目	内容
接口	`GET /api/home/getBannerList`
认证	否
数据库表	banners
实体类	Banner.cs
DTO	BannerDto.cs
服务接口	IHomeService.GetBannerListAsync()
业务逻辑	查询 Status=1 且未删除的记录，按 Sort 降序

任务 H-2：获取测评入口列表

项目	内容
接口	`GET /api/home/getAssessmentList`
认证	否
数据库表	assessment_types
实体类	AssessmentType.cs（已存在）
DTO	AssessmentTypeDto.cs
服务接口	IHomeService.GetAssessmentListAsync()
业务逻辑	查询未删除的记录，按 Sort 降序

任务 H-3：获取宣传图列表

项目	内容
接口	`GET /api/home/getPromotionList`
认证	否
数据库表	promotions
实体类	Promotion.cs
DTO	PromotionDto.cs
服务接口	IHomeService.GetPromotionListAsync()
业务逻辑	查询 Position=1, Status=1 且未删除的记录

3.2 业务详情模块 (BusinessController) - P1

任务 B-1：获取业务详情

项目	内容
接口	`GET /api/business/getDetail?id=1`
认证	否
数据库表	business_pages（需新建）或复用 banners
实体类	BusinessPage.cs
DTO	BusinessDetailDto.cs
服务接口	IBusinessService.GetDetailAsync(id)
业务逻辑	根据ID获取业务介绍页内容（背景图、是否显示参与按钮、跳转链接）
需求来源	需求文档第三章"介绍详情页"

说明：此接口用于 Banner 跳转到业务介绍页时获取详情内容。

3.3 测评模块 (AssessmentController) - P0

任务 A-1：获取测评介绍

项目	内容
接口	`GET /api/assessment/getIntro?typeId=1`
认证	否
数据库表	assessment_types
DTO	AssessmentIntroDto.cs
服务接口	IAssessmentService.GetIntroAsync(typeId)
业务逻辑	根据 typeId 查询测评类型的介绍内容和价格

任务 A-2：获取题目列表

项目	内容
接口	`GET /api/assessment/getQuestionList?typeId=1`
认证	是
数据库表	questions
实体类	Question.cs（已存在）
DTO	QuestionDto.cs
服务接口	IAssessmentService.GetQuestionListAsync(typeId)
业务逻辑	根据 typeId 查询启用的题目，按 QuestionNo 排序

任务 A-3：提交测评答案

项目	内容
接口	`POST /api/assessment/submitAnswers`
认证	是
数据库表	assessment_answers, assessment_records
实体类	AssessmentAnswer.cs, AssessmentRecord.cs
请求模型	SubmitAnswersRequest.cs
响应模型	SubmitAnswersResponse.cs
服务接口	IAssessmentService.SubmitAnswersAsync(userId, request)
业务逻辑	1. 验证记录归属当前用户 2. 保存答案到 assessment_answers 3. 更新记录状态为"生成中" 4. 触发报告生成（异步）

任务 A-4：查询报告生成状态

项目	内容
接口	`GET /api/assessment/getResultStatus?recordId=1`
认证	是
数据库表	assessment_records
DTO	ResultStatusDto.cs
服务接口	IAssessmentService.GetResultStatusAsync(userId, recordId)
业务逻辑	查询记录状态，返回是否完成

任务 A-5：获取测评结果

项目	内容
接口	`GET /api/assessment/getResult?recordId=1`
认证	是
数据库表	assessment_records, assessment_results, report_categories, report_conclusions
DTO	AssessmentResultDto.cs（复杂结构）
服务接口	IAssessmentService.GetResultAsync(userId, recordId)
业务逻辑	1. 验证记录归属且已完成 2. 组装完整报告数据
复杂度	高 - 需要组装多层嵌套数据

任务 A-6：验证邀请码

项目	内容
接口	`POST /api/assessment/verifyInviteCode`
认证	是
数据库表	invite_codes
实体类	InviteCode.cs
请求模型	VerifyInviteCodeRequest.cs
响应模型	VerifyInviteCodeResponse.cs
服务接口	IAssessmentService.VerifyInviteCodeAsync(code)
业务逻辑	验证邀请码是否存在且未使用

任务 A-7：获取往期测评列表

项目	内容
接口	`GET /api/assessment/getHistoryList?page=1&pageSize=20`
认证	是
数据库表	assessment_records, orders
DTO	AssessmentHistoryDto.cs
服务接口	IAssessmentService.GetHistoryListAsync(userId, page, pageSize)
业务逻辑	分页查询用户的测评记录

3.4 订单模块 (OrderController) - P0

任务 O-1：获取订单列表

项目	内容
接口	`GET /api/order/getList?page=1&pageSize=20&orderType=1`
认证	是
数据库表	orders
实体类	Order.cs（已存在）
DTO	OrderItemDto.cs
服务接口	IOrderService.GetListAsync(userId, page, pageSize, orderType)
业务逻辑	分页查询用户订单，支持按类型筛选

任务 O-2：获取订单详情

项目	内容
接口	`GET /api/order/getDetail?orderId=1`
认证	是
数据库表	orders, assessment_records, planner_bookings
DTO	OrderDetailDto.cs
服务接口	IOrderService.GetDetailAsync(userId, orderId)
业务逻辑	查询订单详情，关联测评记录或规划预约

任务 O-3：创建订单

项目	内容
接口	`POST /api/order/create`
认证	是
数据库表	orders, assessment_records, planner_bookings, invite_codes
请求模型	CreateOrderRequest.cs
响应模型	CreateOrderResponse.cs
服务接口	IOrderService.CreateAsync(userId, request)
业务逻辑	1. 创建订单记录 2. 根据类型创建测评记录或规划预约 3. 处理邀请码（如有）
复杂度	高 - 涉及多表操作和事务

任务 O-4：发起支付

项目	内容
接口	`POST /api/order/pay`
认证	是
数据库表	orders
请求模型	PayRequest.cs
响应模型	PayResponse.cs（微信支付参数）
服务接口	IOrderService.PayAsync(userId, orderId)
业务逻辑	调用微信支付统一下单接口
依赖	已有 PayController/PayService

任务 O-5：查询支付结果

项目	内容
接口	`GET /api/order/getPayResult?orderId=1`
认证	是
数据库表	orders
DTO	PayResultDto.cs
服务接口	IOrderService.GetPayResultAsync(userId, orderId)
业务逻辑	查询订单支付状态

3.5 规划师模块 (PlannerController) - P1

任务 P-1：获取规划师列表

项目	内容
接口	`GET /api/planner/getList`
认证	否
数据库表	planners
实体类	Planner.cs
DTO	PlannerDto.cs
服务接口	IPlannerService.GetListAsync()
业务逻辑	查询启用的规划师，按 Sort 排序

任务 P-2：预约规划

项目	内容
接口	`POST /api/planner/book`
认证	是
说明	复用订单创建接口，orderType=2

3.6 分销模块 (InviteController) - P1

任务 I-1：获取邀请信息

项目	内容
接口	`GET /api/invite/getInfo`
认证	是
数据库表	users
DTO	InviteInfoDto.cs
服务接口	IInviteService.GetInfoAsync(userId)
业务逻辑	返回用户邀请码、余额、邀请人数等

任务 I-2：生成邀请二维码

项目	内容
接口	`GET /api/invite/getQrcode`
认证	是
DTO	QrcodeDto.cs
服务接口	IInviteService.GetQrcodeAsync(userId)
业务逻辑	调用微信小程序码接口生成带参数二维码
依赖	微信 API

任务 I-3：获取邀请记录

项目	内容
接口	`GET /api/invite/getRecordList?page=1&pageSize=20`
认证	是
数据库表	users, commissions
DTO	InviteRecordDto.cs
服务接口	IInviteService.GetRecordListAsync(userId, page, pageSize)
业务逻辑	查询下级用户列表及贡献佣金

任务 I-4：获取佣金信息

项目	内容
接口	`GET /api/invite/getCommission`
认证	是
数据库表	users
DTO	CommissionInfoDto.cs
服务接口	IInviteService.GetCommissionAsync(userId)
业务逻辑	返回累计收益、已提现、待提现

任务 I-5：申请提现

项目	内容
接口	`POST /api/invite/applyWithdraw`
认证	是
数据库表	withdrawals, users
实体类	Withdrawal.cs
请求模型	ApplyWithdrawRequest.cs
响应模型	ApplyWithdrawResponse.cs
服务接口	IInviteService.ApplyWithdrawAsync(userId, amount)
业务逻辑	1. 验证余额充足 2. 创建提现记录 3. 扣减用户余额

任务 I-6：获取提现记录

项目	内容
接口	`GET /api/invite/getWithdrawList?page=1&pageSize=20`
认证	是
数据库表	withdrawals
DTO	WithdrawRecordDto.cs
服务接口	IInviteService.GetWithdrawListAsync(userId, page, pageSize)
业务逻辑	分页查询用户提现记录

3.7 系统模块 (SystemController) - P2

任务 S-1：获取用户协议

项目	内容
接口	`GET /api/system/getAgreement`
认证	否
数据库表	configs
DTO	AgreementDto.cs
服务接口	ISystemService.GetAgreementAsync()
业务逻辑	从配置表读取用户协议内容

任务 S-2：获取隐私政策

项目	内容
接口	`GET /api/system/getPrivacy`
认证	否
数据库表	configs
DTO	PrivacyDto.cs
服务接口	ISystemService.GetPrivacyAsync()
业务逻辑	从配置表读取隐私政策内容

任务 S-3：获取关于我们

项目	内容
接口	`GET /api/system/getAbout`
认证	否
数据库表	configs
DTO	AboutDto.cs
服务接口	ISystemService.GetAboutAsync()
业务逻辑	从配置表读取关于我们内容和版本号

3.8 团队模块 (TeamController) - P2

任务 T-1：获取团队介绍

项目	内容
接口	`GET /api/team/getInfo`
认证	否
数据库表	promotions
DTO	TeamInfoDto.cs
服务接口	ITeamService.GetInfoAsync()
业务逻辑	查询 Position=2 的宣传图列表

四、开发顺序建议

第一阶段：核心流程 (P0)

首页模块 - 简单，快速完成
- H-1 Banner 列表
- H-2 测评入口列表
- H-3 宣传图列表
订单模块 - 支付流程核心
- O-3 创建订单（最复杂，优先）
- O-1 订单列表
- O-2 订单详情
- O-4 发起支付
- O-5 支付结果
测评模块 - 业务核心
- A-1 测评介绍
- A-2 题目列表
- A-6 验证邀请码
- A-3 提交答案
- A-4 报告状态
- A-7 往期列表
- A-5 测评结果（最复杂）

第二阶段：分销功能 (P1)

规划师模块
- P-1 规划师列表
分销模块
- I-1 邀请信息
- I-4 佣金信息
- I-3 邀请记录
- I-5 申请提现
- I-6 提现记录
- I-2 邀请二维码

第三阶段：辅助功能 (P2)

系统模块
- S-1 用户协议
- S-2 隐私政策
- S-3 关于我们
团队模块
- T-1 团队介绍

五、需要新建的文件清单

5.1 实体类 (Entities)

文件	对应表	说明
Banner.cs	banners	轮播图
Promotion.cs	promotions	宣传图
Planner.cs	planners	规划师
PlannerBooking.cs	planner_bookings	规划预约
InviteCode.cs	invite_codes	邀请码
Commission.cs	commissions	佣金记录
Withdrawal.cs	withdrawals	提现记录

5.2 DTO 模型 (Models)

Home 模块

Models/Home/BannerDto.cs
Models/Home/AssessmentTypeDto.cs
Models/Home/PromotionDto.cs

Assessment 模块

Models/Assessment/AssessmentIntroDto.cs
Models/Assessment/QuestionDto.cs
Models/Assessment/SubmitAnswersRequest.cs
Models/Assessment/SubmitAnswersResponse.cs
Models/Assessment/ResultStatusDto.cs
Models/Assessment/AssessmentResultDto.cs
Models/Assessment/VerifyInviteCodeRequest.cs
Models/Assessment/VerifyInviteCodeResponse.cs
Models/Assessment/AssessmentHistoryDto.cs

Order 模块

Models/Order/OrderItemDto.cs
Models/Order/OrderDetailDto.cs
Models/Order/CreateOrderRequest.cs
Models/Order/CreateOrderResponse.cs
Models/Order/PayRequest.cs
Models/Order/PayResponse.cs
Models/Order/PayResultDto.cs

Planner 模块

Models/Planner/PlannerDto.cs

Invite 模块

Models/Invite/InviteInfoDto.cs
Models/Invite/QrcodeDto.cs
Models/Invite/InviteRecordDto.cs
Models/Invite/CommissionInfoDto.cs
Models/Invite/ApplyWithdrawRequest.cs
Models/Invite/ApplyWithdrawResponse.cs
Models/Invite/WithdrawRecordDto.cs

System 模块

Models/System/AgreementDto.cs
Models/System/PrivacyDto.cs
Models/System/AboutDto.cs

Team 模块

Models/Team/TeamInfoDto.cs

5.3 服务接口 (Interfaces)

IHomeService.cs
IAssessmentService.cs
IOrderService.cs（扩展已有）
IPlannerService.cs
IInviteService.cs
ISystemService.cs
ITeamService.cs

5.4 服务实现 (Services)

HomeService.cs
AssessmentService.cs
OrderService.cs（扩展已有）
PlannerService.cs
InviteService.cs
SystemService.cs
TeamService.cs

5.5 控制器 (Controllers)

HomeController.cs
AssessmentController.cs
OrderController.cs
PlannerController.cs
InviteController.cs
SystemController.cs
TeamController.cs

六、复杂任务说明

6.1 创建订单 (O-3)

这是最复杂的接口，需要处理：

测评订单：创建 order + assessment_record
规划订单：创建 order + planner_booking
邀请码处理：验证并标记使用
事务管理：确保数据一致性

// 伪代码
public async Task<CreateOrderResponse> CreateAsync(int userId, CreateOrderRequest request)
{
    using var transaction = await _dbContext.Database.BeginTransactionAsync();
    try
    {
        // 1. 创建订单
        var order = new Order { ... };
        
        // 2. 根据类型创建关联记录
        if (request.OrderType == 1) // 测评
        {
            var record = new AssessmentRecord { ... };
        }
        else // 规划
        {
            var booking = new PlannerBooking { ... };
        }
        
        // 3. 处理邀请码
        if (request.InviteCodeId.HasValue)
        {
            // 标记邀请码已使用
            // 订单金额设为0
        }
        
        await transaction.CommitAsync();
        return new CreateOrderResponse { ... };
    }
    catch
    {
        await transaction.RollbackAsync();
        throw;
    }
}

6.2 获取测评结果 (A-5)

需要组装复杂的嵌套数据结构：

基本信息（来自 assessment_record）
八大智能分析（来自 assessment_result + report_category）
个人特质分析
40项细分能力
其他分析模块

建议：

分步骤查询，避免复杂 JOIN
使用 AutoMapper 简化映射
考虑缓存已生成的报告

6.3 提交测评答案 (A-3)

需要处理：

批量保存答案（80道题）
更新记录状态
触发报告生成（可异步）

报告生成逻辑：

根据答案计算各分类得分
计算排名和星级
匹配结论内容
保存到 assessment_result

七、测试要点

7.1 单元测试

服务层方法的业务逻辑测试
边界条件测试（空数据、分页边界等）

7.2 集成测试

API 端到端测试
数据库事务测试

7.3 关键测试场景

场景	测试点
创建订单	测评订单、规划订单、使用邀请码
提交答案	完整答案、部分答案、重复提交
申请提现	余额充足、余额不足、最低金额
分页查询	首页、末页、空数据

八、注意事项

认证：需要登录的接口添加 [Authorize] 特性
软删除：查询时过滤 IsDeleted = false
分页：使用统一的分页响应格式
日志：关键操作记录日志
异常：使用 try-catch 包装，返回友好错误信息
事务：多表操作使用事务
验证：参数验证在控制器层完成

九、进度跟踪

任务ID	任务名称	状态
H-1	Banner 列表	⬜ 待开发
H-2	测评入口列表	⬜ 待开发
H-3	宣传图列表	⬜ 待开发
B-1	业务详情	⬜ 待开发
A-1	测评介绍	⬜ 待开发
A-2	题目列表	⬜ 待开发
A-3	提交答案	⬜ 待开发
A-4	报告状态	⬜ 待开发
A-5	测评结果	⬜ 待开发
A-6	验证邀请码	⬜ 待开发
A-7	往期列表	⬜ 待开发
O-1	订单列表	⬜ 待开发
O-2	订单详情	⬜ 待开发
O-3	创建订单	⬜ 待开发
O-4	发起支付	⬜ 待开发
O-5	支付结果	⬜ 待开发
P-1	规划师列表	⬜ 待开发
I-1	邀请信息	⬜ 待开发
I-2	邀请二维码	⬜ 待开发
I-3	邀请记录	⬜ 待开发
I-4	佣金信息	⬜ 待开发
I-5	申请提现	⬜ 待开发
I-6	提现记录	⬜ 待开发
S-1	用户协议	⬜ 待开发
S-2	隐私政策	⬜ 待开发
S-3	关于我们	⬜ 待开发
T-1	团队介绍	⬜ 待开发

状态说明：⬜ 待开发 | 🔄 开发中 | ✅ 已完成 | ❌ 已取消

24 KiB Raw Blame History Unescape Escape