689 lines
13 KiB
Markdown
689 lines
13 KiB
Markdown
# 创高家具官网 - 后端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));
|
||
}
|
||
}
|
||
```
|