ES Documentation
手册
API
手册
API
简体中文

基础数据（业务）

基础数据模块讲两件事：组织与人员辅助数据（员工及其与平台用户的关联）、对讲组（群组 + 成员绑定 + 异步联动）。文件索引/存储策略族是设备文件与下载任务的库内支撑表。本模块资源表受 MyBatis 租户拦截器按当前认证租户上下文约束，请求中的租户筛选字段不能代替空间切换（认证与空间）。

本页是 data-service basedata 模块接口的业务说明，非业务说明不在本页复述：

  • OpenAPI JSON（可直接导入 Postman 等工具）：https://zxs.netbodycamera.com/main-service/v3/api-docs/basedata
  • 在线 Swagger 视图：data-service · 基础数据
  • 端点全量清单（含权限点与中文说明）：清单层 · basedata

参数、请求/响应字段、错误码等契约事实一律见上述 Swagger 与清单层；本页只讲业务语义与动线。

employee 员工

员工（机构人员）主档：save/updateById 是「无异常即 true」的复合写（可同时维护用户绑定，见 employee-user），不提供 affected-row 数。已知契约冲突（机构缺口页具名）：importList 的当前 Web XLSX 模板不生成 username/password/confirmPassword，而后端保存 DTO 对三者 @NotBlank——导入请求会在发布 JMS 前校验失败，该端点未获正本，对接前先核对模板与校验口径。其余为 CRUD。

  • 用户绑定 wire 惯例：password/confirmPassword 由 Web 按平台约定作摘要变换后发送（该值的生成算法属于内部实现，不在文档披露范围，具体生成方式请与开发人员沟通确认），后端不比较两字段；username 后端要求 3..36，Web 表单仅校验 1..36（短于 3 的输入会在后端失败）。
  • 查询控制字段（like/eq、排序白名单、limit 钳制、页长边界未闭合）约定见 用户中心业务 · query-controls。

场景页：创建雇员并绑定用户、按 ID 读取雇员。契约见清单层 · employee。

employee-attachment 员工附件

员工附件关联 CRUD（场景页未引用）；契约见清单层。

employee-download-task 员工下载任务

员工文件下载任务主档 CRUD（场景页未引用；任务族与文件索引见 file-index）；契约见清单层。

employee-download-task-file-index 员工下载任务文件索引

下载任务与文件索引条目的关联 CRUD（场景页未引用）；契约见清单层。

employee-fingerprint 员工指纹

员工与指纹凭据的关联 CRUD（场景页未引用；指纹扫描仪台账在 device（业务））；契约见清单层。

employee-nfc-card 员工 NFC 卡

员工与 NFC 卡的持有关联 CRUD（场景页未引用；卡台账在 device（业务））；契约见清单层。

employee-talk-group 员工对讲组

员工与对讲组的成员关联 CRUD（对讲组本体见 talk-group；场景页未直接引用本资源——群组成员绑定的业务写法在 talk-group 与 talk-group-data-acquisition-device，面向设备）；契约见清单层。

employee-user 员工用户关联

员工与平台用户是两个实体：员工是组织里的身份，用户是登录账号（user-center 域）；本关联表把两者挂接。save 建立关联、updateById 更换关联的雇员（换人不换账号）；其余 CRUD。usernamePrefix 由服务端按 username 计算；updateById 只持久化 employeeId 与 revision，不改写请求中的 username——要更换关联用户须删除后重建。场景页：建立雇员—用户关联。契约见清单层 · employee-user。

file-index 文件索引

设备文件的库内索引主档。场景页的文件检索动线未直接 REST 引用本资源——Web 检索走 Meilisearch 代理（/system-api/meilisearch/multi-search，REST 形态但不在 springdoc 分组），设备侧检索走 MQTT retrieve；本表是这些检索背后的库内索引面。其余为 CRUD。契约见清单层 · file-index。

file-index-thumbnail 文件索引缩略图

文件索引条目的缩略图关联 CRUD（场景页未引用）；契约见清单层。

storage-policy 存储策略

