# 官网 CMS 后端接口文档

> **版本**: v1.0  
> **Base URL**: `/api/www`  
> **关联文档**: [www-cms-menu.md](./www-cms-menu.md)、[proposal.md](../www/proposal.md)  
> **认证**: 所有接口需登录（`Authorization: Bearer <token>`）

---

## 通用约定

### 响应格式

```json
// 成功
{ "code": 1, "msg": "success", "data": { ... } }
// 错误
{ "code": 0, "msg": "error message", "data": null }
// 无数据
{ "code": 2, "msg": "no data", "data": null }
```

### 分页参数（Query）

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| skip | int | 0 | 跳过条数 |
| limit | int | 20 | 每页条数（最大 1000） |

### 分页响应

```json
{ "items": [...], "total": 100, "skip": 0, "limit": 20 }
```

### 排序参数

列表接口统一支持 `sort_order` 字段，前端通过批量 PATCH 更新排序值实现拖拽排序。

---

## 1. 全局配置 `/api/www/global`

### 1.1 站点信息

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/global/site` | 获取站点信息 |
| PUT | `/api/www/global/site` | 更新站点信息 |

**GET 响应 data：**

```json
{
  "id": 1,
  "site_title": "乐笙 Luxsin",
  "favicon_url": "/uploads/brand/favicon.svg",
  "logo_dark_url": "/uploads/brand/logo-dark.svg",
  "logo_light_url": "/uploads/brand/logo-light.svg"
}
```

**PUT Body：**

```json
{
  "site_title": "乐笙 Luxsin",
  "favicon_url": "/uploads/brand/favicon.svg",
  "logo_dark_url": "/uploads/brand/logo-dark.svg",
  "logo_light_url": "/uploads/brand/logo-light.svg"
}
```

---

### 1.2 页脚配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/global/footer` | 获取页脚配置 |
| PUT | `/api/www/global/footer` | 更新页脚配置 |

**PUT Body：**

```json
{
  "company_name": "深圳市乐笙科技有限公司",
  "company_address": "深圳市南山区...",
  "contact_phone": "0755-12345678",
  "contact_email": "info@luxsin.com",
  "copyright_text": "© 2026 Luxsin. All rights reserved.",
  "icp_number": "粤ICP备XXXXXXXX号",
  "police_number": ""
}
```

---

### 1.3 社交链接

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/global/social` | 获取全部社交链接 |
| PUT | `/api/www/global/social` | 批量更新社交链接 |

**GET 响应 data：**

```json
[
  { "id": 1, "platform": "wechat", "url": "", "qrcode_url": "/uploads/brand/wechat-qr.png", "sort_order": 1 },
  { "id": 2, "platform": "youtube", "url": "https://youtube.com/@luxsin", "qrcode_url": "", "sort_order": 2 }
]
```

**PUT Body：**（全量覆盖）

```json
[
  { "platform": "wechat", "url": "", "qrcode_url": "/uploads/brand/wechat-qr.png" },
  { "platform": "weibo", "url": "https://weibo.com/luxsin", "qrcode_url": "" },
  { "platform": "youtube", "url": "https://youtube.com/@luxsin", "qrcode_url": "" }
]
```

---

### 1.4 SEO 默认值

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/global/seo` | 获取 SEO 默认值 |
| PUT | `/api/www/global/seo` | 更新 SEO 默认值 |

**PUT Body：**

```json
{
  "meta_description": "Luxsin 乐笙科技 - 高保真音频设备",
  "meta_keywords": "DAC,DMP,HiFi,音频,解码器",
  "og_image_url": "/uploads/brand/og-default.jpg"
}
```

---

## 2. 导航管理 `/api/www/nav`

### 2.1 导航入口

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/nav/items` | 获取导航入口列表（按 sort_order 排序） |
| POST | `/api/www/nav/items` | 新增导航入口 |
| PUT | `/api/www/nav/items/:id` | 更新导航入口 |
| DELETE | `/api/www/nav/items/:id` | 删除导航入口 |
| PATCH | `/api/www/nav/items/sort` | 批量更新排序 |

**POST Body：**

```json
{
  "name_zh": "产品",
  "name_en": "Products",
  "link": "/products",
  "is_visible": true,
  "display_mode": "text",
  "icon_name": "",
  "image_url": "",
  "open_new_tab": false
}
```

**PATCH 排序 Body：**

```json
[{ "id": 1, "sort_order": 1 }, { "id": 2, "sort_order": 2 }]
```

---

### 2.2 导航外观

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/nav/appearance` | 获取导航外观配置 |
| PUT | `/api/www/nav/appearance` | 更新导航外观配置 |

