ghy-all/doc/房间群分销功能说明文档（开发视角）.md

<!-- @author Yifei.Kuang -->
# 房间 / 群 / 分销功能说明文档（开发视角）

## 一、整体架构

- 层级结构：
  - 平台 → 房间（Room）→ 群（Group）→ 群员 / 分销身份（Distributor）
- 身份核心：
  - 每条分销身份由「平台 + 房间 + 群 + 用户」组合唯一确定，用于分销归属和订单结算。

---

## 二、房间模块（Room）

### 2.1 房间功能点

- 创建房间申请：
  - 用户提交房间名称、头像、品牌注解等信息。
  - 后台审核通过后，生成房间，并指定房间主。
- 房间信息维护：
  - 房间主可编辑名称、头像、品牌注解。
- 房间顶部功能栏配置：
  - 默认显示「师傅库 / 商城 / 会话厅」三项。
  - 房间主可以修改显示文案（总字数受限），功能类型不变。
- 房间权限与扣点设置（后台）：
  - 是否开启本房间商城。
  - 是否允许本房间下的群进行选品。
  - 房间级扣点与收费策略配置。
- 房间切换：
  - 同一微信可加入多个房间，通过「切换圈子」在不同房间间切换。

---

## 三、群模块（Group）

### 3.1 建群与审核

- 在某房间内，用户可发起建群申请。
- 填写群基础信息（城市、区域、主营类目、群规模等）。
- 审核流程：
  - 房间主初审；
  - 后台终审；
  - 通过后创建群，申请人自动成为群主。

### 3.2 群基本操作

- 群信息维护：
  - 群主可编辑群名、介绍、主营描述等。
- 群状态控制（后台）：
  - 支持群的启用/禁用；
  - 禁用后，群内发单、接单、分销等操作关闭或受限。
- 群主变更：
  - 后台可在必要时调整群主（例如违规处理）。

### 3.3 群监管

- 支持在任意群中驻入“系统机器人/系统监管号”：
  - 具备基本群管理与后台数据采集、监控能力。
  - 用于运营与风险控制。

---

## 四、群员 / 分销身份模块

### 4.1 分销身份规则

- 每个用户在某「平台 + 房间 + 群」组合下对应一个分销身份。
- 同一微信在不同房间/群中拥有多个独立身份：
  - 每个身份有独立的分销链；
  - 后台视为多个“人”。

### 4.2 加入群与分销绑定

- 成员加入群时：
  - 若在该群下不存在分销身份，则系统为其创建一条新身份线。
  - 按既有三级分销规则绑定上级分销。
- 上下级分销关系：
  - 限定在当前群对应的分销线中，不跨群共享。

### 4.3 角色与权限（概念层）

- 群主：
  - 本群最高级分销；
  - 拥有选品、群配置、成员管理等高权限。
- 管理员：
  - 由群主任命，可拥有部分管理能力（禁言、审核、公告等）。
- 普通分销/群员：
  - 不能在群内进行选品；
  - 可以拉人建立下级分销关系。

---

## 五、会话厅与群聊相关功能

### 5.1 订单页面导航（左侧）

- 导航栏包含 4 项：
  - 资源库；
  - 商品城；
  - 会话厅；
  - 附近圈动态。
- 群主可以：
  - 修改导航名称（总字数有限制）；
  - 单独开放/禁用任一入口；
  - 与外层房间首页的导航机制保持一致。
- 右下角「会话大厅」按钮：
  - 进入群聊页面（中间页）；
  - 文案可改，群主/平台可控制是否可用。

### 5.2 资源库（A）

- 展示服务师傅资料与店铺：
  - 格式类似现有“师傅圈”，但样式可定制。
- 群主可设置仅群内成员可见，或继承房间级展示。
- 提供发布入口，支持基于群选品的类目发单。

### 5.3 商品城（B）

- 群级商城展示逻辑：
  - 与整体商城逻辑一致；
  - 差异在于：群商城的选品由群主独立配置。
