官网内容管理-后端接口开发

2026-07-30 17:33:08 +08:00
parent b1c88fc5e6
commit e71d18b331
34 changed files with 4246 additions and 0 deletions
@@ -0,0 +1,633 @@
+# 官网 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",
+  "overlay_enabled": true,
+  "overlay_opacity": 0.3,
+  "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** | |
@@ -0,0 +1,234 @@
+# 官网 CMS 侧边栏菜单设计
+
+> **版本**: v1.0  
+> **关联文档**: [proposal.md](../www/proposal.md)  
+> **目标**: 定义 Dashboard 侧边栏中「官网管理」模块的菜单结构、路由规划及页面职责
+
+---
+
+## 1. 现有菜单结构
+
+| order | 菜单 | 路由 | 说明 |
+|-------|------|------|------|
+| 1 | 首页 | `/home` | Dashboard 数据看板 |
+| 2 | 耳机 | `/headphone` | 品牌管理 / 型号管理 |
+| 3 | OTA 升级 | `/upgrade` | OTA / 目标设备 / 黑名单 |
+| 4 | 分享码 | `/share-code` | 分享码日志 |
+| 5 | 系统 | `/system` | 用户管理（隐藏，仅超管） |
+| 6 | 工具箱 | `/toolbox` | Luxsin Controller |
+
+---
+
+## 2. 新增「官网管理」菜单
+
+在现有菜单之后新增一个顶级分组 **「官网管理」**，包含以下子菜单：
+
+```
+官网管理 (www)
+├── 全局配置 (global)
+│   ├── 站点信息 (basic)
+│   ├── 页脚配置 (footer)
+│   ├── 社交链接 (social)
+│   └── SEO 默认值 (seo)
+├── 导航管理 (nav)
+│   ├── 导航入口 (items)
+│   └── 导航外观 (appearance)
+├── 页面管理 (page)
+│   ├── 首页区块 (home)
+│   ├── 产品列表页 (product-list)
+│   ├── 新闻列表页 (news-list)
+│   ├── 关于我们 (about)
+│   └── 技术支持 (support)
+├── 产品管理 (product)
+│   ├── 产品系列 (series)
+│   └── 产品列表 (list)
+├── 新闻管理 (news)
+│   └── 新闻文章 (articles)
+├── 素材库 (media)
+├── 翻译管理 (i18n)
+├── 联系表单 (contact)
+│   ├── 表单配置 (settings)
+│   └── 提交记录 (submissions)
+└── 页面 SEO (page-seo)
+```
+
+---
+
+## 3. 路由与菜单详细定义
+
+### 3.1 路由命名规范
+
+- 顶级分组: `www`
+- 子菜单: `www_{module}` 格式，用 `_` 分隔层级
+- 路由路径: `/www/{module}` 或 `/www/{module}/{sub}`
+- i18n Key: `route.www_{name}`
+
+### 3.2 完整路由表
+
+| route name | path | icon | order | keepAlive | 说明 |
+|---|---|---|---|---|---|
+| **www** | `/www` | `mdi:globe-model` | 7 | — | 顶级分组 |
+| www_global | `/www/global` | `mdi:application-cog-outline` | 1 | — | 全局配置（分组） |
+| www_global_basic | `/www/global/basic` | `mdi:information-outline` | 1 | ✓ | 站点标题 / Favicon / Logo |
+| www_global_footer | `/www/global/footer` | `mdi:page-layout-footer` | 2 | ✓ | 公司名称 / 地址 / 备案信息 |
+| www_global_social | `/www/global/social` | `mdi:share-variant-outline` | 3 | ✓ | 微信 / 微博 / B站 / YouTube 等 |
+| www_global_seo | `/www/global/seo` | `mdi:magnify` | 4 | ✓ | 全站默认 Meta / OG 图片 |
+| www_nav | `/www/nav` | `mdi:menu` | 2 | — | 导航管理（分组） |
+| www_nav_items | `/www/nav/items` | `mdi:format-list-bulleted` | 1 | ✓ | 入口增删排序 / 显示形式 |
+| www_nav_appearance | `/www/nav/appearance` | `mdi:palette-outline` | 2 | ✓ | 首页/非首页导航风格 |
+| www_page | `/www/page` | `mdi:file-document-outline` | 3 | — | 页面管理（分组） |
+| www_page_home | `/www/page/home` | `mdi:home-outline` | 1 | ✓ | 首页 Section 区块配置 |
+| www_page_product-list | `/www/page/product-list` | `mdi:format-list-bulleted-square` | 2 | ✓ | 产品列表 Page Hero / 列数 |
+| www_page_news-list | `/www/page/news-list` | `mdi:newspaper-variant-outline` | 3 | ✓ | 新闻列表 Page Hero / 分页 |
+| www_page_about | `/www/page/about` | `mdi:account-group-outline` | 4 | ✓ | 关于我们文本/图片/CTA |
+| www_page_support | `/www/page/support` | `mdi:lifebuoy` | 5 | ✓ | 技术支持 FAQ/下载/联系 |
+| www_product | `/www/product` | `mdi:package-variant-closed` | 4 | — | 产品管理（分组） |
+| www_product_series | `/www/product/series` | `mdi:layers-outline` | 1 | ✓ | 产品系列 CRUD |
+| www_product_list | `/www/product/list` | `mdi:view-list-outline` | 2 | ✓ | 产品 CRUD + Section + 参数规格 |
+| www_news | `/www/news` | `mdi:newspaper-variant-multiple-outline` | 5 | — | 新闻管理（分组） |
+| www_news_articles | `/www/news/articles` | `mdi:article-outline` | 1 | ✓ | 新闻文章 CRUD |
+| www_media | `/www/media` | `mdi:image-multiple-outline` | 6 | ✓ | 素材库（独立页面） |
+| www_i18n | `/www/i18n` | `mdi:translate` | 7 | ✓ | 翻译词条管理（独立页面） |
+| www_contact | `/www/contact` | `mdi:email-outline` | 8 | — | 联系表单（分组） |
+| www_contact_settings | `/www/contact/settings` | `mdi:form-textbox` | 1 | ✓ | 表单字段/全局配置 |
+| www_contact_submissions | `/www/contact/submissions` | `mdi:inbox-outline` | 2 | ✓ | 提交记录列表 |
+| www_page-seo | `/www/page-seo` | `mdi:search-web` | 9 | ✓ | 页面级 SEO 覆盖（独立页面） |
+
+---
+
+## 4. 页面职责说明
+
+### 4.1 全局配置
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 站点信息 | §1.1 | `www_site_settings` | 单表单（直接编辑保存） |
+| 页脚配置 | §1.2 | `www_footer_settings` | 单表单 |
+| 社交链接 | §1.3 | `www_social_links` | 列表（增删改排序） |
+| SEO 默认值 | §1.4 | `www_seo_defaults` | 单表单 |
+
+### 4.2 导航管理
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 导航入口 | §2.1 | `www_nav_items` | 列表（拖拽排序/增删改） |
+| 导航外观 | §2.3 | `www_nav_appearance` | 单表单 |
+
+### 4.3 页面管理
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 首页区块 | §3.1 | `www_section_blocks` (page_type=homepage) | Section 编辑器（拖拽排序/增删/配置面板） |
+| 产品列表页 | §3.3 | `www_product_list_settings` | 单表单 |
+| 新闻列表页 | §3.4 | `www_news_list_settings` | 单表单 |
+| 关于我们 | §3.6 | `www_about_settings` | 单表单（多 Section 展开编辑） |
+| 技术支持 | §3.7 | `www_support_settings` | 单表单（多 Section 展开编辑） |
+
+### 4.4 产品管理
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 产品系列 | §4.1 | `www_product_series` | 列表 CRUD |
+| 产品列表 | §4.2 §4.3 | `www_products` + `www_section_blocks` + `www_spec_groups` + `www_spec_items` | 列表 CRUD → 详情页编辑（Section + 参数规格） |
+
+### 4.5 新闻管理
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 新闻文章 | §5.1 §5.2 | `www_news_articles` + `www_news_recommendations` | 列表 CRUD + 富文本编辑器 |
+
+### 4.6 素材库
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 素材库 | §6 | `www_media` + `www_media_tags` + `www_media_tag_map` | 文件管理（上传/分类/标签/搜索/预览） |
+
+### 4.7 翻译管理
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 翻译词条 | §8.3 | `www_i18n_entries` | 列表（搜索/筛选/编辑） |
+
+### 4.8 联系表单
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 表单配置 | §9.1 §9.2 | `www_form_settings` + `www_form_fields` | 单表单 + 字段列表（拖拽排序） |
+| 提交记录 | §9 | `www_form_submissions` | 列表（查看/标记已读/删除） |
+
+### 4.9 页面 SEO
+
+| 子页面 | 对应 proposal | 对应表 | 页面类型 |
+|--------|-------------|--------|---------|
+| 页面 SEO | §7.1 | `www_page_seo` | 列表（按页面类型筛选/编辑） |
+
+---
+
+## 5. 优先级与开发顺序
+
+### P0 - 核心功能（一期必须）
+
+| 序号 | 菜单 | 理由 |
+|------|------|------|
+| 1 | 产品系列 + 产品列表 | 官网核心内容，其他页面依赖产品数据 |
+| 2 | 首页区块 | 官网首屏，营销关键页面 |
+| 3 | 全局配置 | 站点基础信息，所有页面依赖 |
+| 4 | 导航管理 | 站点导航骨架 |
+| 5 | 素材库 | 图片和文件管理，所有页面依赖 |
+| 6 | 翻译管理 | 双语支持基础 |
+
+### P1 - 重要功能（一期完整）
+
+| 序号 | 菜单 | 理由 |
+|------|------|------|
+| 7 | 新闻文章 | 内容营销 |
+| 8 | 产品列表页 / 新闻列表页 | 列表展示配置 |
+| 9 | 关于我们 / 技术支持 | 品牌展示页面 |
+| 10 | 页面 SEO | 搜索引擎优化 |
+
+### P2 - 次要功能（可后置）
+
+| 序号 | 菜单 | 理由 |
+|------|------|------|
+| 11 | 联系表单 | 用户互动，优先级较低 |
+
+---
+
+## 6. 完整侧边栏菜单（最终视图）
+
+```
+📊 首页                    /home
+🎧 耳机                    /headphone
+📦 OTA 升级               /upgrade
+🔗 分享码                  /share-code
+─────────────────────────────
+🌐 官网管理                /www
+  📋 全局配置              /www/global
+    · 站点信息             /www/global/basic
+    · 页脚配置             /www/global/footer
+    · 社交链接             /www/global/social
+    · SEO 默认值           /www/global/seo
+  📍 导航管理              /www/nav
+    · 导航入口             /www/nav/items
+    · 导航外观             /www/nav/appearance
+  📄 页面管理              /www/page
+    · 首页区块             /www/page/home
+    · 产品列表页           /www/page/product-list
+    · 新闻列表页           /www/page/news-list
+    · 关于我们             /www/page/about
+    · 技术支持             /www/page/support
+  📦 产品管理              /www/product
+    · 产品系列             /www/product/series
+    · 产品列表             /www/product/list
+  📰 新闻管理              /www/news
+    · 新闻文章             /www/news/articles
+  🖼️ 素材库               /www/media
+  🌍 翻译管理              /www/i18n
+  ✉️ 联系表单              /www/contact
+    · 表单配置             /www/contact/settings
+    · 提交记录             /www/contact/submissions
+  🔍 页面 SEO             /www/page-seo
+─────────────────────────────
+⚙️ 系统                    /system（隐藏）
+🧰 工具箱                  /toolbox
+```