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