audio/admin
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e6da74cf01d47253db5b24b93ea1ebd592c61ca4
admin/docs/dashboard/www-cms-api.md
T

632 lines
16 KiB
Markdown
Raw Normal View History

官网内容管理-后端接口开发
2026-07-30 17:33:08 +08:00
# 官网 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** | |
Reference in New Issue Copy Permalink