mirror of
https://github.com/hpd840321/starRiverProperty.git
synced 2026-06-09 08:20:31 +08:00
hpd840321
7b2bd307f1
- 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.
316 lines
18 KiB
Markdown
316 lines
18 KiB
Markdown
# 组织信息服务（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 / 分页边界详述）
|
||
|