406 lines
14 KiB
Markdown
406 lines
14 KiB
Markdown
# H5 后台管理系统规划
|
||
|
||
## 目标
|
||
|
||
为当前鸿鹄逸游 H5 项目建设一套可真实上线维护的后台系统，让运营人员可以管理首页内容、目的地、线路产品、活动专题、客户需求、订单线索、消息和客服配置，而不是继续依赖改代码发布。
|
||
|
||
当前 H5 主要是一个静态 Vite + React 应用：
|
||
|
||
- 首页配置来自 `src/content.ts`：轮播、目的地、主题卡、线路分区、底部 CTA。
|
||
- 线路产品来自 `src/generated-products.json`：48 条产品卡片。
|
||
- 目的地搜索、活动页、需求表单、消息、订单、客服经理等流程目前集中写在 `src/App.tsx`。
|
||
- 图片资源在 `public/assets/source`，约 115 个文件。
|
||
|
||
后台建设的核心不是简单加一个管理页面，而是把这些静态内容拆成稳定的数据模型，并提供发布、审核、回滚、权限、日志和运维能力。
|
||
|
||
## 推荐架构
|
||
|
||
### 代码组织
|
||
|
||
建议从单一前端项目演进为 TypeScript monorepo：
|
||
|
||
```text
|
||
apps/
|
||
h5/ # 当前 Vite React H5，可从现有 src/ 迁移
|
||
admin/ # 后台管理端，React + Ant Design Pro 或 shadcn/ui
|
||
api/ # 后端 API，NestJS 或 Fastify
|
||
packages/
|
||
shared/ # 共享类型、校验 schema、接口 DTO
|
||
config/ # eslint/tsconfig 等公共配置
|
||
```
|
||
|
||
保守可落地方案：
|
||
|
||
- 前台 H5：继续 Vite + React，先只改数据来源。
|
||
- 后台 Admin：React + Ant Design Pro。原因是后台表格、筛选、表单、权限、布局成熟，开发快。
|
||
- API：NestJS + Prisma。原因是 TypeScript 体系一致，权限、模块化、OpenAPI、测试更规整。
|
||
- 数据库：PostgreSQL。
|
||
- 缓存/队列：Redis，先用于发布缓存、短信/通知任务、操作频控。
|
||
- 文件存储：阿里 OSS、腾讯 COS 或 S3 兼容对象存储。
|
||
- 部署：Docker + Nginx + CDN，后续可上云托管或 Kubernetes。
|
||
|
||
### 服务边界
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
H5["H5 前台"] --> API["Public API"]
|
||
Admin["后台管理端"] --> AdminAPI["Admin API"]
|
||
API --> DB[("PostgreSQL")]
|
||
AdminAPI --> DB
|
||
AdminAPI --> OSS["对象存储"]
|
||
AdminAPI --> Redis[("Redis")]
|
||
CDN["CDN"] --> H5
|
||
CDN --> OSS
|
||
```
|
||
|
||
## 后台功能模块
|
||
|
||
### 1. 工作台
|
||
|
||
- 今日新增需求、待跟进需求、待确认订单、上架线路数。
|
||
- 最近发布记录、失败任务、异常日志。
|
||
- 快捷入口：新建线路、新建活动、发布首页、导出需求。
|
||
|
||
### 2. 首页装修
|
||
|
||
对应当前 `src/content.ts`。
|
||
|
||
- 轮播管理：图片、标题、副标题、跳转类型、排序、上下架。
|
||
- 锚点分类：探索世界、主题甄选、精选线路、一生一次、鸿鹄稀缺。
|
||
- 目的地宫格：名称、图片、跳转关键词、排序、是否推荐。
|
||
- 主题卡片：主题名、封面、关联线路或活动专题。
|
||
- 线路分区：分区标题图、分区名称、展示线路、排序规则。
|
||
- 底部 CTA：权益卡、公众号、目的地搜索、需求表单等入口。
|
||
- 页脚与品牌图：图片、服务承诺、备案信息。
|
||
- 预览与发布：草稿预览、定时发布、回滚上一版。
|
||
|
||
### 3. 线路产品管理
|
||
|
||
对应当前 `src/generated-products.json` 和产品详情页。
|
||
|
||
- 基础信息：标题、副标题、目的地、产品类型、价格、起价单位、标签。
|
||
- 封面与图集：列表图、详情头图、行程图片。
|
||
- 详情内容：特色、玩法、美食、行程日程、费用包含/不含、预订须知。
|
||
- 售卖配置：上架状态、推荐权重、活动归属、库存/席位说明。
|
||
- 搜索配置：关键词、别名、目的地关联、主题标签。
|
||
- SEO/分享：分享标题、描述、海报图。
|
||
- 批量能力：导入、导出、批量上下架、批量改标签。
|
||
|
||
### 4. 目的地管理
|
||
|
||
对应当前首页目的地、目的地搜索页和搜索别名逻辑。
|
||
|
||
- 国家/城市/地区层级。
|
||
- 热门目的地、出境/国内分类。
|
||
- 搜索别名：例如 `马代 -> 马尔代夫`、`内蒙 -> 内蒙古`。
|
||
- 目的地封面图、推荐线路、活动专题绑定。
|
||
- 排序和上下架。
|
||
|
||
### 5. 活动专题管理
|
||
|
||
对应当前端午甄选、早鸟尊享、鸿鹄逸游等活动页。
|
||
|
||
- 专题标题、封面、介绍文案、活动时间。
|
||
- 关联线路列表。
|
||
- CTA：提交需求、联系客服、跳转线路。
|
||
- 发布状态：草稿、待审核、已发布、已下线。
|
||
- 合规文案：例如活动免责声明。
|
||
|
||
### 6. 客户需求管理
|
||
|
||
对应当前 `DemandPage`，上线后这是最重要的转化入口。
|
||
|
||
- 表单字段：目的地、手机号、出行时间、预算、人数、备注、来源页面、来源线路。
|
||
- 线索状态：新建、已分配、已联系、方案中、已成交、无效。
|
||
- 客户经理分配：手动分配、自动轮询分配。
|
||
- 跟进记录：电话、微信、备注、下次提醒。
|
||
- 防刷：手机号频控、验证码、IP 风控、黑名单。
|
||
- 导出：Excel/CSV，按时间、状态、顾问筛选。
|
||
|
||
### 7. 客户与订单管理
|
||
|
||
对应当前消息、订单中心的真实业务化。
|
||
|
||
- 客户档案：手机号、姓名、微信、偏好、历史需求。
|
||
- 订单/方案：关联客户、线路、顾问、出行时间、人数、报价、状态。
|
||
- 状态流转：需求单 -> 方案 -> 合同/支付 -> 出行中 -> 已完成/售后。
|
||
- 附件：合同、方案 PDF、发票、签证材料。
|
||
- 订单备注和操作日志。
|
||
|
||
### 8. 消息与客服配置
|
||
|
||
- 后台通知：需求分配、订单状态变化、发布失败。
|
||
- 前台消息：活动通知、顾问消息、订单提醒。
|
||
- 客服入口：在线联系、电话、服务时间、企业微信/IM 配置。
|
||
- 短信：验证码、需求提交确认、顾问跟进提醒。
|
||
|
||
### 9. 媒体库
|
||
|
||
- 图片上传、裁剪、压缩、WebP 转换。
|
||
- 图片分组：轮播、目的地、线路、活动、品牌。
|
||
- 文件引用关系：防止删除正在使用的图片。
|
||
- CDN URL、缩略图、多尺寸版本。
|
||
|
||
### 10. 权限与审计
|
||
|
||
- 角色：超级管理员、运营、产品、客服主管、客户经理、只读审计。
|
||
- 权限粒度：菜单权限、按钮权限、数据范围权限。
|
||
- 审核流：重要内容先提交审核再发布。
|
||
- 操作日志：谁在什么时候改了什么，从什么值改到什么值。
|
||
- 登录安全：强密码、二次验证可选、登录 IP 记录。
|
||
|
||
## 核心数据模型
|
||
|
||
第一期建议覆盖这些表：
|
||
|
||
| 表 | 用途 |
|
||
| --- | --- |
|
||
| `admin_users` | 后台用户 |
|
||
| `roles` / `permissions` | RBAC 权限 |
|
||
| `media_assets` | 图片和文件资源 |
|
||
| `site_versions` | 首页/站点配置发布版本 |
|
||
| `home_sections` | 首页模块配置 |
|
||
| `hero_slides` | 首页轮播 |
|
||
| `destinations` | 目的地 |
|
||
| `map_images` | 贵州地图单图配置 |
|
||
| `destination_aliases` | 搜索别名 |
|
||
| `themes` | 主题甄选 |
|
||
| `products` | 线路产品 |
|
||
| `product_images` | 产品图片 |
|
||
| `product_itineraries` | 行程日程 |
|
||
| `product_fee_items` | 费用说明 |
|
||
| `campaigns` | 活动专题 |
|
||
| `campaign_products` | 专题与线路关联 |
|
||
| `leads` | 客户需求/线索 |
|
||
| `lead_followups` | 跟进记录 |
|
||
| `customers` | 客户档案 |
|
||
| `orders` | 订单/方案 |
|
||
| `messages` | 前台消息 |
|
||
| `audit_logs` | 操作审计 |
|
||
|
||
### 示例：产品表
|
||
|
||
```sql
|
||
products (
|
||
id uuid primary key,
|
||
title text not null,
|
||
subtitle text,
|
||
destination_id uuid,
|
||
price_amount integer,
|
||
price_unit varchar(20),
|
||
tags text[],
|
||
cover_asset_id uuid,
|
||
summary text,
|
||
status varchar(20), -- draft, published, archived
|
||
sort_weight integer default 0,
|
||
published_at timestamptz,
|
||
created_at timestamptz not null,
|
||
updated_at timestamptz not null
|
||
)
|
||
```
|
||
|
||
### 示例：线索表
|
||
|
||
```sql
|
||
leads (
|
||
id uuid primary key,
|
||
destination text,
|
||
phone varchar(30) not null,
|
||
travel_date date,
|
||
people_count integer,
|
||
budget_min integer,
|
||
budget_max integer,
|
||
source_page text,
|
||
source_product_id uuid,
|
||
status varchar(30) not null,
|
||
assigned_user_id uuid,
|
||
created_at timestamptz not null,
|
||
updated_at timestamptz not null
|
||
)
|
||
```
|
||
|
||
## API 设计
|
||
|
||
### Public API 给 H5 使用
|
||
|
||
- `GET /api/public/site-config`：首页配置、模块排序、底部导航。
|
||
- `GET /api/public/products`：线路列表，支持目的地、主题、活动、关键词筛选。
|
||
- `GET /api/public/products/:id`：线路详情。
|
||
- `GET /api/public/destinations`：目的地和热门分类。
|
||
- `GET /api/public/campaigns/:slug`：活动专题详情。
|
||
- `POST /api/public/leads`：提交出行需求。
|
||
- `POST /api/public/sms/send-code`：发送验证码。
|
||
|
||
### Admin API 给后台使用
|
||
|
||
- `POST /api/admin/auth/login`
|
||
- `GET /api/admin/dashboard`
|
||
- `CRUD /api/admin/products`
|
||
- `CRUD /api/admin/destinations`
|
||
- `CRUD /api/admin/campaigns`
|
||
- `CRUD /api/admin/site-config/:module`：页面模块配置，覆盖 `heroSlides`、`destinations`、`map`、`themes`、`campaigns`、`ctaBanners`
|
||
- `CRUD /api/admin/media-assets`
|
||
- `GET /api/admin/leads`
|
||
- `PATCH /api/admin/leads/:id/status`
|
||
- `POST /api/admin/leads/:id/followups`
|
||
- `CRUD /api/admin/orders`
|
||
- `GET /api/admin/audit-logs`
|
||
- `POST /api/admin/publish`
|
||
- `POST /api/admin/rollback`
|
||
|
||
## 前台改造路径
|
||
|
||
### 第一步：数据层抽离
|
||
|
||
先不大改 UI，把硬编码内容替换成数据适配层。
|
||
|
||
- 新建 `src/api/client.ts` 和 `src/api/types.ts`。
|
||
- 新建 `src/adapters/siteConfig.ts`，把接口数据转成当前组件需要的结构。
|
||
- 保留本地 JSON fallback，便于本地开发和接口故障降级。
|
||
- 把 `heroSlides`、`destinations`、`map`、`themeCards`、`campaigns`、`sectionHeaders`、`bottomCtas` 从静态 import 改成接口加载。
|
||
|
||
### 第二步：产品和目的地接口化
|
||
|
||
- `generated-products.json` 改为接口 seed 数据。
|
||
- 搜索逻辑从前端 `keywordAliases` 迁移到后端。
|
||
- 产品详情页从 `getDetailMeta` 这类本地推断改为真实详情字段。
|
||
|
||
### 第三步：需求表单真实提交
|
||
|
||
- `DemandPage` 接入 `POST /api/public/leads`。
|
||
- 增加手机号校验、验证码、提交成功页。
|
||
- 后台线索列表能看到来源页面和来源产品。
|
||
|
||
### 第四步：消息与订单真实化
|
||
|
||
- 登录态、客户身份、订单列表需要独立规划。
|
||
- 如果短期不做会员体系，可先保留“提交需求后的查询链接/手机号验证码查询”。
|
||
|
||
## 发布与运维
|
||
|
||
### 发布策略
|
||
|
||
- 内容发布与代码发布分离。
|
||
- 运营修改内容后生成草稿版本。
|
||
- 审核通过后写入 `site_versions`，Public API 默认返回当前发布版本。
|
||
- CDN 缓存使用短 TTL 或发布后主动刷新。
|
||
- 每次发布可回滚到上一版本。
|
||
|
||
### 环境
|
||
|
||
| 环境 | 用途 |
|
||
| --- | --- |
|
||
| local | 本地开发 |
|
||
| dev | 联调环境 |
|
||
| staging | 预发布，连接准生产数据或脱敏数据 |
|
||
| production | 正式环境 |
|
||
|
||
### 监控与备份
|
||
|
||
- API 错误率、响应时间、数据库连接数。
|
||
- 需求提交成功率、短信发送成功率。
|
||
- 每日数据库自动备份，至少保留 14 到 30 天。
|
||
- 对象存储开启版本控制或回收站。
|
||
- 关键操作日志不可被普通管理员删除。
|
||
|
||
### 安全
|
||
|
||
- 后台必须 HTTPS。
|
||
- 管理端登录限流。
|
||
- 所有 Admin API 校验权限。
|
||
- Public API 做参数校验和频控。
|
||
- 手机号等隐私信息后台脱敏展示，导出需要高权限。
|
||
- 防止任意文件上传：限制 MIME、大小、后缀，图片重新编码。
|
||
|
||
## 分阶段交付计划
|
||
|
||
### Phase 1：后台 MVP，约 2 到 3 周
|
||
|
||
目标：运营可以维护首页和线路，H5 可以读取接口。
|
||
|
||
- 搭建 monorepo、API、Admin、数据库。
|
||
- 建立媒体库、产品、目的地、首页配置数据表。
|
||
- 写 seed 脚本，把当前 `content.ts` 和 `generated-products.json` 导入数据库。
|
||
- 后台完成登录、产品列表/编辑、首页配置、图片上传。
|
||
- H5 接入 `site-config` 和 `products`，保留本地 fallback。
|
||
|
||
### Phase 2：线索闭环，约 2 周
|
||
|
||
目标：出行需求可以真实提交、分配、跟进。
|
||
|
||
- 需求表单接口。
|
||
- 后台线索列表、状态流转、跟进记录。
|
||
- 客户经理分配。
|
||
- 短信验证码和提交通知。
|
||
- 导出和基础统计。
|
||
|
||
### Phase 3：活动和发布体系，约 2 到 3 周
|
||
|
||
目标：专题页和首页可以安全发布。
|
||
|
||
- 活动专题管理。
|
||
- 草稿/审核/发布/回滚。
|
||
- 发布日志和操作审计。
|
||
- CDN 刷新。
|
||
- 预发布环境验收。
|
||
|
||
### Phase 4：订单、客户和消息，约 3 到 5 周
|
||
|
||
目标：从线索进一步进入服务履约。
|
||
|
||
- 客户档案。
|
||
- 订单/方案管理。
|
||
- 前台消息和订单查询。
|
||
- 附件上传。
|
||
- 顾问工作台。
|
||
|
||
### Phase 5：生产加固，持续迭代
|
||
|
||
目标：稳定上线维护。
|
||
|
||
- 监控告警、备份恢复演练。
|
||
- 权限细化、数据脱敏。
|
||
- 性能优化和缓存。
|
||
- 自动化测试、CI/CD。
|
||
- 数据分析看板。
|
||
|
||
## MVP 优先级
|
||
|
||
必须先做：
|
||
|
||
1. 后台登录与权限。
|
||
2. 媒体库。
|
||
3. 线路产品管理。
|
||
4. 首页配置管理。
|
||
5. H5 读取接口并保留 fallback。
|
||
6. 需求表单真实提交。
|
||
7. 线索后台跟进。
|
||
8. 发布、回滚、操作日志。
|
||
|
||
可以后做：
|
||
|
||
1. 完整会员登录。
|
||
2. 真实支付。
|
||
3. 复杂订单履约。
|
||
4. 企业微信深度集成。
|
||
5. 多语言/多品牌站点。
|
||
|
||
## 近期可执行清单
|
||
|
||
1. 建立 `apps/h5`、`apps/admin`、`apps/api` 结构。
|
||
2. 设计 Prisma schema，并先覆盖产品、首页、媒体、目的地、线索。
|
||
3. 编写 seed 脚本，把现有静态内容导入数据库。
|
||
4. 做 Public API，先返回与当前 H5 兼容的数据。
|
||
5. 改造 H5 数据加载层，保证 UI 不变。
|
||
6. 做 Admin 的产品管理和首页装修。
|
||
7. 接通需求表单和后台线索列表。
|
||
8. 补充发布版本、回滚、审计日志。
|
||
|
||
## 风险与建议
|
||
|
||
- 不建议一开始就做完整电商订单和支付，旅游定制业务更适合先做线索和顾问跟进闭环。
|
||
- 不建议让后台直接编辑任意 JSON，短期快但长期容易把数据结构搞乱。
|
||
- 不建议 H5 只依赖实时接口，首页配置应支持发布版本和缓存，避免后台故障影响前台展示。
|
||
- 不建议图片继续只放在代码仓库里，真实上线后要进入对象存储和 CDN。
|
||
- 如果预算有限，第一期可以先用单台云服务器 + PostgreSQL + 对象存储；但备份、HTTPS、日志和权限不能省。
|