zcloud_gbs_edgeguard/边缘人脸识别区域安全设计方案.md

边缘人脸识别区域安全设计方案

1. 当前需求结论

综合平台维护企业下面的区域树，并向第三方提供区域查询接口。

当前功能范围：

• 一个企业可以维护多棵或多层区域树。
• 区域支持新增同级区域、新增下级区域、修改和删除。
• 区域包含区域名称、负责人和电子围栏坐标。
• 当前原型要求电子围栏由 4 个有顺序的坐标点组成。
• 摄像头主数据来自第三方接口，综合平台不维护摄像头主档。
• 综合平台保存区域与摄像头的绑定关系。
• 每个已绑定摄像头可以设置负责人。
• 选择区域后，右侧列表展示该区域直接绑定的摄像头。
• 人员、公司、部门、人脸和人员区域准入关系不属于本功能维护范围。
• 综合平台不主动推送，由第三方主动调用区域开放接口。

2. 领域边界

企业（外部公共数据）
└── 区域（综合平台维护，树结构）
    ├── 下级区域
    └── 摄像头绑定（摄像头主数据来自第三方）
        └── 摄像头负责人

2.1 企业

• 企业作为区域树的根节点和数据隔离维度。
• 企业主数据不在区域表中重复维护，只保存 corp_id。
• 页面树由“企业虚拟根节点 + 本地区域节点”组合生成。
• 企业名称通过公共信息翻译或企业公共接口获取，不作为区域的权威数据保存。

2.2 区域

区域是本功能的聚合根，负责：

• 企业归属。
• 父子层级。
• 区域名称。
• 区域负责人。
• 电子围栏坐标。
• 区域状态和逻辑删除。

2.3 摄像头

• 摄像头名称、所属单位、类型、等级、主管部门、在线状态等来自第三方接口。
• 本系统不成为摄像头主数据的权威维护方，但会冗余列表展示和查询所需的摄像头缓存字段。
• 本系统保存第三方摄像头唯一标识、来源系统、区域绑定、摄像头负责人，以及名称、所属单位、类型、等级、主管部门、在线状态等快照。
• 绑定摄像头时写入快照；后续可按查询或定时策略刷新，第三方数据始终是权威来源。
• 第三方临时不可用时可以展示本地最近快照，并显示最近同步时间；不得把缓存快照作为修改第三方摄像头的依据。

3. 关键设计决策

3.1 公司节点不进入区域表

区域表只存真实区域。顶级区域的 parent_id 为空或为 0，通过 corp_id 归属企业。这样不会把外部企业主数据和本地区域数据混为一种实体。

页面树建议返回统一节点结构：

nodeType = CORP    企业虚拟节点
nodeType = REGION  本地区域节点

3.2 区域树规则

• 同一企业下，同一父节点中的区域名称建议唯一。
• 子区域必须与父区域属于同一企业、租户和单位。
• 禁止把节点移动到自身或自己的子孙节点下面。
• 删除包含子区域的节点时，默认禁止删除，先迁移或删除子节点。
• 删除仍绑定摄像头的区域时，默认禁止删除，先解除或迁移绑定。
• 查询区域树时使用批量查询后在内存组树，禁止递归逐节点查询数据库。

是否允许跨层级移动区域、区域最大层级和区域排序规则仍需产品确认。

3.3 四点电子围栏

建议数据库保存一个有顺序的坐标数组，而不是设计 point1_x 到 point4_y 八个固定字段：

[
  {"seq": 1, "longitude": 113.123456, "latitude": 23.123456},
  {"seq": 2, "longitude": 113.223456, "latitude": 23.123456},
  {"seq": 3, "longitude": 113.223456, "latitude": 23.223456},
  {"seq": 4, "longitude": 113.123456, "latitude": 23.223456}
]

一期保存时强制校验：

