# 云游伴侣产品手册

> **适用版本**：当前代码实现（运营端 + 商家管理端 + 微信小程序端）  
> **文档日期**：2026-07-24  
> **阅读原则**：本手册只描述当前已实现、可从代码与已发布菜单确认的能力；“计划中”能力不会作为已授予权限或可承诺功能。

## 1. 产品定位与使用端

云游伴侣是面向旅行社、景区和文旅服务机构的数字讲解与行程内容管理产品。平台由三个协同端组成：

| 使用端 | 主要使用者 | 核心职责 | 当前访问路径 |
| --- | --- | --- | --- |
| 运营端 | 平台运营人员 | 管理商家、套餐、配额、订单、平台 Banner、短信日志与景点知识库 | `/operation/` |
| 商家管理端（C 端） | 商家主账号、子账号、C 端平台管理员 | 维护线路、POI、讲解内容、AI 任务、员工与商户侧使用量 | `/admin/` |
| 微信小程序端 | 游客 | 通过团码加入行程、浏览景点、播放讲解、使用 AI 问答 | 微信小程序 |

官网是产品介绍页面，不承担账号管理或运营操作。

## 2. 核心对象与术语

| 对象 | 说明 |
| --- | --- |
| 商家（商户） | 使用云游伴侣内容管理能力的旅行社、景区或文旅服务机构；由运营端创建。 |
| 商家主账号 | 由运营端为商家创建的管理端登录账号，属于一个商家数据空间。 |
| 子账号 | 由商家主账号创建的协作账号；与主账号共享同一商家数据空间。 |
| 线路 | 一次行程或讲解路线的基础对象，可设置团码，供游客加入行程。 |
| POI | 线路中的景点/兴趣点，可维护名称、坐标、触发半径等信息。 |
| 讲解内容 | 与线路或 POI 关联的文字讲解、AI 生成内容或途径点内容，可生成语音。 |
| 团码 | 游客在小程序中输入，用于获取并加入对应线路。 |
| 套餐与配额 | 运营端定义的可用资源和能力边界，如线路、POI、内容、AI、语音、短信和子账号数量。 |
| 平台 Banner | 面向小程序首页的全局轮播内容；由运营端统一管理，不属于商家内容。 |

## 3. 角色、数据范围与权限结论

### 3.1 角色一览

| 角色 | 所在端 | 数据范围 | 当前已强制的权限边界 |
| --- | --- | --- | --- |
| 平台运营管理员 | 运营端 | 全平台商家、套餐、配额、订单、短信与知识库 | 运营端业务接口要求已登录；当前运营端未按 `role` 字段做菜单或接口细分，已登录运营管理员拥有同一套运营菜单。 |
| C 端平台管理员 | 商家管理端 | 全部商家业务数据 | 登录令牌中 `merchantId` 为空时，线路、POI、内容、AI 任务等商户业务表不附加商家过滤条件。 |
| 商家主账号 | 商家管理端 | 本商家的数据 | 线路、POI、内容、AI 任务等数据按 `merchantId` 隔离；可创建、编辑、禁用和删除自己创建的子账号；新增员工与子账号会检查相应额度。 |
| 商家子账号 | 商家管理端 | 与所属主账号共享的本商家数据 | 继承所属商家的数据范围；**不能查看、创建、编辑或删除子账号**。当前未实现基于角色的菜单/按钮级限制，不能将子账号视为“只读账号”。 |
| 游客 | 微信小程序端 | 通过团码获取的行程及其公开讲解内容 | 不进入运营端或商家管理端；当前小程序主链路以团码访问行程，不提供游客后台管理能力。 |

### 3.2 权限矩阵

说明：`全局` 表示跨商家数据范围；`本商家` 表示系统在业务数据查询与写入时按商家 ID 隔离；`当前可用` 表示页面和接口可使用，但未额外做角色细分。

