starRiverProperty/docs/operations/ninca-common-component-organization-production-upgrade-plan.md

组织信息服务（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）

说明：面向甲方表述，不展开内部类名；强调「策略在组织库、对外仍以人员详情楼层为准、替代语义」。

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）

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 / 分页边界详述）