Blizzard
403 lines
11 KiB
Markdown
403 lines
11 KiB
Markdown
# Sundynix 微服务 API 文档
|
||
|
||
> Base URL 约定: 各服务独立部署，通过 Nginx 统一代理
|
||
|
||
---
|
||
|
||
## 一、用户服务 (user-api) — 端口 9001
|
||
|
||
### 1.1 公开接口（无需鉴权）
|
||
|
||
#### POST /api/user/miniLogin — 微信小程序登录
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"code": "微信wx.login获取的code",
|
||
"clientId": "客户端标识（plant/radio）"
|
||
}
|
||
```
|
||
**响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||
"userInfo": {
|
||
"id": "uuid",
|
||
"name": "用户u278bb",
|
||
"nickName": "",
|
||
"phone": "",
|
||
"openId": "oXxx...",
|
||
"avatarId": "",
|
||
"gender": 0,
|
||
"isVip": 0
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /api/user/loginByPhone — 手机号登录
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"code": "微信getPhoneNumber获取的code",
|
||
"openId": "用户openId",
|
||
"clientId": "客户端标识"
|
||
}
|
||
```
|
||
**响应：** 同 miniLogin
|
||
|
||
---
|
||
|
||
#### POST /api/user/login — 账号密码登录
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"account": "账号",
|
||
"password": "密码"
|
||
}
|
||
```
|
||
**响应：** 同 miniLogin
|
||
|
||
---
|
||
|
||
### 1.2 鉴权接口（Header: Authorization: Bearer {token}）
|
||
|
||
#### GET /api/user/info — 获取当前用户信息
|
||
**响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"userInfo": { /* 用户完整信息 */ }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### PUT /api/user/update — 更新用户信息
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"name": "新名字",
|
||
"account": "新账号",
|
||
"phone": "13800138000",
|
||
"avatarId": "文件ID",
|
||
"nickName": "昵称"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### PUT /api/user/changePassword — 修改密码
|
||
```json
|
||
{ "oldPassword": "旧密码", "newPassword": "新密码" }
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /api/user/list — 用户列表（管理后台）
|
||
```json
|
||
{ "current": 1, "pageSize": 10, "account": "", "phone": "" }
|
||
```
|
||
**响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": { "list": [], "total": 0, "current": 1, "size": 10 }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### DELETE /api/user/delete — 删除用户
|
||
```json
|
||
{ "ids": ["id1", "id2"] }
|
||
```
|
||
|
||
---
|
||
|
||
#### GET /api/user/location?longitude=116.40&latitude=39.90 — 获取位置
|
||
|
||
#### GET /api/user/weather?adcode=110000 — 获取天气
|
||
|
||
---
|
||
|
||
## 二、文件服务 (file-api) — 端口 9002
|
||
|
||
> 所有接口需要鉴权
|
||
|
||
#### POST /api/file/upload — 上传文件
|
||
**请求：** `multipart/form-data`，字段名 `file`
|
||
**响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"id": "文件ID",
|
||
"name": "filename.jpg",
|
||
"url": "https://res.sundynix.cn/...",
|
||
"suffix": "jpg",
|
||
"md5": "abc123..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### DELETE /api/file/delete — 删除文件
|
||
```json
|
||
{ "ids": ["fileId1", "fileId2"] }
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /api/file/list — 文件列表
|
||
```json
|
||
{ "current": 1, "pageSize": 10, "name": "" }
|
||
```
|
||
|
||
---
|
||
|
||
#### GET /api/file/:id — 获取文件详情
|
||
|
||
---
|
||
|
||
## 三、系统服务 (system-api) — 端口 9003
|
||
|
||
> 所有接口需要鉴权
|
||
|
||
### 3.1 客户端管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/sys/client/create | 创建客户端 |
|
||
| PUT | /api/sys/client/update | 更新客户端 |
|
||
| DELETE | /api/sys/client/delete | 删除客户端 |
|
||
| POST | /api/sys/client/list | 客户端列表 |
|
||
|
||
### 3.2 角色管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/sys/role/create | 创建角色 |
|
||
| PUT | /api/sys/role/update | 更新角色 |
|
||
| DELETE | /api/sys/role/delete | 删除角色 |
|
||
| POST | /api/sys/role/list | 角色列表 |
|
||
|
||
### 3.3 菜单管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/sys/menu/create | 创建菜单 |
|
||
| PUT | /api/sys/menu/update | 更新菜单 |
|
||
| DELETE | /api/sys/menu/delete | 删除菜单 |
|
||
| GET | /api/sys/menu/list | 菜单树形列表 |
|
||
| POST | /api/sys/menu/byRole | 根据角色获取菜单 |
|
||
|
||
### 3.4 操作日志
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/sys/log/list | 操作日志列表 |
|
||
| DELETE | /api/sys/log/delete | 删除日志 |
|
||
|
||
### 3.5 字典管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/sys/dict/create | 创建字典 |
|
||
| PUT | /api/sys/dict/update | 更新字典 |
|
||
| DELETE | /api/sys/dict/delete | 删除字典 |
|
||
| POST | /api/sys/dict/list | 字典列表 |
|
||
|
||
---
|
||
|
||
## 四、植物服务 (plant-api) — 端口 9004
|
||
|
||
### 4.1 公开接口
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/plant/callback/wechatpay | 微信支付回调 |
|
||
|
||
### 4.2 我的植物（需鉴权）
|
||
| 方法 | 路径 | 说明 | 请求体示例 |
|
||
|------|------|------|-----------|
|
||
| POST | /api/plant/my/create | 创建植物 | `{name, plantTime, placement, imgIds[]}` |
|
||
| PUT | /api/plant/my/update | 更新植物 | `{id, name, status, ...}` |
|
||
| DELETE | /api/plant/my/delete | 删除植物 | `{ids[]}` |
|
||
| POST | /api/plant/my/list | 植物列表 | `{current, pageSize, name}` |
|
||
| GET | /api/plant/my/:id | 植物详情 | — |
|
||
| POST | /api/plant/my/carePlan | 添加养护计划 | `{plantId, name, targetAction, period}` |
|
||
| POST | /api/plant/my/careRecord | 添加养护记录 | `{plantId, planId, action}` |
|
||
| POST | /api/plant/my/growthRecord | 添加成长记录 | `{plantId, content, imgIds[]}` |
|
||
|
||
### 4.3 百科
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/plant/wiki/list | 百科列表 |
|
||
| GET | /api/plant/wiki/:id | 百科详情 |
|
||
| GET | /api/plant/wiki/class/list | 分类列表 |
|
||
| POST | /api/plant/wiki/class/create | 创建分类 |
|
||
| POST | /api/plant/wiki/star | 收藏/取消百科 |
|
||
|
||
### 4.4 社区帖子
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/plant/post/create | 发布帖子 |
|
||
| POST | /api/plant/post/list | 帖子列表 |
|
||
| GET | /api/plant/post/:id | 帖子详情 |
|
||
| DELETE | /api/plant/post/delete | 删除帖子 |
|
||
| POST | /api/plant/post/comment | 评论帖子 |
|
||
| POST | /api/plant/post/like | 点赞帖子 |
|
||
|
||
### 4.5 其他
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/plant/topic/list | 话题列表 |
|
||
| POST | /api/plant/topic/create | 创建话题 |
|
||
| POST | /api/plant/ocr/classify | OCR植物识别 |
|
||
| POST | /api/plant/exchange/list | 兑换商品列表 |
|
||
| POST | /api/plant/exchange/order | 兑换商品 |
|
||
| POST | /api/plant/ai/chat | AI问答 |
|
||
| GET | /api/plant/ai/history | 聊天历史 |
|
||
| GET | /api/plant/profile/info | 获取用户资料 |
|
||
| PUT | /api/plant/profile/update | 更新用户资料 |
|
||
| POST | /api/plant/config/level/list | 等级配置列表 |
|
||
| POST | /api/plant/config/badge/list | 徽章配置列表 |
|
||
|
||
---
|
||
|
||
## 五、电台服务 (radio-api) — 端口 9005
|
||
|
||
### 5.1 公开接口
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/callback/wechatpay | 微信支付回调 |
|
||
|
||
### 5.2 分类管理（需鉴权）
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/category/create | 创建分类 |
|
||
| PUT | /api/radio/category/update | 更新分类 |
|
||
| DELETE | /api/radio/category/delete | 删除分类 |
|
||
| POST | /api/radio/category/list | 分类列表 |
|
||
|
||
### 5.3 频道管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/channel/create | 创建频道 |
|
||
| PUT | /api/radio/channel/update | 更新频道 |
|
||
| DELETE | /api/radio/channel/delete | 删除频道 |
|
||
| POST | /api/radio/channel/list | 频道列表 |
|
||
| GET | /api/radio/channel/:id | 频道详情 |
|
||
|
||
### 5.4 节目管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/program/create | 创建节目 |
|
||
| PUT | /api/radio/program/update | 更新节目 |
|
||
| DELETE | /api/radio/program/delete | 删除节目 |
|
||
| POST | /api/radio/program/list | 节目列表 |
|
||
| GET | /api/radio/program/:id | 节目详情 |
|
||
| POST | /api/radio/program/tts | TTS生成音频 |
|
||
|
||
### 5.5 音色管理
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/voice/create | 创建音色 |
|
||
| PUT | /api/radio/voice/update | 更新音色 |
|
||
| DELETE | /api/radio/voice/delete | 删除音色 |
|
||
| POST | /api/radio/voice/list | 音色列表 |
|
||
|
||
### 5.6 用户互动
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/interaction/like | 点赞/取消 |
|
||
| POST | /api/radio/interaction/favorite | 收藏/取消 |
|
||
| POST | /api/radio/interaction/comment | 评论节目 |
|
||
| POST | /api/radio/interaction/history | 记录播放历史 |
|
||
| POST | /api/radio/interaction/history/list | 播放历史 |
|
||
| POST | /api/radio/interaction/favorite/list | 收藏列表 |
|
||
|
||
### 5.7 订阅/支付/VIP
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | /api/radio/subscription/list | 我的订阅 |
|
||
| POST | /api/radio/pay/create | 创建支付订单 |
|
||
| POST | /api/radio/vip/list | VIP配置列表 |
|
||
| GET | /api/radio/vip/info | 我的VIP信息 |
|
||
|
||
### 5.8 数据分析
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | /api/radio/analytics/overview | 数据概览 |
|
||
| POST | /api/radio/analytics/channel | 频道数据 |
|
||
| POST | /api/radio/analytics/user | 用户数据 |
|
||
|
||
---
|
||
|
||
## 六、统一规约
|
||
|
||
### 6.1 鉴权方式
|
||
所有需要鉴权的接口，请在请求头中携带：
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
### 6.2 统一响应格式
|
||
```json
|
||
{
|
||
"code": 200, // 200成功，400失败，401未授权
|
||
"msg": "success",
|
||
"data": {} // 具体数据
|
||
}
|
||
```
|
||
|
||
### 6.3 分页请求格式
|
||
```json
|
||
{ "current": 1, "pageSize": 10 }
|
||
```
|
||
|
||
### 6.4 分页响应格式
|
||
```json
|
||
{
|
||
"list": [],
|
||
"total": 100,
|
||
"current": 1,
|
||
"size": 10
|
||
}
|
||
```
|
||
|
||
### 6.5 删除请求格式
|
||
```json
|
||
{ "ids": ["id1", "id2"] }
|
||
```
|
||
|
||
---
|
||
|
||
## 七、数据库设计说明
|
||
|
||
### 7.1 用户扩展表设计
|
||
|
||
基础用户表 `sundynix_user` 只存储**认证和通用信息**（账号、密码、OpenID、手机号等），各业务服务通过扩展表存储业务特有的用户数据：
|
||
|
||
```
|
||
sundynix_user (基础)
|
||
├── sundynix_plant_user_profile (植物服务扩展：等级、阳光值、养护统计)
|
||
└── sundynix_radio_user_profile (电台服务扩展：VIP状态、VIP到期时间)
|
||
```
|
||
|
||
**设计原则：** 新增业务产品时，只需创建新的扩展表，无需修改基础用户表。
|
||
|
||
### 7.2 数据库拆分
|
||
|
||
| 数据库 | 包含的表 |
|
||
|--------|---------|
|
||
| sundynix_user | sundynix_user, sundynix_user_role |
|
||
| sundynix_file | sundynix_oss |
|
||
| sundynix_system | sundynix_client, sundynix_role, sundynix_menu, sundynix_role_menu, sundynix_user_role, sundynix_dict, sundynix_operation_record |
|
||
| sundynix_plant | sundynix_plant_user_profile, sundynix_my_plant, sundynix_care_plan, sundynix_care_record, sundynix_care_task, sundynix_growth_record, sundynix_wiki, sundynix_wiki_class, sundynix_post, sundynix_post_comment, sundynix_post_like, sundynix_post_topic, sundynix_user_star, sundynix_exchange_item, sundynix_exchange_order, sundynix_level_config, sundynix_badge_config, sundynix_user_badge, sundynix_ai_chat_history |
|
||
| sundynix_radio | sundynix_radio_user_profile, sundynix_radio_category, sundynix_radio_channel, sundynix_radio_program, sundynix_radio_voice, sundynix_radio_like, sundynix_radio_favorite, sundynix_radio_comment, sundynix_radio_history, sundynix_radio_subscription, sundynix_radio_subscription_order, sundynix_radio_pay_notify, sundynix_radio_vip_config, sundynix_radio_listen_log |
|
||
|