饶有趣管理端前端详细开发需求文档

1. 文档目的

本文档用于定义“饶有趣”项目管理端前端的详细开发需求。管理端的核心目标不是单纯做后台列表，而是：

让管理员进入后台后，可以直接看到当前小程序前端正在展示的内容。
按模块对前端展示内容进行增删改查。
在修改、删除、发布、下架等关键操作时，必须弹出确认窗口。
在添加或修改图片、视频、图文详情、商品详情时，支持本地上传、即时预览、保存前预览、发布后前端效果预览。
尤其在商品新增和商品详情页编辑时，要做到“操作简单、字段详细、结构清晰、预览直观”。

本文档结合以下现状整理：

小程序前端：miniapp-taro/
小程序接口：backend/raoyouqu/routes_api.py
管理端接口：backend/raoyouqu/routes_admin.py
数据模型：backend/raoyouqu/models.py

2. 项目背景与现状

2.1 当前小程序前端展示结构

当前小程序前端基于 Taro + React，首页和内容区主要包括以下模块：

首页
- 顶部品牌文案
- 首页介绍区三种内容切换：视频 / PPT / 图文
- 快捷入口
- 精选推荐
- 项目亮点
饶平文创
- 商品分类列表
- 全部 / 礼盒定制 / 联农助农 / 扶残助残
- 商品详情页
- 扶残助残专区中还包含：
  - 茶染任务
  - 匠心手作
  - 色卡工具
玩转饶平
- 深圳体验
- 饶平体验
- 体验详情页
认识饶平
- 宣传视频封面区
- 文化图文介绍列表
- 图文详情页
公益任务相关
- 任务展示列表
- 任务详情
- 用户接取和提交作品后的后台审核
色卡工具
- 颜色维度选项
- 预设效果图

2.2 当前后端已具备的管理接口能力

当前后端已提供较完整的管理端接口，支持以下内容管理：

管理员登录
- POST /admin/auth/login
仪表盘统计
- GET /admin/dashboard/summary
首页内容管理
- 首页视频：/admin/home/videos
- 首页 PPT：/admin/home/ppts
- 首页图文：/admin/home/intro-text
- 精选推荐：/admin/home/banners
- 项目亮点：/admin/home/highlights
媒体上传与媒体库
- 上传：POST /admin/upload
- 文件列表：GET /admin/uploads
商品管理
- 商品列表、详情、新增、修改、删除：/admin/products
认识饶平
- 宣传区：/admin/culture/promo
- 图文文章：/admin/culture/articles
玩转饶平
- 体验项目：/admin/experiences
扶残助残任务
- 任务展示：/admin/task-showcases
- 用户任务审核：/admin/user-tasks
色卡工具
- 维度选项：/admin/color-card/options
- 预设图片：/admin/color-card/presets
用户提交内容监控

DIY 记录：/admin/user-diy-records

站点配置

GET/PATCH /admin/site-config

2.3 当前需求的本质

本次要开发的不是“传统后台表格管理页面”，而是“可视化内容运营后台”，即：

左侧是模块菜单；
中间是当前内容列表和编辑入口；
右侧或弹窗中可以实时预览前端展示效果；
管理员能够像维护 CMS 一样维护小程序内容；
删除、修改、发布前必须确认；
上传本地图片和视频时要立即看到预览效果；
商品详情页的编辑不能只给一个 HTML 大文本框，而要尽量拆成可理解的结构化字段。

3. 管理端总体目标

3.1 核心目标

管理端前端应满足以下目标：

可视化
- 管理员进入后台后，优先看到“当前前端展示内容”，而不是只看到数据表。
模块化
- 首页、商品、体验、文化图文、任务、色卡、媒体库、用户提交内容等必须独立成模块。
全量 CRUD
- 对前端展示内容支持新增、编辑、删除、查看、排序、启用/停用或发布/下架。
所见即所得预览
- 添加、编辑时必须支持预览。
- 预览样式尽量接近小程序真实展示效果。
安全操作
- 删除、修改、发布、下架必须二次确认。
简单但详细
- 表单不能过度复杂，但关键字段必须明确，尤其商品详情页编辑必须拆细。
数据可观测
- 管理端必须能查看前端的点击量、浏览量、访问趋势和热点内容数据。

4. 管理端信息架构

建议管理端前端采用以下一级菜单结构：

登录
工作台
数据分析
前端预览中心
首页管理
商品管理
认识饶平
玩转饶平
扶残助残
色卡工具
媒体库
用户内容审核
站点配置

4.1 登录页

功能要求：

