# 客满房非房收入平台｜硬件接入与协作开发方案 V6

版本日期：2026 年 10 月 1 日。

本文定义本轮 UI、交互原型和后续工程的业务边界。当前只做本地可交互原型、模拟厂家、模拟设备事件和演示账单；没有对接真实厂家、设备、支付或资金结算。页面和截图须持续显示“模拟演示”。

## 1. 产品范围：先选择接入模式

| 接入模式 | 适用例子 | 用户和系统流程 | 订单及收入口径 |
|---|---|---|---|
| 厂家外跳 + 对账 | 已有独立小程序或 H5 的充电宝厂家 | 点位扫码 → 展示厂家服务与规则 → 外跳厂家下单 → 厂家订单/账单回传或导入 → 匹配核对 | 点击外跳只是访问记录；订单确认、账单核对和结算分别记录 |
| 厂家 API 租借/计时解锁 | 充电宝柜、具备联网控制能力的计时充电线 | 点位扫码 → 计费规则 → 租借单 → 支付/授权 → 厂家指令 → 使用 → 归还/到期 → 对账 | 支付、解锁、使用结束、退款、结算各有状态，不相互代替 |
| 普通商品销售 | 充电线、非智能情趣用品、旅行用品 | 点位扫码 → 商品下单 → 商户备货/配送 → 用户收货 → 售后与分账 | 沿用“酒店售卖、商户供货履约”，与现有商品体系共用订单 |

充电线需要明确是买走的商品，还是计时解锁的设备；两者不能共用一个履约状态。情趣用品默认按普通隐私商品销售，只有确认具备联网、蓝牙或厂商控制能力的型号，才另行评估智能设备接入。普通商品不要伪造在线率、心跳、解锁或归还字段。

首期以一个模拟充电宝厂家、一个普通充电线供货目录和一个隐私商品目录证明三种流程。收费、分成、押金、预授权及赔付规则均为待确定的商业配置；原型出现的金额只用于交互示例。

## 2. 四级对象：厂家 → 型号 → 设备 → 点位

| 对象 | 必要字段 | 状态与约束 |
|---|---|---|
| 厂家 | 厂家 ID、名称、联系人、合作模式、接口文档版本、测试环境、售后责任、对账周期 | 待资料 → 测试中 → 待验收 → 验收通过 → 已上线；可暂停；模拟记录不得显示真实上线 |
| 型号 | 厂家 ID、型号 ID、产品类别、能力清单、计费方式、说明、接口映射版本 | 普通商品与设备型号分开；声明了能力才可出现对应控制动作 |
| 设备 | 厂家设备 ID、平台设备 ID、型号、SN/IMEI（厂家有才填）、固件、责任商户、在线状态、最近心跳、安装验收 | 在库、待安装、可用、占用、离线、故障、维修、停用、退役；联网状态与生命周期分开 |
| 点位 | 点位 ID、酒店、房间/公共区域、楼层、绑定设备、二维码版本、负责人、安装照片、验收记录 | 草稿、已启用、冻结、作废；房间位置不等于实名入住证明 |

四级对象表示资产管理路径，数据关系不能简单写成永久父子：同一设备可以先后部署到不同点位，一个点位也可以更换设备。部署关系单独记录开始时间、结束时间、安装人和版本；一个设备在同一时刻只能存在一个有效物理部署。充电宝柜与可借出的充电宝可另建父设备/子设备或槽位关系，归还到其他柜时必须保留原借出点位。

普通商品走“厂家/供货方 → 型号或 SKU → 库存 → 酒店在售”的路径，不要求为每条普通充电线创建设备资产。普通商品在房间货架销售时可关联点位，但不强制关联 SN。

二维码绑定平台点位及版本，避免把酒店、房间或设备编号直接当成可任意篡改的业务授权。旧码冻结后不可创建新订单，历史订单仍保留原点位与部署快照。

## 3. 售卖、履约、运维和分账责任