- 所有人看到的商品、类目等均来源于群主选品结果。
- 首页热门类目默认服务类，可左滑出商品类目列表。
- 列表筛选按价格、评分、销量进行。
- 销量统计按整条商品聚合，不再按规格拆分。

### 5.4 会话厅（C）

- 会话厅为“会话/订单流”页面，不是群聊页面。
- 默认进入订单页时落在该列：
  - 支持上拉刷新；
  - 承载订单、系统相关信息的流式展示。

### 5.5 附近圈动态（D）

- 展示商家图文动态的“公共圈子”区域：
  - 默认名称为“附近圈动态”；
  - 群主可以改名，但含义不变（商家圈/动态圈）。

### 5.6 会话大厅图与编辑订单（E）

- 页面中部展示“会话大厅相关图”：
  - 使用会话大厅图的一部分放大，作为视觉入口。
- 支持进入“编辑订单/发单页”：
  - 编辑后的订单可发至全群；
  - 管理员可选择仅发送至单个客户。

---

## 六、群聊在线控制与刷新机制

### 6.1 在线人数限制

- 当群聊在线人数超过上限（群主/后台可配置）：
  - 群主与管理员不受上线限制，始终在线。
  - 系统自动将部分成员标记为离线：
    - 优先踢出近期未发言的成员；
    - 该过程对成员前端为“默默离线”，不会强制踢出页面。

### 6.2 重新上线与刷新

- 被标记为离线的成员：
  - 在输入框输入内容时，自动重新上线。
- 新进群但未发言的成员：
  - 一段时间后，输入框变为“消息刷新”按钮；
  - 点击后重新加载消息，并作为新上线行为。
- 在已超上线限制的状态下：
  - 新进入成员默认离线；
  - 需主动刷新或发言才开始拉取实时消息。

### 6.3 页面跳转与上线状态

- 在群聊中点击任何产品、品类跳转其他页面：
  - 无论是否超限，都视为离线（停止实时连接）。
- 从商品/其他页面返回群聊页：
  - 自动恢复为在线状态。
- 在商品页面点击“聊天”：
  - 跳回群聊，并恢复在线。

---

## 七、会话厅顶部类目与选品关系

### 7.1 顶部类目区

- 顶部显示：
  - 「全部」入口；
  - 若干热门类目。
- 热门类目：
  - 群主从本群的主营/重点品类中选定；
  - 可对特别重要的类目打红点标记。
- 展示方式：
  - 左右滑动；
  - 每行最多 8 个类目，最多展示两行。

### 7.2 选品关系

- 群主 = 分销顶层：
  - 群主在本群选品的结果，体现在“全部”和热门类目展示中。
- 群员：
  - 无法直接在群内进行选品；
  - 仅能浏览、转发商品并参与分销。

---

## 八、群内订单与全域订单

### 8.1 群内订单发起

- 在群聊页面可以通过以下方式生成群内订单：
  - 使用专门的“群内订单发单入口”；
  - 将当前输入框的文字通过快捷键转换为订单（跳转到发单确认页）。
- 生成的群内订单：
  - 在群聊中以订单卡片形式展示；
  - 提供“接单”按钮。

### 8.2 与专业版（师傅端）的联动

- 若群内发单时勾选“保险”等高级字段：
  - 该订单将按专业版（师傅端）逻辑处理；
  - 接单、保险、结算等均走专业端流程。
- 群主可配置：
  - 群内订单是否仅允许本群服务人员接单；
  - 或是否允许进入大厅，被所有专业师傅接单。

### 8.3 全域订单

- 群主可将部分群内订单开放到“全域订单池”：
  - 其他群的服务商也能在“全域订单”中看到这些订单并接单。
- 展示限制：
  - 在群页面或全域订单列表中：
    - 只有服务商能看到具体金额；
    - 普通消费者看不到金额。

### 8.4 订单生命周期（概念）

