mi-assessment/docs/API开发任务清单.md

# 学业邑规划 - 小程序 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

1. **业务详情页接口** - 需求第三章
   - 接口：`GET /api/business/getDetail?id=1`
   - 功能：获取业务介绍页内容（背景长图、是否有参与按钮）
   - 来源：Banner跳转到业务详情页

2. **发送短信验证码** - 如果支持手机号验证码登录
   - 接口：`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 控制器模板
```csharp
[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. 验证记录归属当前用户<br>2. 保存答案到 assessment_answers<br>3. 更新记录状态为"生成中"<br>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. 验证记录归属且已完成<br>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. 创建订单记录<br>2. 根据类型创建测评记录或规划预约<br>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. 验证余额充足<br>2. 创建提现记录<br>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)
1. **首页模块** - 简单，快速完成
   - H-1 Banner 列表
   - H-2 测评入口列表
   - H-3 宣传图列表

2. **订单模块** - 支付流程核心
   - O-3 创建订单（最复杂，优先）
   - O-1 订单列表
   - O-2 订单详情
   - O-4 发起支付
   - O-5 支付结果

3. **测评模块** - 业务核心
   - A-1 测评介绍
   - A-2 题目列表
   - A-6 验证邀请码
   - A-3 提交答案
   - A-4 报告状态
   - A-7 往期列表
   - A-5 测评结果（最复杂）

### 第二阶段：分销功能 (P1)
4. **规划师模块**
   - P-1 规划师列表

5. **分销模块**
   - I-1 邀请信息
   - I-4 佣金信息
   - I-3 邀请记录
   - I-5 申请提现
   - I-6 提现记录
   - I-2 邀请二维码

### 第三阶段：辅助功能 (P2)
6. **系统模块**
   - S-1 用户协议
   - S-2 隐私政策
   - S-3 关于我们

7. **团队模块**
   - 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)
这是最复杂的接口，需要处理：
1. 测评订单：创建 order + assessment_record
2. 规划订单：创建 order + planner_booking
3. 邀请码处理：验证并标记使用
4. 事务管理：确保数据一致性

```csharp
// 伪代码
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)
需要组装复杂的嵌套数据结构：
1. 基本信息（来自 assessment_record）
2. 八大智能分析（来自 assessment_result + report_category）
3. 个人特质分析
4. 40项细分能力
5. 其他分析模块

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

### 6.3 提交测评答案 (A-3)
需要处理：
1. 批量保存答案（80道题）
2. 更新记录状态
3. 触发报告生成（可异步）

报告生成逻辑：
1. 根据答案计算各分类得分
2. 计算排名和星级
3. 匹配结论内容
4. 保存到 assessment_result

---

## 七、测试要点

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

### 7.2 集成测试
- API 端到端测试
- 数据库事务测试

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

---

## 八、注意事项

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

---

## 九、进度跟踪

| 任务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 | 团队介绍 | ⬜ 待开发 | | |

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