| 业务 | 售卖/服务主体 | 履约/运维主体 | 酒店职责 | 账务原则 |
|---|---|---|---|---|
| 外跳厂家服务 | 厂家或其指定运营商，在跳转前明确展示 | 厂家/运营商 | 提供点位、查看授权经营、报修 | 厂家确认的场景收益按合同核对；不把全部厂家流水当酒店所得 |
| 平台内 API 租借 | 由合作方案确定的运营商，订单显式展示 | 厂家云负责设备指令；约定运营商负责现场维修 | 场景、安装配合、经营查询和报修 | 收款主体、服务主体、设备责任方分别配置；上线前锁定合同和支付方案 |
| 普通商品 | 酒店（沿用当前业务要求） | 供货商户负责库存、配送和退换货 | 授权选品、在售和调价、销售与售后协同 | 商品交易额、供货份额与酒店所得分别核对 |

每笔订单保留销售/服务主体、履约机构、场景酒店、服务商、厂家及规则版本。厂家不天然等于商户，服务商不天然等于设备运营商，酒店也不自动拥有解锁和维修权限。同一机构兼任多个职责时仍分别记录。

分账只使用经确认的净交易基数；待支付、预算、押金/预授权、冻结资金均不视为可结算收入。厂家账单“已导入”不表示“核对通过”，核对通过不表示“已打款”。原始账单不得覆盖平台订单与支付记录；差异进入对账工单。

## 4. 各角色页面和权限矩阵

各 B 端均提供 PC 与管理小程序，使用相同权限与数据口径。现有服务商、酒店、商户和财务的“汇总 → 列表 → 明细”结构继续保留。

| 角色 | 首页重点 | 可操作 | 不开放的操作 |
|---|---|---|---|
| 总部接入/运营 | 厂家进度、设备覆盖、异常和对账差异 | 厂家/型号、能力配置、接入验收、设备映射、审计 | 不代用户确认使用，不凭运营按钮确认收款 |
| 总部财务 | 厂家账单、退款、待核对/可结算/已结算 | 对账复核、差异处理、授权结算流程 | 无设备远程控制、改写厂家原始账单权限 |
| 服务商负责人/安装运营 | 所辖酒店部署、离线与故障、安装待办 | 添加部署、安装验收、巡检、报修跟进；按分配处理工单 | 不代酒店接大消费订单，不任意修改设备收入 |
| 服务商财务 | 本服务商设备收益及明细 | 查看授权账单、提出差异 | 无设备配置和解锁权限 |
| 酒店店长 | 本店设备、点位、非房所得、报修 | 申请引入、确认场地、授权点位管理、查看和报修 | 不执行厂家解锁、不代维修人员完工 |
| 酒店前台 | 设备状态、客人异常、工单进度 | 本店报修及协助；收入按授权显示 | 无财务全表、API 密钥、调分账和远程控制 |
| 酒店财务 | 本店订单/退款/分账核对 | 本店金额明细及差异反馈 | 无设备绑定和履约权限 |
| 商户老板 | 商品库存、设备履约任务、经营汇总 | 商品配置、人员、补货/售后、分配运维任务 | 无其他商户和平台完整账本 |
| 商户员工/配送/维修人员 | 本人或被授权任务 | 商品配送、补货、维修记录；维修权需独立授予 | 到店按摩技师不会自动获得设备维修权限 |
| 用户 | 当前点位、可买商品/可租设备、本人订单 | 下单、支付/授权、使用、归还、售后 | 无机构经营与内部账单访问权 |

总部详情建议设“基础资料 / 接入能力 / 型号 / 设备与点位 / 事件 / 对账 / 审计”。酒店详情设“点位与设备 / 使用订单 / 酒店所得 / 报修”。服务商突出“安装任务 / 巡检 / 工单”，商户突出“库存补货 / 配送 / 维修 / 售后”。

模拟测试控制器必须标识为沙箱，不能混入普通酒店员工操作区域；模拟解锁、归还与故障仅供评审。

## 5. 三条流程及异常处理

### 5.1 充电宝 API 租借

点位扫码 → 查询可用设备和规则 → 建立租借单 → 支付或授权 → 请求解锁 → 收到设备取出事件 → 使用中 → 归还事件 → 核定租金 → 退款/争议处理 → 对账 → 达到条件后结算。

