starRiverProperty/backend/cw-elevator-application/cw-elevator-application-service/docs/02-passrule-and-person.md

02 通行规则与人员（passrule / person）

2.1 业务目标

• 通行规则：按 区域/楼层/图库/标签/组织 等维护通行策略，与平台图库、设备绑定任务配合。
• 图库规则引用（ImageRuleRefService）：从 图库/图片 ID 视角查规则列表、只增规则、人员列表、分页等，与 AcsPassRuleService 的「规则主 CRUD」互补。
• 人员：AcsPersonService 面向业务侧人员维护；PersonRuleService 在 规则上下文 下做人员/访客的增删改查及 与图库人员 的关联（如 personDetail）。

2.2 AcsPassRuleService 方法表

方法	概要
listFloor	规则关联楼层列表
getIsDefaultByZoneId	区域下是否默认规则等标识
add / update / delete / detail / page / list	标准 CRUD 与详情分页
listByImageId	按图库/图片查规则 DTO 列表，供设备或绑定流使用

2.3 ImageRuleRefService 方法表

方法	概要
page	图库规则分页（与规则查询参数共用部分字段）
listFloor	图库侧楼层规则列表
listByPersonInfo	按人维度列规则/楼层
listByPersonList	批量人列表与规则关系
detail	单条图库规则详情
addOnlyRule	仅 建规则（设备任务中「非人员」线可能走此路）
update / delete	更新/删除，与 AcsPassRuleService 分工依实现类而定

实现基类提示：passrule/impl/AbstractAcsPassService.java 可抽取与远程/DAO 的共性。

2.4 AcsPersonService 与 PersonRuleService

接口	特点
AcsPersonService	add / edit / delete / page / timeDetail / pageByApp
PersonRuleService	在规则域增加 addVisitor、personDetail(图库人员) 等

2.5 用例图（简）

flowchart LR
  Admin((管理员))
  Admin --> P1[维护通行规则]
  Admin --> P2[按图查规则/楼层]
  Admin --> P3[维护人员/访客]
  P1 --> S1[AcsPassRuleService]
  P2 --> S2[ImageRuleRefService]
  P3 --> S3[PersonRuleService / AcsPersonService]

2.6 时序：仅创建规则（与设备任务线关联）

sequenceDiagram
  participant Task as AcsDeviceTaskServiceImpl
  participant IMG as ImageRuleRefService
  Task->>IMG: addOnlyRule(区域/标签/组织)
  IMG-->>Task: CloudwalkResult
  Note over Task: 成功后再推进 bind 进度

2.7 与设备任务关系（概念）

• 人员绑定：updateFloors 中若带 personId，走 PersonRuleService.add/delete 按 楼层/区域 维度。
• 非人员（标签/组织）：建/删 规则名 与 ImageRuleRef DAO，并调 imageRuleRefService 的删除或 addOnlyRule。

更多细节以 AcsPassRuleServiceImpl.java、AcsDeviceTaskServiceImpl.java 源码为准。