870 lines
24 KiB
Markdown
870 lines
24 KiB
Markdown
# API Contracts — Hyperf RESTful API 契约
|
||
|
||
> 定义 API 设计规范和端点文档。AI Agent 在生成 Controller 和前端 API 调用时参考本文档。
|
||
>
|
||
> **服务对象标注说明**：
|
||
> - 🟦 `[user]` — 仅用户端（`Case-Database-Frontend-user/`）调用
|
||
> - 🟧 `[admin]` — 仅管理端（`Case-Database-Frontend-admin/`）调用
|
||
> - 🟩 `[both]` — 两个前端均可调用
|
||
|
||
---
|
||
|
||
## 1. 通用规范
|
||
|
||
### Base URL
|
||
```
|
||
# 管理端 API
|
||
开发: http://localhost:9501/admin
|
||
生产: https://api.example.com/admin
|
||
|
||
# 用户端 API
|
||
开发: http://localhost:9501/api
|
||
生产: https://api.example.com/api
|
||
```
|
||
|
||
### 统一响应格式
|
||
|
||
**成功**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**列表（带分页）**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"items": [],
|
||
"total": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误**
|
||
```json
|
||
{
|
||
"code": 422,
|
||
"message": "Validation failed",
|
||
"data": {
|
||
"errors": {
|
||
"email": ["The email field is required."]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### HTTP 状态码
|
||
|
||
| 状态码 | 含义 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 201 | 创建成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 (Token 无效/过期) |
|
||
| 403 | 无权限 |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 资源冲突 (锁定) |
|
||
| 422 | 验证失败 |
|
||
| 429 | 请求频率过高 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
### 认证
|
||
|
||
所有需要认证的接口在 Header 中携带：
|
||
```
|
||
Authorization: Bearer <access_token>
|
||
```
|
||
|
||
Token 过期返回 `401`，客户端用 Refresh Token 刷新。
|
||
|
||
### 分页参数
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `page` | int | 1 | 页码 |
|
||
| `page_size` | int | 10 | 每页数量 (max: 100) |
|
||
|
||
### 排序参数
|
||
|
||
```
|
||
?sort=created_at&order=desc
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 核心 API 端点
|
||
|
||
### 2.1 🟦 用户端认证 `[user]` — 16 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| POST | `/api/auth/captcha/challenge` | 获取图形验证码挑战（返回 `captcha_token`, `width`, `target_x`） | 否 |
|
||
| POST | `/api/auth/captcha/verify` | 校验滑块位置（`captcha_token` + `answer_x`，tolerance=10px） | 否 |
|
||
| POST | `/api/auth/register` | 用户注册 | 否 |
|
||
| POST | `/api/auth/login` | 账号密码登录 | 否 |
|
||
| POST | `/api/auth/sms/send` | 发送短信验证码 | 否 |
|
||
| POST | `/api/auth/sms/login` | 短信验证码登录 | 否 |
|
||
| POST | `/api/auth/forgot-password` | 忘记密码（账号/手机号校验后重置） | 否 |
|
||
| POST | `/api/auth/logout` | 登出 | 是 |
|
||
| POST | `/api/auth/refresh` | 刷新 Token | 否（需 Refresh Token） |
|
||
| GET | `/api/auth/profile` | 当前用户信息 | 是 |
|
||
| PUT | `/api/auth/profile` | 更新个人信息 | 是 |
|
||
| GET | `/api/auth/sessions` | 获取当前账号会话列表 | 是 |
|
||
| POST | `/api/auth/sessions/:sessionId/revoke` | 踢出指定会话 | 是 |
|
||
| GET | `/api/auth/enterprise-sso/redirect` | 企业 SSO 跳转入口 | 否 |
|
||
| POST | `/api/auth/enterprise-sso/callback` | 企业 SSO 回调登录 | 否 |
|
||
| POST | `/api/auth/enterprise-sso/direct-login` | 企业平台直达登录（签名票据） | 否 |
|
||
|
||
#### 认证请求字段约定
|
||
|
||
- `/api/auth/register` 必填字段：`username`, `phone`, `sms_code`, `password`, `password_confirm`, `captcha_token`, `agree`。
|
||
- `/api/auth/login` 必填字段：`username_or_phone`, `password`, `captcha_token`。
|
||
- `/api/auth/sms/send` 必填字段：`phone`, `captcha_token`。
|
||
- `/api/auth/sms/login` 必填字段：`phone`, `code`, `captcha_token`。
|
||
- `/api/auth/forgot-password` 必填字段：`username_or_phone`, `phone`, `sms_code`, `new_password`, `new_password_confirm`, `captcha_token`。
|
||
- 协议同意字段：`agree=true`，并由后端记录 `agree_at` 与 `agreement_version`。
|
||
|
||
#### 认证限流策略
|
||
|
||
| 接口 | 限流规则 |
|
||
|------|----------|
|
||
| 登录 `/api/auth/login` | 同 IP 5 次/分钟；同账号 10 次/小时 |
|
||
| 短信发送 `/api/auth/sms/send` | 同手机号 1 次/分钟，5 次/天 |
|
||
| 注册 `/api/auth/register` | 同 IP 3 次/小时 |
|
||
| 找回密码 `/api/auth/forgot-password` | 同账号 3 次/天 |
|
||
|
||
#### 第三方登录
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/auth/oauth/:provider` | OAuth 跳转（provider: wechat / qq） | 否 |
|
||
| GET | `/api/auth/oauth/:provider/callback` | OAuth 回调 | 否 |
|
||
|
||
---
|
||
|
||
### 2.2 🟦 用户端案例 `[user]` — 8 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/cases` | 案例列表（支持多维筛选） | 否 |
|
||
| GET | `/api/cases/:id` | 案例详情 | 否 |
|
||
| GET | `/api/cases/:id/comments` | 案例评论列表 | 否 |
|
||
| POST | `/api/cases/:id/comments` | 发表评论 | 是 |
|
||
| POST | `/api/cases/:id/favorite` | 收藏 / 取消收藏 (toggle) | 是 |
|
||
| POST | `/api/cases/:id/like` | 点赞 / 取消点赞 (toggle) | 是 |
|
||
| GET | `/api/cases/:id/related` | 相关推荐案例 | 否 |
|
||
| GET | `/api/cases/:id/files` | 案例文件列表（按阶段分组） | 否 |
|
||
|
||
#### 案例列表筛选参数
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `category_id` | int | 建筑类型分类 |
|
||
| `style` | string | 风格标签 slug |
|
||
| `keyword` | string | 搜索关键词（标题 / 编号） |
|
||
| `area_min` | number | 最小占地面积 |
|
||
| `area_max` | number | 最大占地面积 |
|
||
| `cost_min` | number | 最低造价 |
|
||
| `cost_max` | number | 最高造价 |
|
||
| `floors` | int | 层数 |
|
||
| `bedroom_count` | int | 卧室数量 |
|
||
| `site_width_min` | number | 最小面宽 |
|
||
| `site_depth_min` | number | 最小进深 |
|
||
| `tag_ids` | string | 标签 ID（逗号分隔） |
|
||
| `is_featured` | boolean | 仅看精选 |
|
||
| `sort` | string | 排序字段：`created_at` / `view_count` / `like_count` |
|
||
| `order` | string | `asc` / `desc` |
|
||
|
||
---
|
||
|
||
### 2.3 🟦 用户端设计师 `[user]` — 4 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/designers/:id` | 设计师详情 | 否 |
|
||
| GET | `/api/designers/:id/cases` | 设计师作品集 | 否 |
|
||
| POST | `/api/designers/:id/follow` | 关注 / 取消关注 (toggle) | 是 |
|
||
| GET | `/api/designers/:id/awards` | 设计师荣誉奖项 | 否 |
|
||
|
||
---
|
||
|
||
### 2.4 🟦 用户端内容 `[user]` — 8 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| GET | `/api/banners` | 首页轮播列表 | 否 |
|
||
| GET | `/api/categories` | 分类列表 | 否 |
|
||
| GET | `/api/tags` | 标签列表（支持 `?type=style` 筛选） | 否 |
|
||
| GET | `/api/tags/hot` | 热门标签 | 否 |
|
||
| GET | `/api/topics` | 专题列表 | 否 |
|
||
| GET | `/api/topics/:id` | 专题详情（含关联案例列表） | 否 |
|
||
| POST | `/api/newsletter/subscribe` | 邮箱订阅 | 否 |
|
||
| GET | `/api/my/favorites` | 我的收藏列表 | 是 |
|
||
|
||
---
|
||
|
||
### 2.5 🟧 管理端认证 `[admin]` — 4 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| POST | `/admin/auth/login` | 管理员登录 | 否 |
|
||
| POST | `/admin/auth/logout` | 登出 | 是 |
|
||
| POST | `/admin/auth/refresh` | 刷新 Token | 否（需 Refresh Token） |
|
||
| GET | `/admin/auth/info` | 当前管理员信息（含角色权限） | 是 |
|
||
|
||
---
|
||
|
||
### 2.6 🟧 管理端案例管理 `[admin]` — 9 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/cases` | 案例列表（含草稿 / 待审 / 已发布 / 已归档筛选） | `case:list` |
|
||
| GET | `/admin/cases/:id` | 案例详情 | `case:detail` |
|
||
| POST | `/admin/cases` | 创建案例 | `case:create` |
|
||
| PUT | `/admin/cases/:id` | 更新案例 | `case:update` |
|
||
| DELETE | `/admin/cases/:id` | 删除案例（软删除） | `case:delete` |
|
||
| PUT | `/admin/cases/:id/status` | 变更案例状态 | `case:status` |
|
||
| PUT | `/admin/cases/:id/featured` | 精选标记 toggle | `case:feature` |
|
||
| POST | `/admin/cases/:id/files` | 上传案例文件（分阶段） | `case:upload` |
|
||
| DELETE | `/admin/cases/:id/files/:fileId` | 删除案例文件 | `case:upload` |
|
||
|
||
---
|
||
|
||
### 2.7 🟧 管理端轮播管理 `[admin]` — 5 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/banners` | 轮播列表 | `banner:list` |
|
||
| POST | `/admin/banners` | 创建轮播 | `banner:create` |
|
||
| PUT | `/admin/banners/:id` | 更新轮播 | `banner:update` |
|
||
| DELETE | `/admin/banners/:id` | 删除轮播 | `banner:delete` |
|
||
| PUT | `/admin/banners/sort` | 批量排序 | `banner:update` |
|
||
|
||
---
|
||
|
||
### 2.8 🟧 管理端专题管理 `[admin]` — 6 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/topics` | 专题列表 | `topic:list` |
|
||
| POST | `/admin/topics` | 创建专题 | `topic:create` |
|
||
| PUT | `/admin/topics/:id` | 更新专题 | `topic:update` |
|
||
| DELETE | `/admin/topics/:id` | 删除专题 | `topic:delete` |
|
||
| POST | `/admin/topics/:id/cases` | 关联案例到专题 | `topic:update` |
|
||
| DELETE | `/admin/topics/:id/cases/:caseId` | 取消关联案例 | `topic:update` |
|
||
|
||
---
|
||
|
||
### 2.9 🟧 管理端分类标签 `[admin]` — 7 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/categories` | 分类列表 | `category:list` |
|
||
| POST | `/admin/categories` | 创建分类 | `category:create` |
|
||
| PUT | `/admin/categories/:id` | 更新分类 | `category:update` |
|
||
| DELETE | `/admin/categories/:id` | 删除分类（需判断无关联案例） | `category:delete` |
|
||
| GET | `/admin/tags` | 标签列表（支持 `?type=` 筛选） | `tag:list` |
|
||
| POST | `/admin/tags` | 创建标签 | `tag:create` |
|
||
| PUT | `/admin/tags/:id` | 更新标签 | `tag:update` |
|
||
| DELETE | `/admin/tags/:id` | 删除标签 | `tag:delete` |
|
||
|
||
---
|
||
|
||
### 2.10 🟧 管理端设计师管理 `[admin]` — 5 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/designers` | 设计师列表 | `designer:list` |
|
||
| POST | `/admin/designers` | 创建设计师 | `designer:create` |
|
||
| PUT | `/admin/designers/:id` | 更新设计师 | `designer:update` |
|
||
| DELETE | `/admin/designers/:id` | 删除设计师 | `designer:delete` |
|
||
| PUT | `/admin/designers/:id/active` | 启用/停用设计师 | `designer:update` |
|
||
|
||
---
|
||
|
||
### 2.11 🟧 管理端评论管理 `[admin]` — 4 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/comments` | 评论列表（支持 `?status=pending` 筛选） | `comment:list` |
|
||
| PUT | `/admin/comments/:id/approve` | 审核通过 | `comment:audit` |
|
||
| PUT | `/admin/comments/:id/reject` | 审核拒绝 | `comment:audit` |
|
||
| DELETE | `/admin/comments/:id` | 删除评论 | `comment:delete` |
|
||
|
||
---
|
||
|
||
### 2.12 🟧 管理端用户与权限 `[admin]` — 8 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/users` | 用户列表 | `user:list` |
|
||
| POST | `/admin/users` | 创建管理员 | `user:create` |
|
||
| PUT | `/admin/users/:id` | 更新用户 | `user:update` |
|
||
| PUT | `/admin/users/:id/status` | 启用/禁用用户 | `user:update` |
|
||
| GET | `/admin/roles` | 角色列表 | `role:list` |
|
||
| POST | `/admin/roles` | 创建角色（含菜单权限分配） | `role:create` |
|
||
| PUT | `/admin/roles/:id` | 更新角色 | `role:update` |
|
||
| GET | `/admin/menus` | 菜单权限树 | `menu:list` |
|
||
|
||
---
|
||
|
||
### 2.13 🟧 管理端系统配置 `[admin]` — 2 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/configs` | 获取系统配置（支持 `?group=site` 筛选） | `config:list` |
|
||
| PUT | `/admin/configs` | 批量更新系统配置 | `config:update` |
|
||
|
||
---
|
||
|
||
### 2.14 🟧 管理端数据仪表盘 `[admin]` — 3 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/dashboard/overview` | 概览统计（总案例数 / 总用户数 / 今日浏览量等） | `dashboard:view` |
|
||
| GET | `/admin/dashboard/trends` | 趋势数据（按日/周/月的浏览 / 注册曲线） | `dashboard:view` |
|
||
| GET | `/admin/dashboard/rankings` | 热门排行（案例浏览 TOP / 下载 TOP / 活跃设计师） | `dashboard:view` |
|
||
|
||
---
|
||
|
||
### 2.15 🟧 管理端日志 `[admin]` — 2 端点
|
||
|
||
| 方法 | 路径 | 说明 | 权限 |
|
||
|------|------|------|------|
|
||
| GET | `/admin/logs/operations` | 操作日志列表 | `log:list` |
|
||
| GET | `/admin/logs/downloads` | 下载日志列表 | `log:list` |
|
||
|
||
---
|
||
|
||
### 2.16 🟩 通用上传 `[both]` — 1 端点
|
||
|
||
| 方法 | 路径 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| POST | `/api/upload/image` | 上传图片（头像/封面/banner） | 是 |
|
||
|
||
---
|
||
|
||
## 3. 请求/响应示例
|
||
|
||
### 3.1 管理端登录
|
||
|
||
```bash
|
||
POST /admin/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"username": "admin",
|
||
"password": "password123"
|
||
}
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"access_token": "eyJhbGci...",
|
||
"refresh_token": "eyJhbGci...",
|
||
"expires_in": 7200,
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"nickname": "超级管理员",
|
||
"avatar": "https://cdn.example.com/avatars/admin.jpg",
|
||
"roles": ["super_admin"],
|
||
"permissions": ["case:*", "banner:*", "topic:*"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 用户端登录（账号密码）
|
||
|
||
```bash
|
||
POST /api/auth/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "13800138000",
|
||
"password": "password123"
|
||
}
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"access_token": "eyJhbGci...",
|
||
"refresh_token": "eyJhbGci...",
|
||
"expires_in": 7200,
|
||
"user": {
|
||
"id": 42,
|
||
"nickname": "建筑师小李",
|
||
"avatar": "https://cdn.example.com/avatars/42.jpg",
|
||
"phone": "138****8000",
|
||
"role_label": "Architect"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 用户端短信登录
|
||
|
||
```bash
|
||
# Step 1: 发送验证码
|
||
POST /api/auth/sms/send
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "13800138000"
|
||
}
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "验证码已发送",
|
||
"data": {
|
||
"expires_in": 300
|
||
}
|
||
}
|
||
|
||
# Step 2: 验证码登录
|
||
POST /api/auth/sms/login
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"phone": "13800138000",
|
||
"code": "123456"
|
||
}
|
||
|
||
# Response 200 (同 3.2 登录响应)
|
||
```
|
||
|
||
### 3.4 案例列表（多维筛选）
|
||
|
||
```bash
|
||
GET /api/cases?category_id=1&style=modern&area_min=100&area_max=300&cost_max=60&floors=3&sort=created_at&order=desc&page=1&page_size=12
|
||
Authorization: Bearer eyJhbGci... (可选)
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 88,
|
||
"title": "云端墅 The Cloud Villa",
|
||
"code": "P-2024-8839",
|
||
"cover_image": "https://cdn.example.com/cases/88/cover.jpg",
|
||
"category": {
|
||
"id": 1,
|
||
"name": "别墅",
|
||
"slug": "villa"
|
||
},
|
||
"layout": "3室2厅3卫",
|
||
"floors_above": 3,
|
||
"site_area": 128.50,
|
||
"total_building_area": 340.00,
|
||
"cost_min": 45.00,
|
||
"cost_max": 55.00,
|
||
"architecture_style": "现代主义",
|
||
"is_featured": true,
|
||
"tags": [
|
||
{ "id": 1, "name": "现代", "type": "style" },
|
||
{ "id": 5, "name": "落地窗", "type": "feature" }
|
||
],
|
||
"lead_designer": {
|
||
"id": 12,
|
||
"name_cn": "张明远",
|
||
"title_badge": "Lead Architect"
|
||
},
|
||
"view_count": 1234,
|
||
"like_count": 56,
|
||
"favorite_count": 23,
|
||
"is_liked": false,
|
||
"is_favorited": true,
|
||
"published_at": "2024-12-15T10:00:00Z"
|
||
}
|
||
],
|
||
"total": 156
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.5 案例详情
|
||
|
||
```bash
|
||
GET /api/cases/88
|
||
Authorization: Bearer eyJhbGci... (可选)
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"id": 88,
|
||
"title": "云端墅 The Cloud Villa",
|
||
"code": "P-2024-8839",
|
||
"cover_image": "https://cdn.example.com/cases/88/cover.jpg",
|
||
"category": { "id": 1, "name": "别墅", "slug": "villa" },
|
||
"status": "published",
|
||
"is_featured": true,
|
||
"layout": "3室2厅3卫",
|
||
"floor_height": "3.6/3.3/3.3m",
|
||
|
||
"dimensions": {
|
||
"site": {
|
||
"site_width": "面宽 ≥ 10.5m",
|
||
"site_depth": "进深 ≥ 12.2m",
|
||
"site_area": 128.50,
|
||
"lighting_restriction": "南侧无遮挡",
|
||
"site_shape": "规则矩形"
|
||
},
|
||
"scale": {
|
||
"floors_above": 3,
|
||
"floors_below": 1,
|
||
"cost_min": 45.00,
|
||
"cost_max": 55.00,
|
||
"total_building_area": 340.00,
|
||
"bedroom_count": 5,
|
||
"bedroom_note": "含1主卧套房"
|
||
},
|
||
"function": {
|
||
"stair_type": "旋转楼梯 + 电梯",
|
||
"special_space": "地下影音室 / 露台花园",
|
||
"bedroom_config": "主卧套房含衣帽间",
|
||
"leisure_space": "屋顶露台 / 下沉式客厅",
|
||
"kitchen_dining": "开放式西厨 + 独立中厨",
|
||
"bathroom_config": "5卫 (含2套干湿分离)"
|
||
},
|
||
"appearance": {
|
||
"architecture_style": "现代主义",
|
||
"roof_type": "平屋顶 + 局部坡屋顶",
|
||
"facade_material": "白色真石漆 + 深灰铝板"
|
||
},
|
||
"structure": {
|
||
"structure_type": "框架结构",
|
||
"foundation_type": "筏板基础",
|
||
"layout_logic": "南北通透 / 动静分区",
|
||
"wall_thickness": "240mm (外) + 120mm (内)",
|
||
"seismic_rating": "7度设防",
|
||
"insulation_type": "外墙外保温 EPS",
|
||
"roof_structure": "SBS防水 + 挤塑板保温"
|
||
}
|
||
},
|
||
|
||
"design_concept": "<p>设计理念正文...</p>",
|
||
"concept_style": "现代主义",
|
||
"concept_material": "混凝土 / 玻璃 / 石材",
|
||
"concept_target": "追求品质生活的年轻家庭",
|
||
"meta": {},
|
||
|
||
"images": {
|
||
"effect": [
|
||
{ "id": 1, "url": "https://cdn.example.com/cases/88/effect-1.jpg", "thumbnail_url": "..." }
|
||
],
|
||
"floor_plan": [
|
||
{ "id": 2, "url": "https://cdn.example.com/cases/88/plan-1f.jpg", "thumbnail_url": "..." }
|
||
],
|
||
"elevation": [
|
||
{ "id": 3, "url": "https://cdn.example.com/cases/88/elev-south.jpg", "thumbnail_url": "..." }
|
||
]
|
||
},
|
||
|
||
"files": {
|
||
"floor_plan": [
|
||
{ "id": 1, "file_name": "一层平面图.dwg", "file_ext": "dwg", "file_size": 2048000 }
|
||
],
|
||
"exterior": [],
|
||
"construction": [
|
||
{ "id": 2, "file_name": "施工图全套.pdf", "file_ext": "pdf", "file_size": 15360000 }
|
||
],
|
||
"structure": [],
|
||
"interior": [],
|
||
"courtyard": []
|
||
},
|
||
|
||
"team": [
|
||
{
|
||
"designer": {
|
||
"id": 12,
|
||
"name_cn": "张明远",
|
||
"name_en": "Zhang Mingyuan",
|
||
"title": "方案主创设计师",
|
||
"title_badge": "Lead Architect",
|
||
"portrait": "https://cdn.example.com/designers/12/portrait.jpg"
|
||
},
|
||
"role": "scheme",
|
||
"is_lead": true
|
||
},
|
||
{
|
||
"designer": {
|
||
"id": 15,
|
||
"name_cn": "李结构",
|
||
"title": "结构工程师",
|
||
"title_badge": "Structural Eng."
|
||
},
|
||
"role": "structure",
|
||
"is_lead": false
|
||
}
|
||
],
|
||
|
||
"tags": [
|
||
{ "id": 1, "name": "现代", "type": "style" },
|
||
{ "id": 5, "name": "落地窗", "type": "feature" }
|
||
],
|
||
|
||
"stats": {
|
||
"view_count": 1234,
|
||
"like_count": 56,
|
||
"favorite_count": 23,
|
||
"download_count": 8,
|
||
"comment_count": 12
|
||
},
|
||
|
||
"user_interaction": {
|
||
"is_liked": false,
|
||
"is_favorited": true
|
||
},
|
||
|
||
"published_at": "2024-12-15T10:00:00Z",
|
||
"created_at": "2024-12-10T08:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.6 管理端文件上传（分阶段）
|
||
|
||
```bash
|
||
POST /admin/cases/88/files
|
||
Authorization: Bearer eyJhbGci...
|
||
Content-Type: multipart/form-data
|
||
|
||
# Form Data
|
||
stage: construction
|
||
file: (binary) 施工图全套.pdf
|
||
|
||
# Response 201
|
||
{
|
||
"code": 201,
|
||
"message": "上传成功",
|
||
"data": {
|
||
"id": 156,
|
||
"case_id": 88,
|
||
"stage": "construction",
|
||
"file_name": "施工图全套.pdf",
|
||
"file_path": "cases/88/construction/施工图全套.pdf",
|
||
"file_size": 15360000,
|
||
"file_ext": "pdf",
|
||
"mime_type": "application/pdf"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.7 管理端创建案例
|
||
|
||
```bash
|
||
POST /admin/cases
|
||
Authorization: Bearer eyJhbGci...
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"title": "云端墅 The Cloud Villa",
|
||
"code": "P-2024-8839",
|
||
"category_id": 1,
|
||
"cover_image": "https://cdn.example.com/cases/88/cover.jpg",
|
||
"layout": "3室2厅3卫",
|
||
"floor_height": "3.6/3.3/3.3m",
|
||
"site_width": "面宽 ≥ 10.5m",
|
||
"site_depth": "进深 ≥ 12.2m",
|
||
"site_area": 128.50,
|
||
"floors_above": 3,
|
||
"floors_below": 1,
|
||
"cost_min": 45.00,
|
||
"cost_max": 55.00,
|
||
"total_building_area": 340.00,
|
||
"bedroom_count": 5,
|
||
"bedroom_note": "含1主卧套房",
|
||
"architecture_style": "现代主义",
|
||
"structure_type": "框架结构",
|
||
"design_concept": "<p>设计理念正文...</p>",
|
||
"tag_ids": [1, 5, 12],
|
||
"team": [
|
||
{ "designer_id": 12, "role": "scheme", "is_lead": true },
|
||
{ "designer_id": 15, "role": "structure", "is_lead": false }
|
||
]
|
||
}
|
||
|
||
# Response 201
|
||
{
|
||
"code": 201,
|
||
"message": "创建成功",
|
||
"data": {
|
||
"id": 88,
|
||
"code": "P-2024-8839",
|
||
"status": "draft"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.8 管理端案例状态变更
|
||
|
||
```bash
|
||
PUT /admin/cases/88/status
|
||
Authorization: Bearer eyJhbGci...
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"status": "published"
|
||
}
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "状态已更新",
|
||
"data": {
|
||
"id": 88,
|
||
"status": "published",
|
||
"published_at": "2024-12-15T10:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.9 设计师详情
|
||
|
||
```bash
|
||
GET /api/designers/12
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"id": 12,
|
||
"name_cn": "张明远",
|
||
"name_en": "Zhang Mingyuan",
|
||
"title": "方案主创设计师",
|
||
"title_badge": "Lead Architect",
|
||
"company": "ZM 建筑事务所",
|
||
"city": "上海",
|
||
"portrait": "https://cdn.example.com/designers/12/portrait.jpg",
|
||
"portrait_caption": "STUDIO PORTRAIT © 2023",
|
||
"years_of_experience": 15,
|
||
"project_count": 42,
|
||
"design_philosophy_quote": "建筑是凝固的音乐",
|
||
"design_philosophy": "<p>设计理念详述...</p>",
|
||
"specialties": [
|
||
{ "id": 20, "name": "参数化设计" },
|
||
{ "id": 21, "name": "可持续建筑" }
|
||
],
|
||
"awards": [
|
||
{
|
||
"year": 2023,
|
||
"title": "红点设计大奖 Red Dot Award",
|
||
"description": "最佳室内设计类 - The Cloud Villa"
|
||
},
|
||
{
|
||
"year": 2022,
|
||
"title": "Architizer A+ Awards",
|
||
"description": "住宅建筑类 - 山水间"
|
||
}
|
||
],
|
||
"stats": {
|
||
"follower_count": 326,
|
||
"view_count": 8920,
|
||
"project_count": 42
|
||
},
|
||
"user_interaction": {
|
||
"is_followed": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.10 管理端创建轮播
|
||
|
||
```bash
|
||
POST /admin/banners
|
||
Authorization: Bearer eyJhbGci...
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"title": "云端墅 — 现代都市别墅的极致诠释",
|
||
"description": "三层框架结构，340㎡ 全功能空间",
|
||
"image": "https://cdn.example.com/banners/cloud-villa.jpg",
|
||
"label": "精选项目",
|
||
"link_type": "case",
|
||
"link_url": "/cases/88",
|
||
"sort": 1,
|
||
"is_active": true
|
||
}
|
||
|
||
# Response 201
|
||
{
|
||
"code": 201,
|
||
"message": "创建成功",
|
||
"data": {
|
||
"id": 5,
|
||
"title": "云端墅 — 现代都市别墅的极致诠释",
|
||
"sort": 1,
|
||
"is_active": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.11 管理端仪表盘概览
|
||
|
||
```bash
|
||
GET /admin/dashboard/overview
|
||
Authorization: Bearer eyJhbGci...
|
||
|
||
# Response 200
|
||
{
|
||
"code": 200,
|
||
"message": "ok",
|
||
"data": {
|
||
"total_cases": 256,
|
||
"published_cases": 198,
|
||
"total_designers": 42,
|
||
"total_users": 3680,
|
||
"today_views": 1250,
|
||
"today_registers": 15,
|
||
"pending_comments": 8,
|
||
"pending_cases": 3
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 端点汇总统计
|
||
|
||
| 分组 | 服务对象 | 端点数 |
|
||
|------|----------|--------|
|
||
| 用户端认证 | 🟦 user | 16 |
|
||
| 用户端案例 | 🟦 user | 8 |
|
||
| 用户端设计师 | 🟦 user | 4 |
|
||
| 用户端内容 | 🟦 user | 8 |
|
||
| 管理端认证 | 🟧 admin | 4 |
|
||
| 管理端案例管理 | 🟧 admin | 9 |
|
||
| 管理端轮播管理 | 🟧 admin | 5 |
|
||
| 管理端专题管理 | 🟧 admin | 6 |
|
||
| 管理端分类标签 | 🟧 admin | 8 |
|
||
| 管理端设计师管理 | 🟧 admin | 5 |
|
||
| 管理端评论管理 | 🟧 admin | 4 |
|
||
| 管理端用户权限 | 🟧 admin | 8 |
|
||
| 管理端系统配置 | 🟧 admin | 2 |
|
||
| 管理端仪表盘 | 🟧 admin | 3 |
|
||
| 管理端日志 | 🟧 admin | 2 |
|
||
| 通用上传 | 🟩 both | 1 |
|
||
| **合计** | | **93** |
|
||
|
||
---
|
||
|
||
*最后更新: 2026-02-28*
|