- 典型状态流：
  - 已发单 → 待服务（需要填写上门时间）→ 已提交 → 已付款 → 已完成。
- 客户侧操作：
  - 在“已提交”中查看支付方式并确认；
  - 确认支付后进入“已付款”。
- 服务侧操作：
  - 服务方确认“已收款，结单”，进入“已完成”。

### 8.5 纯发单群模式

- 对于“只发单、不聊天”的群：
  - 群聊可以不保持实时连接；
  - 用户仅在手动刷新时看到新订单；
  - 群形态接近“单纯接单页面”，以降低系统实时成本。

---

## 九、「我的」与运营视角

- “我的”页面沿用现有商城结构：
  - 包含分销中心、订单、选品等模块。
- 统计以微信号为主视角：
  - 汇总展示该用户在不同房间、群中的运营情况；
  - 可按房间、群进行明细下钻。

---

## 十、后台与审计（功能级）

- 房间管理：
  - 房间申请审批；
  - 房间启用/禁用；
  - 房间级扣点/收费配置。
- 群管理：
  - 建群申请审核；
  - 群启用/禁用；
  - 群主调整；
  - 系统机器人驻入/移除。
- 审计日志：
  - 创建/修改房间、群；
  - 修改扣点与重要配置；
  - 关键权限调整（如群主、管理员变更）等操作均需记录。

---

**文档定位**：开发可读的功能说明（不含字段/接口细节）  
**用途**：指导后续接口设计、表结构设计与前后端实现拆分
-												no message

											
										
										
											2025-12-22 18:05:22 +08:00
