scottpan/msh-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: MSH System\n\n- msh_single_uniapp: Vue 2 + UniApp 前端（微信小程序/H5/App/支付宝小程序）\n- msh_crmeb_22: Spring Boot 2.2 后端（C端API/管理端/业务逻辑）\n- models-integration: AI服务集成（Coze/KieAI/腾讯ASR）\n- docs: 产品文档与设计稿

Browse Source
This commit is contained in:
scottpan
2026-02-28 05:40:21 +08:00
commit 14d29d51c0
2182 changed files with 482509 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/.DS_Store vendored Normal file
View File

Binary file not shown.

5756
docs/PRD_慢生活智能营养专家_v2.0.md Normal file
View File

File diff suppressed because it is too large Load Diff

542
docs/Testing/Coze-API测试文档.md Normal file
View File

@@ -0,0 +1,542 @@
# Coze API 测试文档
> **版本**：v1.0
> **创建日期**：2026-02-08
> **基础路径**：`/api/front/coze`
> **服务端口**：20822
> **认证方式**：免登录（已加入白名单）
---
## 一、配置信息
### 1.1 当前环境配置
| 配置项 | 值 | 说明 |
|--------|-----|------|
| Base URL | `https://api.coze.cn` | Coze 平台 API 地址 |
| Auth Type | `pat` | Personal Access Token 模式 |
| Default Bot ID | `7591133240535449654` | 食谱计算器 Bot |
| Default User ID | `3243981400446844` | 测试用户 ID |
---
## 二、接口清单
| 序号 | 接口名称 | HTTP方法 | 路径 | 说明 |
|------|----------|----------|------|------|
| 1 | 发起对话 | `POST` | `/chat` | 与 Coze Bot 对话（支持流式/非流式） |
| 2 | 流式对话 | `POST` | `/chat/stream` | SSE 流式对话 |
| 3 | 执行工作流 | `POST` | `/workflow/run` | 触发预定义工作流 |
| 4 | 流式执行工作流 | `POST` | `/workflow/stream` | SSE 流式执行工作流 |
| 5 | 查看对话详情 | `POST` | `/chat/retrieve` | 查询对话状态 |
| 6 | 查看对话消息列表 | `POST` | `/chat/messages/list` | 获取对话消息 |
| 7 | 上传文件 | `POST` | `/file/upload` | 上传文件获取 file_id |
---
## 三、接口详细说明
### 3.1 发起对话
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat` |
| Content-Type | `application/json` |
| 是否鉴权 | **否**（白名单） |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `botId` | String | 是 | Coze Bot ID |
| `userId` | String | 是 | 业务系统用户 ID |
| `stream` | Boolean | 否 | 是否流式返回，默认 false |
| `chatHistory` | Array | 否 | 历史对话上下文 |
| `additionalMessages` | Array | 否 | 当前发送的消息 |
**chatHistory 结构**
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `role` | String | 角色：`user` / `assistant` |
| `content` | String | 消息内容 |
| `contentType` | String | 内容类型：`text` / `object_string` / `card` |
#### 测试用例
##### TC-COZE-01: 基础对话测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "你好，请介绍一下自己"
}
]
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "xxxxx",
"conversationId": "xxxxx",
"botId": "7591133240535449654",
"status": "completed",
"createdAt": 1707350400,
"completedAt": 1707350405
}
}
```
##### TC-COZE-02: 食谱计算器测试（男性透析患者）
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "3243981400446844",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L"
}
]
}'
```
##### TC-COZE-03: 食谱计算器测试（女性非透析患者）
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "3243981400446844",
"stream": false,
"additionalMessages": [
{
"role": "user",
"content": "请帮我计算营养方案，我的信息如下：性别女，年龄48岁，身高160cm，未透析，体重52kg，血肌酐180μmol/L"
}
]
}'
```
##### TC-COZE-04: 带历史上下文的对话
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat' \
-H "Content-Type: application/json" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"stream": false,
"chatHistory": [
{
"role": "user",
"content": "我是一名55岁的男性透析患者",
"contentType": "text"
},
{
"role": "assistant",
"content": "好的，我了解了您的基本情况。请问您还有其他健康数据需要提供吗？",
"contentType": "text"
}
],
"additionalMessages": [
{
"role": "user",
"content": "我的身高是170cm，体重65.5kg，血肌酐850"
}
]
}'
```
---
### 3.2 流式对话
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |
#### 测试用例
##### TC-COZE-05: 流式对话测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"botId": "7591133240535449654",
"userId": "test_user_001",
"additionalMessages": [
{
"role": "user",
"content": "请详细介绍一下肾病患者的饮食注意事项"
}
]
}'
```
**预期响应（SSE 格式）**
```
event: message
data: {"event":"conversation.chat.created","chat":{"id":"xxx","conversation_id":"xxx"}}
event: message
data: {"event":"conversation.message.delta","message":{"content":"肾病患者..."}}
event: message
data: {"event":"conversation.message.delta","message":{"content":"需要注意..."}}
event: message
data: {"event":"conversation.chat.completed","chat":{"status":"completed"}}
```
---
### 3.3 执行工作流
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/run` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `workflowId` | String | 是 | 工作流 ID |
| `parameters` | Object | 否 | 工作流输入参数 |
| `isAsync` | Boolean | 否 | 是否异步执行，默认 false |
#### 测试用例
##### TC-COZE-06: 同步执行工作流
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
"workflowId": "1180790412263",
"isAsync": false,
"parameters": {
"gender": "male",
"age": 55,
"height": 170,
"dialysis": true,
"dialysisType": "hemodialysis",
"dryWeight": 65.5,
"creatinine": 850
}
}'
```
##### TC-COZE-07: 异步执行工作流
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/run' \
-H "Content-Type: application/json" \
-d '{
"workflowId": "1180790412263",
"isAsync": true,
"parameters": {
"userId": "test_user_001",
"recordId": 12345
}
}'
```
---
### 3.4 流式执行工作流
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/workflow/stream` |
| Content-Type | `application/json` |
| Response Type | `text/event-stream` |
#### 测试用例
##### TC-COZE-08: 流式工作流测试
```bash
curl -X POST 'http://localhost:20822/api/front/coze/workflow/stream' \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{
"workflowId": "1180790412263",
"parameters": {
"input": "分析用户的饮食记录"
}
}'
```
---
### 3.5 查看对话详情
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/retrieve` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |
#### 测试用例
##### TC-COZE-09: 查询对话详情
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/retrieve' \
-H "Content-Type: application/json" \
-d '{
"conversationId": "7460461142355574825",
"chatId": "7460461142355590000"
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "7460461142355590000",
"conversationId": "7460461142355574825",
"botId": "7591133240535449654",
"status": "completed",
"createdAt": 1707350400,
"completedAt": 1707350410,
"usage": {
"tokenCount": 1500,
"outputCount": 800,
"inputCount": 700
}
}
}
```
---
### 3.6 查看对话消息列表
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/chat/messages/list` |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `conversationId` | String | 是 | 对话 ID |
| `chatId` | String | 是 | Chat ID |
#### 测试用例
##### TC-COZE-10: 获取对话消息列表
```bash
curl -X POST 'http://localhost:20822/api/front/coze/chat/messages/list' \
-H "Content-Type: application/json" \
-d '{
"conversationId": "7460461142355574825",
"chatId": "7460461142355590000"
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": "msg_001",
"role": "user",
"type": "question",
"content": "请帮我计算营养方案",
"contentType": "text",
"createdAt": 1707350400
},
{
"id": "msg_002",
"role": "assistant",
"type": "answer",
"content": "根据您提供的信息，我为您计算了以下营养方案...",
"contentType": "text",
"createdAt": 1707350410
}
]
}
```
---
### 3.7 上传文件
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/coze/file/upload` |
| Content-Type | `multipart/form-data` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `file` | File | 是 | 待上传的文件 |
#### 测试用例
##### TC-COZE-11: 上传图片文件
```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/image.jpg"
```
##### TC-COZE-12: 上传文档文件
```bash
curl -X POST 'http://localhost:20822/api/front/coze/file/upload' \
-F "file=@/path/to/your/document.pdf"
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "file_xxxxx",
"bytes": 102400,
"createdAt": 1707350400,
"fileName": "image.jpg"
}
}
```
---
## 四、错误码说明
| code | message | 说明 |
|------|---------|------|
| 200 | success | 请求成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 认证失败（Token 无效或过期） |
| 404 | Not Found | 资源不存在 |
| 429 | Too Many Requests | 请求频率超限 |
| 500 | Internal Server Error | 服务端内部错误 |
---
## 五、常见问题
### 5.1 Token 过期
当前使用 PAT 模式，Token 有效期 30 天。如遇 401 错误，请检查配置文件中的 `coze.api.token` 是否过期。
### 5.2 Bot ID 无效
确保使用正确的 Bot ID。默认 Bot ID `7591133240535449654` 为食谱计算器专用。
### 5.3 流式接口超时
流式接口默认超时时间为 60 秒。对于长时间运行的对话，请确保客户端保持连接。
---
## 六、Postman 测试集合
可导入以下 JSON 到 Postman 进行测试：
```json
{
"info": {
"name": "Coze API Tests",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "基础对话",
"request": {
"method": "POST",
"header": [{"key": "Content-Type", "value": "application/json"}],
"body": {
"mode": "raw",
"raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"test_user_001\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"你好\"}]}"
},
"url": {"raw": "http://localhost:20822/api/front/coze/chat"}
}
},
{
"name": "食谱计算-男性透析",
"request": {
"method": "POST",
"header": [{"key": "Content-Type", "value": "application/json"}],
"body": {
"mode": "raw",
"raw": "{\"botId\": \"7591133240535449654\", \"userId\": \"3243981400446844\", \"stream\": false, \"additionalMessages\": [{\"role\": \"user\", \"content\": \"请帮我计算营养方案，我的信息如下：性别男，年龄55岁，身高170cm，正在进行血液透析，干体重65.5kg，血肌酐850μmol/L\"}]}"
},
"url": {"raw": "http://localhost:20822/api/front/coze/chat"}
}
}
]
}
```
---
## 七、变更记录
| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-02-08 | System | 初稿 |
---
*文档结束*

808
docs/Testing/Tool模块-API测试文档.md Normal file
View File

