# 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)。