使用管理员账号密码登录。
调用 POST /admin/auth/login。
登录成功后保存管理员 token。
后续所有管理接口统一带管理员 token。
未登录时禁止访问后台页面。

字段：

用户名
密码

交互：

登录中按钮禁用
登录失败显示明确错误提示
登录成功跳转工作台

4.2 工作台

功能要求：

展示管理端首页概览。
调用 GET /admin/dashboard/summary。
显示：
- 总用户数
- 今日新增用户
- 今日 PV
- 今日 UV
- 商品“我想要”点击总数
- 色卡工具使用总数
以概览卡片形式展示前端核心运营数据：
- 首页浏览量
- 商品浏览量
- 文化内容浏览量
- 体验项目浏览量
- 任务浏览量
- 近 7 天访问趋势
- 近 7 天点击趋势

扩展要求：

可增加“最近更新内容”区域。
可增加“待审核用户任务”快捷入口。
可增加“热门内容 Top 榜”快捷入口。

4.3 数据分析

这是新增的一级功能模块，用于查看前端的点击量和浏览数据。

功能目标：

让管理员知道当前哪些页面、模块、内容被看得多。
让管理员知道哪些按钮、商品、任务、文章被点击得多。
为首页运营、商品运营、内容运营提供数据依据。

建议拆分为四个分析子页面：

总览分析
页面浏览分析
内容点击分析
热门内容排行

4.3.1 总览分析

应展示的核心指标：

总浏览量 PV
总访客数 UV
首页浏览量
商品详情浏览量
文章详情浏览量
体验详情浏览量
任务详情浏览量
商品“我想要”点击量
色卡工具使用量

图表要求：

最近 7 天趋势图
最近 30 天趋势图
可切换日期范围

4.3.2 页面浏览分析

页面维度至少包括：

首页
饶平文创页
商品详情页
玩转饶平列表页
体验详情页
认识饶平页
文化图文详情页
任务列表页
任务详情页
色卡工具页

列表字段建议：

页面名称
页面路径
浏览量 PV
访客数 UV
平均停留时长
最近访问时间

4.3.3 内容点击分析

内容维度至少包括：

首页精选推荐点击量
首页项目亮点点击量
商品卡片点击量
商品详情“我想要”点击量
文化文章点击量
体验项目点击量
茶染任务点击量
快捷入口点击量

列表字段建议：

内容类型
内容名称
所属模块
点击量
点击人数
最近点击时间

4.3.4 热门内容排行

应支持按以下维度查看 Top 排行：

浏览量 Top 10
点击量 Top 10
商品热度 Top 10
文章热度 Top 10
体验热度 Top 10
任务热度 Top 10

交互要求：

支持时间范围筛选
支持按模块筛选
支持跳转到对应内容的编辑页

4.3.5 数据筛选要求

分析页面应至少支持以下筛选条件：

今日
近 7 天
近 30 天
自定义时间范围
内容模块
事件类型

4.3.6 数据展示要求

数据分析模块应同时支持两种展示方式：

指标卡片
图表 + 表格

图表建议：

折线图：趋势
柱状图：模块对比
排行表：热点内容

4.4 前端预览中心

这是本项目最重要的页面之一。

功能要求：

管理员进入后台后，可以直观看到目前前端在展示什么。
预览中心应按小程序结构展示：
- 首页
- 饶平文创
- 玩转饶平
- 认识饶平
- 扶残助残
每个模块中的内容卡片右上角应直接提供操作入口：
- 删除
- 修改
- 新增
点击删除必须弹出确认框。
点击修改必须弹出编辑框或抽屉。
点击新增必须弹出新增框。
预览中心中的卡片样式尽量贴近小程序页面，减少管理员理解成本。

建议布局：

左侧：模块导航
中间：当前模块真实内容预览
右侧：操作面板或详情预览

5. 模块级详细需求

5.1 首页管理

首页管理要拆成五个子模块：

首页视频
首页 PPT
首页图文介绍
精选推荐
项目亮点

5.1.1 首页视频管理

对应接口：

GET /admin/home/videos
POST /admin/home/videos
PATCH /admin/home/videos/:id
DELETE /admin/home/videos/:id
上传：POST /admin/upload

管理需求：

以卡片列表形式展示当前首页视频内容。
每张卡片展示：
- 视频封面
- 标题
- 排序值
- 是否启用
卡片右上角展示操作按钮：
- 修改
- 删除
页面顶部提供“新增视频”按钮。
支持本地上传视频文件和封面图片。
上传后立即预览视频封面与视频地址。
可调整排序值。
可启用/停用。

新增/编辑表单字段：

