# 组织信息服务（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>:/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: 访客楼层策略数据持久于组织库
与对外楼层清单展示口径分离管理 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 / 分页边界详述）