| 功能 | 平台运营管理员 | C 端平台管理员 | 商家主账号 | 商家子账号 | 游客 |
| --- | --- | --- | --- | --- | --- |
| 运营概览、商家、套餐、订单、配额、短信、知识库 | 全局管理 | 不适用 | 不适用 | 不适用 | 不适用 |
| 平台首页 Banner | 全局管理 | 不在 C 端提供入口 | 不在 C 端提供入口 | 不在 C 端提供入口 | 读取启用 Banner |
| 线路、POI、讲解内容、AI 任务 | 不适用 | 全局数据范围 | 本商家管理 | 本商家当前可用 | 浏览团码对应行程内容 |
| 内容提交、审核通过/拒绝 | 不适用 | 当前可用 | 当前可用 | 当前可用 | 不适用 |
| 生成 AI 内容、生成语音 | 不适用 | 当前可用，受外部服务配置影响 | 本商家内使用，受配额约束 | 本商家内当前可用，受配额约束 | AI 问答入口 |
| 员工管理 | 不适用 | 可查询、编辑、删除已有员工；新增员工仅允许商家账号 | 本商家新增、编辑、删除，新增受员工额度约束 | 本商家当前可用，新增受员工额度约束 | 不适用 |
| 子账号管理 | 不适用 | 仅管理自己创建的子账号 | 仅管理自己创建的子账号，受子账号额度约束 | 不允许管理子账号 | 不适用 |
| 商户侧用户、游客、日志、使用量页面 | 不适用 | 当前 C 端菜单可访问 | 当前 C 端菜单可访问 | 当前 C 端菜单可访问 | 仅查看自己的小程序界面 |

### 3.3 当前权限实现的重要说明

1. **运营端角色未细分**：运营管理员实体包含 `role` 字段，但当前运营端路由和接口的实际规则是“登录后可访问运营功能”。如需区分运营主管、客服、财务、只读运营等角色，需要后续增加后端授权与前端菜单控制。
2. **C 端 RBAC 基础数据存在，但未完成细粒度落地**：登录信息会返回角色与权限编码，数据库也有角色/权限关系；但当前 C 端菜单未按角色过滤，接口主要按“是否登录 + 商家数据范围”控制。
3. **子账号不是只读角色**：当前已强制限制仅为“子账号不能管理子账号”。如果业务需要“内容编辑只能编辑、审核员只能审核、查看员只能查看”，应在上线前补充接口级权限校验。
4. **Banner 权限已迁移至运营端**：商家管理端没有 Banner 菜单；运营端通过受内部令牌保护的服务间接口管理全局 Banner，小程序只读取启用记录。

## 4. 平台运营管理员手册

### 4.1 每日操作入口

登录运营端后，可使用以下菜单：数据概览、首页 Banner、商家管理、套餐管理、订单管理、短信管理、景点知识库、配额管理。

### 4.2 商家全生命周期管理

#### 4.2.1 新建商家

**适用角色**：平台运营管理员。  
**目标**：为新商家建立内容管理空间、商家主账号和初始配额。

操作步骤：

1. 进入 **商家管理**，点击“新建商家”。
2. 填写商家名称、联系人、联系电话、邮箱和地址。
3. 填写商家管理端的用户名、密码、确认密码和管理员姓名；可使用页面随机生成功能辅助填写。
4. 提交创建。
5. 系统创建商家基础信息、商家管理员账号和配额记录；商家可使用该账号登录商家管理端。

操作要点：

- 联系电话按照中国大陆 11 位手机号格式校验。
- 账号密码仅应在创建或重置时按受控流程交付，不应在公开渠道传播。
- 新建后建议立即进入“查看”核对商家状态、到期时间、套餐和配额。

#### 4.2.2 查看、编辑、启用/禁用与重置密码

| 操作 | 使用场景 | 操作说明 |
| --- | --- | --- |
| 查看 | 核对商家资料、账号、套餐与已用/总配额 | 在商家列表点击“查看”。 |
| 编辑 | 修改联系人、账号、套餐或资源总额 | 点击“编辑”，在“基本信息”或“账号与配额”页签修改后保存；新密码留空表示不改密码。 |
| 启用/禁用 | 暂停或恢复商家的管理端使用资格 | 在列表点击“禁用/启用”，并确认操作。 |
| 重置密码 | 商家忘记密码、账号交接或存在泄露风险 | 在商家详情点击“重置”，通过受控渠道交付新密码。 |
| 删除 | 商家终止使用且确认清退 | 点击“删除”并二次确认。该操作会删除运营端商家关联信息，并通知 C 端清理该商家的线路、POI、内容等数据。 |

**删除警告**：删除属于不可恢复的高影响操作。执行前应导出或确认无需保留业务数据，并取得业务负责人确认。

### 4.3 套餐管理

**目的**：定义商家可购买/使用的资源边界与功能开关。

在 **套餐管理** 中可新建或编辑：

- 套餐名称、编码、价格、有效期和排序；
- 最大线路数、最大 POI 数、AI 调用次数、短信条数、子账号上限；
- Banner、AI、音频功能开关；
- 套餐状态和描述。

推荐流程：先维护套餐 → 新建/编辑商家时选择套餐 → 在商家详情与配额管理中持续观察消耗。

