mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
hpd840321
7b2bd307f1
- 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.
142 lines
6.5 KiB
Markdown
142 lines
6.5 KiB
Markdown
# 中建系统 — 接口调用链路图
|
||
|
||
**文档用途：** 从中建系统（业主/集成侧，含经 **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`
|
||
|