**PUT Body：**

```json
{
  "homepage_style": "transparent",
  "non_homepage_style": "transparent"
}
```

---

## 3. 页面管理 `/api/www/sections`

### 3.1 Section 区块

适用于首页（`page_type=home`）、产品详情页（`page_type=product`）、关于我们（`page_type=about`）、技术支持（`page_type=support`）。

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/sections?page_type=home` | 获取指定页面的 Section 列表 |
| GET | `/api/www/sections?page_type=product&product_id=1` | 获取产品详情页 Section |
| POST | `/api/www/sections` | 新增 Section |
| GET | `/api/www/sections/:id` | 获取 Section 详情（含子数据） |
| PUT | `/api/www/sections/:id` | 更新 Section |
| DELETE | `/api/www/sections/:id` | 删除 Section |
| PATCH | `/api/www/sections/sort` | 批量更新排序 |
| POST | `/api/www/sections/:id/duplicate` | 复制 Section |

**GET 列表响应 data：**

```json
{
  "items": [
    {
      "id": 1,
      "page_type": "home",
      "layout": "hero_split",
      "theme": "dark",
      "title_zh": "聆听，本该如此",
      "title_en": "Listening, Reimagined",
      "is_visible": true,
      "sort_order": 1
    }
  ],
  "total": 5
}
```

**POST Body（新建 Section）：**

```json
{
  "page_type": "home",
  "product_id": null,
  "layout": "hero_split",
  "theme": "dark",
  "bg_type": "image",
  "bg_value": "/uploads/banners/hero-bg.jpg",
  "overline_zh": "旗舰系列",
  "overline_en": "FLAGSHIP SERIES",
  "title_zh": "聆听，本该如此",
  "title_en": "Listening, Reimagined",
  "subtitle_zh": "",
  "subtitle_en": "",
  "content_zh": "",
  "content_en": "",
  "cta_primary_zh": "探索产品",
  "cta_primary_en": "Explore",
  "cta_primary_url": "/products",
  "cta_secondary_zh": "",
  "cta_secondary_en": "",
  "cta_secondary_url": "",
  "media_url_zh": "/uploads/products/dmp-a8.png",
  "media_url_en": "/uploads/products/dmp-a8.png",
  "video_url": "",
  "config": {}
}
```

---

### 3.2 Spec Table 参数规格（Section 子资源）

仅 `layout=spec_table` 的 Section 使用。

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/sections/:section_id/spec-groups` | 获取参数分组列表 |
| POST | `/api/www/sections/:section_id/spec-groups` | 新增参数分组 |
| PUT | `/api/www/sections/:section_id/spec-groups/:group_id` | 更新分组 |
| DELETE | `/api/www/sections/:section_id/spec-groups/:group_id` | 删除分组 |
| PATCH | `/api/www/sections/:section_id/spec-groups/sort` | 分组排序 |
| GET | `/api/www/spec-groups/:group_id/items` | 获取分组下的参数项 |
| POST | `/api/www/spec-groups/:group_id/items` | 新增参数项 |
| PUT | `/api/www/spec-items/:id` | 更新参数项 |
| DELETE | `/api/www/spec-items/:id` | 删除参数项 |
| PATCH | `/api/www/spec-groups/:group_id/items/sort` | 参数项排序 |

**POST 新增分组 Body：**

```json
{
  "title_zh": "基本规格",
  "title_en": "Basic Specifications",
  "default_visible": 5
}
```

**POST 新增参数项 Body：**

```json
{
  "name_zh": "信噪比",
  "name_en": "SNR",
  "value_zh": "≥129.5dB",
  "value_en": "≥129.5dB"
}
```

---

### 3.3 产品列表页配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/page/product-list` | 获取配置 |
| PUT | `/api/www/page/product-list` | 更新配置 |

### 3.4 新闻列表页配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/page/news-list` | 获取配置 |
| PUT | `/api/www/page/news-list` | 更新配置 |

### 3.5 关于我们配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/page/about` | 获取配置 |
| PUT | `/api/www/page/about` | 更新配置 |

### 3.6 技术支持配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/page/support` | 获取配置 |
| PUT | `/api/www/page/support` | 更新配置 |

---

