admin/nanocode

Fork 0

Files

T

Ubuntu 32b43f85bd a

2026-07-03 16:58:28 +08:00

12 KiB

Raw Permalink Blame History

API 接口文档

1. 接口规范

1.1 基础信息

项	值
基础 URL	`''`（相对路径，通过 Vite 代理转发）
后端地址	`http://localhost:10003`
协议	HTTP/HTTPS
数据格式	JSON
字符编码	UTF-8

注意： 前端开发环境使用相对路径调用 API，Vite 代理将 /api、/uploads、/storage 转发到后端服务。生产环境通过 Nginx 统一代理。

1.2 响应格式

{
  "code": 200,
  "message": "success",
  "data": {}
}

1.3 错误码

码	说明
200	成功
400	请求参数错误
401	未认证/Token过期
403	无权限
404	资源不存在
500	服务器内部错误

1.4 认证方式

管理员接口需要在请求头携带 Token：

Authorization: Bearer <jwt_token>

2. 认证接口

2.1 管理员登录

POST /api/auth/login

请求体：

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "admin": {
      "id": 1,
      "username": "admin"
    }
  }
}

2.2 获取当前管理员信息

GET /api/auth/me
Authorization: Bearer <token>

响应：

{
  "code": 200,
  "data": {
    "id": 1,
    "username": "admin"
  }
}

2.3 修改密码

POST /api/auth/change-password
Authorization: Bearer <token>

请求体：

{
  "old_password": "oldpass",
  "new_password": "newpass"
}

3. 前台接口（无需认证）

3.1 获取首页模块

GET /api/home/modules

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "轮播图",
      "code": "banner",
      "type": "banner",
      "title": "",
      "subtitle": "",
      "content": {
        "slides": [
          {
            "image": "/uploads/banner1.jpg",
            "link": "/product",
            "title": "手机就能做尿检"
          }
        ]
      },
      "style_config": {
        "backgroundColor": "#ffffff",
        "paddingTop": "0",
        "paddingBottom": "0"
      }
    }
  ]
}

3.2 获取导航菜单

GET /api/nav

响应：

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "首页",
      "link": "/",
      "is_external": false,
      "children": []
    }
  ]
}

3.3 获取系统设置

GET /api/settings

响应：

{
  "code": 200,
  "data": {
    "site_name": "飞点健康",
    "site_logo": "/logo.png",
    "company_phone": "400-xxx-xxxx",
    "icp": "粤ICP备xxxxxxxx号"
  }
}

4. 后台管理接口（需要认证）

4.1 首页模块管理

获取所有模块（后台）

GET /api/admin/home/modules
Authorization: Bearer <token>

响应： 包含未启用的模块

获取单个模块详情

GET /api/admin/home/modules/:id
Authorization: Bearer <token>

更新模块

PUT /api/admin/home/modules/:id
Authorization: Bearer <token>
Content-Type: application/json

请求体：

{
  "title": "新的标题",
  "subtitle": "副标题",
  "content": {
    "slides": [
      {"image": "/uploads/banner.jpg", "link": "/", "title": "标题"}
    ]
  },
  "style_config": {
    "backgroundColor": "#FEF9E7",
    "paddingTop": "60px"
  },
  "is_enabled": true
}

更新模块排序

PUT /api/admin/home/modules/sort
Authorization: Bearer <token>
Content-Type: application/json

请求体：

{
  "orders": [
    {"id": 1, "sort_order": 1},
    {"id": 2, "sort_order": 2},
    {"id": 3, "sort_order": 3}
  ]
}

切换模块启用状态

PUT /api/admin/home/modules/:id/toggle
Authorization: Bearer <token>

响应：

{
  "code": 200,
  "data": {
    "id": 1,
    "is_enabled": false
  }
}

4.2 导航菜单管理

获取菜单列表

GET /api/admin/nav
Authorization: Bearer <token>

创建菜单

POST /api/admin/nav
Authorization: Bearer <token>
Content-Type: application/json

请求体：