@@ -0,0 +1,808 @@
# Tool 模块 API 测试文档
> **版本**：v1.0
> **创建日期**：2026-02-08
> **基础路径**：`/api/front/tool`
> **服务端口**：20822
> **认证方式**：需登录（Header: `Authori-zation`）
---
## 一、接口总览
### 1.1 模块分类
| 模块 | 接口数量 | 说明 |
|------|----------|------|
| 食谱计算器 | 3 | 营养方案计算与采纳 |
| AI营养师 | 4 | AI 对话问答 |
| 饮食打卡 | 8 | 打卡记录管理 |
| 食物百科 | 4 | 食物查询 |
| 营养知识 | 3 | 知识库查询 |
| 打卡社区 | 9 | 社区互动 |
| 积分系统 | 5 | 积分管理 |
| 首页数据 | 4 | 首页聚合数据 |
| 食谱管理 | 3 | 食谱收藏 |
| 文件上传 | 2 | 图片/语音上传 |
---
## 二、认证说明
所有接口（除特殊标注外）均需要登录认证：
```bash
# Header 示例
-H "Authori-zation: eyJhbGciOiJIUzI1NiJ9.xxxxx"
```
---
## 三、食谱计算器
### 3.1 计算营养方案
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/calculator/calculate` |
| Content-Type | `application/json` |
| 是否鉴权 | **是** |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| `gender` | String | 是 | 性别 | `male` / `female` |
| `age` | Integer | 是 | 年龄（岁） | 1 ≤ age ≤ 150 |
| `height` | Integer | 是 | 身高（cm） | 50 ≤ height ≤ 250 |
| `dialysis` | Boolean | 是 | 是否透析 | true / false |
| `dialysisType` | String | 否 | 透析类型 | `hemodialysis` / `peritoneal` |
| `dryWeight` | Number | 是 | 干体重（kg） | 20 ≤ dryWeight ≤ 300 |
| `creatinine` | Number | 是 | 血肌酐（μmol/L） | 0 < creatinine ≤ 2000 |
#### 测试用例
##### TC-CALC-01: 男性透析患者计算
```bash
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"gender": "male",
"age": 55,
"height": 170,
"dialysis": true,
"dialysisType": "hemodialysis",
"dryWeight": 65.5,
"creatinine": 850
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"id": 100234,
"healthData": {
"eGFR": "7.9",
"standardWeight": "63.0",
"bmi": "22.7",
"bmiStatus": "正常",
"ckdStage": "透析期"
},
"nutritionGoals": {
"protein": "75.6",
"energy": "2205"
},
"foodList": [
{ "number": 1, "name": "谷薯50g", "portion": "5.7" },
{ "number": 2, "name": "淀粉100g", "portion": "0.77" },
{ "number": 3, "name": "绿叶蔬菜200g", "portion": "1" },
{ "number": 4, "name": "瓜果蔬菜200g", "portion": "2" },
{ "number": 5, "name": "奶类230g", "portion": "1" },
{ "number": 6, "name": "肉蛋类50/60g", "portion": "7" },
{ "number": 7, "name": "油脂类10g", "portion": "5.7" }
],
"mealPlan": {
"breakfast": [...],
"lunch": [...],
"dinner": [...]
},
"importantTips": [
"以上配餐由 AI 生成，仅适用于无其他并发症的单纯尿毒症人群",
"透析患者需严格控制水分摄入"
],
"createdAt": "2026-02-08T10:30:00+08:00"
}
}
```
##### TC-CALC-02: 女性非透析患者计算
```bash
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"gender": "female",
"age": 48,
"height": 160,
"dialysis": false,
"dryWeight": 52,
"creatinine": 180
}'
```
##### TC-CALC-03: 参数校验-年龄超出范围
```bash
curl -X POST 'http://localhost:20822/api/front/tool/calculator/calculate' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"gender": "male",
"age": 200,
"height": 170,
"dialysis": false,
"dryWeight": 65,
"creatinine": 100
}'
```
**预期响应**：`code=400, message 包含"年龄"`
---
### 3.2 获取计算结果详情
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `GET /api/front/tool/calculator/result/{id}` |
| 是否鉴权 | **是** |
#### 测试用例
##### TC-CALC-04: 获取计算结果
```bash
curl -X GET 'http://localhost:20822/api/front/tool/calculator/result/100234' \
-H "Authori-zation: YOUR_TOKEN"
```
##### TC-CALC-05: 查询不存在的结果
```bash
curl -X GET 'http://localhost:20822/api/front/tool/calculator/result/999999' \
-H "Authori-zation: YOUR_TOKEN"
```
**预期响应**：`code=404`
---
### 3.3 采纳营养计划
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/calculator/adopt` |
| Content-Type | `application/json` |
| 是否鉴权 | **是** |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `resultId` | Long | 是 | 计算结果 ID |
#### 测试用例
##### TC-CALC-06: 采纳营养计划
```bash
curl -X POST 'http://localhost:20822/api/front/tool/calculator/adopt' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"resultId": 100234
}'
```
**预期响应**
```json
{
"code": 200,
"message": "success",
"data": {
"planId": 56789,
"startDate": "2026-02-08",
"endDate": "2026-02-14"
}
}
```
##### TC-CALC-07: 重复采纳（幂等测试）
```bash
# 同一 resultId 调用两次
curl -X POST 'http://localhost:20822/api/front/tool/calculator/adopt' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{"resultId": 100234}'
```
**预期响应**：返回已存在的 planId
---
## 四、AI 营养师
### 4.1 发送消息给 AI 营养师
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/ai-nutritionist/message` |
| Content-Type | `application/json` |
#### 测试用例
##### TC-AI-01: 发送消息
```bash
curl -X POST 'http://localhost:20822/api/front/tool/ai-nutritionist/message' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"conversationId": "conv_001",
"content": "肾病患者可以吃香蕉吗？"
}'
```
---
### 4.2 获取 AI 回复
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `GET /api/front/tool/ai-nutritionist/response/{messageId}` |
#### 测试用例
##### TC-AI-02: 获取回复
```bash
curl -X GET 'http://localhost:20822/api/front/tool/ai-nutritionist/response/12345' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 4.3 获取对话历史
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `GET /api/front/tool/ai-nutritionist/history` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `page` | Integer | 否 | 页码，默认 1 |
| `limit` | Integer | 否 | 每页数量，默认 20 |
| `conversationId` | Long | 否 | 对话 ID |
#### 测试用例
##### TC-AI-03: 获取对话历史
```bash
curl -X GET 'http://localhost:20822/api/front/tool/ai-nutritionist/history?page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 4.4 清空对话历史
#### 测试用例
##### TC-AI-04: 清空对话
```bash
curl -X POST 'http://localhost:20822/api/front/tool/ai-nutritionist/clear' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"conversationId": "conv_001"
}'
```
---
## 五、饮食打卡
### 5.1 提交打卡记录
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/checkin/submit` |
| Content-Type | `application/json` |
#### 测试用例
##### TC-CHECKIN-01: 提交打卡
```bash
curl -X POST 'http://localhost:20822/api/front/tool/checkin/submit' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"mealType": "breakfast",
"date": "2026-02-08",
"foods": [
{"name": "牛奶", "amount": "250ml"},
{"name": "全麦面包", "amount": "2片"}
],
"images": ["https://cdn.xxx.com/img1.jpg"],
"remark": "早餐清淡"
}'
```
---
### 5.2 获取打卡记录列表
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `page` | Integer | 否 | 页码 |
| `limit` | Integer | 否 | 每页数量 |
| `date` | String | 否 | 日期筛选 YYYY-MM-DD |
| `mealType` | String | 否 | 餐次：breakfast/lunch/dinner |
#### 测试用例
##### TC-CHECKIN-02: 获取打卡列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/checkin/list?page=1&limit=10&date=2026-02-08' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 5.3 获取打卡记录详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/checkin/detail/123' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 5.4 获取连续打卡统计
```bash
curl -X GET 'http://localhost:20822/api/front/tool/checkin/streak' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 5.5 获取打卡日历数据
```bash
curl -X GET 'http://localhost:20822/api/front/tool/checkin/calendar?yearMonth=2026-02' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 5.6 获取打卡任务列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/checkin/tasks' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 5.7 一键复制打卡
```bash
curl -X POST 'http://localhost:20822/api/front/tool/checkin/copy' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"sourceRecordId": 12345,
"targetDate": "2026-02-08",
"mealType": "lunch"
}'
```
---
### 5.8 一键借鉴打卡
```bash
curl -X POST 'http://localhost:20822/api/front/tool/checkin/learn' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"sourcePostId": 67890,
"targetDate": "2026-02-08",
"mealType": "dinner"
}'
```
---
## 六、食物百科
### 6.1 搜索食物
```bash
curl -X GET 'http://localhost:20822/api/front/tool/food/search?keyword=鸡蛋&category=蛋类&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 6.2 获取食物列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/food/list?category=肉类&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 6.3 获取食物详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/food/detail/100' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 6.4 获取相似食物推荐
```bash
curl -X GET 'http://localhost:20822/api/front/tool/food/similar/100' \
-H "Authori-zation: YOUR_TOKEN"
```
---
## 七、营养知识
### 7.1 获取营养知识列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/list?type=article&category=肾病饮食&page=1&limit=10' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 7.2 获取营养知识详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/detail/50' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 7.3 获取营养素详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/knowledge/nutrient/蛋白质' \
-H "Authori-zation: YOUR_TOKEN"
```
---
## 八、打卡社区
### 8.1 获取社区内容列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/community/list?tab=recommend&page=1&limit=10' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 8.2 获取社区内容详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/community/detail/200' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 8.3 发布社区内容
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/publish' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"content": "今天的早餐很健康！",
"images": ["https://cdn.xxx.com/img1.jpg"],
"checkinId": 12345
}'
```
---
### 8.4 点赞/取消点赞
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/like' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"postId": 200,
"isLike": true
}'
```
---
### 8.5 收藏/取消收藏
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/collect' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"postId": 200,
"isCollect": true
}'
```
---
### 8.6 发表评论
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/comment' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"postId": 200,
"content": "看起来很不错！",
"parentId": null
}'
```
---
### 8.7 获取评论列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/community/comment/list/200?page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 8.8 关注/取消关注用户
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/follow' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"userId": 1001,
"isFollow": true
}'
```
---
### 8.9 分享内容
```bash
curl -X POST 'http://localhost:20822/api/front/tool/community/share' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"postId": 200
}'
```
---
## 九、积分系统
### 9.1 获取用户积分信息
```bash
curl -X GET 'http://localhost:20822/api/front/tool/points/info' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 9.2 获取积分规则
```bash
curl -X GET 'http://localhost:20822/api/front/tool/points/rules' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 9.3 获取积分流水
```bash
curl -X GET 'http://localhost:20822/api/front/tool/points/history?type=earn&page=1&limit=20' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 9.4 获取积分兑换列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/points/exchange/list' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 9.5 积分兑换
```bash
curl -X POST 'http://localhost:20822/api/front/tool/points/exchange' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"exchangeId": 10
}'
```
---
## 十、首页数据
### 10.1 获取首页数据
```bash
curl -X GET 'http://localhost:20822/api/front/tool/home/data' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 10.2 获取推荐食谱列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/home/recipes?limit=6' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 10.3 获取推荐营养知识
```bash
curl -X GET 'http://localhost:20822/api/front/tool/home/knowledge?limit=4' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 10.4 获取用户健康档案状态
```bash
curl -X GET 'http://localhost:20822/api/front/tool/home/health-status' \
-H "Authori-zation: YOUR_TOKEN"
```
---
## 十一、食谱管理
### 11.1 获取食谱列表
```bash
curl -X GET 'http://localhost:20822/api/front/tool/recipe/list?mealType=breakfast&page=1&limit=10' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 11.2 获取食谱详情
```bash
curl -X GET 'http://localhost:20822/api/front/tool/recipe/detail/50' \
-H "Authori-zation: YOUR_TOKEN"
```
---
### 11.3 收藏/取消收藏食谱
```bash
curl -X POST 'http://localhost:20822/api/front/tool/recipe/favorite' \
-H "Content-Type: application/json" \
-H "Authori-zation: YOUR_TOKEN" \
-d '{
"recipeId": 50,
"isFavorite": true
}'
```
---
## 十二、文件上传
### 12.1 上传图片
```bash
curl -X POST 'http://localhost:20822/api/front/tool/upload/image?type=checkin' \
-H "Authori-zation: YOUR_TOKEN" \
-F "file=@/path/to/image.jpg"
```
---
### 12.2 上传语音
```bash
curl -X POST 'http://localhost:20822/api/front/tool/upload/voice' \
-H "Authori-zation: YOUR_TOKEN" \
-F "file=@/path/to/voice.mp3"
```
---
## 十三、错误码说明
| code | message | 说明 |
|------|---------|------|
| 200 | success | 请求成功 |
| 400 | 参数校验失败 | 请求参数不符合校验规则 |
| 401 / 410000 | 未登录 | Token 缺失 |
| 410001 | Token 无效 | Token 格式错误 |
| 410002 | 登录过期 | Token 已过期 |
| 403 | 无权限 | 访问他人数据 |
| 404 | 资源不存在 | 数据不存在 |
| 500 | 系统异常 | 服务端内部错误 |
---
## 十四、变更记录
| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-02-08 | System | 初稿 |
---
*文档结束*

25
docs/db/db_design.md Normal file
View File

@@ -0,0 +1,25 @@
## 数据库字典
### tool模块相关表
- 用户表： eb_user
- 用户积分记录表：eb_user_integral_record
- 用户签到表：eb_user_sign
- 文章内容表：eb_article
- 用户积分表： v2_user_points
- 一键打卡记录表： v2_quick_checkin_records
- AI营养师对话表： v2_ai_conversations
- AI营养师消息表： v2_ai_messages
- 营养师咨询记录表： v2_nutritionist_consultations
- 食物百科表： v2_foods
- 营养知识表： v2_knowledge
- 食谱表： v2_recipes
- 打卡社区表： v2_community_posts
- 打卡社区互动表： v2_community_interactions
- 打卡社区评论表： v2_community_comments
- 打卡社区关注表： v2_community_follows
- 营养计划表： v2_nutrition_plans
- 食谱计算器结果表： v2_calculator_results

2594
docs/db/shop-msh.sql Normal file
View File

File diff suppressed because it is too large Load Diff

104
docs/sql/v2_calculator_results_alter.sql Normal file
View File

@@ -0,0 +1,104 @@
-- =========================================================
-- 食谱计算器表结构变更 SQL
-- 版本：v1.0
-- 日期：2026-02-01
-- 说明：根据开发文档优化后，需要新增以下字段
-- =========================================================
-- 检查并添加 bmi_status 字段
ALTER TABLE `v2_calculator_results`
ADD COLUMN IF NOT EXISTS `bmi_status` VARCHAR(20) DEFAULT NULL COMMENT 'BMI状态描述：体型过轻/正常/超重/肥胖'
AFTER `bmi`;
-- 检查并添加 food_list_json 字段
ALTER TABLE `v2_calculator_results`
ADD COLUMN IF NOT EXISTS `food_list_json` TEXT DEFAULT NULL COMMENT '食物份数建议 JSON'
AFTER `energy_intake`;
-- 检查并添加 tips_json 字段
ALTER TABLE `v2_calculator_results`
ADD COLUMN IF NOT EXISTS `tips_json` TEXT DEFAULT NULL COMMENT '重要提示 JSON'
AFTER `meal_plan_json`;
-- 如果表不存在，创建完整表结构
CREATE TABLE IF NOT EXISTS `v2_calculator_results` (
`result_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '计算结果ID',
`user_id` BIGINT NOT NULL COMMENT '用户ID',
-- 输入参数
`gender` VARCHAR(10) NOT NULL COMMENT '性别：male/female',
`age` INT NOT NULL COMMENT '年龄（岁）',
`height` INT NOT NULL COMMENT '身高（cm）',
`weight` DECIMAL(5,2) DEFAULT NULL COMMENT '体重（kg）',
`has_dialysis` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否透析：0-否 1-是',
`dialysis_type` VARCHAR(20) DEFAULT NULL COMMENT '透析类型：hemodialysis/peritoneal',
`dry_weight` DECIMAL(5,2) NOT NULL COMMENT '干体重（kg）',
`creatinine` DECIMAL(8,2) NOT NULL COMMENT '血肌酐（μmol/L）',
-- 计算结果
`egfr` DECIMAL(6,2) NOT NULL COMMENT 'eGFR（ml/min/1.73m²）',
`standard_weight` DECIMAL(5,2) NOT NULL COMMENT '标准体重（kg）',
`bmi` DECIMAL(4,1) NOT NULL COMMENT 'BMI',
`bmi_status` VARCHAR(20) DEFAULT NULL COMMENT 'BMI状态描述',
`ckd_stage` VARCHAR(50) NOT NULL COMMENT 'CKD分期',
`protein_intake` DECIMAL(5,1) NOT NULL COMMENT '每日蛋白质目标（g）',
`energy_intake` INT NOT NULL COMMENT '每日能量目标（kcal）',
-- JSON 数据
`food_list_json` TEXT DEFAULT NULL COMMENT '食物份数建议 JSON',
`meal_plan_json` TEXT DEFAULT NULL COMMENT '配餐方案 JSON',
`tips_json` TEXT DEFAULT NULL COMMENT '重要提示 JSON',
-- 状态字段
`is_adopted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否已采纳：0-未采纳 1-已采纳',
`adopted_at` DATETIME DEFAULT NULL COMMENT '采纳时间',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
PRIMARY KEY (`result_id`),
INDEX `idx_user_id` (`user_id`),
INDEX `idx_created_at` (`created_at`),
INDEX `idx_is_adopted` (`is_adopted`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='营养计算结果表';
-- 营养计划表（如果不存在则创建）
CREATE TABLE IF NOT EXISTS `v2_nutrition_plans` (
`plan_id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '营养计划ID',
`user_id` BIGINT NOT NULL COMMENT '用户ID',
`result_id` BIGINT DEFAULT NULL COMMENT '关联的计算结果ID',
-- 健康数据（冗余存储，便于查询）
`gender` VARCHAR(10) DEFAULT NULL COMMENT '性别',
`age` INT DEFAULT NULL COMMENT '年龄',
`height` INT DEFAULT NULL COMMENT '身高（cm）',
`weight` DECIMAL(5,2) DEFAULT NULL COMMENT '体重（kg）',
`has_dialysis` TINYINT(1) DEFAULT 0 COMMENT '是否透析',
`dialysis_type` VARCHAR(20) DEFAULT NULL COMMENT '透析类型',
`creatinine` DECIMAL(8,2) DEFAULT NULL COMMENT '血肌酐',
-- 计算结果
`egfr` DECIMAL(6,2) DEFAULT NULL COMMENT 'eGFR',
`standard_weight` DECIMAL(5,2) DEFAULT NULL COMMENT '标准体重',
`bmi` DECIMAL(4,1) DEFAULT NULL COMMENT 'BMI',
`ckd_stage` VARCHAR(50) DEFAULT NULL COMMENT 'CKD分期',
`protein_intake` DECIMAL(5,1) DEFAULT NULL COMMENT '蛋白质目标',
`energy_intake` INT DEFAULT NULL COMMENT '能量目标',
-- 配餐方案
`meal_plan_json` TEXT DEFAULT NULL COMMENT '配餐方案 JSON',
-- 计划状态
`status` VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '状态：active/completed/abandoned',
`start_date` DATE NOT NULL COMMENT '开始日期',
`end_date` DATE NOT NULL COMMENT '结束日期',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
PRIMARY KEY (`plan_id`),
INDEX `idx_user_id` (`user_id`),
INDEX `idx_result_id` (`result_id`),
INDEX `idx_status` (`status`),
INDEX `idx_start_date` (`start_date`),
UNIQUE INDEX `uk_user_result` (`user_id`, `result_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='营养计划表';

15
docs/sql/v2_recipes_add_source.sql Normal file
View File

@@ -0,0 +1,15 @@
-- =============================================
-- v2_recipes 表新增 source 相关字段
-- 用于追踪食谱来源（手动/计算器/AI生成等）
-- Author: ScottPan
-- Date: 2026-02-14
-- =============================================
ALTER TABLE v2_recipes
ADD COLUMN `source` VARCHAR(20) DEFAULT 'manual' COMMENT '来源：manual(手动)/calculator(计算器)/ai(AI生成)' AFTER `sort_order`,
ADD COLUMN `source_id` BIGINT DEFAULT NULL COMMENT '来源ID（如计算器结果ID）' AFTER `source`;
-- 新增索引，便于按来源查询
ALTER TABLE v2_recipes
ADD KEY `idx_source` (`source`),
ADD KEY `idx_source_id` (`source_id`);

BIN
docs/慢生活智能营养专家小程序用户界面交互设计文档.pdf Normal file
View File

Binary file not shown.

602
docs/打卡社区功能设计方案.md Normal file
View File

@@ -0,0 +1,602 @@
# 打卡社区功能设计方案
## 慢生活智能营养专家 - 类似小红书的UGC社区
---
## 📋 功能概述
**产品定位**：将个人打卡记录转化为可分享的UGC内容，打造肾病患者的饮食分享社区。
**对标产品**：小红书（内容社区）+ Keep运动社区（打卡分享）
**核心价值**：
1. 📸 **降低UGC门槛** - 打卡记录一键转分享，无需重新创作
2. 👥 **社交连接** - 患者之间互相学习、点赞、评论、关注
3. 🎯 **激励增强** - 社交认同感大幅增强打卡动力
4. 💰 **商业价值** - 优质内容吸引新用户，为KOL孵化和广告变现打基础
---
## 🎨 核心页面展示
### 1. 社区广场（瀑布流）
```
┌────────────────────────────────┐
│ 🏠 社区广场 [发布+] │
└────────────────────────────────┘
【筛选Tab】 [推荐] [最新] [关注] [热门]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【瀑布流布局】（左右2列）
┌──────────┐ ┌──────────┐
│ 图片 │ │ 图片 │
│ │ │ │
├──────────┤ ├──────────┤
│ 🥗 早餐打 │ │ 🍱 午餐低 │
│ 卡第7天│ │ 钾配餐 │
│ │ │ │
│ 👤 张小慢 │ │ 👤 李大康 │
│ ❤️ 128 │ │ ❤️ 256 │
└──────────┘ └──────────┘
```
**关键特性**：
- 瀑布流布局，视觉效果好
- 封面图自动取打卡照片第一张
- 显示点赞数，体现内容质量
- 4个Tab满足不同浏览需求
### 2. 内容详情页
```
┌────────────────────────────────┐
│ 【用户信息】 │
│ 👤 张小慢（透析3年） │
│ 📅 2025-11-20 12:30 │
│ [+ 关注] │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 【图片轮播】1/3 │
│ [滑动查看更多照片] │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 🥗 早餐打卡第7天！终于坚持下来了 │
│ #早餐 #低钾饮食 #透析期 │
│ │
│ 今天的早餐：牛奶+鸡蛋拌面+黄瓜 │
│ 照片不是很好看但营养达标啦~ │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 【营养数据】 │
│ 蛋白质：18.8g (达标94%) │
│ 能量：452kcal (达标90%) │
│ 🎯 整体营养达标率：92% │
└────────────────────────────────┘
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌────────────────────────────────┐
│ ❤️ 128 💬 23 ⭐ 45 ➤ 分享 │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 💬 评论区 │
│ 太棒了！我也要学习这样吃 │
│ 坚持得很好，营养搭配合理👍 │
└────────────────────────────────┘
```
**关键特性**：
- 完整的营养数据展示（来自打卡记录）
- 图片轮播支持1-3张
- 互动栏：点赞/评论/收藏/分享
- 评论区支持点赞和回复
### 3. 发布页面
```
┌────────────────────────────────┐
│ < 分享打卡记录 [发布] │
└────────────────────────────────┘
【选择封面图】从打卡照片中选择
【标题】
🥗 早餐打卡第7天！
[AI帮你写标题 ✨]
【正文】
分享一下你的打卡心得吧~
[AI帮你写描述 ✨]
【添加话题】
#早餐 #低钾饮食 #透析期
[+ 添加话题]
【营养数据】（自动带入）
蛋白质：18.8g 能量：452kcal
【隐私设置】
○ 公开 ○ 仅关注可见 ○ 私密
💡 提示：分享到社区可获得20积分
```
**关键特性**：
- 从打卡记录一键分享（降低门槛）
- AI辅助生成标题和描述（降低创作难度）
- 营养数据自动带入（突出专业性）
- 隐私设置（保护用户隐私）
- 积分激励（促进分享）
### 4. 用户主页
```
┌────────────────────────────────┐
│ 【用户资料卡】 │
│ 👤 张小慢 │
│ 透析3年 | CKD 5期 │
│ 简介：坚持健康饮食，享受慢生活 │
│ [+ 关注] │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 128 作品 | 256 获赞 | 89 粉丝 │
└────────────────────────────────┘
┌────────────────────────────────┐
│ 🏆 成就勋章 │
│ 连续打卡7天 获赞100+ 营养达标王 │
└────────────────────────────────┘
【作品网格】（3列）
┌────┐ ┌────┐ ┌────┐
│图片 │ │图片 │ │图片 │
└────┘ └────┘ └────┘
```
**关键特性**：
- 显示个人标签（疾病状态）
- 数据统计（作品/获赞/粉丝）
- 成就勋章系统
- 作品网格展示
---
## 🔄 用户使用流程
### 完整的内容生产和消费闭环
```
【内容生产】
打卡上传饮食记录
↓
打卡成功页点击"分享到社区"
↓
AI辅助编辑标题和描述
↓
添加话题标签
↓
发布成功 + 获得20积分
↓
内容进入推荐池
【内容消费】
访问社区广场
↓
浏览瀑布流内容（推荐算法）
↓
点击感兴趣的卡片
↓
查看详情（图片/文字/营养数据）
↓
互动（点赞/评论/收藏）
↓
关注优质创作者
↓
形成社交关系
【社交连接】
关注其他用户
↓
"关注"Tab看到关注用户的内容
↓
评论互动
↓
收到回复通知
↓
再次访问社区
【激励闭环】
看到他人优质打卡内容
↓
受到激励，自己也想分享
↓
更认真地打卡（拍照、摆盘）
↓
分享到社区
↓
获得点赞和评论
↓
社交认同感增强
↓
继续坚持打卡和分享
```
---
## 💡 核心功能设计
### 1. 推荐算法
**推荐分数计算**：
```javascript
推荐分数 = 内容质量分 × 0.4
+ 用户兴趣分 × 0.3
+ 时效性分 × 0.2
+ 多样性分 × 0.1
```
**内容质量分**：
- 有配图：+20分
- 3张图：+10分
- 有营养数据：+15分
- 字数>50字：+10分
- 点赞数×0.5分
- 评论数×2分
- 收藏数×3分
**用户兴趣分**：
- 同疾病状态（透析/非透析）：+30分
- 同CKD分期：+20分
- 同餐次（早中晚）：+15分
- 关注的用户：+50分
- 历史互动过的标签：+10分
### 2. 互动系统
**点赞**：
- 点击动画效果（心形放大+红色填充）
- 实时更新点赞数
- 发布者获得通知
**评论**：
- 支持二级评论（回复评论）
- 支持@用户
- 支持Emoji
- 评论可点赞
- 按点赞数排序
**收藏**：
- 一键收藏
- 个人中心查看收藏列表
- 取消收藏
**分享**：
- 微信好友/朋友圈
- 复制链接
- 生成海报（带小程序码）
### 3. 积分奖励
| 行为 | 积分 | 说明 |
|-----|------|------|
| 发布内容到社区 | +20分 | 鼓励分享 |
| 内容获得第1个赞 | +5分 | 正向反馈 |
| 内容获得第10个赞 | +10分 | 里程碑奖励 |
| 内容获得第100个赞 | +50分 | 优质内容奖励 |
| 发布评论 | +2分 | 每日上限10条 |
| 收到评论 | +3分 | 提升互动积极性 |
| 评论被点赞 | +1分 | - |
| 分享到朋友圈 | +5分 | 每日上限1次 |
### 4. 创作者等级
```
Lv1 新手：发布1-10篇
Lv2 达人：发布11-50篇
Lv3 专家：发布51-100篇
Lv4 大咖：发布100+篇 + 平均获赞50+
```
**等级权益**：
- Lv2：解锁话题创建权限
- Lv3：内容优先推荐
- Lv4：认证标识 + 优先审核 + 流量扶持
---
## 📊 数据库设计
### 社区内容表（community_posts）
```sql
CREATE TABLE community_posts (
post_id BIGINT PRIMARY KEY,
user_id BIGINT NOT NULL,
check_in_record_id BIGINT, -- 关联的打卡记录
title VARCHAR(100) NOT NULL,
content TEXT,
cover_image VARCHAR(255),
images_json TEXT,
nutrition_data_json TEXT,
tags_json TEXT,
like_count INT DEFAULT 0,
comment_count INT DEFAULT 0,
collect_count INT DEFAULT 0,
share_count INT DEFAULT 0,
view_count INT DEFAULT 0,
recommend_score DECIMAL(10,2),
hot_score DECIMAL(10,2),
status VARCHAR(20) DEFAULT 'published',
privacy VARCHAR(20) DEFAULT 'public',
created_at TIMESTAMP
);
```
### 互动记录表（community_interactions）
```sql
CREATE TABLE community_interactions (
interaction_id BIGINT PRIMARY KEY,
user_id BIGINT NOT NULL,
post_id BIGINT NOT NULL,
interaction_type VARCHAR(20), -- like, comment, collect, share, view
created_at TIMESTAMP,
UNIQUE KEY (user_id, post_id, interaction_type)
);
```
### 评论表（community_comments）
```sql
CREATE TABLE community_comments (
comment_id BIGINT PRIMARY KEY,
post_id BIGINT NOT NULL,
user_id BIGINT NOT NULL,
content TEXT NOT NULL,
parent_comment_id BIGINT, -- NULL为一级评论
reply_to_user_id BIGINT,
like_count INT DEFAULT 0,
status VARCHAR(20) DEFAULT 'published',
created_at TIMESTAMP
);
```
### 关注关系表（community_follows）
```sql
CREATE TABLE community_follows (
follow_id BIGINT PRIMARY KEY,
follower_id BIGINT NOT NULL, -- 关注者
followee_id BIGINT NOT NULL, -- 被关注者
created_at TIMESTAMP,
UNIQUE KEY (follower_id, followee_id)
);
```
---
## 🎯 核心KPI指标
### 内容生产指标
| 指标 | v2.0目标 | 说明 |
|-----|---------|------|
| 社区内容总量 | 500篇 | 3个月累计 |
| 日均发布量 | 10篇 | 每日新增内容 |
| 发布率 | 10% | 打卡用户中分享到社区的比例 |
### 内容消费指标
| 指标 | v2.0目标 | 说明 |
|-----|---------|------|
| 日均访问用户 | 200人 | 每日访问社区的用户数 |
| 人均浏览数 | 5篇 | 每个用户平均浏览的内容数 |
| 互动率 | 30% | 浏览用户中产生互动的比例 |
### 互动指标
| 指标 | v2.0目标 | 说明 |
|-----|---------|------|
| 日均点赞数 | 500 | 每日产生的点赞总数 |
| 日均评论数 | 100 | 每日产生的评论总数 |
| 日均收藏数 | 50 | 每日产生的收藏总数 |
### 社交指标
| 指标 | v2.0目标 | 说明 |
|-----|---------|------|
| 关注关系数 | 200对 | 用户之间的关注关系总数 |
| 创作者数量 | 50人 | 发布过至少3篇内容的用户 |
### 留存指标
| 指标 | v2.0目标 | 说明 |
|-----|---------|------|
| 社区用户7日留存率 | 60% | 比普通用户高30% |
**北极星指标**：
```
社区健康度 = (日均发布量 × 10)
+ (人均浏览数 × 5)
+ (互动率 × 100)
v2.0目标：≥500分
```
---
## 🚀 开发计划
### 阶段1：MVP版本（2周）
**核心功能**：
- [ ] 社区广场（瀑布流展示）
- [ ] 内容详情页（图片/文字/营养数据）
- [ ] 发布功能（从打卡记录分享）
- [ ] 基础互动（点赞/评论）
**目标**：验证用户是否愿意分享和浏览内容
### 阶段2：完善版本（2周）
**新增功能**：
- [ ] 推荐算法
- [ ] 关注/粉丝系统
- [ ] 用户主页
- [ ] 话题标签
- [ ] 收藏和分享
- [ ] 评论二级回复
**目标**：完善社交体验，提升用户粘性
### 阶段3：运营版本（1周）
**新增功能**：
- [ ] 内容审核机制
- [ ] 创作者等级
- [ ] 成就勋章
- [ ] 举报功能
- [ ] 运营后台
**目标**：确保内容质量，支持运营活动
---
## 💰 商业价值
### 短期价值（3-6个月）
1. **用户增长**
- 优质内容吸引新用户注册
- 预计带来20-30%的新用户增长
2. **用户留存**
- 社区用户7日留存率60%（比普通用户高30%）
- 社交连接增强用户粘性
3. **用户活跃**
- 社区用户DAU/MAU是普通用户的3-4倍
- 日均打开频次提升50%
### 中期价值（6-12个月）
4. **内容资产**
- 积累10000+篇优质UGC内容
- 降低运营成本（不需要大量PGC内容）
5. **KOL孵化**
- 培养100+活跃创作者
- 部分创作者成为KOL（认证营养师、资深患者）
6. **品牌影响力**
- 打造"肾病患者专属社区"品牌认知
- 建立行业壁垒
### 长期价值（12-24个月）
7. **商业变现**
- **广告变现**：信息流广告、品牌合作内容
- **电商导流**：低钾食品、营养补剂推荐
- **会员体系**：优质内容专属查看
- **KOL分成**：创作者激励计划
8. **数据价值**
- 真实饮食数据+用户偏好数据
- 优化AI推荐算法
- 为医疗研究提供数据支持
---
## ⚠️ 风险和应对
### 风险1：冷启动问题
**风险**：初期内容少，用户不愿意访问社区
**应对**：
- 官方账号提前准备100+优质内容
- 种子用户激励（前100名发布用户额外200积分）
- 首页推荐位展示优质社区内容
### 风险2：内容质量低
**风险**：用户分享的内容质量参差不齐
**应对**：
- AI辅助生成标题和描述，降低创作难度
- 推荐算法优先展示高质量内容
- 创作者等级制度，优质创作者流量扶持
### 风险3：违规内容
**风险**：医疗广告、政治敏感内容
**应对**：
- 敏感词过滤（实时拦截）
- 图片审核（腾讯云内容安全API）
- 人工审核（新用户首次发布、被举报内容）
- 处罚机制（警告、封禁）
### 风险4：用户隐私
**风险**：患者不愿意公开疾病信息
**应对**：
- 隐私设置（公开/仅关注可见/私密）
- 匿名发布选项
- 脱敏处理（可选择不显示个人标签）
---
## 📞 总结
### 为什么要做打卡社区？
1. **解决核心痛点**
- 患者孤独感强，需要同伴支持
- 打卡容易坚持不下来，需要社交激励
- 不知道怎么吃得好看，需要优质内容参考
2. **提升产品价值**
- 从工具型产品→社区型产品
- 从单向服务→双向互动
- 从个人使用→社交分享
3. **商业化基础**
- UGC内容吸引新用户，降低获客成本
- 社交连接增强用户粘性，提升LTV
- 为广告、电商、会员变现打基础
### 成功关键
✅ **降低分享门槛** - 打卡记录一键转分享，AI辅助创作
✅ **优质内容优先** - 推荐算法保证用户看到好内容
✅ **社交激励充分** - 点赞/评论/关注形成正向反馈
✅ **内容审核严格** - 确保社区氛围健康
---
**完整PRD章节**：第4.8章 - 打卡社区系统
**文档位置**：`/Users/a123/Documents/Works25/慢生活/爱肾/msh-tools/docs/PRD_慢生活智能营养专家_v2.0.md`
**开发排期**：3-4周（MVP→完善→运营，分三个阶段）
---
**下一步**：需要我生成小程序页面代码吗？ 📱✨

439
docs/打卡详情页_一键打卡入口设计.md Normal file
View File

@@ -0,0 +1,439 @@
# 打卡详情页 - 一键打卡入口设计
> **更新日期**：2025-11-20
> **版本**：v2.2.1
> **核心优化**：在打卡详情页增加"一键打卡"入口
---
## 🎯 优化目标
用户在查看打卡详情时，希望能快速复制该打卡内容，无需返回到列表页操作。
---
## 📱 三个主要入口
### 入口1：打卡历史页 → 直接复制 ⭐推荐快速打卡
```
我的饮食记录
┌──────────────────────────┐
│ 11月19日 早餐 │
│ ✅ 达标率92% ⭐高分 │
│ [📊 查看详情] │
│ [⚡一键复制打卡] ←入口1 │
└──────────────────────────┘
```
**特点**：
- ✅ 最快捷的方式
- ✅ 无需进入详情页
- ✅ 适合确定要复制的情况
- ✅ 30秒完成打卡
**流程**：
```
点击"⚡一键复制打卡"
↓
复制确认页（预览内容）
↓
打卡页（内容已填充）
↓
修改内容（可选）
↓
发布完成（+5积分）
```
---
### 入口2：打卡详情页 → 详细查看后复制 ⭐⭐⭐本次新增
```
我的饮食记录
[📊 查看详情] ←先点这里
↓
打卡详情页
┌──────────────────────────┐
│ 📸 完整照片查看 │
│ 📊 营养数据详情 │
│ 📋 菜品清单 │
│ ┌──────────────────────┐ │
│ │ ⚡一键复制打卡 ←入口2 │ │
│ └──────────────────────┘ │
└──────────────────────────┘
```
**特点**：
- ✅ 查看完整信息后决定
- ✅ 可以看到所有照片和数据
- ✅ 更了解打卡内容
- ✅ 适合需要详细查看的情况
**流程**：
```
点击"📊 查看详情"
↓
进入打卡详情页
↓
查看照片、营养数据、菜品清单
↓
点击"⚡一键复制打卡"
↓
复制确认页
↓
打卡页（内容已填充）
↓
发布完成（+5积分）
```
---
### 入口3：社区打卡详情页 → 借鉴他人 ⭐学习优质内容
```
社区广场 → 他人的打卡
[点击帖子查看详情]
↓
打卡详情页（他人的）
┌──────────────────────────┐
│ 查看他人饮食方案 │
│ 营养数据参考 │
│ ┌──────────────────────┐ │
│ │ 🎬一键借鉴打卡 ←入口3 │ │
│ └──────────────────────┘ │
└──────────────────────────┘
```
**特点**：
- ✅ 学习他人优质饮食方案
- ✅ AI自动调整用量（根据你的情况）
- ✅ 必须上传自己的照片
- ✅ 原作者也会获得积分
**流程**：
```
浏览社区打卡内容
↓
点击感兴趣的帖子
↓
进入打卡详情页（他人的）
↓
点击"🎬一键借鉴打卡"
↓
借鉴确认页（AI调整用量）
↓
打卡页（需上传自己的照片）
↓
发布完成
自己+5积分，原作者+2积分
```
---
## 🎨 UI设计对比
### 场景A：查看【自己的】打卡详情页
```
┌────────────────────────────────┐
│ 【快速操作】 │
│ ┌──────────────────────────┐ │
│ │ ⚡ 一键复制打卡 │ │
│ │ 快速复用这份饮食方案 │ │
│ └──────────────────────────┘ │
│ │
│ 点击后可以： │
│ ✅ 复制照片和备注到新打卡 │
│ ✅ 修改内容后重新发布 │
│ ✅ 可选生成AI视频 │
│ ✅ 获得5积分奖励 │
│ │
│ 💡 适用场景： │
│ • 今天吃的和之前某天一样 │
│ • 想复用高分打卡记录 │
│ • 快速打卡不想重新拍照 │
└────────────────────────────────┘
```
**按钮样式**：
- 颜色：绿色渐变（#4CAF50 → #45B649）
- 大小：宽度100%，高度56px
- 字体：18px，加粗
- 图标：⚡（闪电，表示快速）
- 圆角：12px
- 阴影：0 4px 12px rgba(76, 175, 80, 0.3)
---
### 场景B：查看【他人的】打卡详情页
```
┌────────────────────────────────┐
│ 【一键借鉴】 │
│ ┌──────────────────────────┐ │
│ │ 🎬 一键借鉴打卡 │ │
│ │ 学习这份营养方案 │ │
│ └──────────────────────────┘ │
│ │
│ 点击后可以： │
│ ✅ 复制菜品清单到我的打卡 │
│ ✅ 根据我的情况调整用量 │
│ ✅ AI生成适合我的食谱 │
│ ✅ 获得5积分奖励 │
│ │
│ 💡 适用场景： │
│ • 看到他人的优质打卡想学习 │
│ • 发现适合自己的饮食方案 │
│ • 需要新的饮食灵感 │
└────────────────────────────────┘
```
**按钮样式**：
- 颜色：蓝色渐变（#2196F3 → #1E88E5）
- 大小：宽度100%，高度56px
- 字体：18px，加粗
- 图标：🎬（摄像机，表示学习和记录）
- 圆角：12px
- 阴影：0 4px 12px rgba(33, 150, 243, 0.3)
---
## 💻 技术实现
### 1. 判断打卡详情页的场景
```javascript
/**
* 判断打卡详情页的场景
*/
function getCheckInDetailScene(recordId, currentUserId) {
const record = getCheckInRecordById(recordId);
if (record.user_id === currentUserId) {
// 场景A：查看自己的打卡
return {
scene: 'self',
buttonText: '⚡ 一键复制打卡',
buttonColor: 'green',
buttonClass: 'copy-btn-self',
action: 'copyOwnCheckIn'
};
} else {
// 场景B：查看他人的打卡
return {
scene: 'others',
buttonText: '🎬 一键借鉴打卡',
buttonColor: 'blue',
buttonClass: 'copy-btn-others',
action: 'learnFromOthers'
};
}
}
```
### 2. 一键复制自己的打卡
```javascript
/**
* 一键复制自己的打卡
*/
function copyOwnCheckIn(recordId) {
const record = getCheckInRecordById(recordId);
// 复制数据
const copiedData = {
photos_json: record.photos_json, // 照片URL数组
notes: record.notes, // 备注说明
voice_url: record.voice_url, // 语音备注（如果有）
copied_from_record_id: recordId, // 记录复制来源
is_copied: 1 // 标记为复制的打卡
};
// 保存到临时存储
wx.setStorageSync('tempCheckInData', copiedData);
// 跳转到打卡页
wx.navigateTo({
url: '/pages/check-in/check-in?from=copy&recordId=' + recordId
});
// 埋点统计
trackEvent('copy_own_check_in', {
record_id: recordId,
source: 'detail_page'
});
}
```
### 3. 一键借鉴他人的打卡
```javascript
/**
* 一键借鉴他人的打卡
*/
function learnFromOthers(recordId, currentUserId) {
const record = getCheckInRecordById(recordId);
// 获取用户自己的营养计划
const myPlan = getNutritionPlan(currentUserId);
// AI自动调整菜品用量
const adjustedDishes = adjustDishesForUser(
record.actual_dishes_json,
myPlan
);
// 准备借鉴数据
const learnedData = {
dishes_json: adjustedDishes, // AI调整后的菜品清单
reference_record_id: recordId, // 参考来源
reference_user_id: record.user_id, // 原作者ID
is_learned_from_others: 1 // 标记为借鉴的打卡
};
// 保存到临时存储
wx.setStorageSync('tempCheckInData', learnedData);
// 跳转到打卡页
wx.navigateTo({
url: '/pages/check-in/check-in?from=learn&recordId=' + recordId
});
// 给原作者增加积分（+2分）
addPointsToUser(record.user_id, 2, 'content_learned', recordId);
// 埋点统计
trackEvent('learn_from_others', {
record_id: recordId,
original_user_id: record.user_id,
source: 'detail_page'
});
}
```
### 4. AI调整菜品用量
```javascript
/**
* AI调整菜品用量（根据用户的营养计划）
*/
function adjustDishesForUser(originalDishes, userPlan) {
// 计算原始菜品的总营养
const originalNutrition = calculateTotalNutrition(originalDishes);
// 计算调整比例
const proteinRatio = userPlan.target_protein / originalNutrition.protein;
const energyRatio = userPlan.target_energy / originalNutrition.energy;
// 取平均比例
const avgRatio = (proteinRatio + energyRatio) / 2;
// 调整每个菜品的用量
return originalDishes.map(dish => {
const newAmount = Math.round(dish.amount * avgRatio);
return {
...dish,
amount: newAmount, // 调整后的用量
adjusted: true, // 标记为AI调整过的
original_amount: dish.amount, // 保留原始用量供参考
adjustment_ratio: avgRatio.toFixed(2) // 调整比例
};
});
}
```
---
## 📊 页面路径说明
| 页面 | 路径 | 参数 | 说明 |
|-----|------|------|------|
| 打卡历史页 | `/pages/check-in-history/history` | - | 显示用户的打卡记录列表 |
| 打卡详情页（自己的） | `/pages/check-in-detail/detail` | `?id={recordId}&type=self` | 查看自己的打卡详情 |
| 打卡详情页（他人的） | `/pages/check-in-detail/detail` | `?id={recordId}&type=others` | 查看他人的打卡详情 |
| 复制确认页 | `/pages/copy-confirm/confirm` | `?from={recordId}` | 复制自己的打卡确认页 |
| 借鉴确认页 | `/pages/learn-confirm/confirm` | `?from={recordId}` | 借鉴他人的打卡确认页 |
| 打卡页 | `/pages/check-in/check-in` | `?from=copy&recordId={id}` 或 `?from=learn&recordId={id}` | 填写打卡内容 |
---
## 🎁 积分规则
| 行为 | 积分 | 说明 |
|-----|------|------|
| 一键复制打卡（自己的） | +5分 | 从历史记录快速复制 |
| 一键借鉴打卡（他人的） | +5分 | 学习他人的饮食方案 |
| 内容被借鉴（原作者） | +2分 | 自己的打卡被他人借鉴 |
---
## 📈 预期效果
| 指标 | 优化前 | 优化后 | 提升 |
|-----|-------|-------|------|
| **详情页停留时长** | 15秒 | 30秒 | +100% |
| **从详情页发起的打卡** | 5% | 20% | +300% |
| **一键复制打卡使用率** | 25% | 40% | +60% |
| **打卡转化率** | 30% | 45% | +50% |
**数据支持**：
- 用户在详情页查看完整信息后，打卡意愿更强
- 详情页提供更多上下文，用户更愿意复制高质量打卡
- 减少操作步骤，提升转化率
---
## 💡 设计亮点
### 1. **场景区分** ⭐⭐⭐
- 智能判断是"自己的打卡"还是"他人的打卡"
- 不同场景显示不同的按钮文案和颜色
- 提供差异化的体验
### 2. **三重入口** ⭐⭐⭐
- 历史列表页：快速直接复制
- 详情页：查看后再复制
- 社区详情页：学习他人
### 3. **AI智能调整** ⭐⭐⭐
- 借鉴他人打卡时，AI自动调整菜品用量
- 根据用户的营养计划个性化调整
- 降低借鉴门槛，提升使用率
### 4. **积分激励** ⭐⭐⭐
- 借鉴者获得+5分
- 原作者获得+2分
- 形成"创作-分享-学习"的正向循环
---
## 🚀 下一步优化
1. **智能推荐复制**
- 在详情页根据历史数据推荐"您可能也想复制这几条"
- 提供相似打卡记录推荐
2. **批量复制**
- 支持一次性复制一天的三餐
- 生成"一日食谱计划"
3. **收藏夹功能**
- 收藏优质打卡记录
- 从收藏夹快速复制
4. **打卡模板**
- 将高分打卡保存为模板
- 模板库供用户选择
---
**文档版本**：v2.2.1
**更新日期**：2025-11-20
**产品名称**：慢生活智能营养专家小程序
---
**让每个打卡详情页都成为下一次打卡的起点！** ⚡🎬

1310
docs/用户界面交互设计.md Normal file
View File

File diff suppressed because it is too large Load Diff

197
docs/项目技术栈与架构分析.md Normal file
View File

@@ -0,0 +1,197 @@
# 慢生活（MSH）系统 — 项目技术栈与架构分析
## 一、项目概述
**慢生活**（MSH System）是一套面向 C 端的**商城 + 营养/工具**一体化系统，包含移动端多端应用（UniApp）与基于 CRMEB 的 Java 后端服务。项目在 CRMEB Java 版 v2.2 基础上做了业务定制，并接入了 AI（Coze、KieAI、腾讯云 ASR 等）与文章/工具类能力，形成「慢生活营养专家」产品形态。
---
## 二、整体架构
系统采用**前后端分离 + 多端一体**架构：
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 客户端（多端） │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 微信小程序 │ │ H5 商城 │ │ App(iOS/ │ │ 支付宝/ │ │
│ │ (mp-weixin) │ │ │ │ Android) │ │ 头条等小程序│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │ │
│ msh_single_uniapp (Vue 2 + UniApp) │
└────────────────────────────────────┬────────────────────────────────────┘
│ HTTPS / REST API
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 后端服务（Spring Boot） │
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
│ │ crmeb-front (C 端 API) │ │ crmeb-admin (管理端 API) │ │
│ │ 端口: 20822 (sophia) │ │ 后台管理、定时任务(Quartz) │ │
│ │ /api/front/*, /api/public/* │ │ │ │
│ └──────────────┬──────────────┘ └──────────────┬──────────────┘ │
│ │ │ │
│ └────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ crmeb-service (业务逻辑) │ crmeb-common (工具/实体/配置) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────┬────────────────────────────────────┘
│
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MySQL 8.x │ │ Redis │ │ 对象存储/ │
│ (Druid 连接池) │ │ (缓存/会话/ │ │ 支付/地图等 │
│ │ │ Token/验证码) │ │ OSS/COS/七牛 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
- **前端**：一套 UniApp 源码，通过条件编译发布到微信小程序、H5、App、支付宝/头条等小程序。
- **后端**：多模块 Maven 工程，C 端入口为 `crmeb-front`，管理端为 `crmeb-admin`，共用 `crmeb-service` 与 `crmeb-common`。
- **外部**：MySQL 主库、Redis、阿里云 OSS/腾讯云 COS/七牛、微信/支付宝支付、高德地图、Coze/KieAI 等。
---
## 三、前端技术栈（msh_single_uniapp）
### 3.1 核心框架与语言
| 类别 | 技术选型 | 说明 |
|------------|-----------------|------|
| 跨端框架 | **UniApp** | 基于 Vue 2，一套代码多端运行（微信/支付宝/头条小程序、H5、App） |
| 前端框架 | **Vue 2.x** | 选项式 API，`main.js` 中挂载全局工具与 Store |
| 状态管理 | **Vuex** | `store/index.js` + `store/modules`（如 `app.js`） |
| 构建/工程 | **Vue CLI** | `vue.config.js`：生产环境关闭 sourceMap、压缩时去掉 console |
| 富文本 | **mp-html** | 用于商品/文章等富文本展示（`package.json` 中声明） |
### 3.2 工程结构要点
- **入口与全局**：`main.js`、`App.vue`；全局通过 `Vue.prototype` 挂载 `$util`、`$config`、`$Cache`、`$eventHub`、`$Order`、`$LoginAuth` 等。
- **配置**：`config/app.js` 统一配置 `domain`（API 基地址）、`HTTP_REQUEST_URL`、`HEADER`、`TOKENNAME`（如 `Authori-zation`）等；H5 下可选 VConsole。
- **请求层**：
- 通用业务请求：`utils/request.js`，基于 `uni.request`，前缀 `/api/front/` 或 `/api/public/`，统一处理 401/403/410xxx 跳转登录。
- AI/文章等：`api/models-api.js` 使用同一 `domain`，封装 Coze、KieAI、腾讯 ASR、文章等接口。
- **API 模块化**：`api/api.js`、`api/user.js`、`api/order.js`、`api/store.js`、`api/tool.js`、`api/public.js`、`api/models-api.js` 等按业务拆分。
- **路由与页面**：`pages.json` 配置首页、分包（subPackages）、tabBar、导航栏样式等；首屏为 `pages/tool_main/index`（慢生活营养专家）。
### 3.3 多端与发布
- **manifest.json**：应用名「慢生活」、版本 2.2.1、App 模块（支付、分享、地图、定位、直播等）、微信/支付宝/头条小程序 appid、高德 key、支付与 OAuth 等。
- **发行**：H5 使用 history 路由；微信小程序开启 `lazyCodeLoading: requiredComponents` 控制包体；生产构建通过 `vue.config.js` 做压缩与去 console。
### 3.4 前端技术栈小结
- **语言**：JavaScript（ES6+）
- **UI**：UniApp 内置组件 + 自定义组件（如 `skeleton`、`homeIndex`、`payment`、`jyf-parser` 等）
- **特色**：多端统一、Token 鉴权、登录态校验、分包与懒加载、与 CRMEB 后端约定 `/api/front/`、`/api/public/` 前缀
---
## 四、后端技术栈（msh_crmeb_22）
### 4.1 核心框架与运行时
| 类别 | 技术选型 | 版本/说明 |
|--------------|-----------------------------|-----------|
| 基础框架 | **Spring Boot** | 2.2.6.RELEASE |
| Java | **JDK 1.8** | 编译与运行 |
| 构建 | **Maven** | 多模块 parent POM 管理依赖 |
### 4.2 模块划分
| 模块 | 职责 |
|----------------|------|
| **crmeb-common** | 公共实体、工具类、配置（如 CozeConfig）、通用组件（Druid、MyBatis-Plus、Redis、JWT、验证码等） |
| **crmeb-service** | 业务逻辑层：商城、用户、订单、营销、工具、AI 对接（Coze、KieAI、腾讯 ASR）等 |
| **crmeb-admin** | 管理端 Web API、Quartz 定时任务，打包为 `jxz-admin-2.2.jar` |
| **crmeb-front** | C 端 Web API，打包为 `sophia-front-2.2.jar`，当前 sophia 配置端口 20822 |
### 4.3 数据访问与存储
| 类别 | 技术选型 | 说明 |
|----------|-------------------------|------|
| 关系库 | **MySQL 8.x** | 驱动 `mysql-connector-java` 8.0.33，Druid 连接池 |
| ORM | **MyBatis-Plus** | 3.3.1，含 generator；mapper 扫描 `com.zbkj.**.dao` |
| 分页 | **PageHelper** | 1.2.5，与 MyBatis-Plus 共存时排除 mybatis 避免冲突 |
| 缓存 | **Redis + Jedis** | Spring Boot 2.2 Data Redis，独立 DB 存 accessToken 等 |
| 文档 | **MongoDB** | 仅 driver-core 依赖，用于部分扩展能力 |
### 4.4 安全与认证
- **JWT**：`jjwt-api/impl/jackson` 0.11.5，Token 名称与前端约定（如 `Authori-zation`）。
- **行为验证码**：`spring-boot-starter-captcha`（AJ），支持滑动/点选，缓存可走 Redis。
- **白名单**：`application.yml` 中 `crmeb.ignored` 配置 Swagger、上传、Coze、KieAI 等路径免鉴权。
### 4.5 接口与文档
- **REST**：Spring MVC，C 端前缀 `/api/front/`、`/api/public/`。
- **文档**：Springfox Swagger 2.9.2 + swagger-bootstrap-ui 1.9.3，配置在 `application*.yml` 的 `swagger.basic`。
### 4.6 第三方与中间件（根 POM 管理）
- **工具**：Hutool、Commons Lang3、Fastjson、HttpClient、Dom4j、XStream、Pinyin4j、ZXing（二维码）等。
- **文件与图片**：Commons FileUpload/IO、Thumbnailator、阿里云 OSS、腾讯云 COS、七牛 SDK。
- **支付**：支付宝 SDK、微信（通过 common 或 service 内封装）。
- **AI/开放接口**：Coze API（coze-api 0.2.3）、OkHttp、RxJava（流式）；KieAI、腾讯云 ASR 等通过 HTTP 在 service 层封装。
### 4.7 配置与运行
- **配置**：`application.yml` + `application-{profile}.yml`（如 `sophia`、`dev`、`prod`、`beta`）。
- **数据源/Redis**：在 profile 中覆盖 URL、库名、端口、密码等。
- **日志**：Logback（`logback-spring.xml`），按环境输出到 `./crmeb_log` 或 `./logs`。
---
## 五、models-integration 子项目
- **定位**：独立 Maven 工程（`com.integration:models-integration`），Java 8，Spring Boot 2.7.5。
- **用途**：与「模型/AI」集成相关的独立服务或能力（如统一网关、模型路由等），通过 SpringDoc OpenAPI、Redis、MySQL、AOP 等搭建。
- **与主系统关系**：与 msh_crmeb_22 无直接模块依赖，可单独部署，通过 HTTP 或消息与 front 协作。
---
## 六、部署与运行约定
### 6.1 前端
- **开发**：使用 HBuilderX 或 Vue CLI 运行/发行到各端；API 基地址在 `config/app.js` 的 `domain` 修改（如 `https://sophia-shop.uj345.cc`）。
- **生产**：H5 可部署到任意静态服务器；小程序/App 需在对应平台上传与配置域名白名单。
### 6.2 后端
- **C 端**：以 `sophia` profile 启动 `CrmebFrontApplication`，默认端口 20822，需可访问的 MySQL、Redis。
- **管理端**：启动 `CrmebAdminApplication`，按需配置端口与数据源。
- **包名**：`com.zbkj`，front 的 `@ComponentScan` 包含 `com.zbkj` 与 `com.zbkj.front`，Mapper 扫描 `com.zbkj.**.dao`。
---
## 七、技术栈汇总表
| 层次 | 技术项 | 选型说明 |
|----------|------------------|----------|
| 前端框架 | Vue 2 + UniApp | 多端统一（小程序/H5/App） |
| 状态管理 | Vuex | 登录态、购物车、全局配置等 |
| 请求 | uni.request 封装 | 统一 domain、Token、错误与登录跳转 |
| 后端框架 | Spring Boot 2.2 | 多模块（common/service/admin/front） |
| 数据访问 | MyBatis-Plus + MySQL | Druid 连接池、PageHelper 分页 |
| 缓存 | Redis (Jedis) | 会话、Token、验证码、配置缓存 |
| 认证 | JWT + 行为验证码 | 前端 Header 传 Token |
| 文档 | Swagger 2 + Bootstrap UI | 后端 API 文档 |
| 构建 | Maven / npm | 后端 Maven；前端 Vue CLI / HBuilderX |
| 对象存储 | 阿里云 OSS / 腾讯云 COS / 七牛 | 图片与文件 |
| 支付 | 微信支付、支付宝 | 通过后端封装 |
| AI/能力 | Coze、KieAI、腾讯云 ASR 等 | 在 crmeb-service 中封装，front 暴露 REST |
---
## 八、文档与资源
- **产品与设计**：`docs/` 下 PRD、打卡社区设计、食谱计算器接口文档、用户界面交互设计等。
- **数据库**：`docs/sql`、`msh_crmeb_22/sql` 等目录可存放建表/迁移脚本。
- **接口**：`documents/api` 可补充 C 端/管理端接口说明，与 Swagger 互补。
---
*文档基于当前仓库目录与配置文件整理，用于技术评审、新人上手与架构演进参考。具体版本号以各模块 `pom.xml`、`package.json` 及运行环境为准。*

569
docs/食谱计算器后端接口开发文档.md Normal file
View File

@@ -0,0 +1,569 @@
# 食谱计算器后端接口开发文档
> **版本**：v1.0
> **创建日期**：2026-02-01
> **所属模块**：Tool（工具模块）
> **配套前端**：`msh_single_uniapp/pages/tool/calculator.vue` / `calculator-result.vue`
---
## 一、功能概述
食谱计算器是**慢生活智能营养专家**的核心功能之一，面向肾病（CKD）及透析患者，根据用户输入的健康数据，自动计算：
1. **健康指标**：eGFR、标准体重、BMI、CKD分期
2. **每日营养目标**：蛋白质摄入量（g/d）、能量摄入量（kcal/d）
3. **食物份数建议**：7 类食物的每日推荐份数
4. **一日三餐配餐方案**：早餐、午餐、晚餐的菜品清单（含图片、食材用量）
5. **重要提示**：根据患者情况给出饮食注意事项
用户可进一步**采纳营养计划**，进入打卡流程（另单独接口）。
---
## 二、接口清单
| 序号 | 接口名称 | HTTP方法 | 路径 | 说明 |
|------|----------|----------|------|------|
| 1 | 计算营养方案 | `POST` | `/api/front/tool/calculator/calculate` | 核心接口，输入健康数据，返回计算结果 |
| 2 | 获取计算结果详情 | `GET` | `/api/front/tool/calculator/result/{id}` | 通过结果ID获取完整结果（含配餐） |
| 3 | 采纳营养计划 | `POST` | `/api/front/tool/calculator/adopt` | 用户采纳后创建营养计划，进入打卡流程 |
---
## 三、接口详细设计
### 3.1 计算营养方案
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/calculator/calculate` |
| 是否鉴权 | **是**（需登录） |
| Content-Type | `application/json` |
#### 请求参数（Request Body）
| 参数名 | 类型 | 必填 | 说明 | 校验规则 |
|--------|------|------|------|----------|
| `gender` | String | 是 | 性别 | 可选值：`male` / `female` |
| `age` | Integer | 是 | 年龄（岁） | 1 ≤ age ≤ 150 |
| `height` | Integer | 是 | 身高（cm） | 50 ≤ height ≤ 250 |
| `dialysis` | Boolean | 是 | 是否透析 | `true` / `false` |
| `dialysisType` | String | 否 | 透析类型 | 当 `dialysis=true` 时有效；可选值：`hemodialysis`（血透）/ `peritoneal`（腹透） |
| `dryWeight` | Number | 是 | 干体重（kg） | 20 ≤ dryWeight ≤ 300，支持1位小数 |
| `creatinine` | Number | 是 | 血肌酐（μmol/L） | 0 < creatinine ≤ 2000，支持2位小数 |
**请求示例**
```json
{
"gender": "male",
"age": 55,
"height": 170,
"dialysis": true,
"dialysisType": "hemodialysis",
"dryWeight": 65.5,
"creatinine": 850
}
```
#### 响应参数（Response Body）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| `code` | Integer | 状态码，`200` 表示成功 |
| `message` | String | 提示信息 |
| `data` | Object | 计算结果对象 |
**`data` 结构**
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `id` / `resultId` | Long | 计算结果唯一ID，用于后续查询/采纳 |
| `healthData` | Object | 健康数据计算结果 |
| `nutritionGoals` | Object | 每日营养目标 |
| `foodList` | Array | 食物份数建议列表 |
| `mealPlan` | Object | 一日三餐配餐方案 |
| `importantTips` | Array\<String\> | 重要提示文案列表 |
| `createdAt` | String | 创建时间 ISO8601 |
**`healthData` 结构**
| 字段名 | 类型 | 说明 | 计算公式 |
|--------|------|------|----------|
| `eGFR` | String | 肾小球滤过率（ml/min/1.73m²） | CKD-EPI 公式（见附录 A） |
| `standardWeight` | String | 标准体重（kg） | 男：`(height - 80) × 0.7`；女：`(height - 70) × 0.6` |
| `bmi` | String | 体重指数 | `dryWeight / (height/100)²` |
| `bmiStatus` | String | BMI 状态描述 | 见附录 B |
| `ckdStage` | String | CKD 分期 | 见附录 C |
**`nutritionGoals` 结构**
| 字段名 | 类型 | 说明 | 计算公式 |
|--------|------|------|----------|
| `protein` | String | 每日蛋白质目标（克） | 透析期：`standardWeight × 1.2`；非透析期：`standardWeight × 0.8` |
| `energy` | String | 每日能量目标（千卡） | `standardWeight × 35` |
**`foodList` 结构**（数组，7 项）
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `number` | Integer | 序号 1-7 |
| `name` | String | 食物类别名称（如"谷薯50g"） |
| `portion` | String | 推荐份数 |
**`mealPlan` 结构**
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `breakfast` | Array | 早餐菜品列表 |
| `lunch` | Array | 午餐菜品列表 |
| `dinner` | Array | 晚餐菜品列表 |
**菜品对象结构**
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `name` | String | 菜品名称 |
| `image` | String | 菜品图片 URL |
| `ingredients` | Array\<String\> | 食材列表（如 `["牛奶 120g", "面条 90g"]`） |
**响应示例**
```json
{
"code": 200,
"message": "success",
"data": {
"id": 100234,
"healthData": {
"eGFR": "7.9",
"standardWeight": "63.0",
"bmi": "22.7",
"bmiStatus": "正常",
"ckdStage": "CKD 5期"
},
"nutritionGoals": {
"protein": "75.6",
"energy": "2205"
},
"foodList": [
{ "number": 1, "name": "谷薯50g", "portion": "5.7" },
{ "number": 2, "name": "淀粉100g", "portion": "0.77" },
{ "number": 3, "name": "绿叶蔬菜200g", "portion": "1" },
{ "number": 4, "name": "瓜果蔬菜200g", "portion": "2" },
{ "number": 5, "name": "奶类230g", "portion": "1" },
{ "number": 6, "name": "肉蛋类50/60g", "portion": "7" },
{ "number": 7, "name": "油脂类10g", "portion": "5.7" }
],
"mealPlan": {
"breakfast": [
{
"name": "牛奶",
"image": "https://cdn.xxx.com/images/milk.jpg",
"ingredients": ["牛奶 120g"]
},
{
"name": "鸡蛋拌面",
"image": "https://cdn.xxx.com/images/egg-noodle.jpg",
"ingredients": ["面条 90g", "鸡蛋 120g", "葱花 5g"]
},
{
"name": "凉拌黄瓜",
"image": "https://cdn.xxx.com/images/cucumber.jpg",
"ingredients": ["黄瓜 100g"]
}
],
"lunch": [
{
"name": "米饭",
"image": "https://cdn.xxx.com/images/rice.jpg",
"ingredients": ["大米 100g"]
},
{
"name": "清蒸鲈鱼",
"image": "https://cdn.xxx.com/images/bass.jpg",
"ingredients": ["鲈鱼 120g", "生姜 5g", "葱 5g"]
},
{
"name": "蒜蓉西兰花",
"image": "https://cdn.xxx.com/images/broccoli.jpg",
"ingredients": ["西兰花 150g", "大蒜 5g", "植物油 8g"]
},
{
"name": "冬瓜汤",
"image": "https://cdn.xxx.com/images/wax-gourd-soup.jpg",
"ingredients": ["冬瓜 150g"]
}
],
"dinner": [
{
"name": "杂粮饭",
"image": "https://cdn.xxx.com/images/mixed-rice.jpg",
"ingredients": ["大米 70g", "小米 30g"]
},
{
"name": "香菇炒鸡丁",
"image": "https://cdn.xxx.com/images/chicken-mushroom.jpg",
"ingredients": ["鸡胸肉 100g", "香菇 50g", "植物油 8g"]
},
{
"name": "清炒油菜",
"image": "https://cdn.xxx.com/images/bok-choy.jpg",
"ingredients": ["油菜 150g", "植物油 5g"]
},
{
"name": "番茄蛋花汤",
"image": "https://cdn.xxx.com/images/tomato-egg-soup.jpg",
"ingredients": ["番茄 100g", "鸡蛋 60g"]
}
]
},
"importantTips": [
"以上配餐由 AI 生成，仅适用于无其他并发症的单纯尿毒症人群",
"透析患者需严格控制水分摄入",
"建议低盐饮食（每日少于 5g）",
"注意限制高钾食物（香蕉、橙子、土豆等）",
"限制高磷食物（坚果、动物内脏等）",
"特别提醒：尿毒症合并其他并发症人群不适用此配餐，请务必咨询专业营养师调整方案"
],
"createdAt": "2026-02-01T10:30:00+08:00"
}
}
```
#### 错误码
| code | message | 说明 |
|------|---------|------|
| 400 | 参数校验失败 | 请求参数不符合校验规则 |
| 401 / 410000-410002 | 未登录/登录过期 | 需重新登录 |
| 500 | 系统异常 | 服务端内部错误 |
---
### 3.2 获取计算结果详情
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `GET /api/front/tool/calculator/result/{id}` |
| 是否鉴权 | **是** |
| 路径参数 | `id`：计算结果ID（Long） |
#### 响应
与 3.1 的 `data` 结构相同，用于结果页刷新或分享后重新加载。
---
### 3.3 采纳营养计划
#### 基础信息
| 项目 | 值 |
|------|------|
| 请求路径 | `POST /api/front/tool/calculator/adopt` |
| 是否鉴权 | **是** |
| Content-Type | `application/json` |
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `resultId` | Long | 是 | 计算结果ID |
**请求示例**
```json
{
"resultId": 100234
}
```
#### 响应
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `code` | Integer | 200 成功 |
| `message` | String | 提示信息 |
| `data.planId` | Long | 新创建的营养计划ID |
| `data.startDate` | String | 计划开始日期 |
| `data.endDate` | String | 计划结束日期（默认 +7 天） |
**响应示例**
```json
{
"code": 200,
"message": "采纳成功",
"data": {
"planId": 56789,
"startDate": "2026-02-01",
"endDate": "2026-02-07"
}
}
```
#### 业务规则
1. 同一用户同一时间只能有 **1 个激活状态（`status=active`）** 的营养计划；若已存在则自动将旧计划标记为 `abandoned`。
2. 采纳成功后赠送 **+20 积分**（积分任务：采纳营养方案）。
---
## 四、数据库表设计
### 4.1 计算结果表（calculator_results）
> 存储每次计算的输入与输出，方便查询历史、分析
```sql
CREATE TABLE calculator_results (
result_id BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '主键',
user_id BIGINT NOT NULL COMMENT '用户ID',
-- 输入参数
gender VARCHAR(10) NOT NULL COMMENT '性别：male/female',
age INT NOT NULL COMMENT '年龄（岁）',
height INT NOT NULL COMMENT '身高（cm）',
has_dialysis TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否透析：0-否 1-是',
dialysis_type VARCHAR(20) COMMENT '透析类型：hemodialysis/peritoneal',
dry_weight DECIMAL(5,2) NOT NULL COMMENT '干体重（kg）',
creatinine DECIMAL(8,2) NOT NULL COMMENT '血肌酐（μmol/L）',
-- 计算结果
egfr DECIMAL(6,2) NOT NULL COMMENT 'eGFR（ml/min/1.73m²）',
standard_weight DECIMAL(5,2) NOT NULL COMMENT '标准体重（kg）',
bmi DECIMAL(4,1) NOT NULL COMMENT 'BMI',
bmi_status VARCHAR(20) NOT NULL COMMENT 'BMI状态描述',
ckd_stage VARCHAR(50) NOT NULL COMMENT 'CKD分期',
protein_intake DECIMAL(5,1) NOT NULL COMMENT '每日蛋白质目标（g）',
energy_intake INT NOT NULL COMMENT '每日能量目标（kcal）',
-- 配餐方案（JSON）
food_list_json TEXT COMMENT '食物份数建议 JSON',
meal_plan_json TEXT COMMENT '配餐方案 JSON',
tips_json TEXT COMMENT '重要提示 JSON',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_user_id (user_id),
INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='营养计算结果表';
```
### 4.2 营养计划表（nutrition_plans）
> PRD 中已定义，补充关联
```sql
-- 见 PRD 4.6.5 节
-- 关键字段：
-- plan_id, user_id, gender, age, height, weight, has_dialysis, dialysis_type, creatinine,
-- egfr, standard_weight, bmi, ckd_stage, protein_intake, energy_intake,
-- meal_plan_json, status, start_date, end_date, created_at, updated_at
```
关联关系：`nutrition_plans.source_result_id → calculator_results.id`（可选字段，用于溯源）
---
## 五、核心算法
### 5.1 eGFR 计算（CKD-EPI 2021 公式）
```java
/**
* CKD-EPI 2021 公式（无种族系数）
* @param creatinine 血肌酐 (μmol/L)
* @param age 年龄 (岁)
* @param isFemale 是否女性
* @return eGFR (ml/min/1.73m²)
*/
public static double calculateEGFR(double creatinine, int age, boolean isFemale) {
// 将 μmol/L 转换为 mg/dL
double scr = creatinine / 88.4;
double kappa = isFemale ? 0.7 : 0.9;
double alpha = isFemale ? -0.241 : -0.302;
double multi = isFemale ? 1.012 : 1.0;
double minRatio = Math.min(scr / kappa, 1.0);
double maxRatio = Math.max(scr / kappa, 1.0);
double eGFR = 142 * Math.pow(minRatio, alpha) * Math.pow(maxRatio, -1.200)
* Math.pow(0.9938, age) * multi;
return Math.round(eGFR * 100.0) / 100.0; // 保留2位小数
}
```
### 5.2 标准体重
```java
public static double calculateStandardWeight(int height, boolean isFemale) {
return isFemale
? (height - 70) * 0.6
: (height - 80) * 0.7;
}
```
### 5.3 BMI
```java
public static double calculateBMI(double weight, int height) {
double heightM = height / 100.0;
return Math.round(weight / (heightM * heightM) * 10.0) / 10.0;
}
```
### 5.4 BMI 状态
| BMI 范围 | 状态描述 |
|----------|----------|
| < 18.5 | 体型过轻 |
| 18.5 - 23.9 | 正常 |
| 24.0 - 27.9 | 超重 |
| ≥ 28.0 | 肥胖 |
### 5.5 CKD 分期
| eGFR 范围 | 分期 |
|-----------|------|
| ≥ 90 | CKD 1期 |
| 60 - 89 | CKD 2期 |
| 45 - 59 | CKD 3a期 |
| 30 - 44 | CKD 3b期 |
| 15 - 29 | CKD 4期 |
| < 15（非透析） | CKD 5期 |
| 透析患者 | 透析期 |
### 5.6 营养目标
```java
public static double calculateProtein(double standardWeight, boolean hasDialysis) {
return hasDialysis
? standardWeight * 1.2 // 透析期
: standardWeight * 0.8; // 非透析期
}
public static int calculateEnergy(double standardWeight) {
return (int) Math.round(standardWeight * 35);
}
```
### 5.7 食物份数
基于能量和蛋白质目标，按照《慢性肾脏病患者膳食指导（2017）》推荐比例分配，具体算法可参考专业营养软件或配置表。
### 5.8 配餐方案生成
1. **规则匹配**：基于 CKD 分期、透析类型、营养目标，从预置的 **配餐模板库（recipes）** 中匹配合适方案。
2. **AI 生成（可选）**：调用 AI 模型根据营养目标动态生成菜品及食材用量。
3. **输出**：早/午/晚三餐各 2-4 道菜，包含图片 URL 和食材列表。
---
## 六、性能与安全
### 6.1 缓存策略
| 数据 | 缓存方式 | 过期时间 | 说明 |
|------|----------|----------|------|
| 计算结果 | Redis Hash | 24 小时 | key = `calc_result:{id}` |
| 配餐模板库 | 本地缓存 / Redis | 1 小时 | 减少 DB 查询 |
### 6.2 限流
| 接口 | QPS 限制 | 说明 |
|------|----------|------|
| calculate | 10/用户/分钟 | 防止恶意刷算 |
| result/{id} | 60/用户/分钟 | 允许刷新 |
| adopt | 5/用户/分钟 | 防重复提交 |
### 6.3 幂等性
- **calculate**：每次计算生成新记录，允许重复调用。
- **adopt**：采纳接口需幂等设计，同一 `resultId` 多次调用只创建一个计划；可用 `user_id + result_id` 唯一索引或分布式锁。
### 6.4 数据安全
- 所有接口均需登录鉴权（Header: `Authori-zation`）。
- 用户只能查询/采纳自己的计算结果（`user_id` 校验）。
- 敏感健康数据传输全程 HTTPS。
---
## 七、测试用例
### 7.1 正常场景
| 用例编号 | 描述 | 输入 | 预期输出 |
|----------|------|------|----------|
| TC01 | 男性透析患者计算 | gender=male, age=55, height=170, dialysis=true, dryWeight=65.5, creatinine=850 | 返回 code=200，healthData/nutritionGoals/mealPlan 完整 |
| TC02 | 女性非透析患者 | gender=female, age=48, height=160, dialysis=false, dryWeight=52, creatinine=180 | 返回 code=200，ckdStage 按 eGFR 判断 |
| TC03 | 查询结果详情 | GET /result/100234 | 返回与 calculate 相同结构 |
| TC04 | 采纳营养计划 | resultId=100234 | 返回 planId，计划 status=active |
### 7.2 异常场景
| 用例编号 | 描述 | 输入 | 预期输出 |
|----------|------|------|----------|
| TC11 | 年龄超出范围 | age=200 | code=400, message 包含"年龄" |
| TC12 | 未登录调用 | 无 Token | code=401/410000 |
| TC13 | 查询他人结果 | id 属于其他用户 | code=403 |
| TC14 | 重复采纳 | 同一 resultId 调用两次 | 第二次返回已存在的 planId（幂等） |
---
## 八、附录
### 附录 A：CKD-EPI 2021 公式
> 无种族系数版本，适用于中国人群
```
eGFR = 142 × min(Scr/κ, 1)^α × max(Scr/κ, 1)^(-1.200) × 0.9938^Age × (1.012 if female)
其中：
- Scr = 血肌酐 (mg/dL) = μmol/L ÷ 88.4
- κ = 0.7 (女) / 0.9 (男)
- α = -0.241 (女) / -0.302 (男)
```
### 附录 B：BMI 分类标准（中国）
| BMI | 分类 |
|-----|------|
| < 18.5 | 体型过轻 |
| 18.5 - 23.9 | 正常 |
| 24.0 - 27.9 | 超重 |
| ≥ 28.0 | 肥胖 |
### 附录 C：CKD 分期标准
| 分期 | eGFR (ml/min/1.73m²) | 描述 |
|------|----------------------|------|
| 1期 | ≥ 90 | 肾功能正常或升高 |
| 2期 | 60-89 | 轻度下降 |
| 3a期 | 45-59 | 轻-中度下降 |
| 3b期 | 30-44 | 中-重度下降 |
| 4期 | 15-29 | 重度下降 |
| 5期 | < 15 | 肾衰竭 |
| 透析期 | — | 已接受透析治疗 |
---
## 九、变更记录
| 版本 | 日期 | 作者 | 变更内容 |
|------|------|------|----------|
| v1.0 | 2026-02-01 | — | 初稿 |
---
*文档结束*