初始化

2026-03-05 21:27:11 +08:00
commit 130de0fd5d
140 changed files with 21972 additions and 0 deletions
--- a/docs/architecture/api-contracts.md
+++ b/docs/architecture/api-contracts.md
@@ -0,0 +1,869 @@
+# 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*