{
  "name": "新菜单",
  "link": "/new-page",
  "sort_order": 6,
  "is_enabled": true,
  "is_external": false
}

更新菜单

PUT /api/admin/nav/:id
Authorization: Bearer <token>
Content-Type: application/json

删除菜单

DELETE /api/admin/nav/:id
Authorization: Bearer <token>

4.3 系统设置管理

获取所有设置

GET /api/admin/settings
Authorization: Bearer <token>

更新设置

PUT /api/admin/settings
Authorization: Bearer <token>
Content-Type: application/json

请求体：

{
  "site_name": "新名称",
  "company_phone": "新电话"
}

4.4 图片资源管理

获取图片列表

GET /api/images?page=1&size=20&module=news
Authorization: Bearer <token>

查询参数：

参数	类型	说明
page	int	页码，默认 1
size	int	每页数量，默认 20，最大 100
module	string	按模块筛选（可选：news/product/page）

响应：

{
  "items": [
    {
      "id": 1,
      "filename": "20260421_182026_df70a127.jpg",
      "original_name": "photo.jpg",
      "file_path": "/storage/admin/images/20260421_182026_df70a127.jpg",
      "thumb_path": "/storage/admin/images/thumbnails/20260421_182026_df70a127.jpg",
      "description": null,
      "file_size": 547343,
      "width": 1920,
      "height": 1080,
      "module": "news",
      "created_at": "2026-04-21T18:20:26"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 20
}

上传图片

POST /api/images/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

表单字段：

字段	类型	说明
file	File	图片文件（jpg, jpeg, png, gif, webp, bmp，最大 10MB）
description	string	图片描述（可选）
module	string	所属模块，默认 `news`

响应：

{
  "success": true,
  "data": {
    "id": 1,
    "filename": "20260421_182026_df70a127.jpg",
    "original_name": "photo.jpg",
    "file_path": "/storage/admin/images/20260421_182026_df70a127.jpg",
    "thumb_path": "/storage/admin/images/thumbnails/20260421_182026_df70a127.jpg",
    "file_size": 547343,
    "width": 1920,
    "height": 1080,
    "module": "news",
    "created_at": "2026-04-21T18:20:26"
  }
}

缩略图规则：

上传成功后自动创建缩略图
缩略图尺寸：最大 300x300 像素，等比缩放
缩略图格式：统一为 JPEG，质量 85%
缩略图命名：与原图同名，扩展名统一为 .jpg
缩略图路径：/storage/admin/images/thumbnails/

更新图片描述

PUT /api/images/{image_id}
Authorization: Bearer <token>
Content-Type: multipart/form-data

表单字段：

字段	类型	说明
description	string	新的图片描述

删除图片

DELETE /api/images/{image_id}
Authorization: Bearer <token>

删除规则：

删除数据库记录
同步删除物理文件（原图 + 缩略图）
外部 URL 跳过删除（仅删除数据库记录）

批量删除图片

POST /api/images/batch-delete
Authorization: Bearer <token>
Content-Type: application/json

请求体：

[1, 2, 3]

获取图片插入信息

GET /api/images/{image_id}/insert?size=original
Authorization: Bearer <token>

查询参数：

参数	类型	说明
size	string	`original` 或 `thumb`，默认 `original`

响应：

{
  "id": 1,
  "url": "/storage/admin/images/xxx.jpg",
  "width": 1920,
  "height": 1080,
  "original_name": "photo.jpg"
}

4.5 新闻资讯管理

栏目管理

GET    /api/news/categories           # 获取栏目列表
POST   /api/news/categories           # 创建栏目
GET    /api/news/categories/{id}      # 获取栏目详情
PUT    /api/news/categories/{id}      # 更新栏目
DELETE /api/news/categories/{id}      # 删除栏目

创建栏目请求体：

{
  "name": "公司新闻",
  "slug": "company-news",
  "description": "公司动态和新闻",
  "sort_order": 1,
  "is_enabled": true
}

资讯管理

GET    /api/news/posts?page=1&size=10&category_id=1&keyword=xxx&status=all  # 获取资讯列表
POST   /api/news/posts                                                          # 创建资讯
GET    /api/news/posts/{post_id}                                                # 获取资讯详情
PUT    /api/news/posts/{post_id}                                                # 更新资讯
DELETE /api/news/posts/{post_id}                                                # 删除资讯
POST   /api/news/posts/{post_id}/publish                                        # 发布/取消发布

创建资讯请求体：

{
  "title": "文章标题",
  "slug": "article-slug",
  "content": "# Markdown 内容\n\n正文...",
  "content_type": "markdown",
  "summary": "文章摘要（可选，未提供时自动提取前100字）",
  "cover_image": "/storage/admin/images/xxx.jpg",
  "category_id": 1,
  "is_draft": true
}

删除资讯规则：

删除数据库记录
同步删除封面图及其缩略图（如果存在）

访客端接口（无需认证）

GET /api/news/public/posts?category_slug=xxx&page=1&size=10  # 获取已发布资讯列表
GET /api/news/public/posts/{slug}                              # 通过 slug 获取文章详情
GET /api/news/public/categories                                # 获取启用的栏目列表

4.6 通用文件上传

上传图片（兼容旧接口）

POST /api/upload/image
Authorization: Bearer <token>
Content-Type: multipart/form-data

表单字段：

file: 图片文件 (jpg, png, gif, webp, max 5MB)

响应：

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "/storage/admin/images/20260421_xxx.jpg",
    "filename": "20260421_xxx.jpg",
    "size": 12345,
    "thumb_url": "/storage/admin/images/thumbnails/20260421_xxx.jpg"
  }
}