## 4. 产品管理 `/api/www/products`

### 4.1 产品系列

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/product/series` | 获取系列列表 |
| POST | `/api/www/product/series` | 新增系列 |
| GET | `/api/www/product/series/:id` | 获取系列详情 |
| PUT | `/api/www/product/series/:id` | 更新系列 |
| DELETE | `/api/www/product/series/:id` | 删除系列（检查是否有关联产品） |
| PATCH | `/api/www/product/series/sort` | 批量排序 |

**POST Body：**

```json
{
  "name_zh": "DMP 流媒体系列",
  "name_en": "DMP Streaming Series",
  "overline": "DMP SERIES",
  "subtitle_zh": "数字流媒体播放与系统控制中枢",
  "subtitle_en": "Digital media player and system controller",
  "cover_url": "/uploads/products/dmp-series-cover.jpg",
  "is_visible": true
}
```

---

### 4.2 产品

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/products?series_id=1&is_visible=1` | 获取产品列表（支持筛选） |
| POST | `/api/www/products` | 新增产品 |
| GET | `/api/www/products/:id` | 获取产品详情 |
| PUT | `/api/www/products/:id` | 更新产品 |
| DELETE | `/api/www/products/:id` | 删除产品（级联删除 Section + 参数规格） |

**GET 列表 Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| series_id | int | 按系列筛选 |
| is_visible | 0/1 | 按显示状态筛选 |
| name | string | 按名称模糊搜索 |

**POST Body：**

```json
{
  "series_id": 1,
  "name_zh": "DMP-A8",
  "name_en": "DMP-A8",
  "slug": "dmp-a8",
  "intro_zh": "旗舰数字流媒体播放器",
  "intro_en": "Flagship digital media player",
  "cover_url": "/uploads/products/dmp-a8-cover.jpg",
  "is_visible": true
}
```

---

## 5. 新闻管理 `/api/www/news`

### 5.1 新闻文章

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/news?status=published` | 获取文章列表 |
| POST | `/api/www/news` | 新增文章 |
| GET | `/api/www/news/:id` | 获取文章详情 |
| PUT | `/api/www/news/:id` | 更新文章 |
| DELETE | `/api/www/news/:id` | 删除文章 |

**GET 列表 Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| status | string | 筛选: draft / published / offline |
| title | string | 按标题模糊搜索 |

**POST Body：**

```json
{
  "title_zh": "乐笙发布全新 DMP-A8",
  "title_en": "Luxsin Launches the All-New DMP-A8",
  "slug": "luxsin-dmp-a8-launch",
  "summary_zh": "旗舰数字流媒体播放器正式发布...",
  "summary_en": "The flagship digital media player is now available...",
  "cover_url": "/uploads/news/dmp-a8-launch.jpg",
  "content_zh": "<h2>产品亮点</h2><p>...</p>",
  "content_en": "<h2>Highlights</h2><p>...</p>",
  "status": "published",
  "published_at": "2026-07-30T10:00:00Z"
}
```

---

### 5.2 文章推荐

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/news/:id/recommendations` | 获取文章的推荐列表 |
| PUT | `/api/www/news/:id/recommendations` | 更新推荐文章（全量覆盖，最多 3 篇） |

**PUT Body：**

```json
{ "recommended_ids": [5, 12, 8] }
```

---

## 6. 素材库 `/api/www/media`

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/media?category=product&tag=DMP-A8` | 获取素材列表（分页/筛选/搜索） |
| POST | `/api/www/media/upload` | 上传素材（multipart/form-data） |
| POST | `/api/www/media/upload-batch` | 批量上传 |
| GET | `/api/www/media/:id` | 获取素材详情 |
| PUT | `/api/www/media/:id` | 更新素材信息（文件名/分类/标签） |
| DELETE | `/api/www/media/:id` | 软删除素材（检查引用计数） |

**GET Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| category | string | 分类筛选: product / banner / news / brand / video / document / other |
| tag | string | 按标签名筛选 |
| keyword | string | 按文件名模糊搜索 |
| file_type | string | 按类型筛选: image / video / file |

**GET 响应 data 每项：**

```json
{
  "id": 1,
  "filename": "dmp-a8-front.jpg",
  "file_path": "/uploads/images/products/2026/07/dmp-a8-front.jpg",
  "file_type": "image",
  "mime_type": "image/jpeg",
  "file_size": 245760,
  "width": 1200,
  "height": 900,
  "category": "product",
  "thumbnail_url": "/uploads/thumbnails/dmp-a8-front_thumb.jpg",
  "webp_url": "/uploads/thumbnails/dmp-a8-front.webp",
  "ref_count": 3,
  "tags": ["DMP-A8", "2026新品"],
  "created_at": "2026-07-30T10:00:00Z"
}
```

### 6.1 素材标签

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/media/tags` | 获取所有标签列表 |
| POST | `/api/www/media/tags` | 创建标签 |
| PUT | `/api/www/media/tags/:id` | 重命名标签 |
| DELETE | `/api/www/media/tags/:id` | 删除标签（自动解除关联） |

