chuanggao-website/design/API接口设计.md

# 创高家具官网 - 后端API接口设计

## 一、接口规范

### 1.1 基础规范

| 项目 | 规范 |
|------|------|
| 接口前缀 | `/api` |
| 版本 | v1（URL中体现） |
| 认证方式 | Sa-Token（Header: `Authorization: Bearer {token}`） |
| 响应格式 | JSON统一包装 |

### 1.2 响应结构

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1715164800000
}
```

### 1.3 分页参数

| 参数 | 类型 | 说明 |
|------|------|------|
| page | int | 页码，默认1 |
| size | int | 每页条数，默认10，最大50 |
| sort | string | 排序字段 |
| order | string | 排序方向：asc/desc |

### 1.4 多语言支持

| 参数 | 类型 | 说明 |
|------|------|------|
| lang | string | 语言：zh-CN / en-US，默认从Accept-Language或配置读取 |

---

## 二、前台接口（Portal）

### 2.1 公司信息

#### 获取公司配置
```
GET /api/portal/company/info
```

**响应**
```json
{
  "code": 200,
  "data": {
    "brandName": "创高家具",
    "brandNameEn": "ChuangGao Furniture",
    "slogan": "匠心定制，品质生活",
    "sloganEn": "Crafted for Quality Living",
    "contactPhone": "400-xxx-xxxx",
    "contactEmail": "contact@chuanggao.com",
    "address": "广东省佛山市...",
    "addressEn": "Foshan, Guangdong, China",
    "wechatQr": "https://minio.../uploads/wechat-qr.jpg",
    "socialLinks": {
      "weibo": "...",
      "douyin": "..."
    },
    "icpRecord": "粤ICP备xxxxxxxx号",
    "copyright": "© 2024 创高家具 版权所有",
    "seo": {
      "title": "...",
      "keywords": "...",
      "description": "..."
    }
  }
}
```

---

### 2.2 首页数据

#### 获取首页完整数据
```
GET /api/portal/home/data
```

**响应**
```json
{
  "code": 200,
  "data": {
    "banners": [...],           // 轮播图列表
    "pageBlocks": {...},       // 页面区块配置
    "hotProducts": [...],      // 热门产品（8个）
    "recommendCases": [...],    // 推荐案例（6个）
    "brandStrength": {...}     // 品牌实力数据
  }
}
```

#### 获取轮播图
```
GET /api/portal/carousel/list
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| position | string | 是 | 位置：home_banner, about_banner等 |

---

### 2.3 产品模块

#### 获取产品分类树
```
GET /api/portal/product/category/tree
```

**响应**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "全屋定制",
      "nameEn": "Whole House Custom",
      "code": "custom",
      "icon": "...",
      "image": "...",
      "children": [...]
    }
  ]
}
```

#### 获取产品列表
```
GET /api/portal/product/list
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| categoryId | long | 否 | 分类ID |
| isHot | boolean | 否 | 是否热门 |
| isNew | boolean | 否 | 是否新品 |
| isRecommend | boolean | 否 | 是否推荐 |
| keyword | string | 否 | 关键词搜索 |
| page | int | 否 | 默认1 |
| size | int | 否 | 默认12 |

**响应**
```json
{
  "code": 200,
  "data": {
    "total": 100,
    "pages": 10,
    "current": 1,
    "records": [
      {
        "id": 1,
        "name": "意式极简真皮沙发",
        "nameEn": "Italian Minimalist Leather Sofa",
        "mainImage": "...",
        "summary": "进口头层牛皮...",
        "summaryEn": "...",
        "priceMin": 15800,
        "priceMax": 25800,
        "isShowPrice": false,
        "params": [{"name": "材质", "value": "真皮"}],
        "sceneTags": ["客厅", "大户型"]
      }
    ]
  }
}
```

#### 获取产品详情
```
GET /api/portal/product/detail/{id}
```

---

### 2.4 案例模块

#### 获取案例分类
```
GET /api/portal/case/category/list
```

#### 获取案例列表
```
GET /api/portal/case/list
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| categoryId | long | 否 | 分类ID |
| isRecommend | boolean | 否 | 是否推荐 |
| page | int | 否 | 默认1 |
| size | int | 否 | 默认9 |

#### 获取案例详情
```
GET /api/portal/case/detail/{id}
```

**响应包含**
- 案例基本信息
- 图片轮播数组
- 项目信息（面积、地点、时间）
- 关联产品列表
- 上一篇/下一篇导航

---

### 2.5 新闻模块

#### 获取新闻分类
```
GET /api/portal/news/category/list
```

#### 获取新闻列表
```
GET /api/portal/news/list
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| categoryId | long | 否 | 分类ID |
| isTop | boolean | 否 | 是否置顶 |
| page | int | 否 | 默认1 |
| size | int | 否 | 默认10 |