存储策略配置 CRUD（场景页未引用；文件存储服务器登记在 device（业务））；契约见清单层。

talk-group 对讲组

对讲组业务主体。关键语义：写库成功不等于媒体可用——AudioBridge 房间创建和设备 PTT 配置刷新由后端内部消息链异步联动。

  • saveWithDataAcquisitionDevices / updateWithDataAcquisitionDevices：同一事务内写群组与记录仪（采集设备）的初始/变更绑定；保存成功只表示数据落库。
  • ensureRoom：确保指定群组的 AudioBridge 房间存在——异步受理，HTTP 返回只代表「建房命令已进入内部消息通道」，不代表房间已在 Janus 创建；可作为进群前的补偿收敛调用，不能当媒体就绪信号（房间状态的兜底收敛还有运行时补偿任务，见运行时关联）。
  • pushPttConfig：按当前群组绑定关系为指定设备重生成 PTT 配置并投递到设备（device/{deviceNo}/ptt/deliver/v1）——同样是异步受理，设备是否收到/应用取决于其 PTT 在线状态与端侧行为。
  • removeByIds：批量删除群组。

场景页：新建对讲群组（含成员绑定）、确保对讲房间存在（ensureRoom）、刷新设备 PTT 配置（pushPttConfig）。契约见清单层 · talk-group。

ptt-deliver-payload 设备 PTT 投递载荷（Web join/kick）

device/{deviceNo}/ptt/deliver/v1 上 Web 直发的 join/kick 命令载荷形态（端点特有示例，依据 Web 端实现归纳（2026-09）；设备侧消费语义缺证，正本叙事见通知设备加入/退出对讲房间）。join：

1{
2  "sub": "join",
3  "id": "user,alice,web,8f14e45f",
4  "params": {
5    "talkGroupId": "tg-100",
6    "roomPin": "<roomPin>",
7    "name": "巡逻一组",
8    "samplingRate": 8000,
9    "codec": "pcma",
10    "canSpeak": "0"
11  }
12}

kick：

1{
2  "sub": "kick",
3  "id": "user,alice,web,8f14e45f",
4  "params": { "talkGroupId": "tg-100", "roomPin": "<roomPin>" }
5}

canSpeak 恒为 "0" 是格式占位：设备真实讲话权限以本节 pushPttConfig 链下发的 groups[].canSpeak 为准，两处语义不能混用；roomPin 明文随消息传输。发布 QoS 1、retain false（Web 直发，无重试去重——Broker 重传可能造成设备重复收到同一命令，幂等性由设备端决定，缺证）。

talk-group-data-acquisition-device 对讲组与采集设备关联

群组成员绑定，两个视角两套写法：

  • 群组视角：随 save/updateWithDataAcquisitionDevices 整体提交（见上文）。
  • 设备视角（反向绑定）：updateByDataAcquisitionDeviceIdWithTalkGroups 以单台记录仪为主体，按 SAVE/UPDATE/REMOVE 变更集原子地更新它与各群组的绑定（含讲话权限），任一可靠写失败抛错回滚整批。查询有 pageForTalkGroup（群组视角分页成员）与 getByDataAcquisitionDeviceId（单台设备的群组绑定）。

场景页：按设备更新群组绑定、分页查询对讲群组视角的成员、查询单台记录仪的群组绑定。契约见清单层。

runtime-links 运行时关联

本模块相关的定时任务 / 消费者 / 缓存（全量表见 data-service 定时任务与缓存、device-service 消费者——以下条目均在 device-service 侧，此处只点名不复述）：

  • 定时任务 TalkGroupRoomCompensationScheduling（PT5M，前 3 轮全量、其后分档扩大扫描窗口）：对讲组房间状态周期补偿收敛——ensureRoom 之外的兜底链。
  • 缓存 talkGroupRoomActionDedupCache（3 秒远端）：对讲组房间动作去重。
  • 消费者 PttV1RetrieveConsumer / PttV1TelemetryConsumer：ptt 通道谓词族（retrieve/telemetry）的检索与遥测入库——pushPttConfig 投递的设备侧对端。
目录