# 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 |