• 必须恰好 4 个点。
• 点序号不可重复，按顺时针或逆时针排序。
• 经度范围 [-180, 180]，纬度范围 [-90, 90]。
• 相邻点和首尾点不能重复。
• 四条边不能自相交。
• 围栏面积不能为 0。
• 必须明确坐标系，例如 WGS84、GCJ-02 或 BD-09；坐标系作为字段保存，禁止默认猜测。

使用 JSON 可以满足当前 4 点要求，同时允许未来扩展为多边形。如果后续需要“判断坐标是否在区域内”等空间检索，再增加 MySQL POLYGON 空间字段和空间索引。

3.4 负责人

• 区域负责人保存用户 ID，不重复保存用户主档。
• 摄像头负责人保存在区域摄像头绑定记录中。
• 页面通过 TranslateField 批量翻译负责人姓名，禁止循环逐人查询。
• 原型中负责人是必填单选；是否允许多个负责人，需要产品确认。
• 人员被停用或删除后，负责人绑定如何处理，需要明确校验或提示规则。

3.5 摄像头绑定

• 选择摄像头时调用第三方接口获取可选摄像头列表。
• 保存时只提交选中的第三方摄像头 ID，本系统必须再次校验摄像头存在性和调用方数据范围。
• 建议一期约束“一个来源系统中的一个摄像头只能绑定一个区域”。如果业务允许一个摄像头属于多个区域，再取消唯一约束。
• 重复选择已经绑定到当前区域的摄像头应幂等成功。
• 已绑定其他区域时，应返回明确提示，不静默迁移。
• 解绑只删除本地关系，不调用第三方删除摄像头。
• 在线状态等动态字段允许作为列表快照写入绑定表，并记录 camera_synced_at；第三方实时结果仍是权威数据，刷新失败时展示最近快照。

4. 表结构草案

当前需求确定四张业务表。所有表都包含根目录 AGENTS.md 规定的公共字段。MySQL 8.0 DDL 见 web-infrastructure/src/main/resources/RegionManagementDDL.sql。

4.1 区域表 edgeguard_region

字段	类型建议	说明
id	bigint	区域主键
region_code	varchar(64)	区域编码，建议提供稳定的对外标识
region_name	varchar(100)	区域名称
corp_id	bigint	所属企业 ID
parent_id	bigint	父区域 ID，顶级区域为空或 0
tree_path	varchar(1000)	祖先路径，用于子树查询和防循环
tree_level	int	区域层级，企业下顶级区域从 1 开始
sort_no	int	同级排序
leader_user_id	bigint	区域负责人用户 ID
coordinate_system	varchar(32)	坐标系，例如 GCJ02
fence_points	json	有序电子围栏坐标点，一期固定 4 点
region_status	varchar(32)	ENABLED/DISABLED

建议索引：

• 唯一索引：region_code，是否叠加租户维度按编码生成规则确定。
• 同级名称唯一：tenant_id + corp_id + parent_id + region_name + delete_enum。由于可空字段会影响 MySQL 唯一约束，正式 DDL 需采用非空默认值或规范化唯一键。
• 树查询索引：tenant_id + corp_id + parent_id + delete_enum + sort_no。
• 负责人查询索引：leader_user_id，仅在存在反向查询需求时增加。

4.2 区域摄像头绑定表 edgeguard_region_camera

字段	类型建议	说明
id	bigint	主键
region_id	bigint	本地区域 ID
camera_source	varchar(64)	摄像头来源系统编码
camera_id	varchar(128)	第三方摄像头唯一标识
camera_name	varchar(255)	摄像头名称缓存
camera_unit_id/name	varchar	所属单位标识及名称缓存
camera_type_code/name	varchar	类型编码及名称缓存
camera_level_code/name	varchar	等级编码及名称缓存
camera_dept_id/name	varchar	主管部门标识及名称缓存
online_status	varchar(32)	在线状态缓存
camera_snapshot	json	第三方其他扩展字段快照
camera_synced_at	datetime	缓存最近同步时间
leader_user_id	bigint	摄像头负责人用户 ID
bind_status	varchar(32)	BOUND/UNBOUND，若逻辑删除足够可不单设
bound_time	datetime	绑定时间