标题
视频文件上传
视频 URL
封面图片上传
封面 URL
排序值
是否启用

预览要求：

弹窗右侧显示与小程序首页视频区相似的预览。
可播放预览视频或至少看到封面。

确认要求：

点击“保存修改”前弹出确认框：确认修改该视频内容吗？
点击“删除”前弹出确认框：确认删除该视频吗？删除后前端将不再展示。

5.1.2 首页 PPT 管理

对应接口：

GET /admin/home/ppts
POST /admin/home/ppts
PATCH /admin/home/ppts/:id
DELETE /admin/home/ppts/:id

管理需求：

以轮播卡片列表形式展示当前 PPT 图片。
每项显示：
- 缩略图
- 标题
- 排序
- 是否启用
支持新增、编辑、删除。
支持本地上传图片并立即预览。
管理端预览区域可模拟小程序的 Swiper 效果。

新增/编辑字段：

标题
PPT 图片上传
图片 URL
排序值
是否启用

确认要求：

修改前确认
删除前确认

5.1.3 首页图文介绍管理

对应接口：

GET /admin/home/intro-text
POST /admin/home/intro-text

管理需求：

这是首页介绍区中的“图文”内容。
应提供富文本编辑能力。
管理员可直接输入文字、段落、标题、图片、换行等内容。
编辑后右侧实时预览 RichText 展示效果。
保存前弹出确认框。

字段：

HTML 内容

编辑器要求：

支持基础富文本能力：
- 标题
- 正文
- 加粗
- 段落
- 图片插入
- 列表
- 分隔线
若不做完整富文本编辑器，也至少应提供：
- 文本输入区域
- HTML 预览区域

5.1.4 精选推荐管理

对应接口：

GET /admin/home/banners
POST /admin/home/banners
PATCH /admin/home/banners/:id
DELETE /admin/home/banners/:id

前端展示对应：

首页“精选推荐”网格卡片
点击后可能跳详情，也可能跳小程序页面

管理需求：

列表中直接显示当前推荐卡片。
每项显示：
- 图片
- 标题
- 跳转类型
- 跳转值
- 是否有详情
- 排序
- 是否启用
管理员可以：
- 新增推荐
- 修改推荐
- 删除推荐
- 预览点击后的样式

新增/编辑字段：

标题
推荐图片上传
图片 URL
详情内容 detail_html
跳转类型 link_type
跳转值 link_value
排序值
是否启用

跳转类型要求：

无跳转
小程序页面跳转
前端指定模块跳转
详情页展示

预览要求：

卡片预览
如有详情，支持预览详情页内容

5.1.5 项目亮点管理

对应接口：

GET /admin/home/highlights
POST /admin/home/highlights
PATCH /admin/home/highlights/:id
DELETE /admin/home/highlights/:id

管理需求：

展示当前项目亮点卡片。
每项显示：
- 图标
- 标题
- 摘要
- 排序
- 是否启用
支持新增、修改、删除、预览详情页。

新增/编辑字段：

图标
标题
摘要
详情富文本
排序值
是否启用

5.2 商品管理

商品管理是本项目重点模块，必须支持“列表预览 + 简单但详细的商品编辑 + 商品详情页可视化预览”。

对应接口：

GET /admin/products
POST /admin/products
GET /admin/products/:id
PATCH /admin/products/:id
DELETE /admin/products/:id
上传：POST /admin/upload

5.2.1 商品管理页面结构

商品管理建议拆成以下页面或区域：

商品列表页
商品新增页
商品编辑页
商品详情预览页

5.2.2 商品列表页要求

列表展示字段：

商品封面
商品名称
商品类型 product_type
列表分类 list_category
一级分类 primary_category
状态 status
排序值
创建时间

筛选条件：

商品类型
列表分类
状态
关键词搜索

操作按钮：

查看
修改
删除
预览前端详情页
新增商品

交互要求：

删除前必须弹出确认框。
修改保存前必须弹出确认框。
支持从列表直接进入预览。

5.2.3 商品新增/编辑核心原则

商品新增与编辑必须做到：

表单简单
- 不要求管理员理解数据库结构。
字段详细
- 能完整描述一个商品的前端展示内容。
分区清晰
- 不把所有字段堆在一个弹窗里。
立即预览
- 每编辑一个主要字段，都能在右侧看到前端样式变化。
支持本地上传
- 封面图、图集、工序图、二维码均支持本地选择并上传。

5.2.4 商品新增/编辑表单设计

建议采用“抽屉 + 分区折叠”或“多分栏”方式，而不是一个超长纯表单。

建议分为 6 个编辑分区：

