admin/docs/dashboard/www-cms-api.md

官网 CMS 后端接口文档

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

---

通用约定

响应格式

// 成功
{ "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）

分页响应

{ "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：

{
  "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：

{
  "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：

{
  "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：

[
  { "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：（全量覆盖）

[
  { "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：

{
  "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：

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

PATCH 排序 Body：

[{ "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：

{
  "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：

{
  "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）：

{
  "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：

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

POST 新增参数项 Body：

{
  "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：

{
  "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：

{
  "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：

{
  "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：

{ "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 每项：

{
  "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：

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

PUT 批量 Body：

[
  { "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：

{
  "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：

{
  "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