建议索引：

• 唯一索引：tenant_id + camera_source + camera_id，落实一个摄像头只绑定一个区域。
• 区域列表索引：tenant_id + region_id + delete_enum。
• 摄像头负责人索引：leader_user_id，仅在需要按负责人查询时增加。

当前只缓存已经绑定的摄像头，因此展示字段直接放在绑定表中即可。如果后续要求缓存全部第三方摄像头、未绑定摄像头也要离线搜索，或一个摄像头允许绑定多个区域，则应拆分为“摄像头缓存表 + 区域摄像头关系表”。

5. 页面功能拆解

5.1 区域树

• 按当前用户数据权限加载企业。
• 批量查询企业下全部区域并组装树。
• 支持新增顶级区域、同级区域和下级区域。
• 支持修改和删除区域。
• 选中区域后显示企业/区域面包屑。

5.2 新增或修改区域

入参建议：

• parentId：新增顶级区域时为空。
• corpId：必填。
• regionName：必填。
• leaderUserId：按当前原型必填。
• coordinateSystem：必填。
• fencePoints：必填且恰好 4 点。
• sortNo：可选。

5.3 选择摄像头

• 显示当前区域路径。
• 调用第三方接口分页查询摄像头。
• 支持视频名称、等级、在线状态等第三方支持的条件。
• 已绑定当前区域的摄像头默认勾选。
• 已绑定其他区域的摄像头应禁选或明确标识。
• 确认后计算新增绑定和解除绑定差异，在一个本地事务中保存。

5.4 区域摄像头列表

列表字段来自两部分：

字段	来源
视频名称、所属单位、类型、等级、主管部门、在线状态	本地缓存字段展示，第三方接口负责刷新
所属区域、摄像头负责人、绑定时间	本地绑定字段

列表操作：设置摄像头负责人、查看第三方摄像头详情、解除绑定。原型中的“删除”建议在业务文案中改为“解绑”，避免误解为删除第三方摄像头。

6. 接口建议

6.1 内部区域管理接口

能力	建议接口语义
区域树	按数据权限返回企业虚拟根和区域树
新增区域	新增顶级或下级区域
修改区域	修改名称、负责人、围栏和排序
删除区域	校验子区域和摄像头绑定后逻辑删除
区域摄像头分页	查询选中区域直接绑定的摄像头
可选摄像头分页	代理/调用第三方摄像头查询能力
保存摄像头绑定	批量计算并保存绑定差异
设置摄像头负责人	更新绑定记录负责人
解除摄像头绑定	逻辑删除本地绑定关系

6.2 第三方区域开放接口

综合平台作为区域数据提供方，建议至少提供：

• 区域分页查询。
• 区域详情查询。
• 区域树查询。

开放接口是否返回区域绑定摄像头需要第三方确认。建议区域和摄像头绑定分别返回，避免区域树报文过大：

• RegionCo：区域自身信息、层级、负责人、围栏。
• RegionCameraCo：区域 ID、第三方摄像头 ID、摄像头负责人。

第三方开放接口使用独立鉴权和数据范围，不直接复用页面登录权限。

7. DDD 落位

模块	内容
web-client	Region、RegionCamera 的 Cmd、Qry、Co 和服务接口
web-adapter	区域管理 Controller、第三方区域开放接口
web-app	区域增删改查、组树、摄像头绑定和负责人设置执行器
web-domain	RegionE、RegionCameraBindingE、树及围栏规则、Gateway
web-infrastructure	DO、Mapper、Repository、GatewayImpl、第三方摄像头 Facade 适配
start	RPC Client 和配置装配；当前不需要推送定时任务

第三方摄像头访问能力在 Domain 定义 Gateway，在 Infrastructure 通过 Dubbo 或 HTTP 实现。外部摄像头 DTO 不进入 Domain 和 Client。

