# Go-IoT 双引擎平台 — 需求规格说明书

> **版本**：v4.1
> **日期**：2026-07-15
> **来源**：奇净共享平台需求审评版、4G物联网平台需求表、幻特4G通信协议、QMS接口文档
> **边界**：本文档仅描述业务需求。协议细节见设备端接入文档，API 设计见 api-design.md，数据模型见 er-diagram.md。

---

## 目录

1. [业务域定义](#1-业务域定义)
2. [角色体系](#2-角色体系)
3. [场景一：固定设备管理（Fixed）](#3-场景一固定设备管理fixed)
4. [场景二：共享设备租赁（Shared）](#4-场景二共享设备租赁shared)
   - [4.0 核心状态机](#40-核心状态机)
5. [外部集成](#5-外部集成)
6. [非功能需求](#6-非功能需求)
7. [术语表](#7-术语表)

---

## 1. 业务域定义

### 1.1 核心模型

> **角色 × 设备 × 动作 → 结果**

| 要素 | 说明 |
|------|------|
| **角色** | 谁 — 平台层：运营/财务/研发/运维；业务线层：设备管理员/普通用户/门店员工/门店管理员 |
| **设备** | 操作什么 — 自购设备（Fixed）/ 平台投放设备（Shared） |
| **动作** | 做什么 — 绑定控制 / 扫码用机 / 扫码计费 |
|**结果**| 产出什么 — 遥测数据 / 订单 / 结算单 / 工单 / 分润 |

### 1.2 两条业务线

| 维度 | 场景一（Fixed） | 场景二（Shared） |
|------|----------------|-----------------|
| **设备归属** | 用户自购 | 平台投放 |
| **品牌** | 幻影、幻静等 | 奇净（次氯酸发生器） |
| **核心闭环** | 扫码绑定 → 监控控制 | 扫码用机 → 按制液量计费 → 清结算 |
| **基础设施要求** | 4G 信号覆盖 | 4G 信号覆盖 + 自来水接入或抽水机 + 电源 |
| **用户-设备关系** | 多对多绑定（管理员/普通用户） | 单人单次租赁 |
| **计费模型** | 无 | 按制液量计费（设备完成工作后上报本次制液量，直接扣费）+ 余额 + 分润 |
| **业务线角色** | 设备管理员 / 普通用户（2 类） | 普通用户 / 门店员工 / 门店管理员（3 类） |
| **平台角色** | 运营领导 / 财务管理员 / 研发管理员 / 运维人员（4 类，跨业务线） | |

### 1.3 产品矩阵

平台产品按业务线划分，同一产品内不同角色登录后渲染不同界面。

**Fixed 业务线**：

| 产品 | 使用角色 |
|------|---------|
| Fixed 小程序 | 设备管理员 / 普通用户（按角色叠加渲染界面） |

**Shared 业务线**：

| 产品 | 使用角色 |
|------|---------|
| Shared 小程序 | 普通用户 / 门店员工 / 门店管理员 / 运维人员（按角色叠加渲染界面） |

**平台层（跨业务线）**：

| 产品 | 使用角色 |
|------|---------|
| Web 管理后台 | 运营领导 / 财务管理员 / 研发管理员 / 运维人员 |

---

## 2. 角色体系

角色分为两个层级：

- **平台层**：通过 Web 管理后台管理全平台，跨两条业务线
- **业务线层**：在各业务线小程序内按角色渲染不同界面

### 2.1 角色全景图

```
┌──────────────────────────────────────────────────────────────────┐
│                       Go-IoT 双引擎平台                            │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                   平台层（Web 管理后台）                      │ │
│  │  运营领导（全局审核）│ 财务管理员（资金）│ 研发管理员（技术）│ 运维人员（工单）│ │
│  └────────────────────────────────────────────────────────────┘ │
│                              │                                   │
│            ┌─────────────────┴─────────────────┐                 │
│            │                                   │                 │
│  ┌─────────┴─────────┐             ┌───────────┴───────────┐    │
│  │  Fixed 业务线      │             │  Shared 业务线          │    │
│  │  （固定设备管理）    │             │  （共享设备租赁/奇净）    │    │
│  │                   │             │                       │    │
│  │  小程序            │             │  小程序                 │    │
│  │  ├ 设备管理员      │             │  ├ 普通用户              │    │
│  │  └ 普通用户        │             │  ├ 门店员工              │    │
│  │  （按角色叠加渲染）  │             │  ├ 门店管理员            │    │
│  │                   │             │  └ 运维人员              │    │
│  │                   │             │  （按角色叠加渲染）        │    │
│  └───────────────────┘             └─────────────────────────┘    │
└──────────────────────────────────────────────────────────────────┘
```

### 2.2 平台层角色（跨业务线）

平台层角色通过 Web 管理后台统一管理 Fixed 和 Shared 两条业务线。角色权限通过 RBAC 表（roles/menus/role_menus/user_roles）动态配置，可按需新增角色或调整权限，不固化角色定义。以下为初始预置角色：

| 角色 | 入口 | 分管范围 | 典型权限 |
|------|------|----------|----------|
| **运营领导** | Web 后台 | Fixed + Shared | 全平台经营数据查看、门店入驻审核（含分润比例确认）、结算审核、工单终审、用户风控 |
| **财务管理员** | Web 后台 | Fixed + Shared | 充值/扣费流水、退款审核、门店分润统计、结算单生成与审核、打款状态管理 |
| **研发管理员** | Web 后台 | Fixed + Shared | 设备入库、参数配置、通信密钥管理、系统参数、权限角色分配、OTA 升级、审计日志 |
| **运维人员** | Web 后台 + Shared 小程序 | Fixed + Shared | 工单接收/到场核验/维修记录/拍照存档/完结工单/设备维护状态切换；小程序端：创建门店草稿、设置分润比例（需后台审核后生效） |

> 数据库 role_key 示例：运营领导=`platform_ops_leader`，财务管理员=`platform_finance`，研发管理员=`platform_dev`，运维人员=`platform_maintainer`。实际角色和权限通过后台菜单权限配置动态管理，不写死。

### 2.3 Fixed 业务线角色

| 角色 | 入口 | 说明 |
|------|------|------|
| **设备管理员** | Fixed 小程序 | 首个扫码绑定设备的用户；包含普通用户的全部设备控制权限，额外可管理设备下的普通用户（解绑/删除） |
| **普通用户** | Fixed 小程序 | 被设备管理员绑定或被邀请绑定同设备的用户；有设备控制权限，不可管理其他用户 |

> 注：以上角色为**按设备**划分，非全局角色。同一用户可在设备 A 为管理员，同时在设备 B 为普通用户。以 `device_bindings.is_admin` 字段逐设备记录。小程序内「我管理的设备」（F-03）和「可控制的设备」（F-04）分别展示不同角色下的设备列表。

### 2.4 Shared 业务线角色

| 角色 | 入口 | 核心权限 | 禁止权限 |
|------|------|----------|----------|
| **普通用户** | Shared 小程序 | 登录注册、实名认证、扫码用机、余额充值/扣费、查看订单、申请退款 | 门店管理、平台后台 |
| **门店员工** | Shared 小程序 | 查看本门店设备状态、辅助扫码、紧急停机、提交报修、查看个人工单 | 分润/结算/员工管理/跨门店 |
| **门店管理员** | Shared 小程序 | 包含员工权限 + 门店订单/分润/收入、结算查询、员工管理、本门店全量设备 | 跨门店/平台级配置 |

> 注：Fixed 的"普通用户"与 Shared 的"普通用户"是不同角色——前者是设备绑定关系中的普通成员，后者是租赁消费者。两者权限不同，通过 `role` + `device_mode` 区分。
>
> 注：同一用户可同时拥有多条业务线的身份（如既是 Fixed 设备管理员，又是 Shared 消费者），各身份权限独立，互不冲突。

---

## 3. 场景一：固定设备管理（Fixed）

> 用户自购设备 → 扫码绑定 → 远程监控控制。Fixed 目前无独立商业模式，核心是实现设备的 4G 物联网能力。
> 品牌：幻影、幻静等
>
> **运维模型**：Fixed 为自服务模式。平台提供设备数据监控和故障告警，用户自行处理设备问题。平台不派运维人员上门——设备售后由厂商负责，平台仅提供数据支撑。

### 3.1 Fixed 小程序

#### 3.1.1 设备绑定与管理

| ID | 功能 | 描述 |
|----|------|------|
| F-01 | 扫码绑定设备 | 扫机身二维码绑定设备；同设备可被多用户绑定；首个绑定者为**管理员**，后续为**普通用户**。设备处于"无主"状态时，首个扫码绑定者重新成为管理员 |
| F-02 | 自定义设备名称 | 用户可修改已绑定设备的显示名称 |
| F-03 | 我管理的设备 | 列出作为管理员绑定的设备，可删除普通用户 |
| F-03a | 自解绑设备 | 用户自行解绑某台设备；管理员解绑后自动转移管理员给下一位最早绑定者；若无其他绑定者，设备进入"无主"状态。无主设备在 Web 后台设备列表中标记，研发管理员可为无主设备指定新的 owner_id，指定后新 owner 首次扫码即成为管理员 |
| F-04 | 可控制的设备 | 列出有操作权限的所有设备（管理员+普通） |

#### 3.1.2 设备控制

| ID | 功能 | 描述 |
|----|------|------|
| F-05 | 远程启停 | 远程启动/停止设备 |
| F-06 | 多机联动 | 选择多台绑定设备同时控制 |
| F-07 | 启动设置 | 设置单次工作时长、工作模式 |
| F-08 | 高级设置 | 远程设置启动温度、泵占空比、清洗时间；手动触发保养（用户自行执行，非平台派运维） |

#### 3.1.3 数据展示

| ID | 功能 | 描述 |
|----|------|------|
| F-09 | 设备状态 | 温度、联网状态、工作状态（待机/加热/喷射）、泵状态、加热器状态 |
| F-10 | 运行统计 | 可用时间、单次工作时间、累计工作时间、工作倒计时 |
| F-11 | 设备信息 | 设备编号、4G 信号强度、设备名称、软件版本、4G 编号 |

#### 3.1.4 故障处理闭环

设备故障采用自服务模型，不生成工单、不派运维。完整闭环如下：

```
设备上报告警 → 平台记录 device_alarms
    │
    ├─→ 小程序推送消息给用户（F-12）
    │
    ├─→ 用户点击消息 → 进入故障详情页（F-12a）
    │     ├ 告警类型（高温/需保养/离线）
    │     ├ 当前设备状态（温度/工作状态）
    │     ├ 操作指引（检查通风、检查电源、重启设备）
    │     └ [执行操作] 按钮（F-05 远程启停）
    │
    └─→ Web 后台故障日志（F-18），供平台方查看设备质量趋势
```

| ID | 功能 | 描述 |
|----|------|------|
| F-12 | 异常消息推送 | 高温报警、需冲洗保养时推送小程序消息，点击进入故障详情页 |
| F-12a | 故障详情与处理 | 展示告警类型、当前设备状态、操作指引（如重启、检查通风、联系售后）。用户可在页面直接操作设备（启停 F-05） |

### 3.2 Web 后台管理（Fixed）

| ID | 功能 | 描述 |
|----|------|------|
| F-13 | 登录与角色权限 | 管理员账号登录，按角色展示不同视图 |
| F-14 | 用户数据管理 | 全量用户表格、搜索筛选 |
| F-15 | 设备列表管理 | 设备信息展示、搜索、筛选、导出 |
| F-16 | 绑定关系管理 | 查看/手动解除用户-设备绑定 |
| F-17 | 操作记录 | 用户绑定/解绑/控制指令日志 |
| F-18 | 故障日志 | 设备故障告警查询（仅查询，无工单处理）。供平台方分析设备质量趋势 |
| F-19 | OTA 升级 | 固件上传、单台/批量远程升级。升级前校验设备空闲，运行中设备拒绝升级 |
| F-20 | 数据报表 | 设备使用率、平均工作时长、区域活跃度 |
| F-21 | 历史数据查询 | 设备历史运行曲线 |
| F-22 | 数据导出 | Excel 导出设备/用户/故障/运行数据 |
| F-23 | 数据可视化 | 图表看板 + 地图设备分布 |

---

## 4. 场景二：共享设备租赁（Shared）

> 平台投放设备 → 用户扫码用机 → 按制液量计费 → 门店分润 → 结算打款
> 品牌：奇净（次氯酸发生器）

### 4.0 核心状态机

**生产订单状态转换（production_orders.status）**：

```
         ┌─────────┐
         │ running │──────────────┐
         └────┬─────┘              │
              │                    │
         ┌────▼──────┐      ┌──────▼─────┐
         │ completed │      │   error    │
         └───────────┘      └──────┬─────┘
              ▲              ▲     │
              │              │     │
         ┌────┴──────┐      │     │
         │  stopped  │──────┤     │
         └──────┬────┘      │     │
                │           │     │
                └───────────┘     │
              (10min超时)   ┌─────▼─────┐
                            │  refunded │
                            │  (终态)   │
                            └───────────┘
```

| 状态 | 含义 | 可转换到 |
|------|------|----------|
| running | 设备已启动，生产中 | completed, stopped, error |
| completed | 正常完成，已扣费 | —（终态） |
| stopped | 用户主动停止，等待设备上报实际产量后结算。若停止后 10 分钟仍未收到产量上报，订单自动转 error，按实际已制液量扣费（若为 0 则不扣费），差额退款至用户余额 | completed, refunded, error |
| error | 设备故障/通信异常。已制液部分按实际扣费，未制液部分免收；差额退款至用户余额 | refunded |
| refunded | 已退款 | —（终态） |

### 4.1 Shared 小程序 — 普通用户视图

#### 4.1.1 登录与首页

| ID | 功能 | 描述 |
|----|------|------|
| S-01 | 微信授权登录 | 获取用户身份，绑定手机号 |
| S-02 | 首页设备展示 | 按场地展示附近设备状态、可用性、价格、导航 |
| S-03 | 首页轮播图 | 活动、设备宣传 |

> **扫码行为分流**：同一设备二维码，系统根据扫码者角色进入不同页面。普通用户直接进入启动确认页（S-07）。门店员工/管理员进入设备详情页（S-28），如需自行使用设备可在详情页点击「开始使用」进入消费者流程。运维扫码行为取决于当前所在 tab：首页 tab → 维护诊断页，工单 tab → 到场核验（S-68），安装 tab → 安装定位（S-65）。

#### 4.1.2 扫码用机（核心闭环）

> **首次使用流程**：新用户扫码后可免充值免认证直接使用一次（单次费用上限见 S-75 配置），使用完成后提示本次消费金额，引导充值。累计消费达阈值后要求实名认证。

| ID | 功能 | 描述 |
|----|------|------|
| S-04 | 扫设备二维码 | 识别设备编号、场地、门店归属和可用状态 |
| S-04a | 首次免充值体验 | 新用户（无充值记录）可跳过余额校验直接启动一次，单次费用上限由 S-75 配置。达到上限时自动停止（同 S-08a 机制），已制液量超出上限的差额部分平台承担，记录异常订单供复核，触发免单工单进入 S-14 审核流程。使用完成后提示本次消费，引导充值 |
| S-05 | 延迟实名认证 | 累计消费未达阈值时可跳过实名；达阈值后启动时强制引导认证，未完成则拒绝启动 |
| S-06 | 设备可用性校验 | 在线、空闲、未维护、无故障。非首次用户还需余额不低于最低启动金额 |
| S-07 | 使用前确认 | 单价（元/升）、预估费用、安全提示（次氯酸具腐蚀性，请现制现用，存放不超过 24 小时） |
| S-08 | 使用中实时状态 | 运行状态、预计费用（设备制液量在完成工作后上报，使用中显示的"已制液量"为预估值） |
| S-08a | 余额不足自动停止 | 运行中余额降至最低消费以下时，自动下发停止指令。已制液量按实际扣费，若超出剩余余额则以剩余余额为上限扣费，差额部分平台承担（记录异常订单供复核）。触发免单工单进入 S-14 审核流程 |
| S-08b | 超时自动停止 | 达到计费配置中的"最长运行时长"后自动停止，防止设备无限运行 |
| S-08c | 设备离线处理 | 运行中设备连续 2 分钟无心跳上报，订单自动进入 error 状态，等待人工复核退款 |
| S-08d | 完成取液提醒 | 设备完成制液后推送通知提醒用户取液；若 30 分钟内无下一次使用则标记订单完成 |
| S-09 | 异常提示 | 启动/停止失败提示 |

#### 4.1.3 余额与支付

| ID | 功能 | 描述 |
|----|------|------|
| S-10 | 余额充值 | 实名认证 → 微信支付充值（当前为 Mock 模式，需接入微信支付 API v3）。首次使用后展示"本次消费 X 元，充值更方便"引导。支付回调需做幂等处理（同一 wechat_trade_no 重复回调不重复加款）。回调失败时订单保持 pending，支持后台手动对账补单 |
| S-11 | 余额明细 | 充值、扣费、退款、赠送记录。赠送余额不可提现退款，消费时优先扣赠送余额再扣充值余额 |
| S-12 | 余额不足提醒 | 预估费用大于余额时引导充值 |

#### 4.1.4 订单与退款

| ID | 功能 | 描述 |
|----|------|------|
| S-13 | 订单详情 | 设备、场地、时间、费用、优惠、扣费、状态 |
| S-14 | 异常免单展示 | 免单原因和订单关闭状态。系统自动触发（余额不足/设备离线/计费异常）或用户申请，均生成工单走后台审核 |
| S-15 | 余额退款申请 | 提交退款工单、金额、原因。前置条件：无进行中订单、无冻结中的余额。审核通过 → 退款到微信支付原路返回。审核驳回 → 通知用户驳回原因，用户可重新提交 |

#### 4.1.5 个人中心

| ID | 功能 | 描述 |
|----|------|------|
| S-16 | 用户资料 | 昵称、头像、手机号、余额、实名状态、会员等级、积分 |
| S-17 | 用户反馈 | 故障反馈、投诉、咨询，可上传图片。提交后生成内部工单进入后台工单列表（S-66），由运营领导或运维处理。处理完成后用户在小程序「我的反馈」中收到回复通知 |
| S-18 | 帮助中心 | 常见问题、计费规则（按制液量）、教程、搜索 |

#### 4.1.6 营销

> 当前版本仅实现优惠券（S-19）。会员体系、满减活动、权益卡、积分体系为后续版本规划。

| ID | 功能 | 描述 |
|----|------|------|
| S-19 | 优惠券 | 面额、门槛、有效期、适用场景、下单抵扣。使用优惠券的订单发生退款时，若优惠券仍在有效期内则自动返还，已过期的优惠券作废不返还 |
| S-20 | 会员体系 | 等级、权益、升级进度、有效期、计费优惠（后续版本） |
| S-21 | 满减活动 | 自动匹配、抵扣、明细展示（后续版本） |
| S-22 | 权益卡 | 付费权益卡、剩余次数、有效期、适用场景（后续版本） |
| S-23 | 积分体系 | 积分获取/消耗/兑换、明细、过期提醒（后续版本） |

#### 4.1.7 商城（后续版本）

| ID | 功能 | 描述 |
|----|------|------|
| S-24 | 商品列表 | 耗材、周边、服务套餐 |
| S-25 | 商品下单支付 | 余额或微信支付（当前为 Mock，需接入微信支付 API v3） |

#### 4.1.8 消息通知

| ID | 功能 | 描述 |
|----|------|------|
| S-26 | 订单/异常通知 | 充值成功、订单结束、免单、退款、告警、取液提醒、被门店停止通知 |

### 4.2 Shared 小程序 — 门店角色与运维视图

同一小程序，按角色叠加渲染界面。门店员工 / 门店管理员 / 运维人员登录后看到的界面和功能。

> **门店入驻流程**：运维到现场安装设备 → Shared 小程序「新建门店」填写名称/地址/联系人/建议分润比例 → 生成门店邀请码（二维码）→ 门店管理员扫码加入 → 补全营业执照/结算账户（运维可现场协助）→ 提交后台审核 → 运营领导审核通过并确认分润比例 → 门店激活 → 门店管理员自行添加员工。

| ID | 功能 | 描述 |
|----|------|------|
| S-27 | 门店设备列表 | 本门店下场地内的设备、在线/运行/故障状态 |
| S-28 | 设备详情 | 实时运行参数、最近订单、告警状态 |
| S-29 | 引导扫码 | 辅助顾客扫设备码（不代替付款） |
| S-30 | 紧急停止 | 安全或现场原因停止本门店设备。紧急停止后订单进入 stopped 状态，不自动退款，需后台审核决定是否免单。审核通过 → 订单转 refunded（全额退）。审核不通过 → 订单转 completed（正常扣费）。同时推送通知给被停止的用户 |
| S-31 | 提交报修 | 故障说明、照片、设备编号。提交后生成维修工单进入 S-66 待处理列表 |
| S-31a | 查看个人工单 | 查看自己提交的工单或分配本人的维修工单，按状态筛选 |
| S-32 | 门店订单列表 | 本门店设备使用订单 |
| S-33 | 分润统计 | 订单金额、分润比例、预计可结算金额 |
| S-34 | 结算记录 | 周期结算单、结算状态、打款记录 |
| S-35 | 员工管理 | 门店管理员生成员工邀请码（二维码），员工扫码自动绑定为门店员工。支持增删、启用/禁用、角色分配。移除员工时，其已分配但未完成的工单自动退回 S-66 待处理池。门店至少保留一名管理员，不允许移除最后一位管理员 |

### 4.3 Web 管理后台

#### 4.3.1 数据看板

| ID | 功能 | 描述 |
|----|------|------|
| S-36 | 经营概览 | 总订单数、日/月收入、活跃用户、设备在线率/利用率/故障率、退款率、分润总金额 |
| S-37 | 设备排行 | 场地/门店/单设备统计排行 |

#### 4.3.2 用户管理

| ID | 功能 | 描述 |
|----|------|------|
| S-38 | 用户列表 | 全量用户信息、账户数据、关联数据，搜索/筛选/导出 |
| S-39 | 用户状态管控 | 黑名单（禁止登录和使用，若有进行中订单则系统自动下发停止指令后生效）、限制启动、冻结余额（冻结时若有进行中订单，待订单完成后生效）。黑名单用户仍可申请余额退款（S-15），审核通过后原路退回。以上操作均留存日志 |

#### 4.3.3 设备管理

| ID | 功能 | 描述 |
|----|------|------|
| S-40 | 设备入库 | 批量/单个创建、录入编号（SN 为设备机身标识，由厂商提供）/自动生成密钥、录入型号（code_prefix，通过 model_mode_maps 映射到 fixed/shared 业务线）/参数 |
| S-41 | 设备绑定场地 | 关联/转移/解绑场地，记录历史。场地坐标以运维安装定位（S-65）为准 |
| S-42 | 设备状态监控 | 通信状态（在线/离线）+ 业务状态（空闲/运行中/故障/维护中），传感器实时数据。通信状态取自 devices.status，业务状态取自最新遥测 device_telemetry.work_status |
| S-43 | 设备控制 | 远程停止/重启/禁用/启用，强制审计日志。禁用设备前检查无进行中订单，若有则提示"设备使用中，请等待当前订单完成" |
| S-44 | 参数配置 | 单设备/批量配置运行参数，修改留日志 |
| S-45 | OTA 升级 | 单台或批量远程升级。升级前校验设备状态：无进行中订单（Shared）或设备空闲（Fixed），运行中设备拒绝升级 |

#### 4.3.4 场地 & 门店管理

| ID | 功能 | 描述 |
|----|------|------|
| S-46 | 场地管理 | 增删改场地、地址/区域/绑机/定价/运营状态/营收统计。场地支持三种定价模式：<br>① **系统默认**：未设置场地定价时使用 S-75 中的系统默认单价<br>② **绝对定价**（price_override）：锁定固定单价，不受系统调价影响，适合签了合同的合作场地<br>③ **折扣优惠**（discount_ratio）：按系统默认价 × 折扣率计费，系统调价时自动跟随，适合促销场景 |
| S-47 | 门店资料 | 分两阶段：①运维创建草稿（名称/地址/联系人/建议分润比例）→ ②门店管理员扫码加入后补全（营业执照照片/结算账户信息）。草稿状态门店不可运营。草稿超过 7 天未被激活则自动作废。门店停用前需确认无进行中订单，若有则等待完成后执行。停用时：强制生成当期结算单，设备解绑场地进入待分配状态，员工账号全部禁用 |
| S-47a | 门店邀请码 | 运维创建门店草稿后生成邀请二维码，门店管理员扫码自动绑定为该门店管理员 |
| S-48 | 门店分润比例 | 运维提交建议分润比例，后台审核通过后生效。支持阶梯规则、修改历史 |
| S-49 | 门店员工管理 | 门店子账号增删、启用/禁用、角色分配 |

#### 4.3.5 订单 & 资金

| ID | 功能 | 描述 |
|----|------|------|
| S-50 | 设备订单 | 订单编号/用户/设备/场地/门店/制液量/计费/优惠/扣费/状态，筛选导出 |
| S-51 | 异常订单 | 自动免单/启动失败/停止失败/离线/计费异常，人工复核 |
| S-52 | 充值记录 | 全量微信充值流水，支持异常排查/导出。含 pending 状态订单的对账功能，支持手动补单 |
| S-53 | 扣费流水 | 订单扣费/退款/活动赠送/调整记录 |
| S-54 | 退款审核 | 审核用户余额退款申请 |

#### 4.3.6 分润结算

| ID | 功能 | 描述 |
|----|------|------|
| S-55 | 结算单生成 | 按周期（默认自然月，可配置为自然周/半月）生成门店应结算金额。已退款订单的分润从下一结算周期中扣回（结算逆转）。当期待结算金额为 0 时跳过生成。订单按完成时间（end_time）归属结算周期 |
| S-56 | 结算审核 | 审核结算单、记录打款状态 |

#### 4.3.7 营销 & 商城管理

| ID | 功能 | 描述 |
|----|------|------|
| S-57 | 优惠券管理 | 创建/发放/核销/过期/门槛 |
| S-58 | 满减活动 | 时间/范围/门槛/优惠金额（后续版本） |
| S-59 | 积分规则 | 获取/消耗/兑换/过期规则（后续版本） |
| S-60 | 商品管理 | 商品/库存/价格/上下架（后续版本） |
| S-61 | 商城订单 | 商品订单/支付/发货/售后（后续版本） |

#### 4.3.8 告警 & 工单

| ID | 功能 | 描述 |
|----|------|------|
| S-62 | 告警中心 | 设备告警：离线/故障/低液位/温度异常/电流异常/位置偏差。当前 schema 已支持离线/温度异常(over_temp_1/over_temp_2)/低液位(liquid_low)/清洗提醒(clean_remind)，需新增故障(fault)、电流异常(current_abnormal)、位置偏差(location_deviation)告警类型 |
| S-62a | 耗材不足告警 | 原料（盐/电解质）耗尽或即将耗尽时自动生成耗材补货工单，进入 S-66 待处理列表，派发给运维人员 |
| S-63 | 工单派发 | 查看系统生成的工单并派给运维人员 |
| S-64 | 工单审核 | 查看处理记录/照片/结果，必要时驳回 |

**运维人员工单操作**（运维登录 Shared 小程序后执行）：

| ID | 功能 | 描述 |
|----|------|------|
| S-65 | 设备安装定位 | 运维安装设备时小程序自动获取 GPS 坐标 → 设为设备位置和所属场地的权威坐标 → 写入 devices.lat/lng 和 sites.lat/lng。手机 GPS 精度（5-15m）远高于设备 4G 基站定位，以此为权威源 |
| S-65a | 位置偏差告警 | 设备上报的 4G 基站定位与安装 GPS 坐标偏差超过阈值（如 500m）时自动告警，提示设备可能被移动或 4G 模块异常 |
| S-66 | 待处理工单 | 故障/低液位/电流异常/离线/耗材补货等工单列表，筛选排序 |
| S-67 | 接单 | 确认接收、记录接单时间、状态更新、回执推送。接单后 4 小时未到场扫码（S-68），工单自动退回 S-66 待处理池 |
| S-68 | 到场扫码 | 扫描设备码完成身份核验、记录到场时间/定位 |
| S-69 | 处理记录 | 故障原因、维修过程、更换配件、参数调试 |
| S-70 | 拍照上传 | 处理前/中/后照片，关联工单存档 |
| S-71 | 完成工单 | 标记完成（恢复正常/需持续维护）→ 推送后台审核 |
| S-72 | 维护状态切换 | 进入维护锁定（禁止扫码），解锁恢复。若设备上有进行中订单，拒绝进入维护模式，提示"设备使用中，请等待当前订单完成"。维护完成并解锁后，若关联工单则自动标记工单为已处理 |
| S-72a | 定期保养工单 | 按设备运行时长自动生成保养工单（电解槽清洗、管路冲洗），进入 S-66 待处理列表，派发给运维人员 |
| S-73 | 历史工单 | 个人历史工单查询，按时间/类型/状态筛选 |

> **工单处理流程**：S-66 待处理列表 → 点击接单（S-67）→ 到场扫设备码核验（S-68）→ 填写处理记录（S-69）→ 上传照片（S-70）→ 提交完成（S-71）。整个流程为同一工单的多步骤操作，在小程序中以单页面逐步推进，非多个独立页面。

#### 4.3.9 系统管理

| ID | 功能 | 描述 |
|----|------|------|
| S-74 | 角色权限配置 | 平台层 4 角色 + Shared 业务线 3 角色的权限配置 |
| S-75 | 计费配置 | 默认单价（用户界面：元/升；存储：分/mL）、最低消费（设备产量为 0 时不收取，仅产量 > 0 时生效）、封顶价（达到后停止计费，设备继续运行直至完成或超时）、最长运行时长（安全保护，超时自动停止）、折扣系数、首次免充值单次费用上限、实名认证消费阈值。场地定价优先级见 S-46。系统对设备上报的产量做合理性校验：单次产量超过最大产能阈值（如 50L）时拒绝入账，生成异常订单人工复核 |
| S-76 | 操作日志 | 后台操作/设备控制/退款/结算/参数变更 |

---

## 5. 外部集成

### 5.1 QMS 设备真伪校验

用户扫码绑定设备时，需校验设备编码是否在 QMS（质量管理系统）中备案，拦截非授权设备。

| 参数 | 值 | 说明 |
|------|-----|------|
| 接口 | `POST /qms/iot/user/track` | 批量查询设备在库状态 |
| 超时 | 3 秒 | 单次请求 |
| 重试 | 最多 2 次，间隔 1 秒 | 超时后重试 |
| 降级策略 | 网络不可达时降级放行 | 避免 QMS 故障导致所有绑定阻塞，记录 WARN 日志 |
| 校验结果 | data 非空=通过 / data 为空=拒绝 | 校验失败时拒绝绑定并提示用户 |

> 详细接口说明见 `qms_api.md`。

### 5.2 设备通信

设备通过 4G 模块与平台建立长连接，支持数据上报和指令下发双向通信。通信协议细节见设备端接入文档。

---

## 6. 非功能需求

### 6.1 性能

| 指标 | 要求 |
|------|------|
| 设备并发连接 | 初始部署目标 100 台，架构设计支持 ≥ 10,000 设备同时在线 |
| API 并发 | ≥ 1,000 请求/秒（核心接口） |
| 指令下发延迟 | P99 < 3 秒 |
| 实时状态推送延迟 | < 1 秒 |

### 6.2 可用性

| 指标 | 要求 |
|------|------|
| 系统可用性 | 99.5%（月故障时间 < 3.6 小时） |
| 设备离线检测 | 连续 3 次心跳超时 → 离线告警 |

### 6.3 安全

| 要求 | 说明 |
|------|------|
| 接口鉴权 | 管理后台和小程序 API 均需身份认证，管理后台额外要求角色权限校验 |
| 设备认证 | 每设备唯一标识符 + 密钥 |
| 防重放 | 控制指令需具备幂等性 |
| 防重复扫码 | 同一设备同一时刻仅允许一个用户使用 |
| 关键操作审计 | 设备控制/退款/结算/参数变更需记录操作日志 |
| 数据保留 | Fixed 和 Shared 数据均永久保留，不做自动清理 |
| 数据隔离 | Fixed 和 Shared 两条业务线数据隔离 |
| 通信质量 | MQTT QoS：上行 QoS 0（高频遥测），下行 QoS 1（控制指令需确保送达） |

### 6.4 可维护性

| 要求 | 说明 |
|------|------|
| 结构化日志 | 统一日志格式，关键操作可追溯 |
| 统一错误响应 | 所有 API 使用统一的错误响应格式 |
| 健康检查 | 系统需提供健康检查端点，报告关键依赖连通性 |
| 配置管理 | 配置与代码分离，支持运行时注入 |

---

## 7. 术语表

| 术语 | 定义 |
|------|------|
| **Fixed** | 固定设备管理模式，用户自购设备 → 扫码绑定 → 监控控制 |
| **Shared** | 共享设备租赁模式，平台投放设备 → 扫码用机 → 按制液量计费 |
| **奇净** | 次氯酸发生器品牌，场景二（Shared）的主设备型号 |
| **幻影 / 幻静** | 场景一（Fixed）的工业设备品牌（幻特为 4G 通信协议名称，非设备品牌） |
| **场地** | 设备投放的地理位置，包含经纬度、地址，隶属于门店（门店表尚未实现，通过运营后台直接管理场地） |
| **门店** | 合作商户，管理其下的场地和设备，参与分润 |
| **分润** | 门店按比例从设备使用收入中获得的分成 |
| **结算单** | 按周期生成的门店分润结算凭证，需审核后打款 |
| **工单** | 设备故障/告警自动生成或人工提交的维修任务 |
| **OTA** | Over-The-Air，远程固件升级 |
| **QMS** | 质量管理系统，提供设备真伪校验（外部系统） |
| **幻特** | 4G 通信协议名称（幻特4G通信协议），非设备品牌，Fixed/Shared 共用该协议接入 |
| **维护锁定** | 运维人员在后台将设备置为维护状态，期间禁止扫码使用，维修完成后解锁 |
| **共享锁定** | 平台层管控手段，可对共享设备执行强制锁定，禁止用户扫码启动 |