---

## 7. 翻译管理 `/api/www/i18n`

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/i18n?keyword=nav` | 获取词条列表（支持搜索） |
| PUT | `/api/www/i18n/:id` | 更新词条（仅改中文/英文值） |
| PUT | `/api/www/i18n/batch` | 批量更新词条 |

**GET Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| keyword | string | 按 key 或值模糊搜索 |

**PUT 单条 Body：**

```json
{
  "value_zh": "产品",
  "value_en": "Products"
}
```

**PUT 批量 Body：**

```json
[
  { "id": 1, "value_zh": "产品", "value_en": "Products" },
  { "id": 2, "value_zh": "新闻", "value_en": "News" }
]
```

---

## 8. 联系表单 `/api/www/contact`

### 8.1 表单全局配置

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/contact/settings` | 获取表单配置 |
| PUT | `/api/www/contact/settings` | 更新表单配置 |

### 8.2 表单字段

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/contact/fields` | 获取字段列表 |
| POST | `/api/www/contact/fields` | 新增字段 |
| PUT | `/api/www/contact/fields/:id` | 更新字段 |
| DELETE | `/api/www/contact/fields/:id` | 删除字段 |
| PATCH | `/api/www/contact/fields/sort` | 字段排序 |

**POST Body：**

```json
{
  "name_zh": "姓名",
  "name_en": "Name",
  "field_type": "text",
  "is_required": true,
  "placeholder_zh": "请输入您的姓名",
  "placeholder_en": "Your name",
  "options_json": null
}
```

### 8.3 提交记录

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/contact/submissions?is_read=0` | 获取提交记录列表 |
| GET | `/api/www/contact/submissions/:id` | 查看提交详情 |
| PATCH | `/api/www/contact/submissions/:id/read` | 标记为已读 |
| DELETE | `/api/www/contact/submissions/:id` | 删除提交记录 |

**GET Query 参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| is_read | 0/1 | 筛选已读/未读 |
| start_date | date | 开始日期 |
| end_date | date | 结束日期 |

---

## 9. 页面 SEO `/api/www/page-seo`

| Method | Path | 说明 |
|--------|------|------|
| GET | `/api/www/page-seo?page_type=home` | 获取页面 SEO 配置 |
| GET | `/api/www/page-seo?page_type=product_detail&entity_id=1` | 获取产品详情页 SEO |
| PUT | `/api/www/page-seo` | 创建/更新页面 SEO |

**PUT Body：**

```json
{
  "page_type": "product_detail",
  "entity_id": 1,
  "meta_title": "DMP-A8 - 旗舰数字流媒体播放器",
  "meta_description": "乐笙 DMP-A8 旗舰数字流媒体播放器，支持 PCM 768kHz...",
  "meta_keywords": "DMP-A8,流媒体,播放器,HiFi",
  "og_image_url": "/uploads/products/dmp-a8-og.jpg"
}
```

---

## 附录：接口总览

| # | 模块 | 接口数 | URL 前缀 |
|---|------|--------|---------|
| 1 | 全局配置 | 8 | `/api/www/global/` |
| 2 | 导航管理 | 7 | `/api/www/nav/` |
| 3 | Section 区块 | 18 | `/api/www/sections/` + `/api/www/spec-*` |
| 4 | 页面配置 | 8 | `/api/www/page/` |
| 5 | 产品管理 | 12 | `/api/www/products/` + `/api/www/product/series/` |
| 6 | 新闻管理 | 7 | `/api/www/news/` |
| 7 | 素材库 | 11 | `/api/www/media/` |
| 8 | 翻译管理 | 3 | `/api/www/i18n/` |
| 9 | 联系表单 | 9 | `/api/www/contact/` |
| 10 | 页面 SEO | 3 | `/api/www/page-seo/` |
| | **合计** | **86** | |