# V2 全系统功能测试环境搭建 — 设计文档

**日期**: 2026-05-01
**状态**: 待实施
**关联**: AGENTS.md, maven-cw-elevator-application/deploy/

---

## 1. 目标

搭建 cw-elevator-application V2 (v2.0.7) 的全系统集成功能测试环境，包含电梯应用及其所有上下游依赖服务（CRK人脸识别、报警、cwos-manager、ninca-common、component-organization等），能够：

- 一键搭建全部 17 个组件
- 运行 V1 vs V2 API 对拍测试
- 验证 V2.0.7 租户访客固定楼层功能
- 验证 CRK 联动、报警联动等端到端链路
- 15-20 分钟内完成从零到全部验证

---

## 2. 环境约束

| 约束 | 值 |
|------|-----|
| 部署方式 | 本机进程 (Java服务) + Docker 容器 (基础组件) |
| MySQL | 复用现有: `192.168.3.12:3307`, `root/123456` |
| JDK | Java 8 (`/usr/lib/jvm/java-8-openjdk-amd64`) |
| Maven | 3.5+ |
| Docker | 已安装, `docker compose` 可用 |
| 代码分支 | `release/cw-elevator-v1-lib-min-risk` |
| 测试范围 | 全系统集成 — 全部 17 个组件 |

---

## 3. 组件清单

### 3.1 基础组件 (Docker)

| # | 组件 | 端口 | 来源 |
|---|------|------|------|
| I1 | Consul | 8500 | 已有 `deploy/consul-docker/docker-compose.yml` |
| I2 | Redis | 6379 | 需要新增 compose 条目 (`redis:7-alpine`) |
| I3 | Kafka + Zookeeper | 9092, 2181 | 需要新增 compose 条目 (`bitnami/kafka:3.6`) |
| I4 | Nginx (前端代理) | 8090 | 已有 `docker-compose.frontend-local.yml` |

### 3.2 应用服务 (本机进程)

| # | 组件 | 端口 | 来源 | 数据库 |
|---|------|------|------|--------|
| A1 | ninca-common-backend | 33010 | `星中心/ninca_common_01-ninca_common_backend.tar.gz` | `ninca_common` |
| A2 | component-organization | 33011 | `星中心/ninca_common_component_organization_01-...tar.gz` | `component-organization` |
| A3 | cwos-system-api | 3333 | `星中心/cwos_system_api_01-cwos_system_api/` (已解压) | — |
| A4 | cwos-manager | 3721 | Docker Harbor 镜像 (已有 compose) | `cwos_manager` |
| A5 | cwos-portal | 33008 | `星中心/cwos_portal` SQL 备份 → 重建 | `cwos_portal` |
| A6 | snap-app | 33012 | `星中心/ninca_common_snap_app_01-...tar.gz` | — |
| A7 | vehicle-app | 33013 | `星中心/ninca_common_vehicle_app_01-...tar.gz` | — |
| A8 | person-file-app | 33014 | `星中心/ninca-person-file-app-V2.9.2_20210216.tar.gz` | — |
| A9 | monitor-app | 33015 | `星中心/ninca_common_monitor_app_01-...tar.gz` | — |
| A10 | CRK-std | 16106 (app), 16114 (mgmt) | `星中心/ninca_crk_std_01-ninca_crk_std_backend/` (JAR已就绪) | `ninca_crk_std` |
| A11 | alarm-app | 17011 (app), 17211 (mgmt) | `星中心/ninca_qk_alarm_app_01-ninca_qk_alarm_app/` (JAR已就绪) | `alarm_deploy` |
| A12 | elevator V2 | 18081 | Maven 构建 `maven-cw-elevator-application` | `cw-elevator-application` |
| A13 | elevator V1 | 18080 | 对照基线 (已有 JAR) | `cw-elevator-application` |

### 3.3 数据库 (MySQL 192.168.3.12:3307)

| 数据库 | 备份文件 | 大小 |
|--------|---------|------|
| `cw-elevator-application` | `data_backup/12_*.sql.gz` + `34_*.sql.gz` | 158M + 2.5G |
| `ninca_crk_std` | (含在 CRK 配置中，需确认备份) | — |
| `alarm_deploy` | `data_backup/alarm_deploy_*.sql.gz` | 15M |
| `cwos_manager` | `data_backup/cwos_manager_*.sql.gz` | 51K |
| `cwos_portal` | `data_backup/cwos_portal_*.sql.gz` | 212M |
| `ninca_common` | `data_backup/ninca_common_*.sql.gz` | 6M |
| `component-organization` | `data_backup/component-organization_*.sql.gz` | 212M |
| `ods` | `data_backup/ods_*.sql.gz` | 485K |
| `cloudwalk_device_thirdparty` | `data_backup/cloudwalk_device_thirdparty_*.sql.gz` | 4K |
| `g` / `p` / `12` / `34` | 其他备份 | 小量 |