8. 待确认问题

区域

• 是否需要区域编码，对外唯一标识采用 ID 还是编码？
• 顶级区域 parent_id 使用 NULL 还是 0？
• 区域最大层级是多少，是否允许移动节点？
• 区域负责人是否只能有一个？
• 坐标使用哪种坐标系？四点是否永远固定，还是后续允许任意多边形？
• 是否要求判断摄像头坐标或告警坐标是否处于区域内？
• 区域是否需要启用/停用状态？

摄像头

• 摄像头第三方接口的系统、协议和 Common Facade 是什么？
• 摄像头唯一主键是什么，是否跨企业唯一？
• 是否支持分页及原型中的名称、等级、在线状态筛选？
• 一个摄像头是否只能绑定一个区域？
• 查询某区域时只展示直接绑定摄像头，还是包含所有子区域摄像头？
• 解绑后负责人是否随绑定记录一起失效？
• 第三方不可用时页面是报错，还是允许展示本地快照？

开放接口

• 第三方只查询区域，还是同时查询区域摄像头绑定？
• 需要全量分页、区域树还是更新时间增量查询？
• 是否需要返回逻辑删除区域和已解除绑定关系？
• 鉴权、签名、IP 白名单及租户范围如何确定？

9. 当前不开发内容

• 人员、企业、部门、岗位和人脸主数据维护。
• 人员与区域准入关系。
• 摄像头主数据维护和删除。
• 主动推送、推送任务、回执和失败重试。

上一版人员推送 DDL 已删除。当前 RegionManagementDDL.sql 是根据原型形成的区域表草案；坐标系、摄像头唯一性和区域删除规则确认后，再作为正式迁移脚本执行。

10. 第三方报警接收与处置

10.1 接入方式

报警由第三方产生，建议综合平台提供报警接收回调接口，由第三方主动调用：

第三方 -> 鉴权/验签 -> 幂等校验 -> 报警落库 -> 返回受理成功
                                      └-> 用户后续处置

以 sourceSystem + alarmNo 作为幂等键。第三方重复推送同一报警编号时返回已受理，不重复新增。接收接口只负责报警可靠落库，不同步执行隐患长流程。

第三方至少传摄像头和区域信息，本系统校验并固化企业、区域及摄像头历史快照。区域或摄像头无法识别时是否拒绝接收，待双方接口协议确定。

报警业务报文只要求当前确认字段：报警编号、报警时间、报警地址、区域、摄像头和一张报警截图。来源系统、接收时间及处置状态属于综合平台接入和管理字段，不要求第三方提供。

10.2 图片传输

当前暂定第三方在 JSON 报警报文中直接传单张截图 URL，综合平台在 alarm_image_url 中保存并用于详情展示，不接收文件流，也不保存 BLOB 或 Base64。

正式联调前需要确认 URL 是否长期有效、是否需要鉴权、是否允许综合平台服务端访问。如果 URL 是短期签名地址，应改为稳定文件 ID，或由综合平台接收后转存统一文件服务。

10.3 处置状态机

PENDING（未处置）
  ├─ 误报=是  -> DISPOSED
  └─ 误报=否
       ├─ 隐患=否 -> 填写结果 -> DISPOSED
       └─ 隐患=是 -> 创建隐患 -> DISPOSED

• 误报直接闭环，不进入隐患流程。
• 非误报必须选择是否隐患。
• 非隐患必须填写处置结果，提交后闭环。
• 隐患调用 ZcloudHiddenFacade.aiHiddenAndSave(HiddenAddCmd)，以报警编号作为 foreignKey。
• 隐患流程和进度以隐患服务为准，本地不再维护报警闭环状态。
• 当前报警不经过派单、转办或审批，每条报警只提交一次处置结论；处置人、处置时间及公共更新审计字段用于留痕。

10.4 数据表

区域、摄像头绑定、报警和处置统一维护在 web-infrastructure/src/main/resources/RegionManagementDDL.sql，报警部分包含：

