# 中建系统 — 接口调用链路图

**文档用途：** 从中建系统（业主/集成侧，含经 **Nginx**、**BFF** 或 **intelligent-cwoscomponent** 等）进入云从侧服务时的 **HTTP 调用链** 总览，供联调、验收与领导汇报附图。  
**依据：** 本仓库 `docs/business/访客注册与派梯楼层业务流程走查.md`、Feign 声明及 `AcsPersonController` 等；《升级方案》见 `docs/operations/升级方案正式版本.md`（组织侧策略与 `PersonResult.floorList` 关系以该文为准）。

**范围说明：** 「中建系统」在图中抽象为 **调用发起方**；实际部署的 **主机、端口、网关路径前缀、鉴权头** 以现场集成契约为准，本文只锁 **服务名 + 资源路径** 级语义。

---

## 1. 总览：两条主链路


| 链路                 | 业务意图                         | 起点（中建侧）                                   | 终点侧典型路径                             |
| ------------------ | ---------------------------- | ----------------------------------------- | ----------------------------------- |
| **L1 人员详情 / 楼层清单** | 选人、邀约页、展示被访人默认可达楼层等          | 中建 →（网关）→ **组织信息服务**                      | `POST /component/person/detail`     |
| **L2 访客派梯开通**      | 已有访客 `visitorId` 后写通行规则、绑图库等 | 中建 →（网关）→ **电梯应用**（可选经 intelligent Feign） | `POST /elevator/person/add/visitor` |


电梯应用在 **L2** 内部仍会 **Feign 调用组织**（如 `floorIds` 为空时补全楼层、图库绑定等），详见下文详图。

---

## 2. 链路 L1：人员详情（含楼层清单）

适用于与中建策略升级相关的 **对外楼层口径**：组织侧 `detail` 返回的 `**floorList`**（及策略替代语义）。调用方可为中建前端直连、中建后端经 DMZ 网关、或经统一 API 网关转发。

```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryTextColor':'#111827','lineColor':'#64748b'}}}%%
sequenceDiagram
  autonumber
  participant ZJ as 中建系统<br/>（调用方）
  participant GW as 接入层<br/>Nginx / API 网关（可选）
  participant Org as 组织信息服务<br/>ninca-common-component-organization

  Note over ZJ,Org: 路径以对外契约为准；以下为典型形态
  ZJ->>GW: HTTPS 请求（路由规则依集成）
  GW->>Org: 转发 POST /component/person/detail
  Org->>Org: 组装 PersonResult（含 floorList；策略启用时覆盖语义见升级方案）
  Org-->>GW: CloudwalkResult PersonResult
  GW-->>ZJ: 响应
```



**要点：** 与中建是否「直连组织」或「只访问 `/api` 由电梯/网关二次路由」取决于合同；**语义上** 人员详情权威在 **组织服务** 的 `detail`。

---

## 3. 链路 L2：访客派梯（经电梯 REST，含组织回调）

典型完整顺序：**中建 → 电梯 `add/visitor` →（电梯内部）组织 `detail`、空间 zone、图库 batchBind 等**。若中建通过 **intelligent** 调用，则多一跳 Feign，对外仍落到同一电梯路径。

```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryTextColor':'#111827','lineColor':'#64748b'}}}%%
sequenceDiagram
  autonumber
  participant ZJ as 中建系统
  participant GW as Nginx / 网关（可选）
  participant INTEL as intelligent-cwoscomponent<br/>（可选中转）
  participant EL as 电梯应用<br/>cw-elevator-application
  participant Org as 组织信息服务
  participant COM as ninca-common<br/>空间/区域等

  alt 路径 A：中建直连电梯 HTTP
    ZJ->>GW: POST …/elevator/person/add/visitor
    GW->>EL: 路由至 elevator-app
  else 路径 B：经 intelligent Feign
    ZJ->>INTEL: 业务 SDK / 内部 REST
    INTEL->>EL: Feign POST /elevator/person/add/visitor
  end

  EL->>Org: Feign POST /component/person/detail（floorIds 为空等场景补全楼层）
  Org-->>EL: PersonResult（含 floorList）

  EL->>COM: 按需 POST /sysetting/zone/page 等（楼栋楼层解析，按实现）

  EL->>Org: Feign POST /component/imagestore/person/batchBind 等（绑图库）

  EL-->>ZJ: CloudwalkResult Boolean（经 GW 若存在）

  Note over EL,Org: 策略命中与 floorList 替代发生在组织 detail；电梯侧透传规则见租户策略专项文档
```



---

## 4. 接口—路径清单（与中建联调对照）


| 方向                      | Method / Path（相对服务上下文）                          | 服务                                  |
| ----------------------- | ----------------------------------------------- | ----------------------------------- |
| 中建 / 网关 → 组织            | `POST /component/person/detail`                 | ninca-common-component-organization |
| 中建 / 网关 → 电梯            | `POST /elevator/person/add/visitor`             | cw-elevator-application             |
| intelligent → 电梯（Feign） | `POST /elevator/person/add/visitor`             | 同上（`ElevatorPersonFeignClient`）     |
| 电梯 → 组织                 | `POST /component/person/detail`                 | 组织                                  |
| 电梯 → 组织                 | `POST /component/imagestore/person/batchBind` 等 | 组织                                  |
| 电梯 → 公共组件               | `POST /sysetting/zone/page` 等                   | ninca-common                        |


完整字段与用例见：`docs/business/访客注册与派梯楼层业务流程走查.md` §3～§5。

---

## 5. 逻辑关系图（与附录 A 对照）

```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryTextColor':'#111827','lineColor':'#64748b'}}}%%
flowchart LR
  ZJ[中建系统]
  GW[接入层<br/>Nginx 等]
  EL[电梯应用]
  Org[组织信息服务]
  ZJ --> GW
  GW --> EL
  GW --> Org
  EL --> Org
```



**说明：** 中建既可 **只调组织（L1）**，也可 **调电梯（L2）**；后者必然与组织存在 **出站调用**。平台级分层仍以 `升级方案正式版本.md` **附录 A** 为准。

---

## 6. 修订记录


| 版本   | 日期         | 说明                           |
| ---- | ---------- | ---------------------------- |
| V1.0 | 2026-05-06 | 首版：L1/L2 时序、路径表、与升级方案/走查文档对齐 |


---

**关联文档：**  

- `docs/operations/升级方案正式版本.md`  
- `docs/business/访客注册与派梯楼层业务流程走查.md`  
- `docs/operations/ninca-common-component-organization-production-upgrade-plan.md`