+								<!-- @author Yifei.Kuang -->
 								# 房间 / 群 / 分销功能说明文档（开发视角）
 								## 一、整体架构
 								- 层级结构：
 								  - 平台 → 房间（Room）→ 群（Group）→ 群员 / 分销身份（Distributor）
 								- 身份核心：
 								  - 每条分销身份由「平台 + 房间 + 群 + 用户」组合唯一确定，用于分销归属和订单结算。
 								---
 								## 二、房间模块（Room）
 								### 2.1 房间功能点
 								- 创建房间申请：
 								  - 用户提交房间名称、头像、品牌注解等信息。
 								  - 后台审核通过后，生成房间，并指定房间主。
 								- 房间信息维护：
 								  - 房间主可编辑名称、头像、品牌注解。
 								- 房间顶部功能栏配置：
 								  - 默认显示「师傅库 / 商城 / 会话厅」三项。
 								  - 房间主可以修改显示文案（总字数受限），功能类型不变。
 								- 房间权限与扣点设置（后台）：
 								  - 是否开启本房间商城。
 								  - 是否允许本房间下的群进行选品。
 								  - 房间级扣点与收费策略配置。
 								- 房间切换：
 								  - 同一微信可加入多个房间，通过「切换圈子」在不同房间间切换。
 								---
 								## 三、群模块（Group）
 								### 3.1 建群与审核
 								- 在某房间内，用户可发起建群申请。
 								- 填写群基础信息（城市、区域、主营类目、群规模等）。
 								- 审核流程：
 								  - 房间主初审；
 								  - 后台终审；
 								  - 通过后创建群，申请人自动成为群主。
 								### 3.2 群基本操作
 								- 群信息维护：
 								  - 群主可编辑群名、介绍、主营描述等。
 								- 群状态控制（后台）：
 								  - 支持群的启用/禁用；
 								  - 禁用后，群内发单、接单、分销等操作关闭或受限。
 								- 群主变更：
 								  - 后台可在必要时调整群主（例如违规处理）。
 								### 3.3 群监管
 								- 支持在任意群中驻入“系统机器人/系统监管号”：
 								  - 具备基本群管理与后台数据采集、监控能力。
 								  - 用于运营与风险控制。
 								---
 								## 四、群员 / 分销身份模块
 								### 4.1 分销身份规则
 								- 每个用户在某「平台 + 房间 + 群」组合下对应一个分销身份。
 								- 同一微信在不同房间/群中拥有多个独立身份：
 								  - 每个身份有独立的分销链；
 								  - 后台视为多个“人”。
 								### 4.2 加入群与分销绑定
 								- 成员加入群时：
 								  - 若在该群下不存在分销身份，则系统为其创建一条新身份线。
 								  - 按既有三级分销规则绑定上级分销。
 								- 上下级分销关系：
 								  - 限定在当前群对应的分销线中，不跨群共享。
 								### 4.3 角色与权限（概念层）
 								- 群主：
 								  - 本群最高级分销；
 								  - 拥有选品、群配置、成员管理等高权限。
 								- 管理员：
 								  - 由群主任命，可拥有部分管理能力（禁言、审核、公告等）。
 								- 普通分销/群员：
 								  - 不能在群内进行选品；
 								  - 可以拉人建立下级分销关系。
 								---
 								## 五、会话厅与群聊相关功能
 								### 5.1 订单页面导航（左侧）
 								- 导航栏包含 4 项：
 								  - 资源库；
 								  - 商品城；
 								  - 会话厅；
 								  - 附近圈动态。
 								- 群主可以：
 								  - 修改导航名称（总字数有限制）；
 								  - 单独开放/禁用任一入口；
 								  - 与外层房间首页的导航机制保持一致。
 								- 右下角「会话大厅」按钮：
 								  - 进入群聊页面（中间页）；
 								  - 文案可改，群主/平台可控制是否可用。
 								### 5.2 资源库（A）
 								- 展示服务师傅资料与店铺：
 								  - 格式类似现有“师傅圈”，但样式可定制。
 								- 群主可设置仅群内成员可见，或继承房间级展示。
 								- 提供发布入口，支持基于群选品的类目发单。
 								### 5.3 商品城（B）
 								- 群级商城展示逻辑：
 								  - 与整体商城逻辑一致；
 								  - 差异在于：群商城的选品由群主独立配置。
 								- 所有人看到的商品、类目等均来源于群主选品结果。
 								- 首页热门类目默认服务类，可左滑出商品类目列表。
 								- 列表筛选按价格、评分、销量进行。
 								- 销量统计按整条商品聚合，不再按规格拆分。
 								### 5.4 会话厅（C）
 								- 会话厅为“会话/订单流”页面，不是群聊页面。
 								- 默认进入订单页时落在该列：
 								  - 支持上拉刷新；
 								  - 承载订单、系统相关信息的流式展示。
 								### 5.5 附近圈动态（D）
 								- 展示商家图文动态的“公共圈子”区域：
 								  - 默认名称为“附近圈动态”；
 								  - 群主可以改名，但含义不变（商家圈/动态圈）。
 								### 5.6 会话大厅图与编辑订单（E）
 								- 页面中部展示“会话大厅相关图”：
 								  - 使用会话大厅图的一部分放大，作为视觉入口。
 								- 支持进入“编辑订单/发单页”：
 								  - 编辑后的订单可发至全群；
 								  - 管理员可选择仅发送至单个客户。
 								---
 								## 六、群聊在线控制与刷新机制
 								### 6.1 在线人数限制
 								- 当群聊在线人数超过上限（群主/后台可配置）：
 								  - 群主与管理员不受上线限制，始终在线。
 								  - 系统自动将部分成员标记为离线：
 								    - 优先踢出近期未发言的成员；
 								    - 该过程对成员前端为“默默离线”，不会强制踢出页面。
 								### 6.2 重新上线与刷新
 								- 被标记为离线的成员：
 								  - 在输入框输入内容时，自动重新上线。
 								- 新进群但未发言的成员：
 								  - 一段时间后，输入框变为“消息刷新”按钮；
 								  - 点击后重新加载消息，并作为新上线行为。
 								- 在已超上线限制的状态下：
 								  - 新进入成员默认离线；
 								  - 需主动刷新或发言才开始拉取实时消息。
 								### 6.3 页面跳转与上线状态
 								- 在群聊中点击任何产品、品类跳转其他页面：
 								  - 无论是否超限，都视为离线（停止实时连接）。
 								- 从商品/其他页面返回群聊页：
 								  - 自动恢复为在线状态。
 								- 在商品页面点击“聊天”：
 								  - 跳回群聊，并恢复在线。
 								---
 								## 七、会话厅顶部类目与选品关系
 								### 7.1 顶部类目区
 								- 顶部显示：
 								  - 「全部」入口；
 								  - 若干热门类目。
 								- 热门类目：
 								  - 群主从本群的主营/重点品类中选定；
 								  - 可对特别重要的类目打红点标记。
 								- 展示方式：
 								  - 左右滑动；
 								  - 每行最多 8 个类目，最多展示两行。
 								### 7.2 选品关系
 								- 群主 = 分销顶层：
 								  - 群主在本群选品的结果，体现在“全部”和热门类目展示中。
 								- 群员：
 								  - 无法直接在群内进行选品；
 								  - 仅能浏览、转发商品并参与分销。
 								---
 								## 八、群内订单与全域订单
 								### 8.1 群内订单发起
 								- 在群聊页面可以通过以下方式生成群内订单：
 								  - 使用专门的“群内订单发单入口”；
 								  - 将当前输入框的文字通过快捷键转换为订单（跳转到发单确认页）。
 								- 生成的群内订单：
 								  - 在群聊中以订单卡片形式展示；
 								  - 提供“接单”按钮。
 								### 8.2 与专业版（师傅端）的联动
 								- 若群内发单时勾选“保险”等高级字段：
 								  - 该订单将按专业版（师傅端）逻辑处理；
 								  - 接单、保险、结算等均走专业端流程。
 								- 群主可配置：
 								  - 群内订单是否仅允许本群服务人员接单；
 								  - 或是否允许进入大厅，被所有专业师傅接单。
 								### 8.3 全域订单
 								- 群主可将部分群内订单开放到“全域订单池”：
 								  - 其他群的服务商也能在“全域订单”中看到这些订单并接单。
 								- 展示限制：
 								  - 在群页面或全域订单列表中：
 								    - 只有服务商能看到具体金额；
 								    - 普通消费者看不到金额。
 								### 8.4 订单生命周期（概念）
 								- 典型状态流：
 								  - 已发单 → 待服务（需要填写上门时间）→ 已提交 → 已付款 → 已完成。
 								- 客户侧操作：
 								  - 在“已提交”中查看支付方式并确认；
 								  - 确认支付后进入“已付款”。
 								- 服务侧操作：
 								  - 服务方确认“已收款，结单”，进入“已完成”。
 								### 8.5 纯发单群模式
 								- 对于“只发单、不聊天”的群：
 								  - 群聊可以不保持实时连接；
 								  - 用户仅在手动刷新时看到新订单；
 								  - 群形态接近“单纯接单页面”，以降低系统实时成本。
 								---
 								## 九、「我的」与运营视角
 								- “我的”页面沿用现有商城结构：
 								  - 包含分销中心、订单、选品等模块。
 								- 统计以微信号为主视角：
 								  - 汇总展示该用户在不同房间、群中的运营情况；
 								  - 可按房间、群进行明细下钻。
 								---
 								## 十、后台与审计（功能级）
 								- 房间管理：
 								  - 房间申请审批；
 								  - 房间启用/禁用；
 								  - 房间级扣点/收费配置。
 								- 群管理：
 								  - 建群申请审核；
 								  - 群启用/禁用；
 								  - 群主调整；
 								  - 系统机器人驻入/移除。
 								- 审计日志：
 								  - 创建/修改房间、群；
 								  - 修改扣点与重要配置；
 								  - 关键权限调整（如群主、管理员变更）等操作均需记录。
 								---
 								**文档定位**：开发可读的功能说明（不含字段/接口细节）
 								**用途**：指导后续接口设计、表结构设计与前后端实现拆分