---

## 4. 配置统一化

### 4.1 环境变量 (`config/env.sh`)

```bash
# 基础设施
MYSQL_HOST=192.168.3.12
MYSQL_PORT=3307
MYSQL_USER=root
MYSQL_PASS=123456
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASS=1qaz!QAZ
CONSUL_HOST=127.0.0.1
CONSUL_PORT=8500
KAFKA_HOST=127.0.0.1
KAFKA_PORT=9092
ZK_HOST=127.0.0.1
ZK_PORT=2181

# 服务端口
PORT_ELEVATOR_V2=18081
PORT_ELEVATOR_V1=18080
PORT_CRK_STD=16106
PORT_CRK_MGMT=16114
PORT_ALARM=17011
PORT_ALARM_MGMT=17211
PORT_CWOS_PORTAL=33008
PORT_COMPONENT_ORG=33011
PORT_NINCA_COMMON=33010
PORT_CWOS_MANAGER=3721
PORT_SYSTEM_API=3333
PORT_SNAP=33012
PORT_VEHICLE=33013
PORT_PERSON_FILE=33014
PORT_MONITOR=33015
PORT_NGINX=8090

# Java
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
JAVA_OPTS="-Xmx2048m -Xms512m"
```

### 4.2 配置替换规则

每个 Java 服务的 `application.properties` / `bootstrap.properties` 中需要替换：

| 原始值 (生产) | 替换为 (测试) |
|--------------|-------------|
| `mysql_01.mysql_ip` | `192.168.3.12` |
| `redis_01.redis_ip` | `127.0.0.1` |
| `371bfca....` (Consul UUID host) | `127.0.0.1` |
| `44700995e....` (Kafka broker 1) | `127.0.0.1:9092` |
| `0837a70b5....` (Kafka broker 2) | (移除，仅保留一个 broker) |
| `10.128.161.95` (内网 IP 地址) | `127.0.0.1` |
| `10.0.22.207` (内网 ZK) | `127.0.0.1:2181` |
| `10.128.123.108` (内网 DB) | `192.168.3.12` |
| `10.0.22.102` (内网 CRK IP) | `127.0.0.1` |
| `3306` (生产 DB 端口) | `3307` |

---

## 5. 脚本设计

### 5.1 文件结构

```
源码/scripts/test-env/
├── docker-compose.infra.yml      # 合并 Consul+Redis+Kafka+Nginx
├── config/
│   ├── env.sh                     # 统一环境变量
│   ├── consul/consul-config.json  # Consul 初始化配置
│   └── service-templates/         # 配置文件模板 (.properties 模板)
├── setup.sh                       # 主入口: 一键搭建
├── start-all.sh                   # 启动全部服务
├── stop-all.sh                    # 停止全部服务
├── health-check.sh                # 探活检查
├── prepare-db.sh                  # 数据库恢复
├── prepare-services.sh            # 解压 + 配置注入
├── build-elevator-v2.sh           # 编译 V2 电梯应用
└── verify-functional.sh           # 功能验证
```

### 5.2 启动依赖拓扑

```
I1 Consul ──┐
I2 Redis ───┤  (Docker 并行启动)
I3 Kafka ───┤
I4 Nginx ───┘

A1 ninca-common ─────────────────────────┐
A2 component-org ←── common ─────────────┤
A3 system-api ←── manager ───────────────┤
A4 cwos-manager (Docker) ────────────────┤
A5 cwos-portal ←── org + manager ────────┤
A6 snap-app ←── portal + common ─────────┤
A7 vehicle-app ←── portal + common ──────┤
A8 person-file ←── portal ───────────────┤
A9 monitor-app (独立) ───────────────────┤
A10 CRK-std ←── portal + org + elevator ─┤
A11 alarm-app ←── portal + org + Kafka ──┤
A12 elevator-V2 ←── CRK + portal + org ──┤
A13 elevator-V1 (对拍对照) ───────────────┘
```

### 5.3 主入口执行流程

