[{"data":1,"prerenderedAt":197},["ShallowReactive",2],{"DEV_DOC-content":3,"search-index":97},[4,15,22,28,36,42,48,54,59,65,70,76,81,86,92],{"id":5,"module":6,"category":7,"slug":8,"title":9,"contentMd":10,"sort":11,"status":12,"updatedBy":13,"updatedAt":14},7,"DEV_DOC","快速开始","guide/intro","平台简介","# 平台简介\n\nCleanHub 智能保洁运维平台，面向物业/保洁运营方的「设备发现 → 规则决策 → 派单执行 → 结果验证」保洁闭环平台。\n\n## 核心能力\n\n- **接入平台化**：任何设备（摄像头/NVR/机器人/通知渠道）通过标准驱动包即插即用，无需修改核心代码\n- **规则可视化**：条件→动作 JSON DSL 拖拽编排，非技术人员可配置，实时生效可灰度可回滚\n- **消息总线**：Redis Streams（消费组/ACK/积压原生能力），延迟消息 ZSET 到期转流\n- **可观测性**：traceId 贯穿接入/决策/派发/结果四层，总线积压与分层状态实时可视\n- **多租户**：数据/设备/策略按租户隔离，一套平台管理多个项目，支持两段式注册与审核\n\n## 技术栈\n\n| 层 | 技术 | 说明 |\n|----|------|------|\n| 后端框架 | Spring Boot 3.2.5 + Java 17 | 平台核心 |\n| 消息总线 | Redis Streams | 四主题 + ZSET 延迟队列 |\n| 数据库 | MySQL 8.0 + MyBatis-Plus | 业务数据（33 张表） |\n| 缓存 | Redis 7 | 去重窗口、配置缓存、Streams |\n| RPC | gRPC | 驱动进程通信 |\n| 前端（控制台） | Vue 3 + Ant Design Vue + Vite | 40+ 页面模块 |\n| 前端（官网） | Nuxt 3 SSG + Ant Design Vue | site/help/docs 独立前端 |\n| 前端（企业工作台） | Vue 3 + Ant Design Vue + Vite | 独立 SPA |\n| 前端（飞书） | Vue 3 + Ant Design Vue + Vite | Hash 路由 H5 |\n| 前端（用户中心） | Vue 3 + Ant Design Vue + Vite | 独立 SPA，HashRouter |\n| 部署 | Docker Compose | MySQL/Redis 复用共享实例 |\n\n## 文档导航\n\n- 快速开始：环境与账号 → 首个集成示例\n- 核心概念：租户与项目 / 任务模型 / 驱动与设备\n- 开放平台：认证签名 / 在线接口文档 / 错误码\n- 驱动开发：gRPC 协议 / 模拟器对接 / 插件中心\n- 部署运维：安装与升级",1,"PUBLISHED","seed","2026-09-21T16:54:44",{"id":16,"module":6,"category":7,"slug":17,"title":18,"contentMd":19,"sort":20,"status":12,"updatedBy":13,"updatedAt":21},8,"guide/account","环境与账号","# 环境与账号\n\n## 系统组成\n\n| 组件 | 说明 |\n|------|------|\n| cleanhub-core | Spring Boot 核心（HTTP :8081 / gRPC :50051） |\n| MySQL | 业务数据（独立库 cleanhub，33 张表） |\n| Redis | 消息总线（Streams）+ 缓存/去重 |\n| 控制台 | Vue 3 + Ant Design Vue + Vite（静态托管） |\n| 官网 | Nuxt 3 SSG + Ant Design Vue（独立前端） |\n| 企业工作台 | Vue 3 + Ant Design Vue + Vite（独立 SPA） |\n| 飞书 H5 | Vue 3 + Ant Design Vue + Vite（移动端） |\n| 用户中心 | Vue 3 + Ant Design Vue + Vite（注册/登录/用户中心） |\n\n## 域名架构（6 站点）\n\n| 域名 | 职责 |\n|------|------|\n| cleanhub.la998.com | 官网独立前端（site/help/docs + 全产品入口） |\n| admin.cleanhub.la998.com | 控制台 SPA + /admin /api /ws 代理 |\n| api.cleanhub.la998.com | API 入口（外部集成） |\n| feishu.cleanhub.la998.com | 飞书 H5（直连 core:8081） |\n| tenant.cleanhub.la998.com | 企业工作台（直连 core:8081） |\n| person.cleanhub.la998.com | 用户中心 SPA（注册/登录/用户中心/申请企业） |\n\n## 管理账号\n\n- 初始账号：`admin / ChangeMe123!`（user 表为空时 core 首次启动自动创建）\n- **首次登录必须修改密码**（/admin/auth/change-password）\n- 角色：平台超级管理员（全部操作）/ 平台运维工程师 / 平台审计员 / 企业管理员 / 操作员 / 查看者\n- 平台级身份（account_identity.tenant_id=0）可管理全部租户，操作时显式指定 tenant_id\n\n## 账号体系（两段式注册）\n\n### 第一段：个人账号注册\n普通用户访问用户中心（person.cleanhub.la998.com）注册个人账号（仅需用户名+密码），注册成功即获得纯账号基座——无企业关联、无任何身份，可登录用户中心管理身份和申请加入租户。\n\n### 第二段：开通企业身份\n个人账号登录后可在用户中心提交企业开通申请（填写租户名称、联系人等信息），平台管理员审核通过后自动完成：\n- 为该用户开通所申请企业的成员身份（account_identity）\n- 自动绑定「企业管理员」预置角色\n- 用户获得该租户的管理权限，可登录企业工作台进行日常运维\n\n### 受邀加入\n已有个人账号的用户可通过邀请链接直接加入现有租户，无需重新注册；受邀后自动开通企业身份并绑定指定角色。\n\n## 多身份模型\n\n同一账号可同时拥有平台身份（tenant_id=0）+ 多租户身份。登录后可在控制台/企业工作台内切换当前选中的成员租户，权限按选中域实时计算。\n\n## 开发者接入方式\n\n- **第三方系统**：开放平台 API（API Key + HMAC-SHA256 签名），见「开放平台」章节\n- **设备厂商**：实现驱动进程（gRPC），见「驱动开发」章节\n- **内部运维**：控制台登录后使用，全部接口见在线 API 文档",2,"2026-09-21T17:07:33",{"id":23,"module":6,"category":7,"slug":24,"title":25,"contentMd":26,"sort":27,"status":12,"updatedBy":13,"updatedAt":14},9,"guide/first-integration","首个集成示例","# 首个集成示例\n\n以「第三方系统订阅垃圾发现事件并下发保洁任务」为例，走通开放平台全流程。\n\n## 前置\n\n1. 控制台 → 开放平台 → 创建 API Key，保存返回的 AK/SK（SK 仅展示一次）\n2. 控制台 → 开放平台 → 注册 Webhook 回调地址（如 `https://your-system.com/cleanhub/events`）\n\n## 1. 订阅事件（接收出站推送）\n\n平台清洗通过的事件会推送到你的回调地址：\n\n```\nPOST /cleanhub/events\nX-Cleanhub-Signature: HMAC-SHA256(body, secret)\nX-Cleanhub-Event: TRASH_ALARM\n```\n\n用注册时返回的 secret 校验签名后处理事件。\n\n## 2. 下发任务\n\n```\nPOST /api/v1/tasks/dispatch\nX-Api-Key: \u003CAK>\nX-Timestamp: 1720000000000\nX-Nonce: uuid\nX-Sign: \u003CHMAC-SHA256(ak+timestamp+nonce+body, SK)>\n\n{ \"dispatchType\": \"ROBOT_FIRST\", \"region\": \"A栋大堂\", \"trashType\": \"GENERAL\", \"requestId\": \"req-001\" }\n```\n\n`requestId` 保证幂等：重复提交返回原任务。\n\n## 3. 查询进度\n\n```\nGET /api/v1/tasks/{taskId}\n```\n\n返回任务状态机当前节点（PENDING/DISPATCHING/EXECUTING/VERIFYING/COMPLETED/...）。\n\n> 签名细节与错误码见「开放平台」章节；在线接口文档可直接调试。",3,{"id":29,"module":6,"category":30,"slug":31,"title":32,"contentMd":33,"sort":34,"status":12,"updatedBy":13,"updatedAt":35},10,"核心概念","concepts/tenant-project","租户与项目","# 租户与项目\n\n## 模型\n\n```\n账号（user）：个人账号基座，可拥有多个身份\n └── 身份（account_identity）：域内身份，platform(0) 或 某租户成员\n      └── 角色（user_role）：挂在身份下的角色绑定\n\n租户（tenant）：物业公司/运营方，数据隔离边界\n └── 项目（project）：单个小区/写字楼/园区，配置分层单位\n      └── 设备（device）：归属项目，绑定驱动\n```\n\n## 租户状态\n\n| 状态 | 值 | 说明 |\n|------|---|------|\n| 停用（DISABLED） | 0 | 平台管理员手动停用，账号无法操作 |\n| 启用（ENABLED） | 1 | 正常使用，可执行业务流程 |\n| 待审核（PENDING） | 2 | 自助注册后等待平台管理员审核 |\n| 试用（TRIAL） | 3 | 注册即试用（默认 5 设备/5 用户/30 天） |\n| 待升级（PENDING_UPGRADE） | 4 | 试用期满申请升级，等待审核 |\n\n## 隔离规则\n\n- 数据默认按 `tenant_id` 字段隔离，强隔离场景可独立库\n- 设备/规则/策略/任务/人员/项目均按租户隔离，互不可见\n- 驱动为**平台级资源**（无租户归属），多租户可共用同一驱动\n\n## 身份维度\n\n| 身份类型 | account_identity.tenant_id | 权限 |\n|---------|---------------------------|------|\n| 平台级 | 0 | 可管理全部租户，操作时显式指定 tenant_id |\n| 租户成员 | 非 0 | 自动限定本租户数据，跨租户操作 403 |\n\n同一账号可同时拥有平台身份 + 多租户成员身份，登录后通过端内切换选择当前上下文。\n\n## 配置分层\n\n租户级配置 → 项目级配置 → 设备级配置 → 运行时动态参数，下层覆盖上层，实时生效。",4,"2026-09-19T11:20:29",{"id":37,"module":6,"category":30,"slug":38,"title":39,"contentMd":40,"sort":41,"status":12,"updatedBy":13,"updatedAt":35},11,"concepts/task-model","任务模型","# 任务模型\n\n## 状态机\n\n```\nPENDING → DISPATCHING → EXECUTING → VERIFYING → COMPLETED\n   │          │            │           │\n   │          └────────────┼───────────┴──→ FAILED / TIMEOUT / CANCELLED\n   └───────────────────────┘\n```\n\n- PENDING：等待派发（排队）\n- DISPATCHING：派发中（选择执行器）\n- EXECUTING：执行中（机器人/人员）\n- VERIFYING：二次验证（可选，飞书回调/AI 复检）\n- COMPLETED / FAILED / TIMEOUT / CANCELLED：终态\n\n## 状态流转补充\n\n- **排队超时降级**：DISPATCHING 超时 10min → 原任务 TIMEOUT，新建降级任务（dispatch_type=PERSON/NOTIFY，同 trace_id）\n- **失败重试**：EXECUTING 失败 → retry_count+1，回 DISPATCHING 重新选执行器（排除上次失败的）；满 3 次 → FAILED + 飞书告警\n- **人员超时**：PERSON 任务超时（默认 30min）→ 转备份人员（同任务不新建）；无备份 → FAILED + 飞书告警\n\n## 关键字段\n\n| 字段 | 说明 |\n|------|------|\n| task_id | 任务 ID |\n| trace_id | 全链路追踪 ID（tr-YYYYMMDD-NNNNNN） |\n| event_id | 触发事件 ID（人工/外部派单为空） |\n| dispatch_type | ROBOT_FIRST / PERSON / ROBOT 等 |\n| executor | 执行器（机器人/人员） |\n| trash_type | GLASS / LIQUID / GENERAL 等 |\n| screenshot_url | 现场截图（OSS） |\n| timeline | 各阶段时间戳 JSON |\n\n## 干预操作\n\n- cancel：限 PENDING/DISPATCHING/EXECUTING/VERIFYING\n- redispatch：限 PENDING/TIMEOUT/FAILED\n- complete：限 PENDING/EXECUTING/VERIFYING（人工标记完成）",5,{"id":43,"module":6,"category":30,"slug":44,"title":45,"contentMd":46,"sort":47,"status":12,"updatedBy":13,"updatedAt":35},12,"concepts/driver-device","驱动与设备","# 驱动与设备\n\n## 驱动（Driver）\n\n独立进程实现的设备接入/执行/通知能力包，任意语言（Java/Go/Python）。\n\n| 类型 | 职责 |\n|------|------|\n| DISCOVERY | 发现端：事件上报、设备发现、健康检查 |\n| EXECUTOR | 执行端：执行任务、取消、查询状态 |\n| NOTIFY | 通知渠道（飞书已内置，钉钉/企微待扩展） |\n\n驱动注册流程：进程启动 → `RegisterDriver`（携带注册密钥换取 driver_token）→ 心跳 30s → 上报设备 → 订阅任务。\n\n## 设备（Device）\n\n| 字段 | 说明 |\n|------|------|\n| device_id | 设备唯一标识（与驱动上报一致） |\n| type | AI_CAMERA / AI_NVR / NVR / ROBOT |\n| model | 型号 |\n| location / region | 位置 / 区域（规则作用范围） |\n| driver_id | 绑定的驱动版本 |\n| config_json | 设备级配置覆盖 |\n\n## 安全\n\n- 驱动 token 与开放平台 API Key 相互独立\n- 事件上报校验设备绑定的 driver_id 必须等于上报方驱动（防伪造）\n- 驱动停用 token 立即失效\n- 公网 NPM 已排除 `/api/v1/driver/*`（驱动通道仅内网容器可达）",6,{"id":49,"module":6,"category":50,"slug":51,"title":52,"contentMd":53,"sort":5,"status":12,"updatedBy":13,"updatedAt":14},13,"接入指南","guides/webhook","Webhook 订阅","# Webhook 订阅\n\n## 概述\n\n平台向第三方系统推送事件（出站），回调地址在控制台「开放平台 → Webhook」注册。\n\n## 注册\n\n```\nPOST /admin/webhooks\n{\n  \"tenantId\": 1,\n  \"name\": \"物业总平台\",\n  \"callbackUrl\": \"https://your-system.com/cleanhub/events\",\n  \"eventTypes\": [\"TRASH_ALARM\"],\n  \"enabled\": 1\n}\n```\n\n返回 `secret`（仅创建时展示一次），用于校验平台签名。\n\n## 出站推送\n\n```\nPOST \u003CcallbackUrl>\nX-Cleanhub-Signature: HMAC-SHA256(body, secret)\nX-Cleanhub-Event: TRASH_ALARM\nContent-Type: application/json\n```\n\n## 触发规则\n\n- 事件清洗通过即触发\n- 低置信度丢弃的**不推**\n- 去重命中的**不推**\n- 按 event_types 匹配订阅（空 = 全部）\n\n## 重试\n\n失败重试 3 次，退避 30s/60s/120s，仍失败记 audit 告警。\n\n## 事件示例\n\n```json\n{\n  \"eventId\": \"ev-20260814-000001\",\n  \"tenantId\": 1,\n  \"projectId\": 1,\n  \"deviceId\": \"cam-001\",\n  \"eventType\": \"TRASH_ALARM\",\n  \"trashType\": \"GENERAL\",\n  \"confidence\": 0.93,\n  \"region\": \"A栋大堂\",\n  \"screenshotUrl\": \"https://oss/...\",\n  \"occurredAt\": 1720000000000\n}\n```",{"id":55,"module":6,"category":50,"slug":56,"title":57,"contentMd":58,"sort":16,"status":12,"updatedBy":13,"updatedAt":14},14,"guides/message-bus","消息总线","# 消息总线\n\n平台内部使用 Redis Streams 作为消息总线，四层（接入/决策/派发/结果）通过 Stream 解耦。\n\n## 主题\n\n| 主题 | 生产者 | 消费组 | 消息内容 |\n|------|--------|--------|---------|\n| cleanhub-raw-event | 接入层 | cleanhub-decision-group | 原始事件（设备/类型/置信度/位置/截图） |\n| cleanhub-decision | 决策层（仅命中时） | cleanhub-dispatch-group | 决策结果（动作/优先级/规则ID） |\n| cleanhub-result | 接入层（收回调后） | cleanhub-result-group | 执行结果（成功/失败/耗时） |\n| cleanhub-delay | 派发/结果层 | cleanhub-delay-group | 延迟消息载体（超时检测/重试） |\n\n## 实现要点\n\n- **消费**：`StreamConsumerFactory` 每主题 daemon 线程，非阻塞 XREADGROUP → 反序列化 → handler → XACK\n- **建组**：`XGROUP CREATE \u003Ckey> \u003Cgroup> 0`（幂等，BUSYGROUP 忽略）\n- **延迟**：入 ZSET `cleanhub:delay`（score=到期毫秒），`DelayDispatcher` 每秒 ZPOPMIN 转入目标流\n- **裁剪**：定时任务 XTRIM MAXLEN ~10000（事件已落库，流仅异步载体）\n- **幂等**：冲突/已处理一律 ACK，禁止抛异常重投\n\n## 监控\n\n控制台「消息总线」页实时展示：\n\n- 积压量：`XLEN \u003Ctopic>`\n- 消费组 lag / pending / 消费者数：`XINFO GROUPS`\n- 消息内容预览：`XRANGE \u003Ctopic> COUNT N`\n\n## 分层控制（软启停）\n\nRedis key `cleanhub:control:{group}` = pause/resume，消费线程轮询检查：\n\n| 消费组 | 层 | 消费主题 |\n|--------|----|---------|\n| cleanhub-decision-group | DECISION | cleanhub-raw-event |\n| cleanhub-dispatch-group | DISPATCH | cleanhub-decision |\n| cleanhub-result-group | RESULT | cleanhub-result |\n\n暂停时消息积压不读，恢复后断点续消费，无需重启进程。",{"id":60,"module":6,"category":61,"slug":62,"title":63,"contentMd":64,"sort":23,"status":12,"updatedBy":13,"updatedAt":14},15,"开放平台","api/auth","认证与签名","# 认证与签名（API Key + HMAC-SHA256）\n\n## 凭证\n\n控制台「开放平台」创建 API Key，获得：\n\n- **AK**（api_key）：身份标识\n- **SK**（api_secret）：签名密钥，**仅创建时展示一次**，丢失需删除重建\n\n## 签名算法\n\n```\nsign = HMAC-SHA256(apiKey + timestamp + nonce + body, apiSecret)\n```\n\n请求头：\n\n| 头 | 说明 |\n|----|------|\n| X-Api-Key | AK |\n| X-Timestamp | 毫秒时间戳，有效期 5 分钟（防重放） |\n| X-Nonce | 随机串，5 分钟内去重 |\n| X-Sign | 签名结果（hex） |\n\n## body 规范化\n\n- `body` = **原始请求体字符串**（UTF-8，按收到的原样拼接，不重新序列化）\n- 无 body（GET）用空串\n- 双端必须一致，否则验签失败\n\n## 示例（Node.js）\n\n```javascript\nconst crypto = require(\"crypto\");\nconst body = JSON.stringify(payload);\nconst sign = crypto\n  .createHmac(\"sha256\", sk)\n  .update(ak + timestamp + nonce + body)\n  .digest(\"hex\");\n```\n\n## 租户隔离\n\nAPI Key 绑定租户：第三方只能操作本租户数据。\n\n> OpenAPI JSON 定义端点见「开放平台 → 在线接口文档」。",{"id":66,"module":6,"category":61,"slug":67,"title":68,"contentMd":69,"sort":29,"status":12,"updatedBy":13,"updatedAt":35},16,"api/errors","错误码","# 错误码\n\n## HTTP 状态码\n\n| 状态码 | 场景 |\n|--------|------|\n| 200 | 成功 |\n| 400 | 参数错误 / 业务校验失败 |\n| 401 | 未登录 / token 无效 |\n| 403 | 无操作权限 |\n| 404 | 资源不存在 |\n| 500 | 系统异常 |\n| 503 | 功能禁用（如飞书凭证未配置 / OSS 未配置） |\n\n## 业务错误码（响应体 code）\n\n| code | 含义 | 处理 |\n|------|------|------|\n| 400 | 业务校验失败（message 说明） | 按提示修正参数 |\n| 401 | 登录态无效 / 签名失败 | 重新登录或检查签名 |\n| 404 | 内容/资源不存在 | 检查 ID |\n| 503 | 依赖未配置（飞书/OSS） | 配置对应凭证后重试 |\n\n## 开放平台验签失败\n\n| 现象 | 原因 | 排查 |\n|------|------|------|\n| 401 签名不匹配 | body 规范化不一致 / SK 错误 | 用原始请求体字符串重算 |\n| 401 timestamp 过期 | 时间戳超 5 分钟 | 校准服务器时钟 |\n| 401 nonce 重复 | 5 分钟内重复使用 | 每次生成新 nonce |\n| 403 租户越权 | AK 绑定的租户无权操作目标数据 | 检查租户维度参数 |\n\n## 驱动通道错误\n\n| code | 含义 | 处理 |\n|------|------|------|\n| device_driver_mismatch | 设备绑定的驱动与上报方不一致（防伪造） | 检查设备绑定的驱动版本是否正确 |\n| driver_disabled | 驱动已停用，token 失效 | 启用驱动后重新注册 |\n| driver_not_registered | 驱动未注册（token 缺失） | 驱动进程携带 register_key 重新注册 |\n| driver_token_expired | 心跳超时 driver_token 过期 | 重新注册驱动 |",{"id":71,"module":6,"category":72,"slug":73,"title":74,"contentMd":75,"sort":37,"status":12,"updatedBy":13,"updatedAt":35},17,"驱动开发","driver/grpc","gRPC 协议","# 驱动开发 · gRPC 协议\n\n## 概述\n\n驱动与核心通信统一走 gRPC（proto 包 `clean.driver`），任意语言可实现。\n\n## 驱动 → 核心（CoreService，驱动作为客户端连 core:50051）\n\n| RPC | 说明 |\n|-----|------|\n| ReportEvent | 事件上报（接入层入口） |\n| Heartbeat | 心跳（在线状态，30s 超时判离线） |\n| RegisterDriver | 驱动注册（元信息/endpoint/支持型号，换取 driver_token） |\n| RegisterDevices | 自动发现设备上报（需显式指定 tenant_id） |\n| ReportTaskResult | 任务结果上报（完成/失败/验证回调） |\n\n## 核心 → 驱动（DriverService，核心作为客户端连驱动 endpoint）\n\n| RPC | 说明 |\n|-----|------|\n| ExecuteTask | 下发任务（派发层调用） |\n| CancelTask | 取消任务 |\n| QueryTask | 查询任务状态 |\n| SendNotify | 通知端驱动（未来：钉钉/企微/短信） |\n\n## 关键消息字段\n\n```protobuf\nmessage EventRequest {\n  string device_id = 1;\n  string event_type = 2;       // TRASH_ALARM 等\n  string trash_type = 3;       // GLASS/LIQUID/GENERAL\n  double confidence = 4;       // 0-1\n  string region = 5;\n  Location location = 6;\n  string screenshot_url = 7;   // 驱动持 STS 直传 OSS\n  int64 occurred_at = 8;       // 毫秒时间戳\n}\n```\n\n## 注册密钥与 token\n\n- 首次注册携带 `X-Driver-Register-Key`（.env DRIVER_REGISTER_KEY）换取 driver_token\n- 此后所有请求带 `X-Driver-Token`\n- 核心→驱动回连地址：驱动注册时上报的 endpoint（host:port）\n\n> 驱动事件归属校验：上报设备绑定的 driver_id 必须等于上报方驱动，否则拒绝。",{"id":77,"module":6,"category":72,"slug":78,"title":79,"contentMd":80,"sort":43,"status":12,"updatedBy":13,"updatedAt":35},18,"driver/simulator","模拟器对接","# 模拟器对接\n\n## 概述\n\n内置模拟引擎（同 JVM 直调，非独立驱动），无真实设备即可跑通完整闭环，也支持真实设备 + 模拟数据混合。\n\n## 模拟模式\n\n| 模式 | 说明 | 场景 |\n|------|------|------|\n| 无设备全仿真 | 模拟发生器同时承担发现端+执行端 | 售前演示、功能测试 |\n| 真实+模拟混合 | 部分真实摄像头+部分模拟数据 | 扩容/压测 |\n| 历史数据回放 | 从数据库读历史事件按时间加速重放 | 回归测试、规则调优 |\n| 故障注入 | 模拟设备离线/机器人忙/网络超时 | 降级策略验证（仅测试租户） |\n\n## 接口\n\n| 接口 | 说明 |\n|------|------|\n| GET /admin/simulator/status | 状态 |\n| POST /admin/simulator/start | 启动 |\n| POST /admin/simulator/stop | 停止 |\n| GET/PUT /admin/simulator/config | 参数（事件频率/类型/成功率/延迟） |\n| POST /admin/simulator/replay | 历史回放 |\n| POST /admin/simulator/fault | 注入故障 |\n\n## 演示闭环\n\n演示规则用 ROBOT_FIRST：模拟机器人接收 ExecuteTask 后按可配成功率返回结果，跑通「发现→决策→派单→结果」全自动闭环。\n\n> 模拟器控制台内嵌 SSE 实时链路流：启动后事件从接入→决策→派发→结果逐层可见。",{"id":82,"module":6,"category":72,"slug":83,"title":84,"contentMd":85,"sort":49,"status":12,"updatedBy":13,"updatedAt":21},19,"driver/plugin-center","插件中心与驱动接入","# 插件中心与驱动接入\n\n## 概述\n\n平台所有第三方接入（设备驱动/通知渠道/存储/出站）统一为插件：控制台「插件中心」选模板 + 填参数即完成接入，零代码、零容器。驱动只是插件的一种（DRIVER 类）。\n\n## 插件扩展点\n\n| 扩展点 | 说明 | 预置实现 |\n|--------|------|---------|\n| DRIVER | 设备接入驱动 | simulator / http-webhook / hik-isapi / ezviz-cloud / lechange-cloud |\n| NOTIFY | 通知渠道 | feishu（飞书机器人） |\n| STORAGE | 截图存储 | aliyun-oss / local-disk |\n| AUTH | 登录认证 | feishu-auth（飞书免登） |\n| SINK | 出站集成 | webhook-sink（HMAC 签名推送） |\n\n## 驱动接入（http-webhook，推荐）\n\n1. 控制台「插件中心 → 设备接入 → 通用 HTTP 上报 → 添加实例」\n2. 填写设备清单（JSON：deviceId/type/region）与归属租户，保存后自动生成上报密钥\n3. 实例启动后自动登记平台驱动并按设备清单创建设备（即绑即用）\n4. 设备方配置上报：\n\n```bash\ncurl -X POST https://\u003Cyour-domain>/api/v1/plugin/http-webhook/report \n  -H \"X-Report-Token: \u003C实例上报密钥>\" -H \"Content-Type: application/json\" \n  -d \"{\"deviceId\":\"CAM-001\",\"eventType\":\"TRASH_ALARM\",\"trashType\":\"CAN\",\n       \"confidence\":0.93,\"region\":\"A栋大堂\",\"screenshotUrl\":\"https://...\"}\" \n```\n\n5. 事件进入接入层 → 决策 → 派发 → 通知全链路（与 gRPC 驱动同链路）\n\n## 模拟器（DRIVER#simulator）\n\n内置模拟器已插件化：插件中心可查看/启停模拟器实例，参数（事件间隔/成功率/延迟/设备前缀/归属租户）持久化于实例配置；控制台「系统设置 > 模拟器」页面保留（回放/故障注入/实时链路）。\n\n## 通知/存储插件\n\n- 飞书通知（NOTIFY#feishu）：插件中心添加实例填 appId/appSecret；未创建实例时回退 .env 配置\n- OSS 存储（STORAGE#aliyun-oss）：插件实例配置优先，未配置时 STS 接口保持 503\n\n## 上报密钥\n\n- 密钥在实例创建时生成（可编辑）；泄露可在插件中心编辑实例重新生成\n- 设备归属校验由接入层兜底（设备须已注册且绑定本实例驱动，否则拒绝）",{"id":87,"module":6,"category":88,"slug":89,"title":90,"contentMd":91,"sort":55,"status":12,"updatedBy":13,"updatedAt":21},20,"部署运维","ops/deploy","安装与升级","# 安装与升级\n\n## 部署形态\n\n单机 Docker Compose：core 容器 + 共享 MySQL/Redis（web_network），控制台/官网/企业工作台/飞书 H5/用户中心为静态资源由 NPM 托管。\n\n## 域名架构（6 站点）\n\n| 域名 | 职责 |\n|------|------|\n| cleanhub.la998.com | 官网独立前端（site/help/docs + 全产品入口） |\n| admin.cleanhub.la998.com | 控制台 SPA + /admin /api /ws 代理 |\n| api.cleanhub.la998.com | API 入口（外部集成） |\n| feishu.cleanhub.la998.com | 飞书 H5（直连 core:8081） |\n| tenant.cleanhub.la998.com | 企业工作台（直连 core:8081） |\n| person.cleanhub.la998.com | 用户中心 SPA（注册/登录/用户中心，独立于控制台） |\n\n## 安装流程\n\n1. 服务器获取代码，生成部署配置（deploy 目录：.env / core.yml / init/01-schema.sql）\n2. 本地构建 core 镜像推阿里云仓库（`registry.cn-guangzhou.aliyuncs.com/codenote/cleanhub-core`）\n3. 服务器启动共享 Redis → 启动 core\n4. NPM 配置 6 个站点反代（admin/website/api/feishu/tenant/person）\n5. 浏览器访问控制台 → 引导页初始化（测试连接 → 建表 → 创建管理员）\n\n## 升级流程（core）\n\n1. 本地 `mvn package` 构建 jar → 构建镜像 push\n2. 服务器 `docker pull` → 重启 core 容器\n3. 验证 `/actuator/health` = UP，`/admin/install/status` 返回 JSON\n\n## 关键运维项\n\n| 项 | 说明 |\n|----|------|\n| 健康检查 | `curl https://\u003Cyour-domain>/actuator/health` |\n| driver 隔离验证 | `POST https://\u003Cyour-domain>/api/v1/driver/register` 必须 404 |\n| 备份 | MySQL 逻辑备份 + 部署目录（.env / conf） |\n| 内存 | core 限 640m（5 摄像头 + 5 洗地机规模足够） |\n\n> 详细步骤见仓库 docs/《04-部署指南》。",{"id":93,"module":6,"category":61,"slug":94,"title":95,"contentMd":96,"sort":60,"status":12,"updatedBy":13,"updatedAt":21},21,"api/swagger","OpenAPI 定义","# OpenAPI 定义\n\n后端 OpenAPI JSON 定义由 springdoc 自动扫描生成，接口与代码同步。\n\n## 端点\n\nGET /api/v3/api-docs\n\n| 环境 | 完整地址 |\n|------|---------|\n| 生产 | admin.cleanhub.la998.com/api/v3/api-docs |\n| 说明 | 需携带控制台登录 Cookie，未登录返回 401 |\n\n## 快速查询\n\n```bash\n# 列出全部接口路径\ncurl -s -H \"Cookie: \u003Cyour_jwt>\" https://admin.cleanhub.la998.com/api/v3/api-docs | jq \".paths | keys\"\n\n# 按 tag 过滤\ncurl -s -H \"Cookie: \u003Cyour_jwt>\" https://admin.cleanhub.la998.com/api/v3/api-docs | jq \".tags\"\n```\n\n## 接口前缀约定\n\n| 前缀 | 归属 | 签名方式 |\n|------|------|---------|\n| /admin/** | 控制台内部接口 | 控制台登录态（Cookie / JWT） |\n| /api/v1/** | 开放平台对外接口 | API Key + HMAC-SHA256 签名（见「认证与签名」） |\n\n## 说明\n\n- swagger-ui 未部署，直接消费 JSON 定义即可\n- 各接口的业务错误码见「开放平台 → 错误码」章节\n- 驱动通道通过 gRPC 通信，不走 HTTP API，见「驱动开发 → gRPC 协议」",[98,106,112,117,122,127,132,137,142,147,151,156,160,165,170,176,181,183,184,185,186,187,188,189,190,191,192,193,194,195,196],{"id":99,"module":100,"category":101,"slug":102,"title":103,"contentMd":104,"sort":11,"status":12,"updatedBy":13,"updatedAt":14,"_section":105},22,"HELP","快速上手","help/getting-started","首次使用向导","# 首次使用向导\n\n## 第 1 步：注册账号\n\n### 方式一：用户中心注册（推荐）\n访问用户中心（person.cleanhub.la998.com）注册个人账号（仅需用户名+密码），注册成功即获得纯账号基座。登录后可在用户中心提交企业开通申请，平台管理员审核通过后自动开通企业身份并绑定管理员角色。\n\n### 方式二：受邀加入\n通过管理员发送的邀请链接直接加入已有企业，无需重新注册，受邀后自动开通企业身份并绑定指定角色。\n\n### 方式三：平台管理员创建\n平台管理员在「系统管理 → 用户管理」中创建账号。初始账号 `admin / ChangeMe123!`，**首次登录后立即修改密码**。\n\n## 第 2 步：了解布局\n\n顶部导航可直达各功能模块；本帮助中心每页支持搜索，可随时查找当前功能使用说明。\n\n## 第 3 步：快速体验全流程\n\n1. **系统管理 → 租户/项目**：确认租户与项目已创建\n2. **设备管理**：确认驱动自动发现的设备，或手动注册\n3. **规则中心**：创建一条「高置信度派单」规则\n4. **模拟器**：一键启动，无设备即可看到完整「发现→派单→通知」链路\n5. **任务中心**：查看生成的任务与全链路追踪\n\n## 常用提示\n\n- 所有配置保存即生效（\u003C3 秒），无需重启\n- 修改策略/规则自动记录审计日志，可回滚历史版本\n- 演示阶段开启模拟器，生产环境请关闭","帮助中心",{"id":107,"module":100,"category":108,"slug":109,"title":110,"contentMd":111,"sort":20,"status":12,"updatedBy":13,"updatedAt":21,"_section":105},23,"功能使用","help/dashboard","运营概览","# 运营概览（Dashboard）\n\n## 功能\n\n运维总览看板，5 个统计视图：\n\n| 视图 | 内容 |\n|------|------|\n| 总览 | 事件/任务总量、各状态任务数、今日趋势 |\n| 实时链路 | 当前各层处理 TPS、延迟 P95/P99（SSE 实时推送任务流） |\n| 设备健康度 | 在线率、故障率、平均无故障时间 |\n| 保洁效率 | 平均响应时间、任务完成率、机器人利用率 |\n| Top 告警 | 垃圾高发区域 Top5、频繁报警设备 Top5 |\n\n## 使用方式\n\n- 页面默认展示全部租户数据（平台级账号）；租户内账号自动限定本租户\n- 实时链路流自动推送，无需刷新\n- 点击任务可跳转任务中心查看详情\n\n## 常见问题\n\n**Q：实时链路流不更新？**\nA：检查 NPM 反代是否配置 `/admin/dashboard/stream` 关缓冲（proxy_buffering off）。\n\n**Q：数据为空？**\nA：确认模拟器已启动（演示）或真实设备已上报事件。",{"id":113,"module":100,"category":108,"slug":114,"title":115,"contentMd":116,"sort":27,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},24,"help/tasks","任务中心","# 任务中心\n\n## 功能\n\n全量任务查询与人工干预。\n\n| 能力 | 说明 |\n|------|------|\n| 任务列表 | 按状态/时间/区域/类型筛选，分页 |\n| 任务详情 | 完整链路追踪时间轴（接入→决策→派发→结果） |\n| 人工派单 | 手动创建任务，指定设备或人员 |\n| 任务干预 | 取消/重新派发/标记完成 |\n| 异常任务 | 自动汇总超时/失败/异常任务 |\n\n## 状态说明\n\n`PENDING → DISPATCHING → EXECUTING → VERIFYING → COMPLETED`，异常终态 `FAILED/TIMEOUT/CANCELLED`。\n\n## 人工派单\n\n- 指定 executor 时走直接指派模式（跳过自动选执行器，避免重复下发）\n- 派单后任务直接进入 EXECUTING，并触发 30s 人员处理超时自动闭环\n\n## 干预限制\n\n| 操作 | 适用状态 |\n|------|---------|\n| 取消 | PENDING/DISPATCHING/EXECUTING/VERIFYING |\n| 重新派发 | PENDING/TIMEOUT/FAILED |\n| 标记完成 | PENDING/EXECUTING/VERIFYING |\n\n所有干预操作均写审计日志。",{"id":118,"module":100,"category":108,"slug":119,"title":120,"contentMd":121,"sort":34,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},25,"help/devices","设备管理","# 设备管理\n\n## 功能\n\n统一设备库：注册、驱动绑定、设备影子、批量操作、分组。\n\n| 子模块 | 说明 |\n|--------|------|\n| 设备注册 | 手动注册 / 驱动自动发现后确认（确认时必须指定租户） |\n| 驱动绑定 | 为设备选择驱动版本，支持切换/回滚 |\n| 设备影子 | 在线状态/最后上报时间/当前任务 |\n| 批量操作 | 批量修改配置、批量升级驱动 |\n| 设备分组 | 按区域/楼栋/类型分组，便于规则批量应用 |\n\n## 设备类型\n\nAI_CAMERA（AI 摄像头）/ AI_NVR / NVR（移动侦测）/ ROBOT（清洁机器人）。\n\n## 操作要点\n\n- 设备 `type` 必填\n- 自动发现设备不带租户归属，**确认时必须指定 tenant_id**（防越权）\n- 设备离线阈值默认 300s（策略中心可调）\n\n## 常见问题\n\n**Q：设备一直离线？**\nA：检查驱动心跳（驱动管理页看 last_heartbeat）、设备绑定的驱动版本、网络连通性。\n\n**Q：找不到设备？**\nA：确认驱动已启动并注册，设备自动发现后需在列表中「确认」才正式纳管。",{"id":123,"module":100,"category":108,"slug":124,"title":125,"contentMd":126,"sort":41,"status":12,"updatedBy":13,"updatedAt":21,"_section":105},26,"help/drivers","驱动管理","# 驱动管理\n\n## 功能\n\n平台级驱动仓库：登记、版本管理、绑定、回滚。\n\n| 能力 | 说明 |\n|------|------|\n| 驱动登记 | 上传驱动包并登记元信息（名称/版本/类型/支持型号） |\n| 多版本并存 | 同一驱动多版本，不同设备可绑定不同版本 |\n| 设备绑定 | 设备 → 驱动版本，支持批量升级 |\n| 回滚 | 绑定到当前版本的全部设备回退到同名低版本（配置级秒级生效） |\n| token 管理 | 重置 driver_token（旧 token 立即失效，驱动需重新注册） |\n\n## 驱动类型\n\nDISCOVERY（发现端）/ EXECUTOR（执行端）/ NOTIFY（通知端），可多值（如模拟器=DISCOVERY,EXECUTOR）。\n\n## 运维提示\n\n- 驱动为独立进程/容器，由运维手动部署到平台网络，启动后自动向核心注册\n- 驱动崩溃不影响平台；容器 restart: unless-stopped 自动拉起\n- 心跳 30s 超时判离线 → 运营概览告警\n- 驱动进程容器替换需运维手动操作（上传新版本包 → 部署新容器 → 注册）",{"id":128,"module":100,"category":108,"slug":129,"title":130,"contentMd":131,"sort":47,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},27,"help/rules","规则中心","# 规则中心\n\n## 功能\n\n可视化编排「条件→动作」决策规则，非技术人员可配置。\n\n## 规则结构\n\n```\n条件组（AND/OR）\n ├─ 来源类型 IN (AI_CAMERA, AI_NVR)\n ├─ 置信度 ≥ 0.85\n ├─ 不在静默时段（策略自动注入）\n └─ 同一区域 1 小时内计数 \u003C 3\n执行动作\n ├─ 派发方式：机器人优先\n ├─ 降级方式：飞书通知\n └─ 优先级：高\n生效范围：A栋大堂, B栋走廊\n状态：启用 | 灰度比例：10%\n```\n\n## 操作\n\n- 创建/编辑：落库即生效（决策层每事件直查规则表，\u003C3 秒）\n- 启停：不递增版本\n- 灰度：新规则按设备百分比小流量验证（hash(deviceId) % 100 \u003C gray_ratio）\n- 导入/导出：跨环境迁移\n\n## 灰度建议\n\n新规则先 5% 灰度 → 观察任务成功率 → 逐步放量 → 异常一键回滚。",{"id":133,"module":100,"category":108,"slug":134,"title":135,"contentMd":136,"sort":5,"status":12,"updatedBy":13,"updatedAt":21,"_section":105},28,"help/policies","策略中心","# 策略中心\n\n## 功能\n\n全链路运营参数管理（接入/决策/派发/结果四层），控制台即改即生效。\n\n## 常用参数\n\n| 层 | 关键参数 |\n|----|---------|\n| 接入 | 去重窗口(300s)、设备离线阈值(300s)、事件时效(600s)、上报节流 |\n| 决策 | 置信度阈值(摄像头0.85/NVR0.80)、静默时段(22:00-06:00)、区域频率限制(3次/小时) |\n| 派发 | 机器人排队超时(10min)、任务重试(3次)、飞书通知频控 |\n| 结果 | 二次验证开关、人员处理超时(30min)、日报时间(09:00) |\n\n## 版本与回滚\n\n- 每次保存写策略版本快照（policy_version）\n- 「版本」页按时间倒序查看历史\n- 「回滚」取目标版本覆盖当前并生成新版本，秒级生效\n\n## 灰度发布\n\n新策略按设备百分比灰度，逐步放量，异常一键回滚。\n\n> 派发路由表（区域/垃圾类型 → 执行器映射）也在此配置（dispatchRoute 字段）。",{"id":138,"module":100,"category":108,"slug":139,"title":140,"contentMd":141,"sort":16,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},29,"help/logs","日志中心","# 日志中心\n\n## 功能\n\n结构化日志检索：按 trace_id / device_id / 时间范围 / 层级筛选。\n\n## 使用方式\n\n| 筛选 | 说明 |\n|------|------|\n| trace_id | 全链路追踪 ID（最常用，从任务详情复制） |\n| device_id | 单设备日志 |\n| layer | ACCESS / DECISION / DISPATCH / RESULT |\n| 时间范围 | 默认最近 1 小时 |\n\n## 日志字段\n\n每行含：trace_id、租户、项目、层级、级别、消息、metadata（扩展字段，含 device_id 等）。\n\n## 排查思路\n\n1. 任务详情复制 trace_id\n2. 日志中心按 trace_id 检索 → 查看四层流水\n3. 定位异常层 → 结合「链路追踪」时间轴分析\n\n> 审计日志（配置变更/人工操作）在系统管理 → 审计查询，不在此页。",{"id":143,"module":100,"category":108,"slug":144,"title":145,"contentMd":146,"sort":23,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},30,"help/trace","链路追踪","# 链路追踪\n\n## 功能\n\n按 trace_id 查看事件从接入→决策→派发→结果的全链路时间线，快速定位卡点。\n\n## 使用方式\n\n1. 输入 trace_id（任务中心详情页可复制）\n2. 返回四层流水（按时间升序）\n3. 每行含层级、消息、时间戳，异常层标红\n\n## 实时链路流（WebSocket）\n\n「链路」页内嵌实时流：连接后首帧推最近链路快照，随后实时推送新 trace 帧。\n\n- 前端自动断线重连\n- 心跳 20s 保活\n\n## 常见问题\n\n**Q：实时流空白？**\nA：确认 NPM 已配置 `/ws/` WebSocket 反代（proxy_http_version 1.1; Upgrade/Connection 头）。\n\n**Q：trace_id 查不到数据？**\nA：确认事件确实走到了对应层（可先看消息总线积压）。",{"id":148,"module":100,"category":108,"slug":149,"title":57,"contentMd":150,"sort":29,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},31,"help/bus","# 消息总线\n\n## 功能\n\nRedis Streams 总线实时监控 + 分层软启停。\n\n## 监控指标\n\n| 指标 | 数据源 |\n|------|--------|\n| 积压量 | XLEN 各主题 |\n| 消费组 lag/pending | XINFO GROUPS |\n| 消息预览 | XRANGE 最近 N 条 |\n\n4 个主题：cleanhub-raw-event / cleanhub-decision / cleanhub-result / cleanhub-delay。\n\n## 分层控制（软启停）\n\n| 消费组 | 层 | 说明 |\n|--------|----|------|\n| decision-group | 决策层 | 暂停后不再消费新事件 |\n| dispatch-group | 派发层 | 暂停后不创建任务 |\n| result-group | 结果层 | 暂停后不处理结果 |\n\n- 暂停：消息积压不读（不丢失），适合排查问题\n- 恢复：断点续消费，无需重启进程\n- 操作需平台级管理员权限\n\n## 使用场景\n\n- 决策层异常 → 暂停决策层排查 → 恢复\n- 积压持续增长 → 检查对应层消费是否卡住（结合链路追踪）",{"id":152,"module":100,"category":108,"slug":153,"title":154,"contentMd":155,"sort":37,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},32,"help/simulator","模拟器","# 模拟器\n\n## 功能\n\n内置模拟引擎：无真实设备跑通完整保洁闭环，支持故障注入与历史回放。\n\n## 模式\n\n| 模式 | 说明 |\n|------|------|\n| 无设备全仿真 | 模拟发生器承担发现端+执行端，完整闭环演示 |\n| 真实+模拟混合 | 部分真实 + 部分模拟，压测/扩容验证 |\n| 历史回放 | 数据库历史事件按时间加速重放 |\n| 故障注入 | 设备离线/机器人忙/超时（仅测试租户） |\n\n## 操作\n\n1. 打开模拟器页 → 配置参数（事件频率/类型/置信度/成功率/延迟）\n2. 点击「启动」\n3. 控制台实时链路流即时可见：事件接入→决策→派发→结果逐层推送\n4. 演示结束「停止」\n\n## 参数\n\n| 参数 | 说明 |\n|------|------|\n| 事件频率 | 每秒生成事件数 |\n| 置信度 | 事件置信度（可低于阈值验证过滤） |\n| 成功率 | 模拟机器人执行成功率 |\n| 执行延迟 | 模拟执行耗时 |\n\n## 注意\n\n- 故障注入仅限测试租户，生产环境勿用\n- 演示规则用 ROBOT_FIRST 走全自动闭环；FEISHU 凭证未配置时通知模拟成功（记日志）",{"id":157,"module":100,"category":108,"slug":158,"title":61,"contentMd":159,"sort":43,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},33,"help/openapi","# 开放平台\n\n## 功能\n\n对接第三方系统：API Key 管理 + Webhook 事件订阅。\n\n## API Key\n\n- 创建后返回 AK/SK，**SK 仅展示一次**，请立即保存\n- 请求需携带 `X-Api-Key / X-Timestamp / X-Nonce / X-Sign`（HMAC-SHA256 签名）\n- 删除后该 Key 立即失效\n\n## Webhook 订阅\n\n- 注册回调地址 + 订阅事件类型（空=全部）\n- 平台出站推送带 `X-Cleanhub-Signature`（HMAC-SHA256(body, secret)）\n- 失败重试 3 次（30s/60s/120s），仍失败记审计告警\n\n## 事件触发规则\n\n- 清洗通过即推；低置信度丢弃不推；去重命中不推\n\n## 开发者必读\n\n- 签名算法与 body 规范化：见开发文档「认证与签名」\n- 在线调试：见开发文档「在线接口文档」\n- 接口清单：见开发文档「快速开始 → 首个集成示例」",{"id":161,"module":100,"category":108,"slug":162,"title":163,"contentMd":164,"sort":49,"status":12,"updatedBy":13,"updatedAt":21,"_section":105},34,"help/admin-center","系统管理","# 系统管理\n\n系统管理包含 4 个子模块：租户 / 用户 / 人员 / 项目（仅平台级管理员可管理租户与用户）。\n\n## 租户管理\n\n- 创建租户（名称 + 唯一编码），启停控制\n- 租户是数据隔离边界：设备/规则/策略/任务均按租户隔离\n- **两段式开通**：用户通过用户中心注册账号 → 提交企业开通申请 → 平台管理员审核\n- **审核机制**：新注册租户状态为「待审核」，审核通过后变为「试用」或「启用」\n- **试用期**：试用租户默认 5 设备/5 用户/30 天，到期可申请升级\n- **审核通过**：租户状态变为启用，可正常使用全部功能\n\n## 用户管理\n\n- 创建控制台账号：指定用户名/密码/身份/角色\n- 角色系统：平台预置 6 角色（3 平台级 + 3 租户级），租户可自定义角色\n- 多身份模型：同一账号可拥有平台身份 + 多租户成员身份\n- 停用后该账号立即失效（每请求查库校验）\n\n## 人员管理\n\n- 维护保洁员/执行人：姓名、飞书 open_id、负责区域、状态\n- 人员用于派单与飞书通知（任务通知直达责任人）\n\n## 项目管理\n\n- 租户下多项目（小区/写字楼），配置分层单位\n- 规则/策略可指定项目生效范围（0=租户级全项目）\n\n## 常见问题\n\n**Q：租户内账号能看别的租户数据吗？**\nA：不能。租户内账号强制限定本租户，指定他租户返回 403。\n\n**Q：同一账号如何切换企业身份？**\nA：登录后在控制台/门户使用端内切换功能，选择当前操作的成员企业。",{"id":166,"module":100,"category":108,"slug":167,"title":168,"contentMd":169,"sort":55,"status":12,"updatedBy":13,"updatedAt":21,"_section":105},35,"help/plugin-center","插件中心","# 插件中心\n\n## 入口\n\n顶部菜单「插件中心」，按类型分类：设备接入 / 通知渠道 / 存储 / 出站集成。\n\n## 添加实例（以接入一台设备为例）\n\n1. 选择「设备接入」标签 → 点击「通用 HTTP 上报」模板\n2. 「添加实例」→ 填写设备清单 JSON 与归属租户\n3. 保存后实例自动启动，设备自动登记（设备管理页可见）\n4. 将上报地址与密钥配置到设备端即可\n\n## 管理实例\n\n| 操作 | 说明 |\n|------|------|\n| 启动/停止 | 启停实例（模拟器停止后不再生成事件） |\n| 编辑 | 修改参数，保存后热更新（设备/密钥变更即时生效） |\n| 删除 | 停止并删除实例（不影响已产生的事件/任务数据） |\n| 状态 | RUNNING/STOPPED/ERROR（错误信息控制台可见） |\n\n## 常见问题\n\n- 设备上报返回 401：上报密钥错误，检查实例配置\n- 返回 device_not_registered：设备清单未包含该 deviceId，编辑实例重新保存\n- 模拟器事件不生成：确认模拟器实例已启动（插件中心或「系统设置 > 模拟器」）",{"id":171,"module":100,"category":172,"slug":173,"title":174,"contentMd":175,"sort":60,"status":12,"updatedBy":13,"updatedAt":14,"_section":105},36,"常见问题","help/faq","常见问题（FAQ）","# 常见问题\n\n## 登录与账号\n\n**Q：如何注册账号？**\nA：访问用户中心（person.cleanhub.la998.com）注册个人账号。注册后登录用户中心可提交企业开通申请，或通过邀请链接直接加入已有企业。\n\n**Q：注册后为什么不能操作？**\nA：个人账号注册后为纯账号基座（无企业关联），需提交企业开通申请并等待平台管理员审核通过后，方可获得租户操作权限。\n\n**Q：忘记密码？**\nA：联系平台管理员在系统管理 → 用户管理中重置。\n\n**Q：提示「账号不存在或已停用」？**\nA：账号被停用（每请求实时校验），联系管理员启用。\n\n**Q：同一账号能加入多个租户吗？**\nA：可以。同一账号可拥有多个企业成员身份，登录后通过端内切换选择当前操作的租户。\n\n## 设备与驱动\n\n**Q：设备一直离线？**\nA：① 驱动是否启动并注册（驱动管理看心跳）② 设备驱动绑定是否正确 ③ 网络连通性。\n\n**Q：自动发现的设备在哪确认？**\nA：设备管理 → 列表找到待确认设备 → 确认并指定租户。\n\n## 规则与策略\n\n**Q：规则改了没生效？**\nA：规则落库即生效（\u003C3 秒）。确认规则状态为启用，且条件与事件匹配（可看链路追踪是否命中）。\n\n**Q：怎么安全上线新规则？**\nA：用灰度发布：5% → 观察 → 逐步放量，异常一键回滚。\n\n## 任务\n\n**Q：任务一直 PENDING？**\nA：① 决策层是否命中规则 ② 派发层是否被暂停（消息总线）③ 执行器是否可用。\n\n**Q：机器人排队超时？**\nA：策略中心调大「机器人排队超时」，或配置自动降级通知人员。\n\n## 通知\n\n**Q：收不到飞书通知？**\nA：① 飞书凭证是否配置（.env FEISHU_*）② 人员是否绑定飞书 open_id ③ 通知频控是否触发（默认 20条/分钟）④ 静默时段不派单。\n\n## 其他\n\n**Q：修改连接配置安全吗？**\nA：系统设置保存连接配置会热切换连接池，需确保新配置正确（可先「测试」）。\n\n**Q：租户注册审核在哪里设置？**\nA：平台管理员登录后，进入「系统设置」页面，在「注册审核配置」卡片中可开启或关闭「租户注册需要审核」开关。",{"id":177,"module":100,"category":178,"slug":179,"title":178,"contentMd":180,"sort":66,"status":12,"updatedBy":13,"updatedAt":35,"_section":105},37,"联系我们","help/contact","# 联系我们\n\n## 支持渠道\n\n- **问题反馈**：通过「日志中心」+「链路追踪」提供 trace_id 与截图，最快定位\n- **功能咨询**：联系平台运营团队\n- **开发者对接**：见开发文档「开放平台」「驱动开发」章节\n\n## 提供信息清单\n\n| 类型 | 需要提供 |\n|------|---------|\n| 任务异常 | 任务 ID / trace_id |\n| 设备离线 | 设备 ID / 驱动名称版本 |\n| 通知未达 | 人员姓名 / 时间点 |\n| 性能问题 | 时间范围 / 是否压测 |\n\n## 服务时间\n\n7×24 小时工单支持，紧急问题优先响应。",{"id":5,"module":6,"category":7,"slug":8,"title":9,"contentMd":10,"sort":11,"status":12,"updatedBy":13,"updatedAt":14,"_section":182},"开发文档",{"id":16,"module":6,"category":7,"slug":17,"title":18,"contentMd":19,"sort":20,"status":12,"updatedBy":13,"updatedAt":21,"_section":182},{"id":23,"module":6,"category":7,"slug":24,"title":25,"contentMd":26,"sort":27,"status":12,"updatedBy":13,"updatedAt":14,"_section":182},{"id":29,"module":6,"category":30,"slug":31,"title":32,"contentMd":33,"sort":34,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":37,"module":6,"category":30,"slug":38,"title":39,"contentMd":40,"sort":41,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":43,"module":6,"category":30,"slug":44,"title":45,"contentMd":46,"sort":47,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":49,"module":6,"category":50,"slug":51,"title":52,"contentMd":53,"sort":5,"status":12,"updatedBy":13,"updatedAt":14,"_section":182},{"id":55,"module":6,"category":50,"slug":56,"title":57,"contentMd":58,"sort":16,"status":12,"updatedBy":13,"updatedAt":14,"_section":182},{"id":60,"module":6,"category":61,"slug":62,"title":63,"contentMd":64,"sort":23,"status":12,"updatedBy":13,"updatedAt":14,"_section":182},{"id":66,"module":6,"category":61,"slug":67,"title":68,"contentMd":69,"sort":29,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":71,"module":6,"category":72,"slug":73,"title":74,"contentMd":75,"sort":37,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":77,"module":6,"category":72,"slug":78,"title":79,"contentMd":80,"sort":43,"status":12,"updatedBy":13,"updatedAt":35,"_section":182},{"id":82,"module":6,"category":72,"slug":83,"title":84,"contentMd":85,"sort":49,"status":12,"updatedBy":13,"updatedAt":21,"_section":182},{"id":87,"module":6,"category":88,"slug":89,"title":90,"contentMd":91,"sort":55,"status":12,"updatedBy":13,"updatedAt":21,"_section":182},{"id":93,"module":6,"category":61,"slug":94,"title":95,"contentMd":96,"sort":60,"status":12,"updatedBy":13,"updatedAt":21,"_section":182},1789982486745]