- 指令受理不等于柜门已开；柜门已开不等于已取出；取出不等于租借完成。
- 重复请求使用同一业务幂等键；重复事件不重复扣款、分账或推进状态。
- 指令超时先查询厂家原结果，不能盲目重发导致重复开柜。
- 归还先于取出等乱序事件进入待核查，不能直接跳过应有事实。
- 离线、无可借设备、点位冻结、厂家暂停时停止新单；在途订单与售后继续可查。
- 已扣款但未取出须有退款/人工处理入口，退款成功后以冲正记录影响账务。

### 5.2 普通充电线销售

扫码 → 商品规格 → 门店售价 → 锁库存 → 支付 → 商户接单 → 备货/配送或约定的自取 → 用户收货 → 售后 → 分账。

普通商品不出现解锁和归还按钮。厂家的计时充电线作为不同型号和业务类型另行配置，展示计时开始依据、价格、上限、到期处理和故障退款规则。酒店不代商户点配送完成。

### 5.3 隐私商品销售

扫码 → 隐私商品提示 → 商品详情 → 下单 → 商户备货和隐私配送 → 收货 → 售后与分账。

按实际商品类别配置适当的用户提示和购买条件，具体运营规则另行确认。酒店及无关员工默认查看“隐私商品”脱敏名称、履约状态和授权金额；供货履约人员只访问任务所需信息。普通商品不采集使用时长或个人偏好。智能设备绑定、控制、解绑和数据删除属于另一个能力包，不作为此流程前置条件。

### 5.4 外跳与账单核对

扫码 → 显示点位与厂家服务 → 记录一次导流事件 → 厂家页面下单 → 回传订单或导入账单 → 匹配订单/点位/设备 → 标记差异 → 复核 → 按合作口径确认收益。

外跳失败、无回传、账单缺行、重复账单、退款晚到均须有状态。没有厂家明细接口时只能展示账单覆盖周期和可信的汇总，不虚构实时租借状态。来源归因和厂家是否支持回传，需要在接入前确认。

## 6. 从 UI 到真实接入的协作关卡

本轮主协调智能体与 3 个协作智能体并行工作，文件各自负责，合并后统一验收。

| 智能体 | 本轮职责 | 后续代码开发职责 |
|---|---|---|
| 主协调 | 统一范围、共享模拟模型、合并、预览服务、出图与最终验收 | API 契约、数据层、权限集成、测试及发布统筹 |
| 产品架构与验收 | 流程、角色矩阵、四级对象、分阶段计划、只读业务审查 | 状态机和数据字典评审、验收用例、账务口径复核 |
| PC UI | 总部、酒店、服务商、商户硬件 PC 页面与视觉 | 页面接 API、权限/错误/空状态、端到端交互 |
| 小程序 UI | 对应 B 端移动页及驿呼百应硬件场景 | 小程序工程、同账号数据、真机交互和状态同步 |

| 关卡 | 可评审产物 | 通过条件 |
|---|---|---|
| G1 业务和页面设计 | 流程图、对象、角色、首页/列表/详情/异常结构 | 三种模式区分明确，售卖和履约职责无冲突 |
| G2 UI 修改与出图 | 实际可预览的 PC/小程序页面及关键截图 | 风格一致，主要入口齐全，模拟标识清楚，移动端无横向溢出 |
| G3 本地交互原型 | 厂家、点位、模拟订单/回调/报修联动 | 操作有结果；重复事件、失败和权限边界可演示 |
| G4 正式工程设计 | API 文档、数据库、服务端权限、事件/账务和部署方案 | 字段、责任和资金路径明确；厂家资料与测试权限可用 |
| G5 厂家真实联调 | 厂家沙箱、测试设备、指令/回调/退款/对账证据 | 正常与异常逐笔核对通过；密钥服务端保管 |
| G6 酒店试点 | 安装记录、真实测试订单、财务核对和售后演练 | 一家试点签收，再按结果扩大门店 |

G2/G3 交付的浏览器移动页面是小程序 UI 原型，不等于已发布微信小程序。G4–G6 需要真实厂家接口、设备、收款与小程序主体等资料；没有这些资料时可继续开发模拟适配器和内部服务，但不能宣称接入完成。

## 7. 厂家接入资料与实施步骤

厂家需提供联系人、产品/型号/设备清单、API 或 SDK 文档、沙箱、测试设备、状态/控制/事件接口、签名和错误码、幂等/重试规则、账单样例、退款和售后路径。外跳模式另提供跳转目标、参数和回传能力。计时设备另提供计费起止依据及到期行为；智能设备另提供绑定、解绑和数据处理能力说明。