5. 图片存储规范

5.1 存储目录结构

storage/
├── admin/
│   └── images/              # 管理员上传的图片
│       ├── thumbnails/      # 缩略图目录
│       ├── banners/         # 轮播图（手动维护）
│       ├── features/        # 特色展示图（手动维护）
│       └── 202604/          # 按月分组的旧文件
└── public/                  # 公开访问的文件（预留）

5.2 静态文件挂载

URL 路径	物理路径	说明
`/uploads`	`storage/admin/images`	兼容旧路径，与 `/storage/admin/images` 指向同一目录
`/storage/admin`	`storage/admin`	管理员文件根目录
`/storage/public`	`storage/public`	公开文件目录

5.3 图片 URL 格式

类型	URL 格式	示例
原图	`/storage/admin/images/{filename}`	`/storage/admin/images/20260421_xxx.jpg`
缩略图	`/storage/admin/images/thumbnails/{filename}.jpg`	`/storage/admin/images/thumbnails/20260421_xxx.jpg`

6. Swagger 文档

启动后端后，访问以下地址查看自动生成的 API 文档：

Swagger UI: http://localhost:10003/docs
ReDoc: http://localhost:10003/redoc

12 KiB Raw Permalink Blame History Unescape Escape

API 接口文档

1. 接口规范

1.1 基础信息

1.2 响应格式

1.3 错误码

1.4 认证方式

2. 认证接口

2.1 管理员登录

2.2 获取当前管理员信息

2.3 修改密码

3. 前台接口（无需认证）

3.1 获取首页模块

3.2 获取导航菜单

3.3 获取系统设置

4. 后台管理接口（需要认证）

4.1 首页模块管理

获取所有模块（后台）

获取单个模块详情

更新模块

更新模块排序

切换模块启用状态

4.2 导航菜单管理

获取菜单列表

创建菜单

更新菜单

删除菜单

4.3 系统设置管理

获取所有设置

更新设置

4.4 图片资源管理

获取图片列表

上传图片

更新图片描述

删除图片

批量删除图片

获取图片插入信息

4.5 新闻资讯管理

栏目管理

资讯管理

访客端接口（无需认证）

4.6 通用文件上传

上传图片（兼容旧接口）

5. 图片存储规范

5.1 存储目录结构

5.2 静态文件挂载

5.3 图片 URL 格式

6. Swagger 文档

12 KiB

Raw Permalink Blame History