**文档用途：** 面向甲方领导及项目决策层审批用的升级方案正式稿；技术细节与部署路径详见 `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://:/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[接入来源分组
终端用户 · 中建平台 · 域内第三方] NGX[Nginx
反向代理 · 静态 · 路由] SRC --> NGX end subgraph IN02["② 应用服务层"] direction TB APICH[cw-elevator-application
REST · /api/*] PTsvc[cwos-portal / SPA
/cwos-portal/*] INT[intelligent-cwoscomponent
可选编排中转] LEG[对外口径：人员详情楼层清单] end subgraph IN03["③ 组织领域（本次升级）"] direction TB ODB[(组织库 component-organization
含租户访客楼层策略)] POL[策略：启用则允许列表
覆盖对外楼层清单] OCORE[人员与组织核心逻辑
ninca-common-component-organization] ODB --> POL --> OCORE ODB --> OCORE end end subgraph R2[" "] direction LR subgraph IN04["④ 电梯主数据域"] direction LR ELV[电梯域职责
与②同制品 · 派梯 · 设备 · 区域主数据] EDB[(电梯业务库)] ELV --> EDB end subgraph IN05["⑤ 关联与基础设施"] INFRA[Consul / Ribbon · ZooKeeper / Dubbo
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 链路） **文档结束**