starRiverProperty/docs/operations/中建系统-接口调用链路图.md

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

文档用途： 从中建系统（业主/集成侧，含经 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 网关转发。

%%{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，对外仍落到同一电梯路径。

%%{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 对照）

%%{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