starRiverProperty/docs/operations/升级方案正式版本.md

文档用途： 面向甲方领导及项目决策层审批用的升级方案正式稿；技术细节与部署路径详见 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）导出 PNG 插入 Word。插入 Word 时请导出为浅色背景（勿使用编辑器深色主题截图）；下图已内置浅色配色。

%%{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：业务交互时序图（人员详情与楼层）

展示「查询被访人详情—楼层如何形成」的抽象过程（不涉及内部类名）。

%%{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：产线滚动升级时序图（单次库迁移 + 三台滚动）

%%{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 链路）

文档结束