mi-assessment/docs/开发文档.md

# 学业邑规划 - 开发文档

## 一、项目概述

### 1.1 项目信息
- **项目名称**：学业邑规划
- **项目类型**：微信小程序
- **目标用户**：10-50岁学生及家长
- **核心功能**：多元智能测评、学业规划服务、分销推广

### 1.2 技术栈
| 端 | 技术 |
|---|---|
| 前端 | UniApp + Vue 3 + TypeScript |
| 后端 | .NET 10 Web API (C#) |
| 数据库 | SQL Server 2022 |
| 缓存 | Redis |
| 对象存储 | 阿里云 OSS / 腾讯云 COS |
| 支付 | 微信支付 |
| 接口风格 | RPC 风格（仅 GET / POST 请求） |

### 1.3 项目结构
```
├── uniapp/                 # 小程序前端
├── server/                 # 后端服务
│   └── MiAssessment/
│       ├── src/
│       │   ├── MiAssessment.Api/           # 小程序API接口
│       │   ├── MiAssessment.Admin/         # 后台管理系统
│       │   ├── MiAssessment.Admin.Business/ # 后台业务模块
│       │   ├── MiAssessment.Core/          # 核心业务逻辑
│       │   ├── MiAssessment.Infrastructure/ # 基础设施
│       │   └── MiAssessment.Model/         # 数据模型
│       └── scripts/                        # 数据库脚本
└── docs/                   # 文档资料
```

---

## 二、用户角色与权限

### 2.1 小程序用户角色
| 角色 | 说明 | 权限 |
|---|---|---|
| 游客 | 未登录用户 | 浏览首页、团队页 |
| 普通用户 | 已登录用户 | 购买测评、查看报告、学业规划预约 |
| 合伙人 | 后台配置 | 普通用户权限 + 邀请新用户 + 佣金提现 |
| 渠道合伙人 | 后台配置 | 合伙人权限 + 绑定合伙人为下级 |

### 2.2 后台管理角色
| 角色 | 说明 |
|---|---|
| 超级管理员 | 全部权限 |
| 运营人员 | 内容管理、订单管理、用户管理 |
| 财务人员 | 订单管理、提现审核 |

---

## 三、功能模块详细分解

### 3.1 首页模块

#### 3.1.1 Banner轮播图
| 字段 | 说明 |
|---|---|
| 图片 | 轮播图片URL |
| 跳转类型 | 无跳转 / 内部页面 / 外部链接 / 小程序 |
| 跳转地址 | 根据跳转类型填写 |
| 排序 | 显示顺序 |
| 状态 | 启用/禁用 |

**后台功能**：
- 新增/编辑/删除 Banner
- 拖拽排序
- 启用/禁用

#### 3.1.2 测评入口
| 字段 | 说明 |
|---|---|
| 测评名称 | 如"多元智能测评" |
| 入口图片 | 展示图片 |
| 价格 | 测评价格（元） |
| 状态 | 已上线 / 即将上线 / 已下线 |
| 排序 | 显示顺序 |

**交互逻辑**：
- 点击"已上线"测评 → 进入测评流程
- 点击"即将上线"测评 → 弹出提示"该测评暂未开放"

#### 3.1.3 底部宣传图
| 字段 | 说明 |
|---|---|
| 图片 | 长图URL |
| 排序 | 显示顺序 |
| 状态 | 启用/禁用 |

---

### 3.2 团队页模块

#### 3.2.1 团队介绍
| 字段 | 说明 |
|---|---|
| 图片 | 团队介绍图片 |
| 排序 | 显示顺序 |
| 状态 | 启用/禁用 |

---

### 3.3 用户模块

#### 3.3.1 用户注册/登录
**登录方式**：微信一键登录（获取手机号）

**登录流程**：
```
1. 用户点击登录
2. 调用 wx.login() 获取 code
3. 调用 wx.getPhoneNumber() 获取加密手机号
4. 后端解密手机号，创建/更新用户
5. 返回 token
```

**用户信息**：
| 字段 | 说明 |
|---|---|
| UID | 6位随机数字（不以0开头） |
| 手机号 | 微信授权获取 |
| 昵称 | 默认"用户+UID"，可修改 |
| 头像 | 默认头像，可修改 |
| 用户等级 | 普通用户/合伙人/渠道合伙人 |
| 上级用户ID | 邀请关系绑定 |
| 注册时间 | - |

#### 3.3.2 个人信息页
**功能**：
- 查看/修改头像
- 查看/修改昵称
- 查看UID（不可修改）
- 获取微信头像/昵称

#### 3.3.3 用户协议 & 隐私政策
**后台配置**：
- 富文本编辑器配置内容
- 支持图文混排

---

### 3.4 多元智能测评模块（核心）

#### 3.4.1 基本信息填写页

**用户填写字段**：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 姓名 | 文本 | 是 | - |
| 手机号 | 文本 | 是 | 需验证格式 |
| 性别 | 单选 | 是 | 男/女 |
| 年龄 | 下拉 | 是 | 10岁~50岁 |
| 学业阶段 | 下拉 | 是 | 小学及以下/初中/高中/大专/本科/研究生及以上 |
| 省份 | 下拉 | 是 | - |
| 城市 | 下拉 | 是 | - |
| 区县 | 下拉 | 是 | 必须选择到区县 |

**页面顶部介绍**：后台可配置文字或图片

**按钮状态**：
- 有未填写项 → 按钮灰色不可点击
- 全部填写 → 按钮可点击

**两个入口按钮**：
1. **支付￥XX元 开始测评**
   - 金额从后台配置读取
   - 点击后验证信息 → 拉起微信支付
   
2. **邀请码免费测评**
   - 点击后验证信息 → 弹出邀请码输入框
   - 邀请码验证：不存在/已使用/验证通过

**验证规则**：
- 手机号格式验证（11位数字，1开头）
- 城市必须选择到区县

#### 3.4.2 答题页

**题目结构**：
- 共80道选择题
- 每题10个选项
- 所有题目在一个页面内展示（可滚动）

**题目数据结构**：
| 字段 | 说明 |
|---|---|
| 题号 | 1-80 |
| 题目内容 | 题目描述文本 |
| 选项列表 | 10个选项文本 |

**选项评分标准**（展示给用户）：
| 分值 | 等级 | 描述 |
|---|---|---|
| 1分 | 极弱 | 完全不符合 |
| 2分 | 很弱 | 几乎不符合 |
| 3分 | 较弱 | 偶尔符合 |
| 4分 | 偏弱 | 有时候符合 |
| 5分 | 中等 | 普通一般 |
| 6分 | 略强 | 多数情况符合 |
| 7分 | 偏强 | 大多数情况符合 |
| 8分 | 较强 | 绝大多数情况符合 |
| 9分 | 很强 | 偶尔不符合 |
| 10分 | 极强 | 完全符合 |

**提交逻辑**：
- 点击提交 → 检测未答题目
- 有未答题 → 弹窗显示未答题号列表
- 全部已答 → 提交答案 → 进入生成中页面

#### 3.4.3 测评生成中页

**展示内容**：
- 加载动画
- 提示文字："测评报告生成中，请稍候..."
- 提示可在"往期测评"中查看

**逻辑**：
- 后端异步计算测评结果
- 前端轮询查询状态
- 生成完成 → 自动跳转到结果页

#### 3.4.4 测评结果页

**报告内容结构**：
```
1. 基本信息
   - 姓名、年龄、学业阶段、测评日期

2. 八大智能分析
   - 雷达图展示8项智能得分
   - 最强智能TOP2（展示结论）
   - 较弱智能TOP2（展示结论）

3. 个人特质分析
   - 4项特质得分百分比
   - 最强特质结论

4. 40项细分能力分析
   - 按8大智能分组展示
   - 每组显示5项细分能力
   - 五星图展示
   - 最强10项 / 最弱10项

5. 先天学习类型分析
   - 5种类型得分
   - 最强类型结论

6. 学习关键能力分析
   - 5项能力得分
   - 最弱能力结论（需加强）

7. 科学大脑类型分析
   - 5种脑类型得分
   - 最强/最弱类型结论

8. 性格类型分析
   - 5种性格得分
   - 最强性格结论

9. 未来关键发展能力分析
   - 10项能力得分
   - 最强/最弱能力结论
```

**功能按钮**：
- 保存到本地（导出PDF）

---

### 3.5 测评计分逻辑（核心算法）

#### 3.5.1 题目归属关系

每道题可同时归属多个分类：

**报告1-3（累加计分）**：
- 8大智能（每项对应多道题）
- 40细分能力（每项对应2道题）
- 4项个人特质（每项对应20道题）

**报告4-8（0/1计分）**：
- 5种先天学习类型（每种对应9-10道题）
- 5项学习关键能力（每项对应12道题）
- 5种科学大脑类型（每种对应12道题）
- 5种性格类型（每种对应10道题）
- 10项未来发展能力（每项对应10道题）

#### 3.5.2 计分规则

**规则A（报告1-3）**：
```
得分 = 用户选择的选项序号（1-10）
总分 = 该分类下所有题目得分之和
```

**规则B（报告4-8）**：
```
得分 = 用户选择选项1-5 ? 0 : 1
总分 = 该分类下所有题目得分之和
```

#### 3.5.3 结果判定

**8大智能**：
- 按总分排序
- 排名1 → 最强五星
- 排名2 → 较强五星
- 排名7 → 相对较弱
- 排名8 → 相对较弱

**其他分类**：
- 按总分排序
- 最高分 → 展示最强结论
- 最低分 → 展示最弱结论（部分报告）

#### 3.5.4 题目-分类映射表

详见 `docs/题库和结论/1.各分析报告对应题目/` 目录下各文档。

---

### 3.6 学业规划模块

#### 3.6.1 规划师选择页

**规划师信息**：
| 字段 | 说明 |
|---|---|
| 照片 | 规划师头像 |
| 姓名 | - |
| 介绍 | 简介文本 |
| 价格 | 咨询价格（元） |
| 状态 | 启用/禁用 |
| 排序 | 显示顺序 |

#### 3.6.2 规划时间预约页

**预约信息**：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 预约日期 | 日期选择 | 是 | - |
| 预约时间 | 时间选择 | 是 | - |
| 姓名 | 文本 | 是 | - |
| 手机号 | 文本 | 是 | - |
| 性别 | 单选 | 是 | - |
| 所在年级 | 下拉 | 是 | 小学/初中/高中/大专/本科/研究生及以上 |
| 各科成绩 | 动态 | 部分必填 | 根据年级动态显示 |

**各科成绩动态规则**：
| 年级 | 显示科目 |
|---|---|
| 小学 | 语文、数学、英语（必填） |
| 初中/高中 | 语文、数学、英语（必填）+ 物理、化学、生物、地理、政治（选填） |
| 大专/本科/研究生 | 专业名称（必填） |

**支付流程**：
- 全部必填项填写完成 → 按钮可点击
- 点击支付 → 拉起微信支付
- 支付成功 → 弹出预约成功提示

---

### 3.7 订单模块

#### 3.7.1 我的订单页

**订单列表字段**：
| 字段 | 说明 |
|---|---|
| 订单日期 | 创建时间 |
| 订单编号 | 系统生成 |
| 订单类型 | 测评订单 / 学业规划订单 |
| 项目名称 | 如"多元智能测评" |
| 金额 | 支付金额 |
| 订单状态 | 见下表 |

**测评订单状态**：
| 状态 | 说明 | 操作 |
|---|---|---|
| 待测评 | 已支付，未完成答题 | 【开始测评】 |
| 测评生成中 | 已答题，报告生成中 | - |
| 已测评 | 报告已生成 | 【查看测评结果】 |
| 退款中 | 申请退款处理中 | - |
| 已退款 | 退款完成 | - |

**学业规划订单状态**：
| 状态 | 说明 |
|---|---|
| 已支付 | 预约成功 |

#### 3.7.2 往期测评页

**列表字段**：
| 字段 | 说明 |
|---|---|
| 测评日期 | - |
| 订单编号 | - |
| 测评项目 | - |
| 报告状态 | 测评生成中 / 查看测评结果 |

---

### 3.8 邀请分销模块

#### 3.8.1 邀请新用户页（合伙人专属）

**页面内容**：
- 邀请规则说明
- 专属邀请链接
- 生成二维码按钮
- 分享链接按钮（转发微信好友）
- 已提现/待提现金额
- 申请提现按钮
- 提现记录
- 我的邀请记录列表

#### 3.8.2 邀请关系绑定

**绑定规则**：
- 新用户通过邀请链接/二维码进入小程序
- 首次登录时自动绑定上级
- 绑定后不可更改

**层级关系**：
- 最多2级：A邀请B，B邀请C
- A是B的上级，B是C的上级
- A不能直接看到C的信息

#### 3.8.3 佣金规则

**佣金计算**：
```
下级用户支付成功后：
- 直接上级获得 30% 佣金
- 间接上级（上上级）获得 10% 佣金

如果没有间接上级：
- 直接上级获得 40% 佣金
```

**示例**：
```
用户C支付100元：
- 用户B（C的上级）获得 30元
- 用户A（B的上级）获得 10元

用户B支付100元（B没有上级的上级）：
- 用户A（B的上级）获得 40元
```

#### 3.8.4 提现功能

**提现规则**：
- 最低提现金额：1元
- 只能提现整数
- 提现到微信零钱

**提现状态**：
| 状态 | 说明 |
|---|---|
| 申请中 | 用户提交申请 |
| 提现中 | 后台审核通过，打款中 |
| 已提现 | 打款成功 |
| 已取消 | 后台拒绝申请 |

#### 3.8.5 邀请码管理

**邀请码规则**：
- 5位随机大写字母
- 后台批量生成
- 每个邀请码只能使用一次
- 记录：生成时间、发放给谁、使用状态、使用者、使用的测评

---

### 3.9 系统配置模块（后台）

#### 3.9.1 基础配置
| 配置项 | 说明 |
|---|---|
| 小程序名称 | - |
| 客服微信 | - |
| 关于我们 | 富文本 |
| 用户协议 | 富文本 |
| 隐私政策 | 富文本 |

#### 3.9.2 测评配置
| 配置项 | 说明 |
|---|---|
| 测评价格 | 元 |
| 测评介绍 | 基本信息页顶部展示 |
| 题目管理 | 80道题目及选项 |

#### 3.9.3 规划师管理
- 新增/编辑/删除规划师
- 设置价格、介绍、排序、状态

---

## 四、接口设计概览

> **接口风格说明**：本项目采用 RPC 风格，所有接口仅使用 GET 和 POST 两种请求方法。
> - GET：用于查询操作，参数通过 Query String 传递
> - POST：用于新增、修改、删除等操作，参数通过 Request Body (JSON) 传递

### 4.1 小程序端接口

#### 用户模块
| 方法 | 接口 | 说明 |
|---|---|---|
| POST | /api/user/login | 微信登录 |
| GET | /api/user/getProfile | 获取个人信息 |
| POST | /api/user/updateProfile | 更新个人信息 |
| POST | /api/user/updateAvatar | 更新头像 |

#### 首页模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/home/getBannerList | 获取Banner列表 |
| GET | /api/home/getAssessmentList | 获取测评入口列表 |
| GET | /api/home/getPromotionList | 获取底部宣传图 |

#### 团队模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/team/getInfo | 获取团队介绍 |

#### 测评模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/assessment/getIntro | 获取测评介绍 |
| GET | /api/assessment/getQuestionList | 获取题目列表 |
| POST | /api/assessment/submitAnswers | 提交测评答案 |
| GET | /api/assessment/getResult | 获取测评结果 |
| GET | /api/assessment/getResultStatus | 查询报告生成状态 |
| POST | /api/assessment/verifyInviteCode | 验证邀请码 |

#### 订单模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/order/getList | 获取订单列表 |
| GET | /api/order/getDetail | 获取订单详情 |
| POST | /api/order/create | 创建订单 |
| POST | /api/order/pay | 发起支付 |
| GET | /api/order/getPayResult | 查询支付结果 |

#### 学业规划模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/planner/getList | 获取规划师列表 |
| POST | /api/planner/book | 预约规划 |

#### 分销模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/invite/getInfo | 获取邀请信息 |
| GET | /api/invite/getQrcode | 生成邀请二维码 |
| GET | /api/invite/getRecordList | 获取邀请记录 |
| GET | /api/invite/getCommission | 获取佣金信息 |
| POST | /api/invite/applyWithdraw | 申请提现 |
| GET | /api/invite/getWithdrawList | 获取提现记录 |

#### 系统模块
| 方法 | 接口 | 说明 |
|---|---|---|
| GET | /api/system/getAgreement | 获取用户协议 |
| GET | /api/system/getPrivacy | 获取隐私政策 |
| GET | /api/system/getAbout | 获取关于我们 |

### 4.2 接口请求/响应规范

#### 请求格式
```json
// GET 请求示例
GET /api/order/getDetail?orderId=123456

// POST 请求示例
POST /api/user/updateProfile
Content-Type: application/json

{
  "nickname": "张三",
  "avatar": "https://xxx.com/avatar.jpg"
}
```

#### 响应格式
```json
{
  "code": 0,           // 状态码：0成功，非0失败
  "message": "success", // 提示信息
  "data": {}           // 业务数据
}
```

#### 错误码定义
| 错误码 | 说明 |
|---|---|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | 未登录 |
| 1003 | 登录已过期 |
| 1004 | 无权限 |
| 2001 | 业务错误（具体看message） |
| 5000 | 系统错误 |

---

## 五、页面清单

### 5.1 小程序页面

| 页面 | 路径 | 说明 |
|---|---|---|
| 首页 | /pages/index/index | TabBar页面 |
| 团队 | /pages/team/index | TabBar页面 |
| 我的 | /pages/mine/index | TabBar页面 |
| 登录 | /pages/login/index | - |
| 个人信息 | /pages/mine/profile | - |
| 我的订单 | /pages/order/list | - |
| 订单详情 | /pages/order/detail | - |
| 往期测评 | /pages/assessment/history | - |
| 业务详情 | /pages/business/detail | Banner跳转 |
| 测评-基本信息 | /pages/assessment/info | - |
| 测评-答题 | /pages/assessment/questions | - |
| 测评-生成中 | /pages/assessment/loading | - |
| 测评-结果 | /pages/assessment/result | - |
| 学业规划-规划师 | /pages/planner/list | - |
| 学业规划-预约 | /pages/planner/book | - |
| 邀请新用户 | /pages/invite/index | 合伙人专属 |
| 邀请二维码 | /pages/invite/qrcode | - |
| 提现记录 | /pages/invite/withdraw | - |
| 关于 | /pages/about/index | - |
| 用户协议 | /pages/agreement/user | - |
| 隐私政策 | /pages/agreement/privacy | - |

### 5.2 后台管理页面

| 模块 | 页面 |
|---|---|
| 首页 | 数据概览（用户数、订单数、收入等） |
| 用户管理 | 用户列表、用户详情、等级设置 |
| 订单管理 | 订单列表、订单详情、退款处理 |
| 测评管理 | 题目管理、测评记录、报告查看 |
| 内容管理 | Banner管理、测评入口、宣传图、团队介绍 |
| 规划师管理 | 规划师列表、预约记录 |
| 分销管理 | 邀请码管理、佣金记录、提现审核 |
| 系统设置 | 基础配置、协议配置、价格配置 |

---

## 六、非功能需求

### 6.1 性能要求
- 页面加载时间 < 2秒
- 接口响应时间 < 500ms
- 支持1000并发用户

### 6.2 安全要求
- 接口鉴权（JWT Token）
- 敏感数据加密存储
- 防SQL注入、XSS攻击
- 微信支付签名验证

### 6.3 兼容性要求
- 微信基础库版本 >= 2.20.0
- iOS 10.0+
- Android 5.0+

---

## 七、开发计划建议

### 第一阶段：基础框架（1周）
- [ ] 数据库设计
- [ ] 后端项目搭建
- [ ] 小程序项目搭建
- [ ] 微信登录对接

### 第二阶段：核心功能（2周）
- [ ] 首页、团队页、我的页
- [ ] 测评流程（信息填写→答题→结果）
- [ ] 测评计分算法实现
- [ ] 微信支付对接

### 第三阶段：扩展功能（1周）
- [ ] 学业规划模块
- [ ] 订单管理
- [ ] 往期测评

### 第四阶段：分销系统（1周）
- [ ] 邀请关系绑定
- [ ] 佣金计算
- [ ] 提现功能
- [ ] 邀请码管理

### 第五阶段：后台管理（1周）
- [ ] 内容管理
- [ ] 用户管理
- [ ] 订单管理
- [ ] 数据统计

### 第六阶段：测试上线（1周）
- [ ] 功能测试
- [ ] 性能测试
- [ ] 小程序审核
- [ ] 正式上线

---

## 八、双数据库架构

### 8.1 架构说明

本项目采用双数据库架构，严格区分后台管理数据与业务数据：

| 数据库 | 名称 | 职责 |
|--------|------|------|
| Admin 库 | `MiAssessment_Admin` | 后台管理系统自身运行所需数据（RBAC、审计、运营配置） |
| Business 库 | `MiAssessment_Business` | C端用户产生的或直接服务C端的业务数据 |

### 8.2 配置数据分离

| 配置类型 | 所在库 | 表名 | 说明 |
|----------|--------|------|------|
| 运营配置 | Admin 库 | `admin_configs` | 支付密钥、小程序配置、上传凭证、短信配置等 |
| 业务配置 | Business 库 | `configs` | 测评价格、佣金比例、提现限额、联系方式、协议内容等 |

### 8.3 DbContext 映射

| DbContext | 所在项目 | 连接数据库 | 读写权限 |
|-----------|----------|------------|----------|
| `AdminDbContext` | MiAssessment.Admin | Admin 库 | 读写 |
| `AdminBusinessDbContext` | MiAssessment.Admin.Business | Business 库 | 读写 |
| `AdminConfigDbContext` | MiAssessment.Admin.Business | Admin 库 | 只读 |
| `AdminConfigReadDbContext` | MiAssessment.Model | Admin 库 | 只读 |
| `MiAssessmentDbContext` | MiAssessment.Model | Business 库 | 读写 |

### 8.4 跨库访问规则

1. Business 项目对 Admin 库**只读**，通过 `AdminConfigDbContext`
2. Core/API 项目对 Admin 库**只读**，通过 `AdminConfigReadDbContext`
3. Admin 库的**写操作只通过 Admin 项目**的 `AdminDbContext` 进行
4. 连接字符串：Admin 库 = `AdminConnection`，Business 库 = `DefaultConnection`

---

## 九、附录

### 9.1 设计图地址
Figma: https://www.figma.com/design/88edYGASUcyID6afiwILdf/项目?node-id=432-1991

### 9.2 相关文档
- 需求文档：`docs/需求文档.md`
- 题库文档：`docs/题库和结论/`
- 设计切图：`docs/切图/`
- 设计图：`docs/设计图/`

### 9.3 题目-分类映射汇总

详见各分析报告对应题目文档，核心映射关系已在 3.5 节说明。