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