#### 获取新闻详情
```
GET /api/portal/news/detail/{id}
```

---

### 2.6 关于创高

#### 获取页面区块内容
```
GET /api/portal/page/blocks
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageCode | string | 是 | 页面代码: about, join等 |

#### 获取荣誉资质列表
```
GET /api/portal/honor/list
```

**参数**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 否 | 类型：certificate/award/patent/partner |

---

### 2.7 招商加盟/联系我们

#### 获取加盟政策
```
GET /api/portal/franchise/policies
```

#### 提交留言表单
```
POST /api/portal/contact/submit
```

**请求体**
```json
{
  "type": "join",           // join/cooperate/feedback/other
  "name": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "company": "某某公司",
  "address": "广东省深圳市",
  "subject": "加盟咨询",
  "message": "想了解加盟政策..."
}
```

---

## 三、管理后台接口（Admin）

### 3.1 认证模块

#### 管理员登录
```
POST /api/admin/auth/login
```

**请求体**
```json
{
  "username": "admin",
  "password": "admin123",
  "captcha": "abc123"
}
```

#### 登出
```
POST /api/admin/auth/logout
```

#### 获取当前用户信息
```
GET /api/admin/auth/info
```

---

### 3.2 公司信息管理

#### 更新公司信息
```
PUT /api/admin/company/update
```

**请求体**（对应 f_company 表字段）

#### 获取公司信息
```
GET /api/admin/company/info
```

---

### 3.3 轮播图管理

#### 轮播图列表
```
GET /api/admin/carousel/list
```

#### 创建轮播图
```
POST /api/admin/carousel/create
```

#### 更新轮播图
```
PUT /api/admin/carousel/update/{id}
```

#### 删除轮播图
```
DELETE /api/admin/carousel/delete/{id}
```

#### 批量更新排序
```
PUT /api/admin/carousel/sort
```

---

### 3.4 产品管理

#### 产品分类管理
```
GET    /api/admin/product/category/list
POST   /api/admin/product/category/create
PUT    /api/admin/product/category/update/{id}
DELETE /api/admin/product/category/delete/{id}
```

#### 产品管理
```
GET    /api/admin/product/list           // 支持分页、分类筛选、关键词搜索
POST   /api/admin/product/create
PUT    /api/admin/product/update/{id}
DELETE /api/admin/product/delete/{id}
PUT    /api/admin/product/status/{id}   // 上下架
PUT    /api/admin/product/sort          // 批量排序
```

---

### 3.5 案例管理

```
GET    /api/admin/case/category/list
POST   /api/admin/case/category/create
PUT    /api/admin/case/category/update/{id}
DELETE /api/admin/case/category/delete/{id}

GET    /api/admin/case/list
POST   /api/admin/case/create
PUT    /api/admin/case/update/{id}
DELETE /api/admin/case/delete/{id}
```

---

### 3.6 新闻管理

```
GET    /api/admin/news/category/list
POST   /api/admin/news/category/create
PUT    /api/admin/news/category/update/{id}
DELETE /api/admin/news/category/delete/{id}

GET    /api/admin/news/list
POST   /api/admin/news/create
PUT    /api/admin/news/update/{id}
DELETE /api/admin/news/delete/{id}
PUT    /api/admin/news/publish/{id}    // 发布/下线
PUT    /api/admin/news/top/{id}         // 置顶/取消置顶
```

---

### 3.7 页面区块管理（核心功能）

#### 获取页面所有区块
```
GET /api/admin/page/blocks
```

**参数**: pageCode (home/about/products/cases/contact)

#### 更新区块内容
```
PUT /api/admin/page/block/update/{id}
```

**请求体**
```json
{
  "contentZh": "中文内容",
  "contentEn": "English Content",
  "image": "https://minio.../image.jpg",
  "imagesJson": ["url1", "url2"],
  "linkUrl": "/products",
  "linkTextZh": "查看产品",
  "linkTextEn": "View Products",
  "isShow": true
}
```

#### 批量更新区块
```
PUT /api/admin/page/blocks/batch-update
```

---

### 3.8 文件上传/媒体库（MinIO）

#### 单文件上传
```
POST /api/admin/upload/single
```

**Content-Type**: multipart/form-data

**参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| file | File | 上传的文件 |
| usedIn | string | 使用位置：carousel/product/case/news/page |

**响应**
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "fileName": "banner-01.jpg",
    "fileSize": 1024000,
    "filePath": "/uploads/carousel/banner-01.jpg",
    "fullUrl": "http://minio:9000/chuanggao-images/uploads/carousel/banner-01.jpg",
    "width": 1920,
    "height": 600,
    "thumbUrl": "..."
  }
}
```