表	用途
edgeguard_alarm	报警事实、区域/摄像头快照、当前状态、统计维度
edgeguard_alarm_disposal	是否误报、是否隐患、直接处置结果及关联隐患 ID

Common 已有 ZcloudHiddenFacade 的 aiHiddenAndSave、listByForeignKey 和 queryHiddenCheckStatus 等能力。本系统不复制隐患主表，也不缓存隐患状态、级别和进度。创建成功后只在报警处置表保存 hidden_id；详情页根据该 ID 调用隐患服务查询实时详情。

为处理隐患接口临时失败，处置表仅额外保存 hidden_create_status 和 hidden_create_error。它们属于调用可靠性字段，不是隐患业务数据。以报警编号作为 foreignKey 保证隐患创建幂等。

10.5 统计

一期直接聚合报警主表，不建统计结果表：

• 股份端按 corp_id 统计各分公司报警总数、未处置和已处置。
• 分公司端按 region_id 统计各区域报警总数、未处置和已处置。
• 可统计误报数、隐患数和非隐患处置数。

报警保存发生时的企业、区域和摄像头快照，后续改名或移动不影响历史台账。数据量较大后再增加按日汇总表。

10.6 待确认

• 第三方报警接口的 JSON 报文、鉴权、签名及重试规则。
• 第三方报警 ID 是否在来源系统内永久唯一。
• 报警截图 URL 的有效期、访问鉴权和网络可达性。
• 处置结果字典。
• 误报是否仍需填写处置原因。
• 隐患级别、确认人、整改人和期限由谁填写。
• 是否允许修改处置结论、重新打开报警及是否需要审批。

10.7 报警查看权限升级

当前需求只控制报警列表的可见范围，不需要增加业务表：

• 摄像头负责人从报警入库开始即可查看该摄像头产生的报警。
• 报警保持 PENDING 且超过配置的升级时长后，所属区域负责人也可以查看。
• 当前升级时长为 10 分钟，必须配置化，禁止硬编码在查询 SQL 中。
• 超时基准使用综合平台 received_time，不使用第三方 alarm_time，避免延迟推送导致报警刚入库就被升级。
• 报警处置后进入台账的查看范围按页面数据权限确定，不再依赖 10 分钟规则。

查询逻辑：

当前用户是摄像头负责人
OR
当前用户是区域负责人
  AND disposal_status = PENDING
  AND received_time <= 当前时间 - 配置分钟数

摄像头负责人从 edgeguard_region_camera.leader_user_id 获取，区域负责人从 edgeguard_region.leader_user_id 获取。负责人发生变更后按当前负责人权限查询；如果未来要求报警产生时锁定负责人，再在报警表增加负责人快照字段。

本规则只表示“能够在列表看到”，不表示系统主动通知。若后续要求短信、消息中心或待办提醒，并需要记录发送结果和防止重复通知，再设计通知记录或升级标记。

11. 待开发接口总清单

11.1 接口设计约定