### 4.4 配额管理

**目的**：全局查看并手工调整单个商家的资源额度。

操作步骤：

1. 进入 **配额管理**，可按商家名称搜索。
2. 查看 AI、TTS、内容、线路、POI、短信和子账号的“已用 / 总额”。
3. 点击“调整配额”，修改总额后保存。
4. 子账号总额不能低于当前已用数量。

商家管理端会显示配额预警、近 30 天趋势和使用明细；当使用量达到总额的 80% 及以上时会出现预警提示。

### 4.5 首页 Banner 管理

**目的**：维护小程序首页面向游客展示的全局 Banner。

操作步骤：

1. 进入 **首页 Banner**。
2. 新增时填写 Banner 图片地址，设置标题、跳转地址（如有）、排序、生效状态及时间信息。
3. 保存后检查列表中的启用状态与排序。
4. 需要修改时编辑；不再使用时停用或删除。

业务边界：

- Banner 为平台全局内容，不归属某一商家。
- 商家管理端不提供 Banner 管理入口。
- 小程序仅加载启用的 Banner，按排序展示。

### 4.6 订单、短信和景点知识库

| 模块 | 可执行操作 | 关键边界 |
| --- | --- | --- |
| 订单管理 | 按订单号、支付状态检索；查看详情；对待支付订单执行“确认支付” | 当前为管理端状态确认流程，不应表述为已接入真实第三方支付。 |
| 短信管理 | 按手机号、短信类型、发送状态检索发送日志 | 当前页面用于查询，不提供直接发送入口。 |
| 景点知识库 | 按景点名/状态查询；编辑景点介绍；启用/停用复用 | 启用后，相同景点可优先复用已有介绍，命中时不调用 AI、也不扣减 AI 配额。 |
| 数据概览 | 查看商家数量、趋势、套餐分布、即将到期提醒等 | 用于运营监控，不替代财务结算报表。 |

## 5. 商家管理端操作手册

### 5.1 登录与数据范围

商家主账号和子账号从商家管理端登录。登录成功后获得带商家标识的会话令牌；系统对线路、POI、讲解内容和 AI 任务等商户业务数据按商家 ID 过滤。

操作原则：

- 商家账号只维护本商家数据，不应通过 ID 猜测或访问其他商家数据。
- C 端平台管理员的数据范围不同于商家账号，可查看跨商家业务数据，应严格控制该账号的使用与交接。
- 账号被禁用、商家被停用或商家到期后，应由运营端处理状态或套餐问题。

### 5.2 线路与 POI 管理

**线路管理** 用于建立行程基础信息和团码；游客需要团码加入行程。

建议操作顺序：

1. 进入 **线路管理**，新建线路并填写线路基础信息、团码和状态。
2. 为线路维护 POI/景点信息，包括名称、经纬度、地址和触发半径。
3. 在 **内容管理** 中按线路或 POI 创建讲解内容。
4. 完成审核与语音生成后，再将团码交给游客使用。

管理端支持线路的新增、查询、编辑和删除。删除线路前，应确认关联 POI、内容及小程序使用影响。

### 5.3 内容管理：人工内容、AI 内容、审核与语音

内容管理是商家端的核心操作页面，支持按关键词、线路、内容类型和状态筛选。

#### 内容类型

| 类型 | 用途 | 主要输入 |
| --- | --- | --- |
| 景点介绍 | 为指定 POI 维护讲解文本 | POI、标题、讲解内容、可选语音设置 |
| 线路介绍 | 为整条线路维护介绍文本 | 线路、标题、讲解内容、可选语音设置 |
| AI 生成 | 根据景点名称和可选描述生成初稿 | 线路、景点名称、描述、坐标/地址（可选） |
| 途径点 | 批量生成路线途径点讲解任务 | 线路、起点、终点、预计生成数量 |

#### 内容状态流转

当前页面提供以下状态和操作：

```text
草稿 → 提交审核 → 待审核 → 审核通过
                       └── 审核拒绝
```

操作步骤：

1. 点击“新增内容”，选择内容类型并填写必填项；或使用 AI 生成/途径点生成。
2. 保存后在列表中检查草稿内容。
3. 点击“提交审核”。
4. 对待审核内容执行“通过”或“拒绝”。
5. 对需要播放的内容选择音色并点击“生成语音”；生成成功后可播放验证。

**当前权限注意**：提交、审核通过与审核拒绝目前位于同一内容管理页面，系统尚未将“编辑”和“审核”拆分为不同角色权限。需要双人复核的商家应通过内部流程约束，而不要误认为系统已强制审批人分离。