#### 多文件上传
```
POST /api/admin/upload/multiple
```

#### 获取媒体库列表
```
GET /api/admin/media/list
```

**参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| fileType | string | image/video/document |
| usedIn | string | 使用位置筛选 |
| page | int | 页码 |
| size | int | 每页条数 |

#### 删除媒体文件
```
DELETE /api/admin/media/delete/{id}
```

#### 获取图片直链
```
GET /api/admin/media/url/{id}
```

**响应**: 返回可直接访问的URL（已考虑MinIO公开读配置）

---

### 3.9 荣誉资质管理

```
GET    /api/admin/honor/list
POST   /api/admin/honor/create
PUT    /api/admin/honor/update/{id}
DELETE /api/admin/honor/delete/{id}
```

---

### 3.10 加盟政策管理

```
GET    /api/admin/franchise/policy/list
POST   /api/admin/franchise/policy/create
PUT    /api/admin/franchise/policy/update/{id}
DELETE /api/admin/franchise/policy/delete/{id}
```

---

### 3.11 留言管理

#### 留言列表
```
GET /api/admin/message/list
```

**参数**
| 参数 | 类型 | 说明 |
|------|------|------|
| type | string | 留言类型筛选 |
| status | int | 处理状态筛选 |
| startDate | date | 开始日期 |
| endDate | date | 结束日期 |

#### 留言详情
```
GET /api/admin/message/detail/{id}
```

#### 回复留言
```
PUT /api/admin/message/reply/{id}
```

**请求体**
```json
{
  "replyContent": "感谢您的咨询，我们会尽快联系您...",
  "status": 2  // 已回复
}
```

---

### 3.12 管理员账号管理

```
GET    /api/admin/user/list
POST   /api/admin/user/create
PUT    /api/admin/user/update/{id}
DELETE /api/admin/user/delete/{id}
PUT    /api/admin/user/status/{id}    // 启用/禁用
PUT    /api/admin/user/reset-password/{id}
```

---

## 四、接口安全

### 4.1 前台接口
- 无需登录，公开访问
- 限流：单个IP 100次/分钟

### 4.2 管理后台接口
- 需登录，Sa-Token 验证
- 权限检查：根据 role 字段判断
- 限流：单个用户 30次/分钟

### 4.3 文件上传
- 文件类型白名单：jpg, jpeg, png, gif, webp, mp4, pdf
- 单文件大小限制：图片10MB，视频100MB
- 图片自动压缩：超过1920px自动压缩，生成缩略图

---

## 五、MinIO 存储结构

```
chuanggao-images (bucket)
├── uploads/
│   ├── carousel/         # 轮播图
│   │   ├── home-01.jpg
│   │   └── about-01.jpg
│   ├── products/          # 产品图片
│   │   ├── 2024/
│   │   └── thumbs/       # 缩略图
│   ├── cases/             # 案例图片
│   ├── news/              # 新闻封面
│   ├── pages/             # 页面区块图片
│   ├── company/           # 公司相关（logo、二维码）
│   └── honor/             # 荣誉证书
└── temp/                  # 临时文件（定期清理）
```

---

## 六、Controller 层设计示例

```java
// PortalCompanyController.java - 前台公司信息
@RestController
@RequestMapping("/api/portal/company")
public class PortalCompanyController {
    
    @GetMapping("/info")
    public Result<CompanyVO> getCompanyInfo(@RequestParam(defaultValue = "zh-CN") String lang) {
        // 根据lang返回对应语言内容
    }
}

// AdminCompanyController.java - 后台公司管理
@RestController
@RequestMapping("/api/admin/company")
@SaCheckLogin
public class AdminCompanyController {
    
    @GetMapping("/info")
    public Result<CompanyVO> getInfo() {
        return Result.success(companyService.getInfo());
    }
    
    @PutMapping("/update")
    @SaCheckRole("admin")
    public Result<Void> update(@RequestBody @Valid CompanyDTO dto) {
        companyService.update(dto);
        return Result.success();
    }
}

// AdminUploadController.java - 文件上传
@RestController
@RequestMapping("/api/admin/upload")
@SaCheckLogin
public class AdminUploadController {
    
    @PostMapping("/single")
    public Result<MediaVO> uploadSingle(
            @RequestParam("file") MultipartFile file,
            @RequestParam(defaultValue = "other") String usedIn) {
        return Result.success(uploadService.upload(file, usedIn));
    }
}
```