基准 URL:
https://<host>/api/v1
| 模块 | 目录 | 说明 |
|---|---|---|
| 认证 | auth/ | 注册、登录、令牌刷新、个人资料、密码、注销 |
| 区域 | regions/ | 区域的 CRUD |
| 位置 | locations/ | 位置的 CRUD（从属于区域） |
| 植物种类 | plant-species/ | 植物种类的 CRUD（查询公开，管理需 ADMIN） |
| 植物 | plants/ | 植物的 CRUD |
| 植物标签 | plant-tags/ | 植物标签的 CRUD |
| 养护记录 | plant-journals/ | 养护记录的 CRUD（支持批量关联植物） |
| 媒体文件 | media/ | 文件上传 |
| 用户反馈 | feedbacks/ | 提交建议，支持附带图片 |
| 管理 | admin/ | JWT 密钥轮换（需 ADMIN） |
| 附录 | appendices/ | 通用数据结构、枚举速查表、端点速查 |
除公开端点外，所有接口需在请求头携带 JWT Access Token：
Authorization: Bearer <access_token>
Access Token 过期后使用刷新令牌获取新令牌。
Instant 类型（timestamp、createdAt、updatedAt、eventTime）序列化为 13 位毫秒级 Unix 时间戳（number）。non_null，值为 null 的字段不会出现在 JSON 中。所有接口统一返回到 ApiResponse<T> 结构：
{
"code": 200,
"message": "success",
"data": { ... },
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"timestamp": 1747123456789
}
| 字段 | 类型 | 说明 |
|---|---|---|
code |
number |
状态码，200 表示成功 |
message |
string |
状态描述，成功时为 "success" |
data |
object |
业务数据，由各接口定义。无数据时不出现此字段 |
requestId |
string |
请求追踪 ID（UUID） |
timestamp |
number |
响应时间（13 位毫秒级 Unix 时间戳） |
分页接口 data 部分统一使用 PageResult<T> 结构：
{
"code": 200,
"message": "success",
"data": {
"items": [ ... ],
"page": 0,
"size": 20,
"total": 150
},
"requestId": "...",
"timestamp": 1747123456789
}
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array |
当前页数据列表 |
page |
number |
当前页码（从 0 开始） |
size |
number |
每页记录数 |
total |
number |
总记录数 |
分页查询参数：?page=0&size=20（page 默认 0，size 默认 20）。