nanocode/new-media-platform/website-new/docs/API.md

# API 接口文档

## 1. 接口规范

### 1.1 基础信息

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

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

### 1.2 响应格式

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

### 1.3 错误码

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

### 1.4 认证方式

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

```
Authorization: Bearer <jwt_token>
```

## 2. 认证接口

### 2.1 管理员登录

```http
POST /api/auth/login
```

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

**响应：**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "admin": {
      "id": 1,
      "username": "admin"
    }
  }
}
```

### 2.2 获取当前管理员信息

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

**响应：**
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "username": "admin"
  }
}
```

### 2.3 修改密码

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

**请求体：**
```json
{
  "old_password": "oldpass",
  "new_password": "newpass"
}
```

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

### 3.1 获取首页模块

```http
GET /api/home/modules
```

**响应：**
```json
{
  "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 获取导航菜单

```http
GET /api/nav
```

**响应：**
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "首页",
      "link": "/",
      "is_external": false,
      "children": []
    }
  ]
}
```

### 3.3 获取系统设置

```http
GET /api/settings
```

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

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

### 4.1 首页模块管理

#### 获取所有模块（后台）

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

**响应：** 包含未启用的模块

#### 获取单个模块详情

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

#### 更新模块

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

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

#### 更新模块排序

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

**请求体：**
```json
{
  "orders": [
    {"id": 1, "sort_order": 1},
    {"id": 2, "sort_order": 2},
    {"id": 3, "sort_order": 3}
  ]
}
```

#### 切换模块启用状态

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

**响应：**
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "is_enabled": false
  }
}
```

### 4.2 导航菜单管理

#### 获取菜单列表

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

#### 创建菜单

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

**请求体：**
```json
{
  "name": "新菜单",
  "link": "/new-page",
  "sort_order": 6,
  "is_enabled": true,
  "is_external": false
}
```

#### 更新菜单

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

#### 删除菜单

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

### 4.3 系统设置管理

#### 获取所有设置

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

#### 更新设置

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

**请求体：**
```json
{
  "site_name": "新名称",
  "company_phone": "新电话"
}
```

### 4.4 图片资源管理

#### 获取图片列表

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

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

**响应：**
```json
{
  "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
}
```

#### 上传图片

```http
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` |

**响应：**
```json
{
  "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/`

#### 更新图片描述

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

**表单字段：**
| 字段 | 类型 | 说明 |
|------|------|------|
| description | string | 新的图片描述 |

#### 删除图片

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

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

#### 批量删除图片

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

**请求体：**
```json
[1, 2, 3]
```

#### 获取图片插入信息

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

**查询参数：**
| 参数 | 类型 | 说明 |
|------|------|------|
| size | string | `original` 或 `thumb`，默认 `original` |

**响应：**
```json
{
  "id": 1,
  "url": "/storage/admin/images/xxx.jpg",
  "width": 1920,
  "height": 1080,
  "original_name": "photo.jpg"
}
```

### 4.5 新闻资讯管理

#### 栏目管理

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

**创建栏目请求体：**
```json
{
  "name": "公司新闻",
  "slug": "company-news",
  "description": "公司动态和新闻",
  "sort_order": 1,
  "is_enabled": true
}
```

#### 资讯管理

```http
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                                        # 发布/取消发布
```

**创建资讯请求体：**
```json
{
  "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
}
```

**删除资讯规则：**
- 删除数据库记录
- 同步删除封面图及其缩略图（如果存在）

#### 访客端接口（无需认证）

```http
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 通用文件上传

#### 上传图片（兼容旧接口）

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

**表单字段：**
- `file`: 图片文件 (jpg, png, gif, webp, max 5MB)

**响应：**
```json
{
  "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`