DeXun/chuanggao-website

Fork 0

Files

王文昊 abc3b4f875 创高项目初始化

2026-05-12 16:53:18 +08:00

13 KiB

Raw Blame History

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

一、接口规范

1.1 基础规范

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

1.2 响应结构

{
  "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

响应

{
  "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

响应

{
  "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

响应

{
  "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

响应

{
  "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

请求体

{
  "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

请求体

{
  "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}

请求体

{
  "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

响应

{
  "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}

请求体

{
  "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 层设计示例

// 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));
    }
}

13 KiB Raw Blame History Unescape Escape

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

一、接口规范

1.1 基础规范

1.2 响应结构

1.3 分页参数

1.4 多语言支持

二、前台接口（Portal）

2.1 公司信息

获取公司配置

2.2 首页数据

获取首页完整数据

获取轮播图

2.3 产品模块

获取产品分类树

获取产品列表

获取产品详情

2.4 案例模块

获取案例分类

获取案例列表

获取案例详情

2.5 新闻模块

获取新闻分类

获取新闻列表

获取新闻详情

2.6 关于创高

获取页面区块内容

获取荣誉资质列表

2.7 招商加盟/联系我们

获取加盟政策

提交留言表单

三、管理后台接口（Admin）

3.1 认证模块

管理员登录

登出

获取当前用户信息

3.2 公司信息管理

更新公司信息

获取公司信息

3.3 轮播图管理

轮播图列表

创建轮播图

更新轮播图

删除轮播图

批量更新排序

3.4 产品管理

产品分类管理

产品管理

3.5 案例管理

3.6 新闻管理

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

获取页面所有区块

更新区块内容

批量更新区块

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

单文件上传

多文件上传

获取媒体库列表

删除媒体文件

获取图片直链

3.9 荣誉资质管理

3.10 加盟政策管理

3.11 留言管理

留言列表

留言详情

回复留言

3.12 管理员账号管理

四、接口安全

4.1 前台接口

4.2 管理后台接口

4.3 文件上传

五、MinIO 存储结构

六、Controller 层设计示例

13 KiB

Raw Blame History