Initial commit: reorganized source tree

- backend/: 13 Maven modules (cw-elevator-application, cloudwalk-cloud, intelligent-cwoscomponent, ninca-crk, etc.) - frontend/: 4 Vue projects (elevator-front, cwos-portal, alarm-front, front_acs) + decompiled + scripts - scripts/: build, test-env, tools (Docker Compose, service templates, API parity) - docs/: AGENTS.md, superpowers specs, architecture docs - .gitignore: standard Java/Maven exclusions Moved from legacy maven-*/ root layout to backend/ organized structure.
2026-06-09 16:30:29 +08:00 · 2026-05-09 09:00:12 +08:00
commit 7b2bd307f1
7260 changed files with 612980 additions and 0 deletions
@@ -0,0 +1,108 @@
+# 00 总览：模块定位与领域结构
+
+## 1. 模块在系统中的位置
+
+`cw-elevator-application-service` 是电梯应用的 **业务编排与领域服务实现** 层：
+
+- **向上** 被 `cw-elevator-application-web`（HTTP 入口）等调用。
+- **向下** 依赖 `cw-elevator-application-data`（DAO/MyBatis）与多类 **OpenFeign 客户端**（CWOS 设备/人员/图库/系统设置、访客标准服务、第三方 MQTT 等）。
+- **横切** 使用 Spring 事件（`CloudwalkEventManager`）、缓存（`@Cacheable`）、异步（`@Async`）等。
+
+```mermaid
+flowchart LR
+  subgraph Web["cw-elevator-application-web"]
+    C[Controllers]
+  end
+  subgraph Svc["cw-elevator-application-service 本文档范围"]
+    D[device]
+    P[passrule / person]
+    R[record]
+    Z[zone / code]
+    M[mqtt / export / ...]
+  end
+  subgraph Data["cw-elevator-application-data"]
+    DAO[DAO / Mapper]
+  end
+  subgraph Ext["外部服务 Feign / HTTP"]
+    W[CWOS intelligent-*]
+    V[访客 ninca-crk-std]
+    Q[MQTT 第三方]
+  end
+  C --> Svc
+  Svc --> DAO
+  Svc --> W
+  Svc --> V
+  Svc --> Q
+```
+
+## 2. 领域全景（思维导图）
+
+```mermaid
+mindmap
+  root((elevator service))
+    设备 device
+      本应用电梯设备 CRUD
+      与平台设备联动分页
+      重组绑定 楼层/人员/条件
+      异步任务 进度
+    通行与人员
+      规则 passrule
+      图库规则 image 规则
+      人员 acs 与 规则 person
+    记录 record
+      通行记录
+      识别记录
+      分析统计
+    区域与编码
+      区域树 zone
+      电梯码 codeElevatorArea
+    集成
+      mqtt 推送
+      导出 export
+      下载 downloadcenter
+      文件 storage
+```
+
+## 3. 核心服务接口与包对应关系
+
+```mermaid
+classDiagram
+  class AcsElevatorDeviceService
+  class AcsDeviceTaskService
+  class AcsPassRuleService
+  class ImageRuleRefService
+  class AcsPersonService
+  class PersonRuleService
+  class AcsElevatorRecordService
+  class AcsRecogRecordService
+  class ZoneService
+  class AcsElevatorCodeService
+  class MqttService
+  AcsElevatorDeviceService : +设备与绑定编排
+  AcsDeviceTaskService : +updateFloors 任务推进
+  AcsPassRuleService : +规则 CRUD 与图库 list
+  ImageRuleRefService : +图库视角规则
+  AcsPersonService : +人员 page 等
+  PersonRuleService : +规则内人员/访客
+  AcsElevatorRecordService : +通行记录
+  AcsRecogRecordService : +识别记录 add
+  ZoneService : +区域树
+  AcsElevatorCodeService : +电梯码
+  MqttService : +sendInfoToOne
+```
+
+## 4. 与外部系统协作（逻辑视图）
+
+| 外部能力 | 典型用途 |
+|----------|----------|
+| `intelligent` 设备/人员/图库/系统设置 | 设备主数据、人员同步、图库、区域树 |
+| `ninca-crk-std`（IP 配置 + RestTemplate 或 Feign） | 访客 **three 线** 与 **Feign `VisitorFeignClient`** 不同路径 |
+| `cloudwalk-device-thirdparty` / MQTT | 发布主题推送识别摘要 |
+| DaVinci 文件分片 | `AcsFileStorageService` 大文件 |
+| 下载中心 | 异步任务结果取回 |
+
+## 5. 读文档建议
+
+1. 先读 [01-device-and-task.md](01-device-and-task.md) 理解「设备—楼层—任务」主路径。
+2. 再读 [02-passrule-and-person.md](02-passrule-and-person.md) 理解规则与人员两条下发线。
+3. 记录、MQTT 与事件见 [03-record-recognition.md](03-record-recognition.md) 与 [04-mqtt-visitor-event.md](04-mqtt-visitor-event.md)。
@@ -0,0 +1,75 @@
+# 01 设备与设备任务（`device`）
+
+## 1.1 业务目标
+
+- 维护 **本应用视角** 的电梯设备与平台设备（`DeviceService`）的关联数据。
+- 支持 **重组/绑定**：按区域、标签、组织等条件选择楼层，将 **人员** 或 **规则** 批量下发到设备侧（经远程服务）。
+- 通过 **设备任务**（`AcsDeviceTaskService` / `AcsDeviceTaskServiceImpl`）在楼层维度 **有界并行** 执行远程步骤，并 **按完成顺序** 推进任务上的 `bindDevices` 等进度（与走查约定 §9 一致）。
+
+## 1.2 主接口 `AcsElevatorDeviceService`
+
+| 方法 | 行为概要 |
+|------|----------|
+| `add` / `edit` / `delete` | 电梯设备增删改，写本库并协调平台设备信息 |
+| `get` / `getById` / `getFo` | 分页列表、单条、表单选项数据 |
+| `getBuildingId` / `getBusinessId` | 从查询条件解析楼宇或租户 |
+| `devicePage` | 走 **平台** 设备分页，与 `Acs` 表关联展示 |
+| `listUnbindFloors` / `listFloors` / `listCondition` / `listConditionByLabelIds` | 绑定时待选楼层、已绑楼层、条件筛选（标签等） |
+| `bindingFloors` / `bindingPerson` | 启动绑定：创建/更新设备任务，异步 `updateFloors` |
+| `getTask` / `setTaskStop` | 查询任务进度、停止任务 |
+
+**实现类**：`device/impl/AcsElevatorDeviceServiceImpl.java`。
+
+## 1.3 设备任务 `AcsDeviceTaskService`
+
+| 方法 | 行为概要 |
+|------|----------|
+| `updateFloors` | 在 **增加楼层 / 删除楼层** 两路上，将远程调用按 **每批 `UPDATE_FLOORS_FLOOR_PARALLEL` 个楼层** 提交到 `elevatorRemoteBoundedExecutor`；`FeignThreadLocalUtil` 在子任务中恢复租户上下文；每步成功再 `advanceBindProgressOne` 更新 `bindDevices`。 |
+
+**实现类**：`device/impl/AcsDeviceTaskServiceImpl.java`。
+
+## 1.4 用例级视图（操作者：管理员 / 系统）
+
+```mermaid
+flowchart TB
+  subgraph 电梯设备管理
+    A[增删改电梯设备]
+    B[分页查询/详情]
+  end
+  subgraph 重组绑定
+    C[选楼层/人员或规则]
+    D[启动 bindingFloors/bindingPerson]
+    E[异步 updateFloors]
+  end
+  A --> B
+  C --> D --> E
+```
+
+## 1.5 时序：启动楼层绑定后异步推进（概念）
+
+```mermaid
+sequenceDiagram
+  participant Web as Web/Controller
+  participant Dev as AcsElevatorDeviceServiceImpl
+  participant Task as AcsDeviceTaskService
+  participant Pool as 有界线程池
+  participant Remote as 人员/规则 Feign
+  Web->>Dev: bindingFloors(参数)
+  Dev->>Task: 异步 updateFloors(...)
+  loop 每批楼层
+    Task->>Pool: invokeAll(子任务)
+    Pool->>Remote: add/delete 单楼层步骤
+    Remote-->>Task: 成功
+    Task->>Task: advanceBindProgressOne(taskId)
+  end
+```
+
+## 1.6 设备设置子域 `device/setting`
+
+- **`AcsDeviceSettingService`**：如体温相关设置查询（`getTemperatureSetting`）。
+- **`AcsDeviceImageStoreAppBindService`**：设备与图库应用绑定/解绑等（实现见 `setting/impl`）。
+
+## 1.7 与邻域关系
+
+- **规则/人员**：`updateFloors` 内调 `PersonRuleService`、`ImageRuleRefService` 等，取决于绑定参数是 `personId` 还是标签/组织。
+- **data 层**：`AcsDeviceTaskDao`、设备相关 DAO 在 **data 模块**。
@@ -0,0 +1,68 @@
+# 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 用例图（简）
+
+```mermaid
+flowchart LR
+  Admin((管理员))
+  Admin --> P1[维护通行规则]
+  Admin --> P2[按图查规则/楼层]
+  Admin --> P3[维护人员/访客]
+  P1 --> S1[AcsPassRuleService]
+  P2 --> S2[ImageRuleRefService]
+  P3 --> S3[PersonRuleService / AcsPersonService]
+```
+
+## 2.6 时序：仅创建规则（与设备任务线关联）
+
+```mermaid
+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` 源码为准。
@@ -0,0 +1,63 @@
+# 03 通行记录与识别记录（`record`）
+
+## 3.1 业务目标
+
+- **电梯通行/开门记录**（`AcsElevatorRecordService`）：分页查询、**新增**（落库、访客判断、发域事件）、修改状态、统计、Redis 缓存键等。
+- **人员识别记录**（`AcsRecogRecordService`）：单接口 `add`，与图库/识别流对接。
+- **图库文件**（`PersonFileService`）：`upload` 小图片字节上传，给记录新增时 **Base64 解码后** 调图库。
+- **`SendRecordTimeService`**：接口体为空，**无方法**，可视为占位或历史契约保留。
+
+## 3.2 `AcsElevatorRecordService` 方法表
+
+| 方法 | 概要 |
+|------|------|
+| `openRecord` | 分页查开门记录明细，**一年** 窗口校验；组装区域/片区/人员展示字段 |
+| `add` | 见 [04-mqtt-visitor-event.md](04-mqtt-visitor-event.md) 的访客与事件说明 |
+| `modify` | 按条件改开门记录 **状态**（如从 INIT 更新） |
+| `createCache` | 分布式任务锁下 **Redis 缓存** 初始化 |
+| `pageInfo` | 分页查询请求维表信息类结果 |
+| `analyseCycle` / `analyseCount` | 按周期/条件的开门统计、排行等 |
+
+**实现类**：`record/impl/AcsElevatorRecordServiceImpl.java`。
+
+## 3.3 识别子域
+
+- **`AcsRecogRecordService#add`**：`AcsRecogRecordServiceImpl` 中增加识别记录（实现细节见同文件）。
+
+## 3.4 流程图：`openRecord` 主路径
+
+```mermaid
+flowchart TD
+  A[入参+分页] --> B{时间跨度>1年?}
+  B -- 是 --> X[失败返回]
+  B -- 否 --> C[DAO 分页]
+  C --> D[去重取片区/区域id]
+  D --> E[批量查设备片区名]
+  E --> F[取区域树缓存/区域父名]
+  F --> G[批量查人员底库照]
+  G --> H[组装 AcsElevatorRecordResult 分页返回]
+```
+
+## 3.5 时序：`add` 落库前访客与人员（节选）
+
+```mermaid
+sequenceDiagram
+  participant S as AcsElevatorRecordServiceImpl
+  participant HTTP as ninca-crk-std HTTP
+  participant P as PersonService
+  participant DAO as AcsElevatorRecordDao
+  participant EVT as CloudwalkEventManager
+  S->>HTTP: POST three/visitor/record/query
+  HTTP-->>S: 是否访客+被访人
+  S->>P: detail(识别脸 id)
+  P-->>S: 工号/组织
+  S->>DAO: add(DTO)
+  S->>EVT: publish(VisitorRecordPushEvent)
+```
+
+## 3.6 领域事件
+
+- 类型：`record/result/VisitorRecordPushEvent.java`  
+- 主题 `getTopic()` 固定为 `VISITOR_RECORD_TOPIC`（供订阅方区分）。
+
+与 MQTT 的关系见 [04-mqtt-visitor-event.md](04-mqtt-visitor-event.md)。
@@ -0,0 +1,51 @@
+# 04 MQTT、访客与域事件
+
+## 4.1 双通道：访客查询
+
+| 方式 | 路径/Bean | 使用场景（本模块） |
+|------|-----------|---------------------|
+| **HTTP + RestTemplate** | `combineAuthClientURI("intelligent/three/visitor/record/query")` | `AcsElevatorRecordServiceImpl#add` 反查是否访客 |
+| **Feign** | `VisitorFeignClient` → `/intelligent/visitor/record/query` | 定义在 `visitor/client`，**本模块内无直接注入调用** |
+
+两者 **不是** 同一路径；业务上均面向标准访客中心，但 **「three」** 与 **「intelligent」** 为产品/版本差异，部署时需与 `ninca-crk-std` 实际路由一致。
+
+## 4.2 `MqttService` 与 `MqttServiceImpl`
+
+| 项 | 说明 |
+|----|------|
+| `sendInfoToOne` | `@Async`：先 **睡眠约 10s** 等待识别记录落库，再查识别流水，拼 `AcsElevatorRecordMqttParam`，向 topic `{businessId}+_elevator_record` 发 JSON |
+| 远程 | `MqttFeignClient#publish` → 设备第三方 MQTT 服务 |
+
+**调用关系**：本模块中 **`AcsElevatorRecordServiceImpl` 注入了 `MqttService` 但当前未调用**；若产品要求「保存记录后推送大屏」，可在 **监听 `VisitorRecordPushEvent` 的处理器** 或 **在 `add` 成功后** 显式调用 `sendInfoToOne`（需评估与异步睡眠设计是否一致）。
+
+## 4.3 时序：MQTT 推送（当显式调用 `sendInfoToOne` 时）
+
+```mermaid
+sequenceDiagram
+  participant Caller as 业务/监听器
+  participant M as MqttServiceImpl
+  participant DAO as AcsRecogRecordDao
+  participant F as MqttFeignClient
+  Caller->>M: sendInfoToOne(DTO)
+  Note over M: sleep 10s
+  M->>DAO: page(识别流水)
+  DAO-->>M: 人名/标签
+  M->>F: publish(topic, JSON)
+  F-->>M: CloudwalkResult
+```
+
+## 4.4 状态机：从「仅事件」到「+ MQTT」（部署选项）
+
+```mermaid
+stateDiagram-v2
+  [*] --> RecordSaved: add DAO 成功
+  RecordSaved --> EventPublished: VisitorRecordPushEvent
+  EventPublished --> MqttOptional: 可选
+  MqttOptional --> MqttPush: 若接线 sendInfoToOne
+  MqttOptional --> NoMqtt: 当前默认
+```
+
+## 4.5 域事件与 MQTT 解耦说明
+
+- `VisitorRecordPushEvent` 经 `CloudwalkEventManager` 发布，**不保证** 与 MQTT 同一步骤执行。
+- 下游可独立订阅 **事件** 与 **MQTT topic**，避免强耦合。
@@ -0,0 +1,45 @@
+# 05 区域与电梯区域编码（`zone` / `codeElevatorArea`）
+
+## 5.1 `ZoneService`
+
+| 方法 | 概要 |
+|------|------|
+| `tree` | 入参 `ZoneNextTreeParam`，调 **平台区域/系统设置** 能力，组装 **下一级树** 等，返回 `List<ZoneTreeResult>`（实现中常经 Feign + 工具类 `ZoneTreeCollectors`） |
+| `page` | 区域维度的分页列表 `ZoneResult` |
+
+**实现类**：`zone/impl/ZoneServiceImpl.java`。
+
+## 5.2 `AcsElevatorCodeService`（`codeElevatorArea`）
+
+| 方法 | 概要 |
+|------|------|
+| `insertNew` / `updateOld` | 电梯与区域绑定的 **编码** 数据维护 |
+| `get` / `getFirstByParentId` | 单条/按父级取首条 |
+| `mapByZoneIds` | **批量** 按区域 id 查电梯编码，供树形接口 **一次** 拉取，避免 N+1（见接口内 Javadoc） |
+
+## 5.3 时序：区域树 + 树上网格批量取码（概念）
+
+```mermaid
+sequenceDiagram
+  participant Web as 上层
+  participant Z as ZoneService
+  participant Sy as 平台区域服务
+  participant C as AcsElevatorCodeService
+  Web->>Z: tree(参数)
+  Z->>Sy: Feign 取区域
+  Sy-->>Z: AreaTree
+  Z-->>Web: ZoneTreeResult
+  Web->>C: mapByZoneIds(多 zoneId)
+  C-->>Web: Map 区域id→编码
+```
+
+## 5.4 用例简图
+
+```mermaid
+flowchart TB
+  U[运营/系统]
+  U --> T[浏览区域树选楼层]
+  U --> M[维护电梯-区域码]
+  T --> ZoneService
+  M --> AcsElevatorCodeService
+```
@@ -0,0 +1,51 @@
+# 06 导出、下载与存储（`export` / `downloadcenter` / `storage`）
+
+## 6.1 异步导出 `export`
+
+- 抽象基类：`AcsAbstractExportAsyncService` —— 泛型封装 **分页拉取** → 转 Excel 行 DTO → 与下载中心协作。
+- **实现示例**：`ElevatorDeviceExportService`  
+  - 注入 `AcsElevatorDeviceService#get` 取设备分页。  
+  - 在 `queryPage` 中将 DTO 转为 `ElevatorDeviceRecordExcelResult`，并翻译 **在线/禁用** 等展示中文。
+
+**典型时序**（概念）：
+
+```mermaid
+sequenceDiagram
+  participant User as 用户/任务
+  participant E as ElevatorDeviceExportService
+  participant D as AcsElevatorDeviceService
+  participant DC as 下载中心
+  User->>E: 触发导出任务
+  loop 分页
+    E->>D: get(查询+分页)
+    D-->>E: 行数据
+  end
+  E->>DC: 完成文件/回写状态
+```
+
+## 6.2 下载中心 `AcsDownloadCenterService`
+
+| 方法 | 概要 |
+|------|------|
+| `createDownload` | 创建下载任务/令牌 |
+| `finishDownload` | 任务完成回执 |
+| `queryDownloadStatus` | 轮询或查询状态 |
+
+**实现类**：`downloadcenter/impl/AcsDownloadCenterServiceImpl.java`（以源码为准）。
+
+## 6.3 分片文件 `AcsFileStorageService`（`storage`）
+
+| 方法 | 概要 |
+|------|------|
+| `filePartInit` / `filePartAppend` / `filePartFinish` | DaVinci/门户 **分片上传** 生命周期 |
+| `getFileBase64` | 按 id 回读为 Base64 |
+
+## 6.4 ER/依赖（导出子域）
+
+```mermaid
+flowchart LR
+  Export[导出任务] --> Abs[AcsAbstractExportAsyncService]
+  Abs --> Svc[具体领域 Service 如 设备]
+  Abs --> Download[AcsDownloadCenterService]
+  Storage[AcsFileStorageService] -.大文件.-> 门户
+```
@@ -0,0 +1,42 @@
+# 07 横切与公共（`common` / `cacheable` / 基类）
+
+## 7.1 `AcsApplicationService`
+
+- 方法 `getApplicationId`：按业务/租户等解析 **应用 ID**（`AcsApplicationServiceImpl` 实现，细节见类）。
+
+## 7.2 `AcsAreaTreeCacheableService`
+
+- 包装 `SysettingAreaService#tree`。
+- `@Cacheable`：`ACS_AreaTreeCache`，key 与 `CacheOverrideConfig` 中 **租户前缀** 拼出，减少区域树 **重复远程调用**。
+
+## 7.3 基类
+
+| 类 | 作用 |
+|----|------|
+| `AbstractCloudwalkService` | 与 Cloudwalk 框架通用基能力（见父类/模块） |
+| `AbstractAcsDeviceService` | 设备域公用：区域树展平、构造带 `FeignThreadLocalUtil` 的 `CloudwalkCallContext` 等（见 `common/AbstractAcsDeviceService`） |
+| `AbstractAcsPassService` | 通行/规则子域抽取（见 `passrule/impl`） |
+
+## 7.4 空接口
+
+- `SendRecordTimeService`：无方法；若需扩展 **发送记录时间** 类能力，可在此增方法并由实现类承载。
+
+## 7.5 包级 `package-info`
+
+各子包在源码中已逐步补充 `package-info.java`（`device`/`record`/`mqtt`/`visitor` 等），可与本 `docs` 互参。
+
+## 7.6 多维度总览表（维度矩阵）
+
+| 维度 | 读者关注点 | 建议文档 |
+|------|------------|----------|
+| 业务价值 | 电梯设备、规则、人员、记录 | 01–03 |
+| 集成 | 访客、MQTT、Feign | 04, 00 |
+| 可运维 | 缓存、异步、任务进度 | 01, 07, 04 |
+| 可观测 | 事件、topic、锁 | 03, 04, 03-锁 |
+
+**读文档优先级（示意，非绝对）**
+
+|  | 远程依赖多 | 本地/缓存多 |
+|--|------------|-------------|
+| **写路径多** | 设备任务、规则+人员 | （较少） |
+| **读路径多** | 记录 openRecord | 区域树缓存、电梯码 map |
@@ -0,0 +1,361 @@
+# 访客与电梯业务：注册/登记与派梯授权完整说明
+
+> 本文档覆盖 **组织组件**（`maven-ninca-common-component-organization`）、**智能组件 Feign 路由**（`maven-intelligent-cwoscomponent`）与 **电梯应用**（`maven-cw-elevator-application`）中与「访客派梯」相关的可追踪路径；区分 **访客主数据登记** 与 **`POST /elevator/person/add/visitor` 派梯授权**。文中源码路径均相对于各 Maven 模块仓库根目录。
+
+---
+
+## 1. 概念与边界
+
+| 概念 | 通常含义 | 在本项目中的落点 |
+|------|----------|------------------|
+| **访客主数据登记/注册** | 在标准访客/一卡通中录入档案 | **不在**电梯应用内完成完整登记 UI；人员以 **`visitorId`（平台 personId）** 等形式存在于外部服务。 |
+| **电梯侧「访客派梯授权」** | 在已有访客人员 ID 前提下写入通行规则、绑定图库、访期 | **`PersonRuleServiceImpl#addVisitor`** → **`POST /elevator/person/add/visitor`**（`AcsPersonController`）。 |
+| **通行记录「是否访客」打标** | 识别流水写库时标记访客/被访人 | **`AcsElevatorRecordServiceImpl#add`** → CRK **`/intelligent/three/visitor/record/query`**（见第 8 节）。 |
+
+---
+
+## 2. 组件关系总览
+
+访客邀约页、电梯 **`addVisitor`** 在 **`floorList` 语义上应对齐**：二者都应依赖 **`PersonService.detail` → `PersonResult.floorList`**（经 Intelligent 转发到组织 **`POST /component/person/detail`**）。组织组装 `floorList` 时会 **Feign 回调电梯**（见 **§3.3**）：电梯 **`image_rule_ref`** 里已有的人员—楼层规则，经 **`/elevator/passRule/image`** 转成 **`zoneId` 列表**，再写回组织的 **`floorList`**。
+
+```mermaid
+flowchart LR
+  subgraph fe["前端 / BFF / 第三方"]
+    UI[访客邀约 / 派梯调用方]
+  end
+  subgraph intelligent["maven-intelligent-cwoscomponent"]
+    PS[PersonService / RestPersonServiceImpl]
+    PFC[PersonFeignClient → /component/person]
+  end
+  subgraph org["maven-ninca-common-component-organization"]
+    PC[PersonController /component/person]
+    IMG[ImgPersonServiceImpl]
+    EF[ElevatorFeignClient → /elevator/passRule/image]
+  end
+  subgraph elevator["maven-cw-elevator-application"]
+    AC[AcsPersonController /elevator/person/add/visitor]
+    PR[PersonRuleServiceImpl addVisitor]
+    IRR[ImageRuleRefDao / ZoneService / DeviceImageStoreDao]
+    IS[ImageStorePersonService Feign 绑定图库]
+  end
+  UI --> PS
+  PS --> PFC --> PC --> IMG
+  IMG --> EF
+  UI --> AC --> PR
+  PR --> PS
+  PR --> IRR
+  PR --> IS
+```
+
+---
+
+## 3. 组织侧：被访人 `detail` 与 `floorList`（邀约页 / UC-01 的数据源）
+
+### 3.1 HTTP 入口与实现类
+
+| 项 | 说明 |
+|----|------|
+| **路径** | **`POST /component/person/detail`** |
+| **Controller** | `cwos-component-organization-web` · `PersonController#detail` |
+| **服务** | `ImgStorePersonService#detail` → **`ImgPersonServiceImpl#detail`** |
+
+对外契约返回 **`CloudwalkResult<ImgStorePersonGetResult>`**；经 Intelligent **`PersonFeignClient`** 解码为 **`PersonResult`**（字段名一致部分落入 **`floorList`**，电梯 **`addVisitor`** 仅消费 **`PersonResult.getFloorList()`**）。
+
+### 3.2 `ImgPersonServiceImpl#detail` 处理顺序（与源码一致）
+
+| 步骤 | 做什么 | 与 `floorList` 的关系 |
+|------|--------|----------------------|
+| 1 | **`selectByPrimaryKey`** 查组织库人员 | 无此人则 **`data` 可为 null**（见下） |
+| 2 | 可选 **`defaultFloor`** → **`zoneFeignClient.findZonelist`** | 仅 **`floorName` 展示**，**不等于**下面得到的 **`floorList`** |
+| 3 | 可选 **`vehicleFeignClient.getVehicleIds`** | 与楼层列表无关 |
+| 4 | **`getImgStorePersonResults`** | 得到 **`organizationIds`、`labelIds`**，供 **§3.3** 调用电梯 |
+| 5 | **`elevatorFeignClient.listByImageId(...)`**（Feign，语义见 **§3.3**） | **唯一**写入 **`floorList` / `floorNames`**（在返回码成功且进入分支时） |
+| 6 | （规范）租户 **`allow_zone_ids` 替代** | **当前未实现**，运行态 **`floorList`** = 步骤 5 结果 |
+| 7 | **`portalUserService.query`** 填创建/更新人姓名 | 与楼层无关 |
+
+- **查无此人**：**`result` 仍为 null**，接口 **`CloudwalkResult.success(null)`**；电梯 **`addVisitor`** 取 **`personResult == null`** → **`76260531`**。  
+- **步骤 5 失败或未进入分支**：**`floorList` 不会被赋值**（可能为 **null** / 未覆盖）；UC-01 **`addVisitor`** → **`76260531`**。
+
+---
+
+### 3.3 组织 Feign `listByImageId` ↔ 电梯 HTTP ↔ 真实落库（避免混淆）
+
+这一块名字容易混：**组织侧 Java 方法叫 `listByImageId`，并不等于电梯里另一个 DAO 方法 `listByImageId`。**
+
+#### 3.3.1 组织侧调用（入口）
+
+| 项 | 说明 |
+|----|------|
+| **组织代码** | `ElevatorFeignClient#listByImageId`（`cwos-component-organization-service/.../feign/ElevatorFeignClient.java`） |
+| **HTTP** | **`POST {elevator-base}/elevator/passRule/image`**（Feign **`name`** 一般为 **`feign.elevator.name`**，如 **`elevator-app`**） |
+| **请求体** | **`AcsPassRuleImageForm`**：`personId`、`businessId`、`includeOrganizations`、`includeLabels`（对应组织 **`detail`** 里 **`getImgStorePersonResults`** 填好的档案字段） |
+
+#### 3.3.2 电梯侧实际执行（与「另一个 listByImageId」区分）
+
+| 易混点 | 说明 |
+|--------|------|
+| **本链路** | **`AcsPassRuleController`**（类上 **`@RequestMapping("/elevator/passRule")`**）方法 **`@RequestMapping("/image")`** → **`ImageRuleRefServiceImpl#listByPersonInfo`** → **`ImageRuleRefDao#listByPersonInfo`** → **`ImageRuleRefMapper.xml#listByPersonInfo`** |
+| **勿混** | **`AcsPassRuleServiceImpl#listByImageId`** → **`acsPassRuleDao.listByImageId`** 查的是 **`it_acs_pass_rule`**，按 **`imageStoreIds`** 过滤——**不是**组织 Feign 这条 HTTP 路径当前走的实现。 |
+
+#### 3.3.3 `listByPersonInfo` 在查什么（业务语义）
+
+- **表**：电梯库 **`image_rule_ref`**（人员与楼层通行规则引用：访客 **`addVisitor`** 写入的也是这张表的语义同类数据）。  
+- **返回字段**：**`DISTINCT zone_id, zone_name`**（映射 **`AcsPassRuleImageResultDto`**）。  
+- **查询逻辑（摘要）**：  
+  - 至少包含：**`person_id = 被访人`** 且 **`person_delete = 0`** 的规则所对应的楼层；  
+  - 若 **`includeOrganizations` / `includeLabels`** 非空，SQL 中另有 **`OR`** 分支，按机构/标签关联规则补充楼层，并排除 **`person_delete = 1`** 等条件下已标记删除的 **`zone_id`**（详见 **`ImageRuleRefMapper.xml`** 全文）。  
+  - **排序**：**`order by CAST(zone_name as signed)`**（按楼层名称可解析的数字排序）。
+
+因此：**组织 `detail` 里的 `floorList`，本质上是「电梯侧已为该被访人（及档案上的机构/标签）开通过的楼层 zoneId 列表」的只读投影**，不是组织库自己存的楼层字段。
+
+#### 3.3.4 组织如何把返回值写进 `detail`
+
+仅当 **`images.getCode()`** 等于 **`00000000`**（成功）时，`ImgPersonServiceImpl#detail` 才遍历 **`images.getData()`**，把每条 **`zoneId`** 依次 **`floorList.add`**，并把 **`zoneName`** 拼成逗号分隔的 **`floorNames`**。  
+若 Feign **失败**、**超时**、或业务码非 **`00000000`**：**不会进入该分支**，**`floorList` 保持未赋值** → 下游 UC-01 常 **`76260531`**。
+
+#### 3.3.5 与「访客派梯 `addVisitor`」的数据关系（闭环）
+
+| 环节 | 数据 |
+|------|------|
+| 被访人已在电梯侧挂规则 | **`image_rule_ref`** 中有 **`person_id=被访人`** 等记录 |
+| 组织 **`detail`** | **`listByImageId`(Feign) → `/passRule/image` → `listByPersonInfo`** 读出 **zone 列表** → **`PersonResult.floorList`** |
+| 电梯 **`addVisitor` UC-01** | 再次 **`PersonService.detail`**，用同一 **`floorList`** 作为 **`effective`**，再 **写入访客**的 **`image_rule_ref`** 等 |
+
+所以：**`floorList` 不是「组织凭空算的」，而是「电梯规则表里已有被访人楼层」经 **`/passRule/image`** 汇总后的结果**；租户策略若要做「替代」，应在步骤 **§3.2 第 6 步**改 **`floorList`**，而不是再发明一套与 **`image_rule_ref`** 无关的算法（除非产品另行约定）。
+
+---
+
+### 3.4 时序图 — 组织侧「单人 detail」（含回调电梯）
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant Caller as 调用方 / Intelligent
+  participant PC as PersonController
+  participant IMG as ImgPersonServiceImpl
+  participant Zone as ZoneFeignClient
+  participant Veh as VehicleFeignClient
+  participant Elev as ElevatorFeignClient<br/>方法名 listByImageId
+  participant EA as 电梯 AcsPassRuleController<br/>/elevator/passRule/image<br/>→ ImageRuleRefService listByPersonInfo
+
+  Caller->>PC: POST /component/person/detail
+  PC->>IMG: detail(param, context)
+  IMG->>IMG: selectByPrimaryKey(personId)
+  opt defaultFloor 非空
+    IMG->>Zone: findZonelist
+    Zone-->>IMG: ZoneResult
+  end
+  IMG->>Veh: getVehicleIds
+  Veh-->>IMG: vehicle ids
+  IMG->>IMG: getImgStorePersonResults → organizationIds, labelIds
+  IMG->>Elev: listByImageId(AcsPassRuleImageForm)
+  Elev->>EA: POST /elevator/passRule/image
+  EA->>EA: listByPersonInfo → SQL image_rule_ref
+  EA-->>Elev: List zoneId/zoneName
+  Elev-->>IMG: CloudwalkResult code=00000000 + list
+  IMG->>IMG: setFloorList / setFloorNames（策略替代：待实现）
+  IMG-->>PC: ImgStorePersonGetResult
+  PC-->>Caller: CloudwalkResult
+```
+
+---
+
+## 4. 电梯侧：`addVisitor` 业务步骤
+
+### 4.1 对外入口
+
+| 项 | 值 |
+|----|-----|
+| HTTP | **`POST /elevator/person/add/visitor`** |
+| Controller | `cw-elevator-application-web` · **`AcsPersonController#addVisitor`** |
+| 实现 | **`PersonRuleServiceImpl#addVisitor`** |
+
+### 4.2 与源码一致的执行顺序
+
+**阶段 1 — 被访人详情（必经）**
+
+- 组装 **`PersonDetailParam`**：`id = param.getPersonId()`（被访人），**`businessId = context.getCompany().getCompanyId()`**。
+- **`personService.detail(detailParam, context)`** → Intelligent **`PersonFeignClient`** → 组织 **`POST /component/person/detail`**。
+- 失败或 **`personResult == null`** → 返回失败码（常见 **`76260531`**）。
+
+**阶段 2 — 生效楼层 `effective`（UC 分流）**
+
+- **`callerProvidedFloors = !CollectionUtils.isEmpty(param.getFloorIds())`**  
+  - **`true`（UC-02）**：**`effective = param.getFloorIds()`**（**不**使用 **`personResult.getFloorList()`** 作为列表来源；**仍已执行阶段 1**，用于保证被访人可查）。  
+  - **`false`（UC-01）**：**`effective = personResult.getFloorList()`**；**空** → **`76260531`**。
+
+**阶段 3 — 再次空集校验** — 防御 **`effective` 仍为空**。
+
+**阶段 4 — 楼栋与图库**
+
+- **`zoneService.page`**：查询 **`effective.get(0)`** 对应 **`ZoneResult`**，取 **`parentId`** 作为楼栋。
+- **`deviceImageStoreDao.getByBuildingId(parentId)`** → **`imageStoreId`**（后续 **`batchBind` / `updateGroupPersonRef`** 均绑定该图库）。
+
+**阶段 5 — 每层通行规则引用**
+
+- 对每个 **`floorId`**：**`imageRuleRefDao.getDefaultByZoneId(floorId)`** 取默认父规则，拼装 **`ImageRuleRefAddDto`**（**`personId = visitorId`**），**`imageRuleRefDao.insertList`**。
+
+**阶段 6 — 图库与分组**
+
+- **`ImageStorePersonBindParam`**：`imageStoreId`、`personIds=[visitorId]`、访期 **`begVisitorTime`/`endVisitorTime`**。
+- **`imageStorePersonService.batchBind`**（Feign 至 Intelligent/组织图库能力）。
+- **`updateGroupPersonRef`** 同步组人员引用。
+
+**异常** — 未捕获的运行异常包装 **`76260530`**；**`batchBind`** 失败透传下游码。
+
+### 4.3 租户策略语义（与仓库规范一致）
+
+电梯 **不**注入 **`TenantVisitorFloorPolicyDao`**，**不**在 **`addVisitor` 内做 `floorList ∩ allow`**。租户 **`allow_zone_ids` 替代**须落在 **组织 `detail`**（见第 3.2 节「待实现」说明）。
+
+---
+
+## 5. 时序图 — 电梯 `addVisitor`（UC-01：不传 floorIds）
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant C as 调用方
+  participant API as AcsPersonController
+  participant PR as PersonRuleServiceImpl
+  participant PS as PersonService Intelligent
+  participant Org as 组织 /component/person/detail
+  participant Z as ZoneService
+  participant DIS as DeviceImageStoreDao
+  participant IRR as ImageRuleRefDao
+  participant IS as ImageStorePersonService
+
+  C->>API: POST /elevator/person/add/visitor（floorIds 空）
+  API->>PR: addVisitor(param, context)
+  PR->>PS: detail(personId, businessId)
+  PS->>Org: Feign POST detail
+  Org-->>PS: PersonResult.floorList
+  PS-->>PR: PersonResult
+  Note over PR: effective = floorList；空则 76260531
+  PR->>Z: page(首 floorId)
+  Z-->>PR: ZoneResult.parentId
+  PR->>DIS: getByBuildingId(parentId)
+  DIS-->>PR: imageStoreId
+  loop 每个 floorId
+    PR->>IRR: getDefaultByZoneId + insertList
+  end
+  PR->>IS: batchBind(visitorId, 访期, imageStoreId)
+  IS-->>PR: 成功
+  PR->>IS: updateGroupPersonRef
+  PR-->>API: CloudwalkResult Boolean
+  API-->>C: 结果
+```
+
+## 6. 时序图 — 电梯 `addVisitor`（UC-02：显式 floorIds）
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant C as 调用方
+  participant API as AcsPersonController
+  participant PR as PersonRuleServiceImpl
+  participant PS as PersonService Intelligent
+  participant Z as ZoneService
+  participant DIS as DeviceImageStoreDao
+  participant IRR as ImageRuleRefDao
+  participant IS as ImageStorePersonService
+
+  C->>API: POST /elevator/person/add/visitor（floorIds 非空）
+  API->>PR: addVisitor
+  PR->>PS: detail(被访人)（校验被访人存在）
+  PS-->>PR: PersonResult
+  Note over PR: effective = param.floorIds（不用 detail.floorList）
+  PR->>Z: page(首 floorId)
+  Z-->>PR: parentId
+  PR->>DIS: getByBuildingId
+  DIS-->>PR: imageStoreId
+  loop 每层
+    PR->>IRR: 默认规则 + insertList visitorId
+  end
+  PR->>IS: batchBind + updateGroupPersonRef
+  PR-->>API: success
+```
+
+---
+
+## 7. 活动图（addVisitor 分支汇总）
+
+```mermaid
+flowchart TD
+  Start([POST /elevator/person/add/visitor]) --> D[PersonService.detail 被访人]
+  D --> E{success 且 PersonResult 非空?}
+  E -- 否 --> E1[76260531 等]
+  E -- 是 --> F{param.floorIds 非空?}
+  F -- 是 UC-02 --> G[effective = floorIds]
+  F -- 否 UC-01 --> H{personResult.floorList 非空?}
+  H -- 否 --> E1
+  H -- 是 --> G2[effective = floorList]
+  G --> K[zone.page 首层 → imageStoreId]
+  G2 --> K
+  K --> L[逐层 ImageRuleRef 挂 visitorId]
+  L --> M[batchBind + updateGroupPersonRef]
+  M --> Ok([true])
+```
+
+---
+
+## 8. 主线 B：通行记录落库时「访客身份」认定（非派梯）
+
+**场景**：设备上报识别结果写入电梯通行记录。
+
+**实现**：`AcsElevatorRecordServiceImpl#add` 在写库前 **`RestTemplateUtil.post`** → **`http://{ninca-crk-std}/intelligent/three/visitor/record/query`**；返回非空则 **`isVisitor=1`** 并回填被访人。该路径 **不创建** 访客主档，与第 3～7 节派梯链路独立。
+
+```mermaid
+sequenceDiagram
+  participant R as AcsElevatorRecordServiceImpl
+  participant HTTP as CRK three/query
+  participant DAO as 电梯记录 DAO
+  R->>HTTP: visitorId + tenant
+  HTTP-->>R: 访客档案或空
+  R->>DAO: add(含 isVisitor, interviewee)
+```
+
+---
+
+## 9. 其它：MQTT 访客标签
+
+`MqttServiceImpl` 若识别流水 **`personLabelIds` 含 "1"**，MQTT JSON 置 **`isVisitor=true`**（**标签维度**，与档案访客不同）。
+
+---
+
+## 10. 错误与日志索引（addVisitor）
+
+| 场景 | 码 |
+|------|-----|
+| detail 失败 / 被访人无数据 / UC-01 **`floorList` 为空** / **`effective` 仍为空** | **`76260531`** |
+| 其它未预期异常 | **`76260530`** |
+| **`batchBind`** 失败 | 透传下游 **code/message** |
+
+**日志关键字**：`根据被访人添加访客派梯权限`、`UC-01` / `UC-02`、`最终生效楼层`、`访客添加派梯权限`、`远程调用绑定人员图库`。
+
+---
+
+## 11. 关键源码索引
+
+| 层级 | 路径 |
+|------|------|
+| 电梯 Controller | `cw-elevator-application-web/.../person/controller/AcsPersonController.java` |
+| 电梯派梯 | `cw-elevator-application-service/.../person/impl/PersonRuleServiceImpl.java` **`addVisitor`** |
+| Intelligent Feign | `intelligent-cwoscomponent-rest/.../person/feign/PersonFeignClient.java`（**`/component/person/detail`**） |
+| 组织 Controller | `cwos-component-organization-web/.../controller/PersonController.java` **`/detail`** |
+| 组织 detail 实现 | `cwos-component-organization-service/.../ImgPersonServiceImpl.java` **`detail`** |
+| 组织→电梯 Feign | `cwos-component-organization-service/.../feign/ElevatorFeignClient.java`（方法 **`listByImageId`** → **`POST /elevator/passRule/image`**） |
+| 电梯「按人员信息列楼层」 | `cw-elevator-application-web/.../passrule/controller/AcsPassRuleController.java` **`/image`** |
+| 电梯实现 | `cw-elevator-application-service/.../passrule/impl/ImageRuleRefServiceImpl.java` **`listByPersonInfo`** |
+| 电梯 SQL | `cw-elevator-application-data/.../mapper/ImageRuleRefMapper.xml` **`listByPersonInfo`**（表 **`image_rule_ref`**） |
+| （勿与本链路混淆） | `AcsPassRuleServiceImpl#listByImageId` / **`it_acs_pass_rule`** — **不同入口** |
+| 通行访客打标 | `cw-elevator-application-service/.../record/impl/AcsElevatorRecordServiceImpl.java` **`add`** |
+
+---
+
+## 12. 规范交叉引用
+
+- 租户楼层策略 **替代** 语义与迁移边界：**`docs/superpowers/specs/2026-05-06-tenant-visitor-policy-organization-implementation.md`**
+
+---
+
+**说明**：组织 **`detail` 内租户策略替代**若未落地，UC-01 的 **`floorList`** 完全等于 **`/elevator/passRule/image` → `listByPersonInfo`** 返回的 **zone 列表**（经 Feign **`listByImageId`** 写入 **`ImgStorePersonGetResult`**）。与产品「仅开放接待层」不一致时，应排查 **`image_rule_ref` 数据**、该接口 **成功与否**，以及 **组织侧策略替代**是否已实现。
@@ -0,0 +1,56 @@
+# `cw-elevator-application-service` 业务逻辑文档总索引
+
+本目录以 **本 Maven 模块源码根**（`src/main/java/cn/cloudwalk/elevator`）为范围，对电梯应用 **业务编排层** 作多维度说明：分域业务、接口级能力、用例/时序/流程等图（Mermaid）及与外部系统的协作关系。
+
+| 元数据 | 说明 |
+|--------|------|
+| 模块路径 | `maven-cw-elevator-application/cw-elevator-application-service` |
+| 文档根 | 本目录 `.../cw-elevator-application-service/docs/` |
+| 源码包根 | `cn.cloudwalk.elevator` |
+| 产出形态 | Markdown + Mermaid（可用支持 Mermaid 的 IDE、Git 站点或 [mermaid.live](https://mermaid.live) 渲染） |
+
+## 与仓库级文档的关系
+
+- 全仓约定、走查、接口不变等说明见仓库根下 **`../../../docs/`**（相对本文件）。
+- 发布包与**历史 JAR 接口对拍**（计划/报告）见聚合工程目录 **`../../docs/elevator-api-parity/PLAN.md`**、脚本 `../../scripts/run_elevator_parity.sh`。
+- 本目录专注 **本 service 模块内** 类职责与业务流程梳理，不替代对外 API 合同文档。
+
+## 分册导航
+
+| 文档 | 内容摘要 |
+|------|----------|
+| [00-overview.md](00-overview.md) | 模块定位、包结构、领域全景、组件依赖图 |
+| [01-device-and-task.md](01-device-and-task.md) | 设备 CRUD、绑定楼层/人员、设备任务与并行推进 |
+| [02-passrule-and-person.md](02-passrule-and-person.md) | 通行规则、图库规则引用、人员规则、人员管理 |
+| [03-record-recognition.md](03-record-recognition.md) | 电梯通行记录、识别记录、图库文件、分析统计 |
+| [04-mqtt-visitor-event.md](04-mqtt-visitor-event.md) | MQTT 推送、访客查询差异、域事件 `VisitorRecordPushEvent` |
+| [05-zone-code.md](05-zone-code.md) | 区域树/分页、电梯区域编码 |
+| [06-export-download-storage.md](06-export-download-storage.md) | 异步导出、下载中心、分片存储 |
+| [07-cross-cutting.md](07-cross-cutting.md) | 缓存、公共应用 ID、基类、空接口等横切项 |
+| [08-visitor-registration-and-elevator-auth.md](08-visitor-registration-and-elevator-auth.md) | **访客：登记/授权边界、派梯 `add/visitor` 全链路、记录打标、时序/活动图** |
+
+## 包 → 主入口（速查）
+
+| 包路径 | 主要 `*Service` 接口 / 类 |
+|--------|---------------------------|
+| `device` | `AcsElevatorDeviceService`、`AcsDeviceTaskService` |
+| `device/setting` | `AcsDeviceSettingService`、`AcsDeviceImageStoreAppBindService` |
+| `passrule` | `AcsPassRuleService`、`ImageRuleRefService` |
+| `person` | `AcsPersonService`、`PersonRuleService` |
+| `record` | `AcsElevatorRecordService`、`AcsRecogRecordService`、`PersonFileService`、`SendRecordTimeService`（空） |
+| `zone` | `ZoneService` |
+| `codeElevatorArea` | `AcsElevatorCodeService` |
+| `mqtt` | `MqttService` |
+| `export` | `AcsAbstractExportAsyncService` 子类如 `ElevatorDeviceExportService` |
+| `downloadcenter` | `AcsDownloadCenterService` |
+| `storage` | `AcsFileStorageService` |
+| `common` | `AcsApplicationService` |
+| `cacheable` | `AcsAreaTreeCacheableService`（非 interface，为 `@Service` 包装） |
+
+## 图例说明
+
+- **用例图**：采用 Mermaid `flowchart` / `C4` 简图表达参与者与用例分箱；需要标准 UML 用例图时可自工具导出。
+- **时序图**：`sequenceDiagram` 表示一次调用链。
+- **活动/状态**：`flowchart TB` 或 `stateDiagram-v2` 表示分支与状态。
+
+最后更新与源码版本以当前工作区 `cw-elevator-application-service` 反编译/还原代码为准；若与线上运行版本不一致，以发布制品为准。