基础信息
列表展示设置
详情主体内容
图集管理
工序图示管理
发布设置与预览

A. 基础信息

字段：

商品名称 name
商品简介 summary
出品方 producer
产地 origin
商品类型 product_type
- 礼盒
- 助农
- 匠心

说明：

商品简介用于列表卡片和详情页顶部简介。
商品名称和简介必须在右侧同步更新预览。

B. 列表展示设置

字段：

列表分类 list_category
- all 为前端聚合概念，不作为保存值
- 可选值应至少覆盖：
  - brand
  - farm
  - assist
  - handmade
一级分类 primary_category
商品封面图
排序值 sort_order
状态 status
- published
- draft
- archived

说明：

封面图用于商品列表和详情页默认首图。
应支持本地上传后立即显示缩略图。
handmade 需明确支持，用于“匠心手作”独立页面。

C. 详情主体内容

字段：

制作流程文本 process_text
图文详解 detail_html
我想要二维码 qr_code_url

说明：

process_text 用于前端切分成流程标签，建议后台编辑时按“步骤1 -> 步骤2 -> 步骤3”格式输入。
detail_html 不建议只给一个原始 HTML 文本框，建议提供图文编辑器。
二维码支持本地上传和图片预览。

D. 图集管理

字段结构：

图集数组 gallery
- 图片 URL
- 排序值

交互要求：

可添加多张图。
每张图支持：
- 本地上传
- 删除
- 调整顺序
- 预览
至少应支持拖拽排序或上移下移。
若未配置图集，前端默认使用封面图。

E. 工序图示管理

字段结构：

工序步骤数组 flow_steps
- 步骤序号 step_order
- 工序图片 image_url
- 文案说明 caption

交互要求：

可新增多个工序步骤。
每个步骤都应有独立卡片。
每个步骤卡片包含：
- 序号
- 上传图片
- 说明文字
- 删除按钮
支持预览当前工序图在前端详情页中的显示样式。

F. 发布设置与预览

字段：

状态
保存
保存并发布
取消

功能要求：

编辑区右侧固定显示“前端效果预览”。
预览内容尽量贴近 miniapp-taro/src/pages/product/detail.tsx 的实际结构：
- 轮播图
- 商品标题
- 简介
- 产地溯源
- 出品方
- 制作流程标签
- 工序图示
- 图文详解
- “我想要”按钮和二维码展示逻辑

5.2.5 商品模块重点交互

必须实现：

点击“新增商品”
- 弹出商品编辑框
- 默认空白表单
- 右侧显示空白预览模板
点击“修改”
- 弹出商品编辑框
- 自动带出现有数据
- 右侧显示当前商品预览
点击“删除”
- 弹出确认框
- 文案建议：确认删除该商品吗？删除后前端列表与详情页将不可访问。
点击“保存修改”
- 弹出确认框
- 文案建议：确认保存对该商品的修改吗？
点击“保存并发布”
- 弹出确认框
- 文案建议：确认发布该商品吗？发布后将显示在小程序前端。

5.2.6 商品模块特别要求

这是本次需求中的重点：

商品详细页面的新增和修改必须“简单详细”。
后台不能只让管理员填一个富文本然后猜前端效果。
管理员必须能很清楚地知道：
- 哪个字段显示在列表卡片
- 哪个字段显示在详情顶部
- 哪个字段显示在流程标签
- 哪个字段显示在工序图示
- 哪个字段显示在图文详解
商品编辑页面应在字段旁给出简要说明文案。

5.3 认识饶平管理

5.3.1 宣传视频区管理

对应接口：

GET /admin/culture/promo
PATCH /admin/culture/promo

展示内容：

标题
副标题
封面图
视频地址

功能要求：

编辑后实时预览宣传区卡片效果。
支持本地上传封面图和视频。
保存前确认。

5.3.2 文化图文文章管理

对应接口：

GET /admin/culture/articles
POST /admin/culture/articles
GET /admin/culture/articles/:id
PATCH /admin/culture/articles/:id
DELETE /admin/culture/articles/:id

列表字段：

封面图
标题
分类
摘要
列表编号 list_no
排序值
状态

新增/编辑字段：

分类
标题
封面图
摘要
正文图文内容 body_html
列表编号
排序值
状态

交互要求：

支持文章卡片预览
支持详情页预览
删除、修改、发布前确认

5.4 玩转饶平管理

对应接口：

GET /admin/experiences
POST /admin/experiences
GET /admin/experiences/:id
PATCH /admin/experiences/:id
DELETE /admin/experiences/:id

5.4.1 体验项目列表要求

列表字段：