```
setup.sh:
  Phase 1: 环境检查 (< 10s)
    ├── JDK 8 检查
    ├── Maven 检查
    ├── Docker 检查
    ├── MySQL 连通性检查 (192.168.3.12:3307)
    └── 端口冲突检查

  Phase 2: 数据库准备 (~5min)
    ├── 创建所有数据库 (如不存在)
    ├── 解压并导入 11 个 SQL 备份
    └── 执行 V2 DDL (tenant_visitor_floor_policy.sql)

  Phase 3: Docker 启动 (~30s)
    ├── docker compose up infra
    ├── 等待 Consul Ready
    ├── 等待 Kafka Ready
    └── 启动 Nginx

  Phase 4: 服务准备 (~5-10min)
    ├── 解压 5 个 tar.gz
    ├── 从模板生成各服务配置文件
    ├── 编译 V2 电梯应用
    └── 同步 JAR 到 deploy/

  Phase 5: 服务启动 (~2min)
    ├── 按拓扑序依次启动 13 个 Java 服务
    ├── 每个服务启动后探活确认
    └── 失败自动重试 (max 3 次)

  Phase 6: 验证 (~2min)
    ├── 全端口探活
    ├── Consul 注册检查
    ├── V1/V2 API 对拍 (pytest)
    └── 输出验证报告

  总耗时: ~15-20 分钟
```

---

## 6. 验证矩阵

| ID | 验证项 | 命令/方法 | 通过标准 |
|----|--------|----------|---------|
| H1 | 所有端口可达 | `nc -z 127.0.0.1 <port>` x 15 | 全部 open |
| H2 | 所有 HTTP 健康检查 | `curl /actuator/health` x 8 | 全部 200 + UP |
| H3 | Consul 服务注册 | `curl :8500/v1/agent/services` | 10+ 服务已注册 |
| F1 | V1/V2 API 对拍 | `pytest tools/elevator_api_parity/tests/` | 全部通过 |
| F2 | V2.0.7 UC-01 基线 | 不传 floorIds, 无策略 | floorList 全集 |
| F3 | V2.0.7 UC-01 固定楼层 | 不传 floorIds, 有策略 | floorList ∩ allow |
| F4 | V2.0.7 无交集 | allow 与 floorList 无交集 | 错误码 76260532 |
| F5 | V2.0.7 被访人无楼层 | personId 无楼层 | 错误码 76260531 |
| F6 | V2.0.7 UC-02 | 显式传 floorIds | 不读策略表 |
| F7 | CRK 联动 | curl CRK → 电梯回调 | CRK 日志有 Feign 记录 |
| F8 | 报警 Kafka 消费 | 提交事件 → alarm 日志 | Kafka 消息到达 |
| F9 | Nginx 前端代理 | `curl :8090` | cwos-portal 首页 |
| I1 | MySQL 连通 | `mysql -h 192.168.3.12 -P3307 -e 'SELECT 1'` | 1 |

---

## 7. 已知风险与缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| `星中心/*.tar.gz` 内 JAR 版本与 DB 备份不匹配 | 启动失败 | 从同一时间点导出 (2026-04-23) 的 DB 备份对齐 |
| Docker Kafka 首次启动慢 | Phase 3 超时 | 脚本增加 60s 等待 + 重试逻辑 |
| V2 Maven 编译需 Nexus 私服 | 编译失败 | 已有 `build_nexus_only.sh` 降级方案 |
| cwos-portal 无独立 JAR | 无法启动 | 从 DB 备份 `cwos_portal` 库确认部署方式 |
| 端口冲突 (已有进程占用) | 启动失败 | Phase 1 预先检查, 用 `lsof` 检测并提示 |
| ES (Elasticsearch) 依赖 | alarm 启动可能失败 | alarm `application.properties` 配置 ES, 需 Docker 添加 |

---

## 8. 未解决问题

1. **cwos-portal 部署方式**: 星中心中没有 cwos-portal 的 JAR 或 tarball, 仅 DB 备份中有 `cwos_portal` 数据。需确认其部署形态 (fat JAR? war? Docker?)。
2. **cwos-system-api 启动入口**: `cwos_system_api_01-cwos_system_api/` 已解压, 需确认 JAR 入口和端口。
3. **Elasticsearch**: alarm 依赖 ES (`elasticsearch.ip`), 是否需要在 Docker Compose 中添加 ES 容器？
4. **Dubbo/ZK**: V1 电梯 bootstrap 配置有 Dubbo + ZK, V2 是否需要？可以在 Docker Compose 中添加 ZK。

---

## 9. 产出物

- `源码/scripts/test-env/docker-compose.infra.yml` — 基础组件 Docker Compose
- `源码/scripts/test-env/setup.sh` — 一键搭建脚本
- `源码/scripts/test-env/config/env.sh` — 统一环境变量
- `源码/scripts/test-env/config/service-templates/` — 14 个配置模板
- `源码/scripts/test-env/start-all.sh` / `stop-all.sh` — 启停脚本
- `源码/scripts/test-env/verify-functional.sh` — 功能验证脚本