接入步骤：收资料 → 判断模式与能力缺口 → 明确售卖/收款/运维/售后主体 → 字段与账单映射 → 模拟适配器 → 厂家沙箱 → 单台实物测试 → 单店安装验收 → 真实支付退款与对账 → 小范围上线。

密钥、设备控制和验签在正式系统服务端实现，不能放入浏览器、小程序包或截图。本轮不采集生产密钥、不联系外部厂家、不发起真实指令或付款。

## 8. 开发优先顺序

原有会议/团队/协议来源、商户核销、酒店商品和财务主线继续保留，硬件作为独立增量能力，不改写既有订单语义。

| 顺序 | 阶段 | 交付 | 依赖 |
|---|---|---|---|
| 1 | 本轮 UI/原型 | 厂家/型号/设备/点位，三种模式，PC 与移动角色入口、关键页面出图 | 共享模拟数据契约 |
| 2 | 本轮 UI/原型 | 充电宝模拟租借/解锁/归还、普通商品下单、报修、外跳对账状态 | 第 1 项对象及权限边界 |
| 3 | 正式 P0 | 后端组织权限、设备/点位关系、审计、模拟适配器和订单状态机 | API 与数据库设计冻结 |
| 4 | 正式 P0 | 选定一家充电宝厂家真实沙箱；支付/事件/退款/对账 | 厂家资料、测试设备、资金路径 |
| 5 | 正式 P0 | 普通充电线接现有商品履约，单店设备安装与报修、PC/小程序联调 | 稳定商品库存与支付接口 |
| 6 | 正式 P1 | 外跳账单导入、多厂家适配、批量部署、补货巡检、隐私商品运营 | 首店试点与售后记录 |
| 7 | 正式 P2 | 确有需求的智能设备控制、复杂计时/赔付、自动结算 | 厂家能力和商业规则独立评审 |

按关卡完成情况排期，不承诺固定上线日期。厂家资料不齐或缺少真实设备时，内部原型和模拟联调可继续推进，真实接入阶段需等对应依赖可用。

## 9. 业务验收清单

| 编号 | 场景 | 必须达到的结果 |
|---|---|---|
| H01 | 看三种接入模式 | 普通商品没有虚假的在线/归还，外跳没有虚假的实时履约，API 能力按型号控制 |
| H02 | 厂家/设备/点位停用 | 拦截新订单；在途订单、售后和历史归因仍可处理 |
| H03 | 设备转店或换点位 | 保留部署历史；旧订单仍归原点位，新单使用新绑定 |
| H04 | 酒店前台/财务/商户技师访问 | 无越权设备控制与分账；敏感商品按岗位脱敏 |
| H05 | 连点解锁与重复回调 | 一次有效指令、一次有效状态流转、一次账务记录 |
| H06 | 解锁超时或取出失败 | 显示待核查/退款处理，不冒充使用完成 |
| H07 | 乱序、错误签名、未知设备事件 | 不推进业务事实，进入异常处理并保留证据 |
| H08 | 归还/到期/取消 | 按模式结束使用，不把押金或授权额度计为收入 |
| H09 | 普通商品缺货/配送/退款 | 缺货拒绝新单；履约由商户执行；退款产生可追溯冲正 |
| H10 | 外跳一次或重复导入账单 | 外跳不新增支付收益；重复账单不重复入账；差异可定位 |
| H11 | 调价或修改分账规则 | 新单使用新版本；历史价格/规则快照不变 |
| H12 | PC 与小程序同一账户 | 同数据范围和权限；本地原型只承诺同源浏览器联动 |
| H13 | 账务核对 | 交易、退款、净额、各方份额和结算状态可逐笔追溯；汇总不混入预估 |
| H14 | 原型截图与页面文案 | 明确模拟厂家与设备、未接真实支付、未发布真实小程序 |

本轮至少以可复现的模拟场景核对 H01–H14 的已实现部分，并将未实现项记录为正式开发验收目标；不以“按钮存在”替代接口、设备或资金验收。真实上线前由业务、技术、财务共同核对设备证据、支付退款流水、厂家账单及售后责任。