Files
admin/docs/dashboard/www-cms-api.md
T
2026-08-13 14:23:01 +08:00

632 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 官网 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** | |