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.
389 lines
22 KiB
Markdown
389 lines
22 KiB
Markdown
**文档用途：** 面向甲方领导及项目决策层审批用的升级方案正式稿；技术细节与部署路径详见 `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](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[接入来源分组<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：业务交互时序图（人员详情与楼层）
|
||
|
||
展示「查询被访人详情—楼层如何形成」的抽象过程（不涉及内部类名）。
|
||
|
||
```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 链路）
|
||
|
||
**文档结束** |