封面图
名称
地区 region
地点
时长说明
标签文案 badge
状态
排序值

筛选条件：

地区
状态

5.4.2 新增/编辑字段

地区
名称
封面图
地点
时间说明
时长说明
徽标文案
徽标颜色
简介
体验流程 flow_text
非遗价值 value_text
注意事项富文本 notice_html
排序值
状态

预览要求：

列表卡片预览
详情页预览

确认要求：

修改、删除、发布前确认

5.4.3 体验 DIY 扩展需求

当前后端详情接口已返回 diy_schemas，但管理端缺少独立的 schema/choice CRUD 接口。

因此若要实现“体验 DIY 配置项后台可管理”，应补充接口需求：

新增 DIY 分组
修改 DIY 分组
删除 DIY 分组
新增分组选项
修改分组选项
删除分组选项
调整排序

该部分应列为二期或接口补充项。

5.5 扶残助残管理

扶残助残模块应包含三个管理子模块：

茶染任务
匠心手作商品入口
色卡工具配置

5.5.1 茶染任务管理

对应接口：

GET /admin/task-showcases
POST /admin/task-showcases
GET /admin/task-showcases/:id
PATCH /admin/task-showcases/:id
DELETE /admin/task-showcases/:id

列表展示字段：

封面图
任务名称
分类
难度
截止说明
状态标签
排序
是否启用

新增/编辑字段：

名称
分类
封面图
难度
截止说明
状态标签
描述
要求
流程文案
材料说明
参考图
排序值
是否启用

预览要求：

列表卡片预览
任务详情页预览

5.5.2 匠心手作管理

前端“匠心手作”实质使用商品数据，且通过 list_category=handmade 展示。

因此后台要求如下：

商品管理中必须支持 handmade 分类。
在扶残助残模块中应提供“匠心手作快捷入口”，跳转到商品管理并自动筛选 list_category=handmade。
在预览中心中应能看到“匠心手作页面”的真实展示效果。

5.5.3 色卡工具管理

对应接口：

GET /admin/color-card/options
POST /admin/color-card/options
PATCH /admin/color-card/options/:id
DELETE /admin/color-card/options/:id
GET /admin/color-card/presets
POST /admin/color-card/presets
PATCH /admin/color-card/presets/:id
DELETE /admin/color-card/presets/:id

管理需求：

维度管理
- 展示布料、纹样、媒染剂、时长等维度下的选项
- 支持新增选项、修改选项、删除选项
预设图管理
- 针对四维组合维护效果图
- 支持本地上传图片并预览
组合配置要求
- 管理端应提供下拉选择器选择四个 option
- 可上传对应效果图
- 可查看现有组合是否已存在

5.6 媒体库管理

对应接口：

POST /admin/upload
GET /admin/uploads

功能要求：

统一管理所有已上传图片和视频。
可按以下条件筛选：
- 文件类型
- 关键字
- 扩展名
列表展示：
- 缩略图或视频标识
- 文件名
- URL
- 文件类型
- 大小
- 更新时间
在业务模块中上传文件时，应支持：
- 直接从本地上传
- 或从媒体库选择已有资源
图片和视频都应支持预览。

扩展建议：

当前后端没有媒体删除接口，如需要管理端删除历史文件，应补充后端接口。

5.7 用户内容审核

5.7.1 用户任务审核

对应接口：

GET /admin/user-tasks
PATCH /admin/user-tasks/:id

功能要求：

展示用户提交的任务作品。
列表字段：
- 用户信息
- 任务信息
- 当前状态
- 提交图片
- 提交说明
- 接取时间
- 提交时间
- 完成时间
审核操作：
- 标记完成
- 修改状态
操作前弹出确认框。

5.7.2 用户 DIY 记录查看

对应接口：

GET /admin/user-diy-records

功能要求：

查看用户保存的色卡或 DIY 记录。
支持按来源筛选。
支持查看预览图。

5.8 数据分析

数据分析模块用于满足“管理端可以看到前端的点击量和浏览数据”这一需求。

5.8.1 现阶段已具备的接口基础

当前后端已具备以下分析相关能力：

仪表盘概览：GET /admin/dashboard/summary
原始埋点事件查询：GET /admin/analytics/events
前端上报埋点：POST /api/v1/analytics/events
商品“我想要”点击已单独计入 want_click

说明：

当前后端适合先做“基础数据看板”和“原始事件查询”。
如果要做更完整的模块级分析和排行榜，建议补充聚合分析接口。

5.8.2 管理端分析页面需求

应新增“数据分析”一级菜单，至少包含以下页面：

数据总览
页面浏览分析
点击行为分析
热门内容排行
原始埋点记录

