Initial commit: reorganized source tree

- 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.
This commit is contained in:
hpd840321
2026-05-09 09:00:12 +08:00
commit 7b2bd307f1
7260 changed files with 612980 additions and 0 deletions
+389
View File
@@ -0,0 +1,389 @@
**文档用途:** 面向甲方领导及项目决策层审批用的升级方案正式稿;技术细节与部署路径详见 `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 链路)
**文档结束**