### 5.4 AI 任务与语音生成

| 功能 | 操作 | 资源影响 |
| --- | --- | --- |
| AI 生成内容 | 在内容管理中选择 AI 生成，或进入 **AI 任务** 创建、查看、提交和删除任务 | 消耗 AI 调用额度；也可能优先命中平台知识库而不扣减 AI 额度。 |
| 途径点生成 | 输入线路起终点与数量，生成路线相关任务 | 消耗相应 AI 能力与额度。 |
| 语音生成（TTS） | 对内容选择音色并生成/重新生成音频 | 消耗 TTS 额度；内容更新后旧语音会标为“需重新生成”。 |
| 语音播放 | 已生成且未过期的语音可在管理端播放 | 仅用于内容校验，不代表小程序端所有网络环境均已验收。 |

AI、TTS 与地图等第三方能力取决于套餐配额及运行环境配置。若密钥、服务或额度不可用，页面操作会失败或返回未配置提示；应先检查配额与运营配置，避免反复提交。

### 5.5 员工管理

员工用于维护商家内导游、讲解员或运营人员的基础信息。

操作步骤：

1. 进入 **员工管理**。
2. 新增员工，填写姓名及可选的工号、手机号、职位、头像等信息。
3. 在列表中编辑、删除或变更员工状态。

规则：

- 新增员工仅允许商家账号执行；系统为员工写入所属商家。
- 新增时会检查员工额度；运营端不可达时，代码会放行新增，后续应由运营人员核对额度。
- 商家账号不能编辑或删除其他商家的员工。

### 5.6 子账号管理

**商家主账号操作步骤**：

1. 进入 **子账号管理**，点击“新建子账号”。
2. 设置用户名、密码、姓名、手机号和邮箱。
3. 保存后可在列表中编辑信息、重置该子账号密码、启用/禁用或删除。
4. 子账号达到上限时，联系运营人员升级套餐或调整额度。

已实现规则：

- 子账号与主账号共享同一商家数据空间。
- 商家主账号只能管理自己创建的子账号。
- 子账号不能创建、编辑、删除或查看子账号列表。
- 默认额度可为 2 个，但实际可创建数量以运营端当前商家配额为准。
- 当前界面没有“角色分配”页面；页面提示中的角色控制属于后续需要完善的能力，不能据此假定已存在内容编辑/只读分权。

### 5.7 用户、游客、日志与使用量

| 模块 | 用途 | 建议操作 |
| --- | --- | --- |
| 用户管理 | 查询小程序用户信息 | 按需检索、核对使用情况。 |
| 游客管理 | 查看游客访问/行程相关基础数据 | 用于服务跟进和运营分析。 |
| 日志管理 | 查询登录日志、操作日志和操作记录 | 按用户名、模块、操作类型、操作人和日期筛选；排查异常登录或误操作。 |
| 使用量统计 | 查看 AI、TTS、内容、线路、POI 的配额进度、趋势和使用明细 | 使用量接近 80% 时提前联系运营人员处理套餐或配额。 |

## 6. 微信小程序游客操作手册

### 6.1 游客主流程

```text
打开小程序 → 输入团码加入行程 → 查看行程/POI → 选择景点 → 播放讲解
                                      ↓
                                 使用 AI 问答 / 查看个人页
```

### 6.2 操作说明

1. **加入行程**：在欢迎页或首页进入“加入行程”，输入团码。团码长度需在 4 至 20 个字符之间。
2. **查看行程**：团码有效且线路包含 POI 后，进入“行程”页查看景点列表、进度和自动讲解开关。
3. **选择景点与播放**：点击 POI 进入播放页；存在有效音频时可播放、暂停、切换上一/下一景点，并查看地图标记。
4. **浏览路线**：在路线页查看当前行程的 POI，并可选择景点播放。
5. **AI 问答**：在 AI 页输入问题或使用快捷问题，系统调用游客侧 AI 问答接口返回回复。
6. **个人页**：查看当前行程进度、自动讲解开关和本次客户端内保存的历史行程记录。

### 6.3 游客侧边界

- 小程序首页加载运营端管理的启用 Banner。
- 团码不存在、无 POI 或无讲解内容时，小程序会提示用户联系导游或稍后重试。
- 小程序会请求位置权限以支持地图和自动讲解相关交互；用户可以拒绝授权。实际自动触发效果依赖真机定位、网络和音频环境，不应在未完成真机验收前承诺全程自动播放。
- 当前历史行程逻辑主要依赖小程序运行时全局状态，不应把它当作跨设备、长期保存的个人行程档案。