5.8.3 数据总览

显示字段：

总 PV
总 UV
今日 PV
今日 UV
商品“我想要”点击总数
色卡工具使用总数
各模块浏览量占比
各模块点击量占比

图表要求：

最近 7 天 PV/UV 趋势
最近 7 天点击趋势
模块访问占比图

5.8.4 页面浏览分析

管理端应能查看页面级浏览数据。

页面维度建议包括：

首页
商品列表页
商品详情页
文化文章详情页
体验详情页
任务详情页
色卡工具页

字段要求：

页面名称
页面路径
PV
UV
平均停留时长
最近访问时间

5.8.5 点击行为分析

管理端应能查看内容级点击数据。

分析对象至少包括：

首页 banner 点击
首页项目亮点点击
商品卡片点击
商品“我想要”点击
文章点击
体验点击
任务点击
快捷入口点击

字段要求：

内容名称
内容类型
所属模块
点击量
点击用户数
最近点击时间

5.8.6 热门内容排行

排行榜应支持：

按浏览量排行
按点击量排行
按时间范围排行
按模块排行

每条排行数据应支持：

查看详情
跳转对应编辑页
在预览中心定位该内容

5.8.7 原始埋点记录

原始事件页用于排查数据问题与验证埋点是否正常。

对应接口：

GET /admin/analytics/events

列表字段建议：

事件类型 event_type
页面路径 page_path
目标类型 target_type
目标 ID target_id
用户 ID
扩展信息 meta_json
创建时间

筛选条件：

事件类型
时间范围
页面路径
目标类型

5.8.8 与各业务模块联动要求

各内容管理模块中，应补充显示“当前内容数据表现”，至少包括：

首页 banner / 项目亮点
- 展示点击量
- 展示最近 7 天点击趋势
商品
- 展示详情页浏览量
- 展示“我想要”点击量
- 展示最近 7 天趋势
文化文章
- 展示详情浏览量
- 展示点击趋势
体验项目
- 展示详情浏览量
- 展示点击趋势
茶染任务
- 展示详情浏览量
- 展示点击或接取量

说明：

若某项数据暂时没有后端聚合接口，可先展示“原始事件计数”或在需求中标注待补接口。

5.9 站点配置

对应接口：

GET /admin/site-config
PATCH /admin/site-config

管理需求：

管理默认配置项。
至少支持：
- 默认“我想要”二维码
- 其他基础配置

交互要求：

配置修改前确认
保存成功提示

6. 通用交互规范

6.1 删除确认

凡是删除操作，必须弹出确认窗口。

统一要求：

标题：删除确认
内容：明确说明删除后前端会发生什么变化
按钮：
- 取消
- 确认删除

示例：

删除 PPT：确认删除该 PPT 吗？删除后首页轮播将不再展示。
删除商品：确认删除该商品吗？删除后前端列表与详情页将不可访问。

6.2 修改确认

凡是重要修改，保存前必须弹出确认窗口。

统一要求：

标题：保存确认
内容：确认保存本次修改吗？
按钮：
- 继续编辑
- 确认保存

6.3 发布确认

凡是发布、启用、上架操作，必须弹出确认窗口。

统一要求：

标题：发布确认
内容：确认发布后，小程序前端将显示最新内容。是否继续？

6.4 预览要求

所有内容模块都应具备至少一种预览方式：

卡片预览
详情页预览
富文本预览
视频/图片预览

优先要求：

编辑时右侧实时预览
保存前支持完整预览

6.5 上传要求

上传图片或视频时必须满足：

支持本地选择文件
上传中显示进度或 loading
上传成功后自动回填 URL
上传成功后立即预览
上传失败给出明确提示

7. 前端页面与组件开发建议

7.1 页面建议

建议至少包含以下页面：

登录页
工作台
前端预览中心
首页管理
商品管理
商品编辑页
文化内容管理
体验项目管理
任务管理
色卡管理
媒体库
用户任务审核
用户 DIY 记录查看
数据分析页
站点配置

7.2 通用组件建议

建议抽离以下通用组件：

确认弹窗组件
图片上传组件
视频上传组件
富文本编辑组件
前端效果预览组件
可排序图片列表组件
工序步骤编辑组件
表单分组折叠面板组件
数据指标卡组件
趋势图表组件
热门排行表组件

7.3 商品编辑专用组件

商品模块建议单独抽离：

商品基础信息表单
商品图集编辑器
商品工序编辑器
商品富文本详情编辑器
商品详情预览面板

8. 接口映射表

8.1 认证

8.2 首页