• 页面内部接口统一放在 /edgeguard/**，使用登录态、接口权限和数据权限。
• 第三方开放接口统一放在 /open/edgeguard/**，使用独立的应用鉴权、签名、防重放和租户/企业授权范围。
• 新增使用 POST，修改使用 PUT，删除或解绑使用 DELETE，详情使用 GET，复杂分页查询使用 POST。
• 新增、修改入参使用 XxxCmd，分页查询使用 XxxPageQry，返回对象使用 XxxCo。
• 单对象返回 SingleResponse<T>，分页返回 PageResponse<T>，集合返回 MultiResponse<T>，无数据操作返回 Response。
• 下表中的权限编码先使用“待分配”标识，等菜单和权限资源建立后再填写真实值，禁止复制示例权限编码。
• corpId、tenantId、orgId 等数据范围不得只信任前端入参，必须结合当前用户上下文和数据权限校验。
• 接口路径是当前开发基线；如果项目统一网关会自动增加服务前缀，Controller 中不重复拼接网关前缀。

11.2 区域管理接口

编号	方法与路径	用途	主要入参	主要返回	核心规则	优先级
REGION-01	GET /edgeguard/regions/tree	加载企业虚拟根及区域树	可选 corpId	MultiResponse<RegionTreeNodeCo>	企业来自公共服务；区域一次批量查询后内存组树；按当前用户企业数据权限过滤	P0
REGION-02	GET /edgeguard/regions/{id}	查询区域详情	id	SingleResponse<RegionCo>	校验数据权限；负责人姓名使用公共翻译；围栏返回有序点集合	P0
REGION-03	POST /edgeguard/regions	新增顶级或下级区域	RegionAddCmd	SingleResponse<Long>	校验父子企业一致、同级名称、负责人、坐标系及四点围栏；生成 regionCode/treePath/treeLevel	P0
REGION-04	PUT /edgeguard/regions/{id}	修改区域	id + RegionUpdateCmd	Response	一期不提供父节点迁移；修改名称、负责人、围栏、排序和状态；使用版本号防并发覆盖	P0
REGION-05	DELETE /edgeguard/regions/{id}	删除区域	id	Response	存在子区域或有效摄像头绑定时禁止删除；使用逻辑删除	P0

RegionAddCmd 建议字段：

• corpId、parentId、regionName、leaderUserId。
• coordinateSystem、List<FencePointCmd> fencePoints。
• sortNo、remarks。

RegionUpdateCmd 在上述可修改字段外增加 id/version/regionStatus。regionCode、corpId、treePath 和 treeLevel 不允许由前端直接修改。

11.3 区域摄像头接口

编号	方法与路径	用途	主要入参	主要返回	核心规则	优先级
CAMERA-01	POST /edgeguard/region-cameras/page	查询区域已绑定摄像头	RegionCameraPageQry	PageResponse<RegionCameraCo>	必须传 regionId；从本地快照分页；支持名称、等级、在线状态；负责人批量翻译	P0
CAMERA-02	POST /edgeguard/region-cameras/candidates/page	查询第三方可选摄像头	CameraCandidatePageQry	PageResponse<CameraCandidateCo>	通过 Infrastructure Gateway 调第三方；标记未绑定、已绑定当前区域、已绑定其他区域	P0，依赖第三方契约
CAMERA-03	PUT /edgeguard/regions/{regionId}/cameras	保存区域摄像头选择结果	regionId + RegionCameraBindCmd	Response	入参提交选中的 cameraSource + cameraId；服务端重新查询权威数据；计算新增和解绑差异并在本地事务保存；重复提交幂等	P0，依赖第三方契约
CAMERA-04	PUT /edgeguard/region-cameras/{id}/leader	设置摄像头负责人	id + CameraLeaderUpdateCmd	Response	负责人必须为有效用户；只修改当前有效绑定	P0
CAMERA-05	DELETE /edgeguard/region-cameras/{id}	解除摄像头绑定	id	Response	只解除本地关系，不删除第三方摄像头；写入 UNBOUND/unboundTime	P0
CAMERA-06	GET /edgeguard/region-cameras/{id}	查看摄像头详情	id	SingleResponse<RegionCameraCo>	优先查询第三方实时详情；失败时返回本地快照并明确 snapshot=true	P1，依赖第三方契约

RegionCameraPageQry 至少包含 regionId，可选 cameraName/cameraLevelCode/onlineStatus。摄像头选择接口的分页字段和筛选能力最终以第三方接口能力为准。

11.4 第三方区域开放接口

编号	方法与路径	用途	主要入参	主要返回	核心规则	优先级
OPEN-REGION-01	POST /open/edgeguard/regions/page	第三方分页查询区域	OpenRegionPageQry	PageResponse<OpenRegionCo>	只返回调用方被授权企业的数据；默认不返回逻辑删除数据	P1
OPEN-REGION-02	GET /open/edgeguard/regions/{regionCode}	第三方查询区域详情	regionCode	SingleResponse<OpenRegionCo>	对外使用稳定的 regionCode，不暴露仅供内部使用的查询规则	P1
OPEN-REGION-03	GET /open/edgeguard/regions/tree	第三方查询企业区域树	corpId	MultiResponse<OpenRegionTreeNodeCo>	corpId 必须在应用授权范围内；只返回真实区域节点	P1
OPEN-REGION-04	POST /open/edgeguard/region-cameras/page	第三方查询区域摄像头绑定	OpenRegionCameraPageQry	PageResponse<OpenRegionCameraCo>	与区域接口分开分页，避免区域树报文过大；是否开放负责人字段联调前确认	P1

开放接口不直接复用页面 Controller。鉴权失败、签名错误、越权、参数错误和服务异常需要使用双方约定的稳定错误码。

11.5 报警接收与处置接口

编号	方法与路径	用途	主要入参	主要返回	核心规则	优先级
ALARM-01	POST /open/edgeguard/alarms	接收第三方报警	AlarmReceiveCmd	SingleResponse<AlarmReceiveCo>	以 sourceSystem + alarmNo 幂等；服务端设置 receivedTime/PENDING；根据摄像头绑定固化企业、区域和摄像头快照	P0，依赖第三方报文/鉴权
ALARM-02	POST /edgeguard/alarms/page	报警处置列表/台账分页	AlarmPageQry	PageResponse<AlarmCo>	未处置列表执行负责人和10分钟升级规则；台账按页面数据权限；支持编号、区域、状态、时间筛选	P0
ALARM-03	GET /edgeguard/alarms/{id}	查询报警及处置详情	id	SingleResponse<AlarmDetailCo>	返回报警、处置结论和 hiddenId；不复制隐患详情，前端按 ID 调隐患服务	P0
ALARM-04	POST /edgeguard/alarms/{id}/disposal	提交报警处置	id + AlarmDisposeCmd	Response	一条报警只处置一次；校验误报/隐患条件；保存处置记录并将报警改为 DISPOSED	P0
ALARM-05	POST /edgeguard/alarms/{id}/hidden/retry	重试创建隐患	id	Response	仅 isHiddenHazard=1 且创建失败时允许；以报警编号作为 foreignKey 保证幂等	P1

AlarmReceiveCmd 当前确认字段：

• sourceSystem、alarmNo、alarmTime、alarmAddress。
• cameraSource、cameraId、cameraName。
• regionCode（第三方可传，但最终以本地摄像头绑定匹配结果校验）。
• alarmImageUrl。

AlarmReceiveCo 返回本地 alarmId、alarmNo 和 repeated，重复推送返回受理成功而不是重复插入。

AlarmDisposeCmd 建议字段：

• isFalseAlarm：必填。
• isHiddenHazard：非误报时必填。
• disposalResultCode/disposalResultName/disposalDescription：非误报且非隐患时按业务规则必填。
• 创建隐患所需字段暂不固化到本文，确认 HiddenAddCmd 必填项后补充；禁止由 Controller 直接调用隐患 Facade。

处置事务边界：先完成本地处置条件校验；隐患远程创建不能放在持有数据库锁的长事务中。远程调用成功后保存 hiddenId/SUCCESS；失败时保存 FAILED/error 并允许 ALARM-05 重试。报警是否在隐患创建失败时立即标记为 DISPOSED，开发 ALARM-04 前必须最终确认。

11.6 报警统计接口

统计接口属于已确认开发范围，依据原型 E:\job_worde\人脸识别原型\人脸识别原型\人脸识别综合原型.html 实现，不再作为待确认功能：

• 分公司端按当前分公司下的区域分页展示：报警区域、报警总数、未处置、已处置、查看。
• 股份端按分公司分页展示：分公司名称、报警总数、未处置、已处置。
• 股份端点击分公司名称下钻到该分公司的区域统计。
• 区域统计点击“查看”进入统计报警台账，并自动携带公司和区域条件。
• 统计报警台账展示报警编号、报警区域、报警摄像头、报警时间、处置状态和查看操作；查询复用 ALARM-02。
• 没有报警的已维护区域也要展示为 0，不能只从报警表 GROUP BY 后返回有数据的区域；区域维度应以有效区域表为主表左连接报警聚合结果。

编号	方法与路径	用途	主要入参	主要返回	核心规则	优先级
STAT-01	POST /edgeguard/alarm-statistics/corporations	股份端按分公司统计	AlarmCorpStatisticQry	PageResponse<AlarmCorpStatisticCo>	按 corpId 聚合总数、未处置、已处置；公司名称来自公共服务；受股份端数据权限控制	P0
STAT-02	POST /edgeguard/alarm-statistics/regions	分公司端及股份下钻按区域统计	AlarmRegionStatisticQry	PageResponse<AlarmRegionStatisticCo>	必须传或从权限确定 corpId；以有效区域为基础分页并关联报警聚合，包含报警数为0的区域	P0

统计页面点击公司或区域后的明细复用 ALARM-02，携带 corpId/regionId/disposalStatus，不再增加重复的台账查询接口。

11.7 暂不单独开发的接口

• 企业、部门、岗位、用户主数据接口：统一调用公共服务或使用 TranslateField，本项目不维护。
• 摄像头新增、修改、删除接口：摄像头主数据归第三方，本项目只查询和绑定。
• 隐患详情、进度和整改接口：复用隐患服务，本项目只保存 hiddenId。
• 报警附件接口：当前只有单张截图 URL，直接保存在报警主表。
• 报警派单、转办、操作轨迹接口：当前报警直接处置，没有派单流程。
• 人员、人脸和人员区域准入接口：不在当前项目范围。
• 主动推送、回执和失败重试接口：当前综合平台是数据提供方和报警接收方，不主动推送。

11.8 外部依赖契约

依赖	使用接口	当前状态	开发前需要确认
企业/用户公共服务	REGION-01~04、CAMERA-04、统计展示	已有公共能力	企业数据权限来源、负责人有效性校验和批量翻译字段
第三方摄像头服务	CAMERA-02/03/06	契约待提供	协议、分页报文、筛选字段、唯一 ID、详情接口、超时和错误码
第三方报警平台	ALARM-01	契约待联调	JSON 报文、鉴权签名、重试策略、截图 URL 有效期、区域/摄像头无法匹配时的处理
隐患服务 ZcloudHiddenFacade	ALARM-04/05	Common 已有能力	HiddenAddCmd 必填字段、返回的隐患 ID、幂等行为、失败错误码

11.9 建议实现顺序与状态

接口状态统一使用：TODO、DOING、DONE、BLOCKED。每完成一个接口，需要同时更新本文状态、请求/响应示例、权限编码和异常码。

开发批次	接口	当前状态	原因
第1批：区域闭环	REGION-01~05	DOING	分层实现、校验、测试及编译已完成；待菜单资源分配真实权限编码后转 DONE
第2批：摄像头绑定	CAMERA-01~05	TODO	本地绑定可开发；候选和保存快照依赖第三方摄像头契约
第3批：报警与统计	ALARM-01~04、STAT-01~02	TODO	统计需求和下钻行为已由原型确认；与报警主流程同批开发、联调
第4批：开放查询	OPEN-REGION-01~04	TODO	需先确认第三方实际需要和开放鉴权方案
第5批：增强能力	CAMERA-06、ALARM-05	TODO	实时详情降级和隐患失败重试

推荐从 REGION-01 区域树接口开始逐个实现。每个接口的完成标准包括：Client 契约、Controller、App 执行器、Domain 规则、Infrastructure 查询/持久化、权限与数据范围、参数校验、异常码、单元测试或集成测试，以及 Maven 编译通过。