## 7. 关键业务规则与运营边界

### 7.1 商家数据隔离

- C 端对线路、POI、讲解内容、AI 任务等商家业务表采用 `merchantId` 隔离。
- 商家主账号与子账号使用同一商家数据空间。
- C 端平台管理员的 `merchantId` 为空，不参与该业务表过滤，因此应作为高权限账号管理。
- 运营端不承担商家内容生产，主要承担商家、套餐、配额和商业运营管理。

### 7.2 套餐、额度与功能开关

- 套餐定义资源上限与 Banner、AI、音频等功能开关。
- 商家新增线路、POI、内容、AI 调用、语音生成、子账号和员工时，可能受到额度检查。
- 运营端可通过商家编辑或配额管理直接调整总额；调整后应让商家刷新页面再复核。
- 已用量同步可能依赖运营端内部服务调用；如运营端暂时不可达，应在恢复后复核额度数据。

### 7.3 内容质量与发布责任

- AI 生成的是可编辑初稿，商家应对事实准确性、版权、适宜性和最终发布内容负责。
- 语音生成前应先校对文字；文字变更后应重新生成并试听。
- 当前审核状态功能不等于岗位职责隔离。对外发布前建议建立“编辑—复核—发布”人工流程。

### 7.4 高影响操作清单

| 操作 | 影响 | 建议控制 |
| --- | --- | --- |
| 删除商家 | 清理运营端关联数据并通知 C 端清理商家内容 | 双人确认、保留业务确认记录。 |
| 禁用商家 | 影响商家登录和持续服务 | 明确禁用原因、预计恢复时间和通知对象。 |
| 重置商家/子账号密码 | 影响账号访问安全 | 通过受控渠道交付新密码，要求首次使用后自行修改（如后续能力上线）。 |
| 调低配额 | 可能立即阻止新增或生成操作 | 不低于已用数量，先沟通商家。 |
| 停用知识库 | 后续同名景点不再复用该介绍 | 评估 AI 成本和内容质量影响。 |
| 删除/停用 Banner | 影响所有小程序游客首页展示 | 先检查活动、生效时间和替代内容。 |

## 8. 当前实现限制与后续建议

1. **角色权限需继续完善**：运营端和 C 端均应实现服务端的菜单、按钮和接口级角色授权，而不是仅依赖前端显示或商家数据隔离。
2. **子账号需补齐角色分配**：建议至少提供“商家管理员、内容编辑、审核员、只读查看”四类角色，并在接口层校验。
3. **支付应以实际支付网关为准**：当前订单页提供的是管理端确认支付流程，正式商业化前需接入真实支付、回调验签、退款和对账能力。
4. **游客身份与历史应持久化**：如需要跨设备历史、反馈追踪或权益管理，应接入小程序用户身份与服务端持久化。
5. **第三方服务应独立运维**：AI、TTS、地图服务需配置密钥、超时、失败重试、额度告警与降级策略。
6. **敏感信息不得公开展示**：账号、密码、手机号、身份证明、内部接口地址和密钥不得放入官网、登录页、控制台欢迎页或公开文档。

## 9. 推荐日常操作清单

### 平台运营管理员

- 每日查看即将到期商家、异常配额和订单待支付状态。
- 每周核对商家禁用/启用状态、短信日志、知识库启停和 Banner 生效内容。
- 新建商家后完成账号交付、套餐确认和登录验收。
- 删除商家、降低配额、停用 Banner 前执行二次确认。

### 商家主账号

- 每次新行程按“线路 → POI → 内容 → 审核 → 语音试听 → 团码交付”完成检查。
- 每周查看使用量统计，配额接近预警阈值时提前联系运营人员。
- 定期检查子账号、员工状态和登录/操作日志，及时禁用离职或不再使用的账号。
- AI 初稿和语音内容发布前进行人工复核。

### 游客服务人员/导游

- 出发前确认团码有效、线路已配置 POI、关键 POI 已有可播放音频。
- 向游客说明团码加入方法和定位权限用途；不强制游客授权定位。
- 遇到“无讲解内容”“音频无法播放”时，优先核对网络、团码、内容状态和音频生成状态。

---

## 附：本手册依据

本手册依据当前项目的运营端与 C 端路由、鉴权配置、子账号/员工/配额服务、内容管理页面、运营管理页面以及小程序页面实现整理。功能或权限发生变更时，应同步更新本手册，尤其是角色授权、套餐配额、Banner 归属和支付能力相关章节。