视频列表：GET /admin/home/videos
新增视频：POST /admin/home/videos
修改视频：PATCH /admin/home/videos/:id
删除视频：DELETE /admin/home/videos/:id
PPT 列表：GET /admin/home/ppts
新增 PPT：POST /admin/home/ppts
修改 PPT：PATCH /admin/home/ppts/:id
删除 PPT：DELETE /admin/home/ppts/:id
首页图文：GET /admin/home/intro-text
保存首页图文：POST /admin/home/intro-text
精选推荐列表：GET /admin/home/banners
新增精选推荐：POST /admin/home/banners
修改精选推荐：PATCH /admin/home/banners/:id
删除精选推荐：DELETE /admin/home/banners/:id
项目亮点列表：GET /admin/home/highlights
新增项目亮点：POST /admin/home/highlights
修改项目亮点：PATCH /admin/home/highlights/:id
删除项目亮点：DELETE /admin/home/highlights/:id

8.3 媒体

上传文件：POST /admin/upload
文件列表：GET /admin/uploads

8.4 商品

商品列表：GET /admin/products
新增商品：POST /admin/products
商品详情：GET /admin/products/:id
修改商品：PATCH /admin/products/:id
删除商品：DELETE /admin/products/:id

8.5 认识饶平

宣传区获取：GET /admin/culture/promo
宣传区修改：PATCH /admin/culture/promo
文章列表：GET /admin/culture/articles
新增文章：POST /admin/culture/articles
文章详情：GET /admin/culture/articles/:id
修改文章：PATCH /admin/culture/articles/:id
删除文章：DELETE /admin/culture/articles/:id

8.6 玩转饶平

体验列表：GET /admin/experiences
新增体验：POST /admin/experiences
体验详情：GET /admin/experiences/:id
修改体验：PATCH /admin/experiences/:id
删除体验：DELETE /admin/experiences/:id

8.7 扶残助残

任务列表：GET /admin/task-showcases
新增任务：POST /admin/task-showcases
任务详情：GET /admin/task-showcases/:id
修改任务：PATCH /admin/task-showcases/:id
删除任务：DELETE /admin/task-showcases/:id
色卡维度：GET /admin/color-card/options
新增色卡选项：POST /admin/color-card/options
修改色卡选项：PATCH /admin/color-card/options/:id
删除色卡选项：DELETE /admin/color-card/options/:id
色卡预设列表：GET /admin/color-card/presets
新增色卡预设：POST /admin/color-card/presets
修改色卡预设：PATCH /admin/color-card/presets/:id
删除色卡预设：DELETE /admin/color-card/presets/:id

8.8 用户内容审核

用户任务列表：GET /admin/user-tasks
更新用户任务状态：PATCH /admin/user-tasks/:id
用户 DIY 记录：GET /admin/user-diy-records

8.9 数据分析

仪表盘概览：GET /admin/dashboard/summary
原始埋点列表：GET /admin/analytics/events
前端埋点上报：POST /api/v1/analytics/events

8.10 配置

配置获取：GET /admin/site-config
配置更新：PATCH /admin/site-config

9. 需要补充或确认的后端能力

虽然当前后端已覆盖大部分内容管理，但若要完整满足“可视化管理端”要求，建议补充以下能力：

9.1 媒体删除接口

现状：

可上传
可查看列表
不可删除媒体文件

建议补充：

删除媒体接口
引用校验能力，避免删除仍被使用的文件

9.2 统一排序保存接口

现状：

各模块支持单条记录 sort_order

建议补充：

批量排序接口
便于拖拽后一次性保存排序

9.3 体验 DIY 配置项管理接口

现状：

体验详情可返回 diy_schemas
无对应的 schema/choice 独立 CRUD 接口

建议补充：

DIY 分组与分组选项的完整管理接口

9.4 数据聚合分析接口

现状：

已有概览接口 GET /admin/dashboard/summary
已有原始埋点接口 GET /admin/analytics/events
已有前端埋点上报接口 POST /api/v1/analytics/events
当前缺少按页面、按内容、按日期、按模块聚合后的专用分析接口

建议补充：

页面浏览趋势接口
内容点击趋势接口
热门内容排行接口
按模块聚合的 PV/UV/点击接口
单个内容的最近 7 天/30 天趋势接口

9.5 前端埋点标准化

现状：

已有 analytics_event 模型和事件上报能力
但文档层面尚未明确所有页面和按钮的埋点标准

建议补充：

统一的 event_type 枚举
统一的 page_path 规范
统一的 target_type 规范
统一的 meta_json 字段约定
页面浏览、内容点击、按钮点击、转化点击的埋点清单

