huangping/starRiverProperty
1
0
Fork 0
mirror of https://github.com/hpd840321/starRiverProperty.git synced 2026-06-09 08:20:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

Initial commit: reorganized source tree

Browse Source 
- 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.
This commit is contained in:
hpd840321
2026-05-09 09:00:12 +08:00
commit 7b2bd307f1
7260 changed files with 612980 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/operations/deploy_cw_elevator_v1_lib_to_nexus.py
Executable
+148
View File
@@ -0,0 +1,148 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
将 cw-elevator-application-V1.0.0.20211103/lib 下全部 JAR 作为初始构件上传到 Nexus。
脚本位置：docs/operations/deploy_cw_elevator_v1_lib_to_nexus.py（与文档同目录，便于运维查找）。
规则：
1. 若 JAR 内含 META-INF/maven/**/pom.properties，则使用其中的 groupId / artifactId / version。
2. 否则使用后备坐标：cn.cloudwalk.elevator.v1.bootlib:<文件名去 .jar>:V1.0.0.20211103
（保证与 Maven Central 坐标不冲突，且一文件一构件。）
version 含 SNAPSHOT 时上传到 maven-snapshots，否则 maven-releases。
需 ~/.m2/settings.xml 中配置 server id：nexus-releases、nexus-snapshots（与 URL 对应）。
"""
from __future__ import annotations
import argparse
import os
import subprocess
import sys
import zipfile
from pathlib import Path
# 仓库根目录 = 本文件所在 docs/operations/ 的上两级
DEFAULT_LIB = Path(__file__).resolve().parent.parent.parent / "cw-elevator-application-V1.0.0.20211103" / "lib"
RELEASES_URL = "http://192.168.3.12:8081/repository/maven-releases/"
SNAPSHOTS_URL = "http://192.168.3.12:8081/repository/maven-snapshots/"
RELEASES_ID = "nexus-releases"
SNAPSHOTS_ID = "nexus-snapshots"
FALLBACK_GROUP = "cn.cloudwalk.elevator.v1.bootlib"
FALLBACK_VERSION = "V1.0.0.20211103"
def read_maven_coords(jar: Path) -> tuple[str, str, str] | None:
try:
with zipfile.ZipFile(jar, "r") as zf:
for name in zf.namelist():
if name.endswith("pom.properties") and "META-INF/maven" in name.replace(
"\\", "/"
):
raw = zf.read(name).decode("utf-8", errors="replace")
props: dict[str, str] = {}
for line in raw.splitlines():
line = line.strip()
if not line or line.startswith("#") or "=" not in line:
continue
k, _, v = line.partition("=")
props[k.strip()] = v.strip()
gid = props.get("groupId")
aid = props.get("artifactId")
ver = props.get("version")
if gid and aid and ver:
return gid, aid, ver
except (zipfile.BadZipFile, OSError):
return None
return None
def fallback_coords(jar: Path) -> tuple[str, str, str]:
stem = jar.name[:-4] if jar.name.lower().endswith(".jar") else jar.name
return FALLBACK_GROUP, stem, FALLBACK_VERSION
def is_snapshot_version(version: str) -> bool:
return "SNAPSHOT" in version.upper()
def deploy_one(
jar: Path,
group_id: str,
artifact_id: str,
version: str,
dry_run: bool,
) -> int:
url = SNAPSHOTS_URL if is_snapshot_version(version) else RELEASES_URL
rid = SNAPSHOTS_ID if is_snapshot_version(version) else RELEASES_ID
cmd = [
"mvn",
"-q",
"deploy:deploy-file",
f"-DrepositoryId={rid}",
f"-Durl={url}",
f"-Dfile={jar}",
f"-DgroupId={group_id}",
f"-DartifactId={artifact_id}",
f"-Dversion={version}",
"-Dpackaging=jar",
"-DgeneratePom=true",
]
if dry_run:
print("DRY-RUN:", " ".join(cmd))
return 0
r = subprocess.run(cmd, capture_output=True, text=True)
if r.returncode != 0:
combined = (r.stdout or "") + (r.stderr or "")
# Nexus maven-releases 对已存在 release 坐标禁止覆盖
if "cannot be updated" in combined:
print(f"SKIP (already in repo): {jar.name} -> {group_id}:{artifact_id}:{version}")
return 0
sys.stderr.write(f"FAIL {jar.name} -> {group_id}:{artifact_id}:{version}\n")
if r.stdout:
sys.stderr.write(r.stdout)
if r.stderr:
sys.stderr.write(r.stderr)
return r.returncode
def main() -> int:
p = argparse.ArgumentParser(description="Deploy all JARs from elevator V1 lib to Nexus.")
p.add_argument(
"--lib",
type=Path,
default=DEFAULT_LIB,
help="Directory containing .jar files",
)
p.add_argument("--dry-run", action="store_true", help="Print mvn commands only")
args = p.parse_args()
lib: Path = args.lib
if not lib.is_dir():
print("Not a directory:", lib, file=sys.stderr)
return 2
jars = sorted(lib.glob("*.jar"))
if not jars:
print("No JAR files in", lib, file=sys.stderr)
return 2
ok, fail = 0, 0
for i, jar in enumerate(jars, 1):
coords = read_maven_coords(jar)
if coords:
gid, aid, ver = coords
src = "embedded"
else:
gid, aid, ver = fallback_coords(jar)
src = "fallback"
print(f"[{i}/{len(jars)}] {jar.name} -> {gid}:{aid}:{ver} ({src})")
rc = deploy_one(jar, gid, aid, ver, args.dry_run)
if rc == 0:
ok += 1
else:
fail += 1
print(f"Done. ok={ok} fail={fail}")
return 0 if fail == 0 else 1
if __name__ == "__main__":
sys.exit(main())
docs/operations/ninca-common-component-organization-prod-rolling-upgrade-3-instances.md
+43
View File
@@ -0,0 +1,43 @@
# 生产滚动升级：ninca-common-component-organization（三实例）
**现场根目录（部署包）：**
`/media/zebra/9e8fa357-7db6-4d70-88ed-d5de5a059a663/星河湾星中星/部署包/ninca_common_component_organization_01-ninca_common_component_organization`
根下含 `bootstrap.properties`、`application-node.properties` 示例、`sql/`；三台各用子目录（本仓样例为 `…207` / `…208` / `…209`，与 `application-node.properties` 里 `component-organization-01`～`03` 对应）。
---
## 1. 为什么这样升级对终端用户额外风险小
三台是**滚动替换**：任意时刻总有两台在跑，上游 Consul/Ribbon 或负载均衡会把流量导向健康实例，不会像整机停机那样突然断服务。
数据库脚本在 `**component-organization`** 库里**只执行一次**（维护窗口、由 DBA 或授权人在单点执行），避免三台各跑一遍弄乱数据。
若新版本在某台不满意，可**换回停机前备份的旧 JAR**；涉及访客楼层等策略时，也可在库或配置侧**关闭/禁用策略**降低影响（与研发确认具体字段）。运行与构建均为 **JDK 8**。
---
## 2. 升级顺序（先库后应用）
1. **数据库（一次）**
在 `**component-organization`** 上按变更单执行对应 DDL/DML（脚本与部署包 `sql/`、`docs/sql/` 同源说明一致）。**同一迁移禁止在三台应用机上重复执行。** 慎用含 `DROP TABLE` 的「全量安装」类脚本；生产优先增量脚本。迁移验证落库后再动应用。
2. **应用（逐台）**
建议顺序如 **207 → 208 → 209**（或按现网约定）。**每台流程：** 若现场有 LB/摘流习惯可先摘该实例 → `stop.sh` 停进程 → **备份当前 Fat JAR**（如加 `.bak.日期`）→ 上传新 JAR（与发布说明 **SHA-256** 一致；三台用同一制品）→ **JDK 8** 下 `start.sh` 启动 → 本节第 3 步检查通过后再处理下一台。
保留各节点 `application-node.properties` 中的节点差异（Consul、instance-id、IP 等）；合并新版本键值时勿把数据源/Redis/注册中心改成测试环境。
---
## 3. 每台做完看什么（最多三条）
- **健康：** `http://<节点IP>:<management.port>/actuator/health`（路径以现场为准）应为 **UP**。
- **日志：** `logs/` 下 info/error，无持续报错、无连库/注册中心失败风暴。
- **冒烟：** 按变更单做只读或低风险接口抽查；若本次含访客楼层策略，用只读方式确认读取符合预期。
---
## 4. 不满意怎么撤回
**应用：** 停进程 → 把备份的 JAR 换回运行文件名 → 再起动并按上节三项看一眼。可只回滚有问题的那台。
**库：** 优先与研发确认是否可通过关策略、改配置规避；若必须还原库，由 DBA 在评估窗口内操作，必要时先停写或停齐三台应用，避免双写分叉。
---
**备忘：** 三台最终应用包 **SHA-256 一致**；`sql/README.txt` 中对含 `DROP` 的脚本风险有说明，执行前核对变更单。
docs/operations/ninca-common-component-organization-production-upgrade-plan.md
+315
View File
@@ -0,0 +1,315 @@
# 组织信息服务（ninca-common-component-organization）产线升级方案
**文档性质：** 正式发布稿（可向甲方及项目组同步）
**适用组件：** `ninca-common-component-organization`（以下简称「组织信息服务」）
**运行基线：** JDK 8；制品需与发布说明中的 **SHA-256** 校验一致
---
## 1 概述与目标
### 1.1 背景
组织信息服务负责人员与组织维度数据，产线通常以 **三实例** 部署，通过服务注册与负载均衡对外统一入口。本次升级在保持业务连续性的前提下，完成数据库与应用制品的协同发布。
### 1.2 目标
| 序号 | 目标 |
| --- | --------------------------------------------------------------------------- |
| G1 | 在约定维护窗口内完成 **数据库迁移（单次执行）** 与 **应用滚动升级**，任意时刻保障 **不少于 2/3 实例** 对外可用能力 |
| G2 | 策略类变更（如租户访客可达楼层）以 **组织侧库表与配置** 为权威来源；对外接口契约保持稳定，仍以 **人员详情中的楼层清单** 作为业务侧读取口径 |
| G3 | 升级过程可追溯：制品校验、节点备份、探活与日志核对均有明确检查项 |
| G4 | 预留 **应用级回滚** 路径；库级回滚仅在评估后由 DBA 执行 |
### 1.3 本次变更的业务语义（策略侧）
- **策略存储位置：** 租户访客可达楼层等策略配置落在 **组织信息服务所用数据库（`component-organization`）** 中，由组织侧维护与下发相关逻辑。
- **对外呈现：** 业务平台与其它系统仍以 **人员详情接口返回的楼层清单** 为准进行展示与后续编排。
- **合并语义：** 当组织侧配置了访客楼层策略时，其语义为对可达楼层的 **替代（覆盖）**，**不与** 电梯侧或其它环节的计算结果做 **求交**；具体字段与开关以变更单及研发确认为准。
---
## 2 功能实现思路与方案（本次升级对应能力）
本节说明「租户访客可达楼层策略」在组织信息服务内的实现思路，便于甲方技术接口人与乙方研发对齐验收口径；不涉及对外接口路径变更。
### 2.1 设计原则
| 原则 | 说明 |
| ---------- | --------------------------------------------------------------------------------------- |
| **权威在组织库** | 策略数据仅存于 `**component-organization`** 库表；三台应用实例 **无状态、读同一库**，故滚动升级时只要迁移执行正确，各实例行为一致。 |
| **对外契约不变** | 仍通过既有 **人员详情** 等接口返回楼层相关字段；不在本文扩展新 REST 路径。 |
| **替代非求交** | 策略启用且允许列表非空时，对返回给调用方的可达楼层集合采用 **整单替代**；规范语义下 **不做** 与电梯侧原始列表的 **交集过滤**。 |
| **命中与降级** | 按被访人所属 **组织机构 ID 链** 依次尝试命中策略；未命中、策略停用、或查询异常时 **回退** 为既有逻辑（通常仍会与电梯侧权限数据组装原始楼层），避免阻断主流程。 |
### 2.2 数据模型与脚本
| 项 | 说明 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **表** | `tenant_visitor_floor_policy`（建在 `**component-organization`** 库）。 |
| **关键字段（业务视角）** | **组织节点**：与行政组织树节点 ID 一致；**启用标志**；**允许到访区域列表**（存为 JSON 数组字符串，元素为区域/楼层在通行系统中的标识）；默认租户级策略下 **楼栋维度字段为空**（与现网 Mapper 命中规则一致）。 |
| **脚本来源** | 仓库 `docs/sql/` 与部署包 `sql/` 同源；典型建表：`organization_tenant_visitor_floor_policy.sql`；租户初始化按变更单选用 `organization_tenant_visitor_floor_policy_init_*.sql` 等。**生产慎用含 `DROP TABLE` 的全量安装脚本**，优先增量 DDL/DML。 |
### 2.3 服务端逻辑（实现分层）
1. **数据访问层**：按 **组织节点 ID** 查询 **启用** 的策略行；默认策略满足「楼栋字段为空」等现场约定条件（与运行代码一致）。
2. **策略服务**：解析允许列表 JSON；若解析失败或为空，视为 **未生效**，由上层走原逻辑。
3. **人员业务装配**：在 **人员详情** 分支中，先按既有方式获取电梯侧权限相关的楼层数据，再在 **返回前** 若策略命中则用策略列表 **替换** 对外楼层标识集合及展示用名称组装结果；在 **访客分页（访客模式）** 分支中，若策略命中则 **优先** 用策略生成楼层展示，减少对电梯接口的重复依赖（具体以当前发布制品代码为准）。
4. **多组织归属**：被访人若关联多个组织 ID，按约定顺序 **首个命中** 即采用该条策略，避免多处冲突。
### 2.4 验收口径建议（与研发对齐）
| 场景 | 期望行为 |
| ----------- | ------------------------------------- |
| 策略未启用或未配置 | **人员详情** 中楼层相关表现与升级前一致（在其它依赖系统正常前提下）。 |
| 策略启用且允许列表有效 | **人员详情** 返回的楼层清单 **与策略配置一致**（替代语义）。 |
| 关闭策略或清空允许列表 | 恢复为未启用路径下的行为。 |
### 2.5 与其它系统的职责边界
- **组织信息服务**：持久化策略、在人员详情/访客列表等路径写入 **对外一致的楼层清单**。
- **电梯 / 区域主数据**：仍为区域标识与电梯权限数据来源之一；组织侧在部分路径会先读取再 **替换** 输出，不改变「业务平台应以人员详情楼层为准」的集成约定。
- **若历史曾在电梯应用侧单独配置同类租户策略**：应按变更单做 **职责收口**，避免同一租户两套规则；电梯侧仅 **透传** 上游给出的楼层清单参与派梯（与研发白皮书一致）。
---
## 3 适用范围与假设
### 3.1 适用范围
- 部署形态：**同一部署包根路径下三台独立进程**（示例子目录 `…207` / `…208` / `…209`），与节点专属配置（如 `application-node.properties` 中的 `component-organization-01`～`03`）对应。
- 数据库：`**component-organization`** 库；本次迁移脚本 **全环境仅执行一次**。
- 不包含：电梯应用、人脸识别 GPU 后端等其它组件的升级步骤（若存在联动，以变更单为准单独约定）。
### 3.2 前提假设
| 假设 | 说明 |
| --- | ----------------------------------------------- |
| H1 | 维护窗口已审批，相关方已知会 |
| H2 | 新制品已从受控仓库获取，**SHA-256** 与发布说明一致 |
| H3 | 三台均可 SSH/运维通道登录，具备 `stop.sh` / `start.sh` 执行权限 |
| H4 | Consul/Ribbon 或前置负载均衡能将流量导向健康实例；摘流操作若存在，按现网规范执行 |
| H5 | JDK 运行环境为 **JDK 8**，与构建一致 |
### 3.3 部署包根路径（事实引用）
**现场根目录（部署包）：**
`/media/zebra/9e8fa357-7db6-4d70-88ed-d5de5a059a663/星河湾星中星/部署包/ninca_common_component_organization_01-ninca_common_component_organization`
根目录通常包含 `bootstrap.properties`、`application-node.properties` 示例、`sql/` 等；**三台实例各占用一个子目录**，本仓库样例为 `…207`、`…208`、`…209`。
---
## 4 变更说明（数据 / 应用）
### 4.1 数据层（`component-organization`）
| 类型 | 说明 |
| ---- | ------------------------------------------------- |
| 执行次数 | **仅执行一次**（维护窗口内、单点执行），禁止在三台应用机上重复跑同一套迁移 |
| 脚本来源 | 与部署包 `sql/` 及项目 `docs/sql/` 说明保持一致；执行前对照变更单勾选脚本编号 |
| 风险脚本 | 含 `DROP TABLE` 等「全量安装」类脚本生产慎用；优先 **增量** DDL/DML |
| 验证 | 迁移后做抽样查询或变更单要求的校验 SQL，确认落库正确后再启动首批应用实例 |
### 4.2 应用层（三实例）
| 项 | 要求 |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| 制品 | 三台使用 **同一 Fat JAR**，文件名与 **SHA-256** 与发布说明一致 |
| 运行时 | **JDK 8** 启动 |
| 节点差异 | 保留各节点 `application-node.properties` 中的 Consul、instance-id、监听 IP 等 **现场差异**；合并新版本配置键时 **勿将数据源、Redis、注册中心改为测试环境** |
| 滚动约束 | 逐台替换；任意时刻保证 **至少 2 台健康**，即满足 **≥ 2/3 可用** |
---
## 5 风险评估与控制措施
| 风险 | 影响 | 控制措施 |
| -------- | --------- | -------------------------------------------- |
| 迁移脚本重复执行 | 数据错乱、约束冲突 | **单次执行**；变更单注明执行人与执行时间点 |
| 制品错误或篡改 | 运行异常或安全隐患 | 发布前比对 **SHA-256**；仅从受控渠道获取 |
| 单台升级失败 | 该实例不可用 | 保留旧 JAR 备份；失败实例可先隔离再回滚 |
| 策略语义理解偏差 | 业务展示与预期不符 | 本文第 1.3 节、**第 2 章** 与变更单三重对齐；上线后按验证清单抽查 |
| 库级回滚需求 | 难度大、窗口长 | 优先 **关策略/配置降级**；库回滚由 DBA 评估，必要时暂停写入或协调三台停机窗口 |
---
## 6 升级步骤
### 6.1 总原则
**先库后应用**：数据库迁移验证通过后，再按实例滚动替换应用。**数据库脚本只执行一次**（针对 `component-organization`）。
### 6.2 阶段 A — 数据库（单次）
1. 确认变更单中的脚本列表与顺序；核对 `sql/README.txt` 等对高危脚本（含 `DROP`）的说明。
2. 在授权窗口内，由 **DBA 或授权人** 在 **单连接点** 对 `**component-organization`** 执行迁移。
3. 执行记录：时间、执行人、脚本版本号或 Git 标签（若有）、校验 SQL 结果摘要。
4. **禁止** 在三台应用主机上各自再执行一遍同一迁移。
### 6.3 阶段 B — 应用滚动（三台；示例顺序 207 → 208 → 209）
对 **每一台** 重复下列步骤；**上一台** 健康检查通过后再处理 **下一台**，以保证滚动期间 **≥ 2/3** 实例可用。
| 步骤 | 操作要点 |
| --- | -------------------------------------- |
| B1 | （可选）若现场习惯摘流，先摘除当前实例流量 |
| B2 | `stop.sh` 停止进程 |
| B3 | **备份** 当前运行的 Fat JAR（建议命名含 `.bak` 与日期） |
| B4 | 上传新 JAR，校验 **SHA-256** 与发布说明一致 |
| B5 | **JDK 8** 执行 `start.sh` |
| B6 | 按 **第 7 节** 做探活与日志检查；含访客楼层策略时增加只读冒烟 |
| B7 | 通过后处理下一台 |
实例顺序可按现网约定调整；原则不变：**始终保留多数实例对外服务**。
### 6.4 阶段 C — 收口
- 确认三台 **SHA-256** 一致且均为新版本进程。
- 汇总执行记录与验证结果，归档变更单闭环材料。
---
## 7 验证与观察
### 7.1 每台升级后立即检查（建议上限三项，避免清单冗长）
| 检查项 | 方法 | 期望 |
| --- | ---------------------------------------------------------- | --------------------- |
| 健康 | `http://<节点IP>:<management.port>/actuator/health`（路径以现场为准） | 状态为 **UP** |
| 日志 | `logs/` 下 info / error | 无持续异常；无数据库或注册中心连接失败风暴 |
| 冒烟 | 变更单要求的只读或低风险接口；若含访客楼层策略 | 按 **第 2.4 节** 口径抽查 |
### 7.2 观察期建议
上线后 **24～72 小时**（可按项目约定）关注错误日志量、接口耗时与业务侧反馈；策略类变更需业务方配合 spot check。
---
## 8 回滚
### 8.1 应用回滚（常用）
1. `stop.sh` 停止该实例。
2. 将备份的 Fat JAR 恢复为运行文件名。
3. **JDK 8** 启动后重复 **第 7.1 节** 检查。
4. 可 **仅回滚异常实例**，无需三台同时回滚（除非变更单要求版本一致）。
### 8.2 数据库 / 策略回滚
- **优先：** 与研发确认是否可通过 **关闭策略、调整配置** 消除影响。
- **库结构或数据回滚：** 由 **DBA** 在评估窗口操作；必要时先 **停写** 或协调 **三台应用暂停**，避免双写分叉。
---
## 9 组织分工
| 角色 | 职责 |
| ------------ | -------------------------------------------- |
| 项目经理 / 甲方接口人 | 维护窗口确认、干系人知会、对外结论同步 |
| 运维 / 现场实施 | 应用启停、JAR 替换与备份、探活与日志初判 |
| DBA | `component-organization` 单次迁移执行或复核、库级回滚评估与执行 |
| 研发 / 架构 | 变更单技术内容、策略语义与配置项确认、疑难日志分析 |
| 测试 / 业务代表 | 冒烟用例与验收点确认、上线后业务侧抽查 |
---
## 附录 A 业务数据流（Mermaid）
说明：面向甲方表述，不展开内部类名；强调「策略在组织库、对外仍以人员详情楼层为准、替代语义」。
```mermaid
flowchart LR
subgraph client["用户侧与会端"]
U[住户 / 访客 / 物业终端]
end
subgraph platform["业务平台"]
P[门禁梯控等业务编排]
T2["对外口径：人员详情中的楼层清单"]
end
subgraph org["组织信息服务"]
DB[(组织库)]
S[人员与组织数据]
T1["策略配置落在组织库"]
T3["策略语义：替代覆盖非求交"]
DB --> S
DB --- T1
S --- T3
end
subgraph area["区域与电梯相关能力"]
E[电梯权限与派梯等]
end
U --> P
P --> S
S --> P
P --> E
P --- T2
```
---
## 附录 B 系统交互时序（Mermaid）
```mermaid
sequenceDiagram
participant User as 用户端
participant Biz as 业务平台
participant Org as 组织信息服务
participant Area as 区域与电梯相关系统
User->>Biz: 业务操作（通行 / 访客等）
Biz->>Org: 查询人员与组织信息（含人员详情）
Org->>Biz: 返回人员详情（含楼层清单等）
Note over Org: 访客楼层策略数据持久于组织库<br/>与对外楼层清单展示口径分离管理
Biz->>Area: 下发通行或派梯请求（按业务编排）
Area->>Biz: 执行结果 / 状态
Biz->>User: 界面与设备反馈
```
---
## 附录 C 术语对照（内部研发 → 对外沟通）
| 内部常用表述 | 对外可用表述 |
| ----------------------------------- | ----------------------------- |
| `component-organization` 库 | 组织信息服务业务库 |
| ninca-common-component-organization | 组织信息服务 / 组织组件（按甲方合同用语选用） |
| Feign / Ribbon / Consul | 服务注册与调用（一笔带过或按甲方技术口径） |
| 租户访客楼层策略表 / 配置 | 租户侧访客可达楼层策略（配置在组织侧） |
| 替代（非求交） | 策略生效时以组织侧配置为准覆盖，不与其它环节结果做交集过滤 |
---
**文档版本：** 1.1
**关联参考：**
- `docs/operations/ninca-common-component-organization-prod-rolling-upgrade-3-instances.md`（现场滚动操作备忘）
- `docs/superpowers/specs/2026-05-06-tenant-visitor-policy-organization-implementation.md`（策略契约与 detail / 分页边界详述）
docs/operations/中建系统-接口调用链路图.md
+141
View File
@@ -0,0 +1,141 @@
# 中建系统 — 接口调用链路图
**文档用途：** 从中建系统（业主/集成侧，含经 **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`
docs/operations/升级方案正式版本.md
+389
View File
@@ -0,0 +1,389 @@
**文档用途：** 面向甲方领导及项目决策层审批用的升级方案正式稿；技术细节与部署路径详见 `docs/operations/ninca-common-component-organization-production-upgrade-plan.md`。
---
# 组织信息服务（ninca-common-component-organization）产线升级方案
**正式发布稿 / 甲方审批版**
| 项目 | 内容 |
| ---- | ------------ |
| 文档版本 | **V1.1** |
| 编制单位 | 乙方项目组 |
| 编制日期 | 2026年05月07日 |
| 密级 | 内部公开 / 甲方项目组 |
---
## 文档控制与批准
### 修订记录
| 版本 | 日期 | 作者 | 变更说明 |
| ---- | ---------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| V1.0 | 2026-05-07 | 乙方项目组 | 首次正式提交甲方审批 |
| V1.1 | 2026-05-08 | 乙方项目组 | 更正 DDL 风险表述；完善附录 Mermaid 图（附录 A 增补入口/Nginx、电梯域及 Consul·ZK·关联服务等平台关系；明确「业务平台」拆分与电梯应用双重抽象）；新增业务时序图与滚动升级时序图；去除文稿前缀说明；附录 A 终端回流经 Nginx 对称建模并澄清箭头语义，④ 电梯域节点命名与② 区分；附录 B 参与者与附录 A 分层术语对齐；附录 A 场内按接入/应用/组织/电梯域/关联能力分栏；附录 A 将「域内第三方」与「中建相关」等价并与终端用户同列于「①」、取消 EXT；术语路由改用路径 A/B/C 避免与图中①～⑤冲突 |
### 审阅与批准
| 角色 | 姓名 / 部门 | 签字 | 日期 |
| ------- | ----------- | ---------- | -------- |
| 甲方技术负责人 | ___________ | __________ | ________ |
| 甲方业务负责人 | ___________ | __________ | ________ |
| 乙方项目经理 | ___________ | __________ | ________ |
| 现场运维负责人 | ___________ | __________ | ________ |
---
## 执行摘要（领导必读）
| 项目 | 说明 |
| -------- | ----------------------------------------------------------------------------------------------------- |
| **升级原因** | 为满足「租户访客可达楼层策略」统一在组织侧管理，减少多源配置不一致，提升通行业务准确性。 |
| **业务收益** | ① 策略落在组织信息服务所用数据库，配置口径单一；② 对外人员详情等接口路径与契约不变，业务平台默认无改造；③ 策略语义为 **覆盖（替代）**，便于甲乙方对齐验收。 |
| **维护窗口** | 计划 **2026年X月X日 21:00 ~ X月X日 02:00**（共5小时）。 业务影响：滚动升级期间 **始终有≥2台实例对外服务**；单实例切换时可能出现 **秒级延迟**，不设「整机停机」。 |
| **升级内容** | ① 在 `**component-organization`** 库执行迁移（**全环境仅一次**）；② 三台应用实例依次滚动替换为同一制品（JDK 8）。 |
| **成功标准** | 三台健康、策略可按租户启用/停用验证、冒烟通过、约定观察期内无关联重大异常。 |
| **回滚承诺** | 应用级回滚可快速恢复旧制品；策略可通过 **停用策略行** 降级，优先避免库结构回滚。 |
---
## 1 背景与业务目标
### 1.1 背景
组织信息服务负责人员与组织数据的维护。租户访客可达楼层等策略若在多系统分散配置，易产生不一致与运维成本。本次升级将 **策略权威收口至组织信息服务所用数据库**，业务平台仍以既有 **人员详情** 等接口获取楼层清单，实现 **策略统一、接口契约稳定**。
### 1.2 业务目标
| 序号 | 目标 |
| --- | ----------------------------------- |
| G1 | 维护窗口内完成升级，任意时刻 **≥2/3 实例** 可用，业务连续。 |
| G2 | 策略仅存组织侧库表；对外接口不因本次升级而变更 URL/字段契约。 |
| G3 | 过程可追溯，回滚路径明确。 |
### 1.3 本次变更的业务语义（关键）
> **替代（覆盖），规范语义下非「求交」**
> 租户启用访客楼层策略且允许列表有效时，人员详情等路径返回的楼层清单 **以组织侧配置为准整单呈现**；**不与**电梯侧原始列表做 **交集过滤** 作为规范语义。
> 策略未配置、停用或异常降级时，行为与升级前一致（在依赖系统正常前提下）。
---
## 2 业务影响与变更范围
### 2.1 影响范围
| 影响对象 | 说明 |
| --------------- | -------------------------------------------- |
| 业务平台（门禁、访客、通行等） | **接口契约不变**；租户启用策略后，人员详情中的 **楼层内容** 按组织侧策略呈现。 |
| 电梯 / 区域主数据 | **不要求甲方单独改造**；组织信息服务在未命中策略时仍按既有逻辑与电梯侧数据组装。 |
| 组织信息服务 | 库表迁移（单次）+ 应用制品滚动升级（三台）。 |
### 2.2 不变承诺
- 对外 REST 路径与签名保持兼容（与变更单锁定版本一致）。
- 未启用策略的租户，目标行为与升级前一致。
- 策略查询异常等场景 **降级** 为既有逻辑，避免阻断人员详情主链路（以实际部署制品为准）。
---
## 3 详细升级计划
### 3.1 前置条件检查
| 编号 | 检查项 | 确认方式 |
| ---- | ------------------------------------ | ------- |
| PC-1 | 维护窗口已通过甲方审批，相关方已通知 | 邮件/会议纪要 |
| PC-2 | 新制品已从受控渠道获取，SHA-256 与发布说明一致 | 校验比对 |
| PC-3 | 三台服务器可运维登录，具备启停权限 | 运维验证 |
| PC-4 | 注册中心/负载均衡可将流量导向健康实例 | 控制台查看 |
| PC-5 | 数据库 `component-organization` 已备份且可连接 | DBA 确认 |
### 3.2 升级步骤与时间预估
**总窗口：约 5 小时（实操约 2 小时 + 缓冲）**
#### 阶段 A：数据库迁移（单次，约 10～20 分钟）
- **执行人**：DBA 或授权人
- **执行位置**：仅在 **单管控终端** 连接 `**component-organization`**，**禁止**在三台应用主机各执行一遍同一脚本。
- **内容**：按变更单选用 `**docs/sql/` / 部署包 `sql/`** 中脚本；典型建表见 `organization_tenant_visitor_floor_policy.sql`，租户初始化见变更单指定的 `*_init_*.sql`。
- **风险说明（重要）**：含 `**DROP TABLE`** 或重建类的「全量安装」脚本 **不得默认用于生产**；须经评审与备份后再执行。增量 `**CREATE TABLE IF NOT EXISTS`** 类脚本相对安全，但仍 **只执行一次** 并留痕。
- **验证**：抽样校验表对象及约定查询；通过后进入阶段 B。
#### 阶段 B：应用滚动升级（每台约 15～25 分钟，三台合计约 45～75 分钟）
实例顺序示例：**207 → 208 → 209**（与部署包 `ninca_common_component_organization_01-ninca_common_component_organization` 下子目录对应；顺序可按现场安排调整）。
| 步骤 | 操作 | 备注 |
| --- | ------------------------ | ---------- |
| B1 | （可选）摘除当前实例流量 | 依负载均衡与运维规范 |
| B2 | `stop.sh` 停止进程 | |
| B3 | 备份当前 JAR（`.bak` + 日期） | |
| B4 | 上传新 JAR，校验 SHA-256 | 三台同一制品 |
| B5 | `start.sh` 启动（**JDK 8**） | |
| B6 | 健康检查与冒烟（见第 4 章） | 上一台通过后再下一台 |
| B7 | 恢复流量（若曾摘流） | |
#### 阶段 C：收口与观察（约 30 分钟）
三台均为新版本且健康；按甲方测试租户验证策略启停；进入约定观察期。
---
## 4 验证标准与验收确认
### 4.1 每台升级后即时验证
| 验证项 | 方法 | 期望结果 |
| ---- | ------------------------------------------------------ | ------------------ |
| 健康检查 | `http://<IP>:<management.port>/actuator/health`（以现场为准） | `UP` |
| 日志 | `logs/` | 无持续 ERROR、无注册/连库风暴 |
| 冒烟 | 人员详情等变更单约定接口 | 无 5xx；策略租户符合「替代」口径 |
### 4.2 整体验收清单（甲方签字确认）
| 编号 | 验收项 | 通过标准 | 甲方确认 |
| ---- | -------- | --------------------------------------------- | ---- |
| AC-1 | 三实例健康 | 三台均 UP，观察期内稳定 | □ |
| AC-2 | 数据库变更正确 | `tenant_visitor_floor_policy`（及变更单涉及对象）存在且可读写 | □ |
| AC-3 | 策略语义（替代） | 启用策略后详情楼层与配置一致；停用后恢复升级前行为 | □ |
| AC-4 | 业务冒烟 | 访客/通行典型场景无阻断性故障 | □ |
| AC-5 | 性能 | 人员详情接口耗时相对升级前无明显劣化（阈值由变更单约定） | □ |
---
## 5 风险评估与应对措施
| 风险事件 | 概率 | 业务影响 | 应对措施 |
| --------------- | --- | ---- | ---------------------------- |
| 迁移脚本误执行（重复或错库） | 低 | 高 | 单次、单点、变更单勾脚本；DBA 复核连接串 |
| 误执行含 DROP 的全量脚本 | 低 | 高 | 生产默认只用评审过的增量脚本；全量须书面审批 |
| 单台升级失败 | 中 | 低 | 多数实例仍可用；该台回滚旧 JAR |
| 策略配置与业务预期不符 | 中 | 中 | 上线前测试环境确认；生产可通过停用策略降级 |
| 库级回滚 | 极低 | 高 | **优先停策略**；库回滚须甲方书面批准与 DBA 方案 |
---
## 6 回滚策略
### 6.1 应用回滚（常用）
单台：`stop.sh` → 恢复备份 JAR → `start.sh`（JDK 8）→ 健康检查。可只回滚故障实例。
### 6.2 策略 / 数据降级
- **停用策略**（表中启用标志或等价配置）：通常 **无需** 卸版本即可恢复旧展示逻辑（与研发确认字段）。
- **库结构回滚**：高风险，须甲方书面授权与 DBA 执行。
---
## 7 组织分工与紧急联络
| 角色 | 职责 | 姓名 | 联系方式 |
| ------- | ---------- | -------- | -------- |
| 甲方技术负责人 | 窗口审批、协调资源 | ________ | ________ |
| 甲方业务代表 | 验收与业务抽查 | ________ | ________ |
| 乙方项目经理 | 方案与指挥 | ________ | ________ |
| 现场运维 | 启停、制品替换、探活 | ________ | ________ |
| DBA | 单次迁移、库回滚评估 | ________ | ________ |
**升级期间紧急联络（24 小时待命）**
- 乙方技术热线：XXX-XXXX-XXXX
- 甲方 IT 应急：XXX-XXXX-XXXX
---
## 8 升级完成确认与签字
**声明：** 升级过程将严格按审批方案执行；完成后由甲方代表确认验收。
| 角色 | 签字 | 日期 |
| ------- | --- | --- |
| 甲方技术负责人 | | |
| 甲方业务负责人 | | |
| 乙方项目负责人 | | |
---
## 附录 A：业务数据流图（策略在组织侧 · 平台关系概览）
**术语：「业务平台」（本文档用语）**
指 **场内** 门禁 / 访客 / 通行等场景中，**依赖组织侧既有 HTTP 契约（如人员详情）** 的上层组合，**不是单一进程或单一仓库**。典型路由形态（与下图 **①～⑤ 分区序号不同维度**）：**路径 A** Nginx `**/api/*`** → `**cw-elevator-application**`；**路径 B** `**/cwos-portal/*`** → `**cwos-portal**` / SPA；**路径 C** 可选 `**intelligent-cwoscomponent`** 中转。**「域内第三方」与「中建相关」在本文可等价归类**；附录 A 图中 **①** 将三类接入 **合并为同一分组节点**（框内文字罗列），以减少连线交叉。**不再单独划「域外 EXT」区**。**人员详情权威**在组织侧（如 `**POST /component/person/detail`**）。详见 `docs/architecture/Maven聚合工程说明.md`、`docs/business/访客注册与派梯楼层业务流程走查.md`。
（**图中序号：** **①～⑤** = **场内**按角色分层；**版面**为 **第一行左→右：①②③**，**第二行左→右：④⑤**；为减少穿插，**图中仅保留主干与必要的跨层虚线**，响应回流、可选直达 API、镜像详情口径等见下列 **图注**。）
下列图示可在支持 Mermaid 的工具中渲染（如 VS Code、Typora、[mermaid.live](https://mermaid.live)）导出 PNG 插入 Word。**插入 Word 时请导出为浅色背景**（勿使用编辑器深色主题截图）；下图已内置浅色配色。
```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryColor':'#ffffff','primaryTextColor':'#111827','primaryBorderColor':'#cbd5e1','secondaryColor':'#f8fafc','tertiaryColor':'#f1f5f9','lineColor':'#64748b','clusterBkg':'#fafafa','clusterBorder':'#e2e8f0','edgeLabelBackground':'#ffffff','fontSize':'13px'},'flowchart':{'padding':16,'nodeSpacing':36,'rankSpacing':44,'curve':'basis'}}}%%
flowchart TB
subgraph R1[" "]
direction LR
subgraph IN01["① 接入层"]
SRC[接入来源分组<br/>终端用户 · 中建平台 · 域内第三方]
NGX[Nginx<br/>反向代理 · 静态 · 路由]
SRC --> NGX
end
subgraph IN02["② 应用服务层"]
direction TB
APICH[cw-elevator-application<br/>REST · /api/*]
PTsvc[cwos-portal / SPA<br/>/cwos-portal/*]
INT[intelligent-cwoscomponent<br/>可选编排中转]
LEG[对外口径：人员详情楼层清单]
end
subgraph IN03["③ 组织领域（本次升级）"]
direction TB
ODB[(组织库 component-organization<br/>含租户访客楼层策略)]
POL[策略：启用则允许列表<br/>覆盖对外楼层清单]
OCORE[人员与组织核心逻辑<br/>ninca-common-component-organization]
ODB --> POL --> OCORE
ODB --> OCORE
end
end
subgraph R2[" "]
direction LR
subgraph IN04["④ 电梯主数据域"]
direction LR
ELV[电梯域职责<br/>与②同制品 · 派梯 · 设备 · 区域主数据]
EDB[(电梯业务库)]
ELV --> EDB
end
subgraph IN05["⑤ 关联与基础设施"]
INFRA[Consul / Ribbon · ZooKeeper / Dubbo<br/>Redis / Kafka · CRK · ninca-common 等]
end
end
NGX --> APICH
NGX --> PTsvc
APICH --> OCORE
PTsvc -.-> OCORE
OCORE --> ELV
OCORE -.-> INFRA
ELV -.-> INFRA
style R1 fill:transparent,stroke:none
style R2 fill:transparent,stroke:none
```
> **版式说明：** **①** 使用 **单一「接入来源分组」** 节点汇总三类主体，**一条边** 接入 **Nginx**，避免三源并列的多条平行边。**⑤** 合并为 **一块关联与基础设施**，与 **③④** 各保留 **一条虚线**，其余协作关系见 **图注** 与正文路径 A/B/C，**不在图中重复画回流**（如 HTTP 响应经 Nginx 回到终端、组织与电梯域之间的数据返回等，与附录 B 一致）。**②** 中 **INT / LEG** 仅作层内说明，**不与域外再连线**，以免与主干抢线。
**图注：** **「业务平台」** 指 **②**。**请求主路径**：① → ②（经 Nginx 至 REST/门户等）→ ③（Feign）→ ④；**③↔④** 在组装人员详情时的回调与返回**未单独画箭头**，避免与主干重复。**可选**：中建/域内第三方 **直达** 电梯 REST、**intelligent** 编排等，以实际集成为准。**响应路径**（②→① 等）与 **对外口径（LEG）** 图中略。**⑤** 为注册发现、消息及公共能力等，与多组件的细分连接以实际配置为准。
---
## 附录 B：业务交互时序图（人员详情与楼层）
展示「查询被访人详情—楼层如何形成」的抽象过程（不涉及内部类名）。
```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryTextColor':'#111827','lineColor':'#64748b'}}}%%
sequenceDiagram
autonumber
participant User as 终端用户
participant Biz as 业务平台（上层调用方 · 门禁/访客/通行等 ）
participant Org as 组织信息服务
participant Elev as 电梯域（区域主数据等）
User->>Biz: 访客邀约 / 查询被访人等业务操作
Biz->>Org: 请求人员详情（需楼层信息）
Org->>Elev: 获取原始可达区域
Elev-->>Org: 返回原始区域列表
Org->>Org: 读取组织库策略；若启用且有效则用策略列表替换对外楼层
Org-->>Biz: 返回人员详情（含楼层清单）
Biz-->>User: 界面展示可选楼层 / 后续通行办理
Note over Org: 策略未命中或异常时降级为既有组装逻辑，避免阻断主流程。
```
（本图 **业务平台** 指 **场内** 上层调用侧（同附录 A `**②`**）；**终端用户** 与 **中建/域内第三方** 与附录 A `**①`** 同列，本图从进入应用编排之后的链路抽象起笔。）
---
## 附录 C：产线滚动升级时序图（单次库迁移 + 三台滚动）
```mermaid
%%{init: {'theme':'base','themeVariables':{'background':'#ffffff','primaryTextColor':'#111827','lineColor':'#64748b'}}}%%
sequenceDiagram
autonumber
participant DBA as DBA / 授权人
participant DB as 组织库 component-organization
participant Ops as 现场运维
participant N1 as 实例 ①
participant N2 as 实例 ②
participant N3 as 实例 ③
Note over DBA,DB: 阶段 A：仅执行一次
DBA->>DB: DDL/DML（变更单勾选脚本）
DB-->>DBA: 校验落库
Note over Ops,N3: 阶段 B：逐台；全程保持 ≥2 台对外服务能力
Ops->>N1: 停 → 备份 JAR → 换新制品 → 启 → 健康检查
N1-->>Ops: 通过
Ops->>N2: 同上
N2-->>Ops: 通过
Ops->>N3: 同上
N3-->>Ops: 通过
Note over Ops: 阶段 C：三台版本一致，收口与观察期
```
（实例编号 ①②③ 与现场 **207 / 208 / 209** 等目录一一对应，以运维台账为准。）
---
## 附录 D：技术术语对照（供甲乙双方对齐）
| 对外沟通用语 | 内部对应 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 中建 / 域内第三方 / 用户（入口侧） | 附录 A `**①`** 以 **「接入来源分组」** 单框汇总三类主体，接 **Nginx** 后进入 `**②`**；**域内第三方** 与 **中建相关** 在语义上可等价归类。非「业务平台」统称（业务平台见下行） |
| 业务平台（本文档 · 场内） | 非单一服务：经 `/api` 的 **cw-elevator-application**、经 `/cwos-portal/*` 的 **cwos-portal**/SPA、可选 **intelligent-cwoscomponent** 等依赖组织契约的上层组合（见附录 A `**②`**、`AGENTS.md` 拓扑） |
| 组织信息服务 | ninca-common-component-organization |
| 组织信息服务业务库 | `component-organization` 数据库 |
| 租户访客楼层策略表 | `tenant_visitor_floor_policy` |
| 覆盖（替代）语义 | 非求交、规范上对楼层清单整单替换 |
| 服务注册与路由 | Consul / Ribbon |
---
**关联技术方案：** `docs/operations/ninca-common-component-organization-production-upgrade-plan.md`（含功能实现思路 §2、附录图与术语全文）
**中建侧接口调用链：** `docs/operations/中建系统-接口调用链路图.md`（从中建系统发起的 L1 人员详情 / L2 访客派梯完整 HTTP·Feign 链路）
**文档结束**