9.6 预览草稿能力

现状：

商品、文章、体验有 status
首页视频/PPT/banner/highlight 多为 is_active

建议补充：

若后续需要更完整的“保存草稿但前端不生效”，建议首页各内容也支持草稿状态。

10. 验收标准

管理端前端完成后，应满足以下验收标准：

管理员登录后，可以进入工作台和预览中心。
预览中心能看到当前前端正在展示的内容。
首页、商品、文化图文、体验、任务、色卡等模块均可独立管理。
所有前端展示内容都至少支持查看、修改、删除，能新增的内容必须支持新增。
删除和修改操作必须弹出确认框。
图片和视频支持本地上传并即时预览。
富文本内容支持编辑和预览。
商品新增和商品详情页编辑做到字段清晰、操作简单、预览直观。
商品图集和工序图支持多项编辑。
保存、发布、删除后，前端展示与管理端预览保持一致。
管理端可以查看前端页面浏览量、内容点击量和基础趋势数据。
数据分析页支持按时间范围、模块、事件类型进行筛选。

11. 推荐实施优先级

P0

登录
工作台
数据分析
前端预览中心
首页管理
商品管理
媒体上传与预览
删除/修改确认弹窗

P1

认识饶平管理
玩转饶平管理
茶染任务管理
色卡工具管理
用户任务审核

P2

媒体库增强
批量排序
更细粒度的草稿预览
体验 DIY 配置扩展
更完整的数据聚合分析

12. 结论

本管理端前端应定位为“面向运营和内容维护的可视化后台”，而不是单纯的数据管理系统。核心价值在于：

管理员能看到当前前端真实展示效果。
管理员能直接在可视化界面中增删改查前端内容。
修改和删除操作安全可控。
图片、视频、富文本、商品详情等内容都能边编辑边预览。
商品详情编辑必须成为整个管理端中最清晰、最好用的内容编辑模块。
管理员还能通过数据分析模块看到前端的浏览量、点击量和热点内容表现。

如果进入下一步开发阶段，建议优先先出两份补充文档：

管理端页面原型说明
管理端接口对接字段说明

FilesExpand file tree

管理端前端详细开发需求.md

Latest commit

History

管理端前端详细开发需求.md

File metadata and controls

饶有趣管理端前端详细开发需求文档

1. 文档目的

2. 项目背景与现状

2.1 当前小程序前端展示结构

2.2 当前后端已具备的管理接口能力

2.3 当前需求的本质

3. 管理端总体目标

3.1 核心目标

4. 管理端信息架构

4.1 登录页

4.2 工作台

4.3 数据分析

4.3.1 总览分析

4.3.2 页面浏览分析

4.3.3 内容点击分析

4.3.4 热门内容排行

4.3.5 数据筛选要求

4.3.6 数据展示要求

4.4 前端预览中心

5. 模块级详细需求

5.1 首页管理

5.1.1 首页视频管理

5.1.2 首页 PPT 管理

5.1.3 首页图文介绍管理

5.1.4 精选推荐管理

5.1.5 项目亮点管理

5.2 商品管理

5.2.1 商品管理页面结构

5.2.2 商品列表页要求

5.2.3 商品新增/编辑核心原则

5.2.4 商品新增/编辑表单设计

A. 基础信息

B. 列表展示设置

C. 详情主体内容

D. 图集管理

E. 工序图示管理

F. 发布设置与预览

5.2.5 商品模块重点交互

5.2.6 商品模块特别要求

5.3 认识饶平管理

5.3.1 宣传视频区管理

5.3.2 文化图文文章管理

5.4 玩转饶平管理

5.4.1 体验项目列表要求

5.4.2 新增/编辑字段

5.4.3 体验 DIY 扩展需求

5.5 扶残助残管理

5.5.1 茶染任务管理

5.5.2 匠心手作管理

5.5.3 色卡工具管理

5.6 媒体库管理

5.7 用户内容审核

5.7.1 用户任务审核

5.7.2 用户 DIY 记录查看

5.8 数据分析

5.8.1 现阶段已具备的接口基础

5.8.2 管理端分析页面需求

5.8.3 数据总览

5.8.4 页面浏览分析

5.8.5 点击行为分析

5.8.6 热门内容排行

5.8.7 原始埋点记录

5.8.8 与各业务模块联动要求

5.9 站点配置

6. 通用交互规范

6.1 删除确认

6.2 修改确认

6.3 发布确认

6.4 预览要求

6.5 上传要求

7. 前端页面与组件开发建议

7.1 页面建议

7.2 通用组件建议

7.3 商品编辑专用组件