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.
203 lines
8.5 KiB
Markdown
203 lines
8.5 KiB
Markdown
# AGENTS.md — 星河湾星中星 (starRiverProperty)
|
|
|
|
**Last updated:** 2026-05-07 (目录重组后)
|
|
**Branch:** release/cw-elevator-v1-lib-min-risk
|
|
|
|
## OVERVIEW
|
|
|
|
CloudWalk (云从科技) 电梯/门禁/报警/人脸识别系统。Maven 多模块单体仓库 + 独立部署运行包。
|
|
- **源码/ (submodule)**: 可编辑的 Maven 源码树 (主要迭代区)，含 backend/ (13 个 Maven 项目) + frontend/ (前端源码)
|
|
- **runtime/**: 运行时部署包 + 配置文件 (生产/预发镜像)
|
|
- **packages/**: 13 个组件的完整 tar.gz 压缩包
|
|
- **data-backups/**: 各服务数据库备份 (SQL gz)
|
|
- **archive/**: 历史/参考/遗留内容 (反编译源码、前端备份等)
|
|
- **nginx/**: Nginx 配置
|
|
|
|
当前重心: **电梯应用 v2 (cw-elevator-application) 后端服务** 的功能测试环境搭建与 V1/V2 对比测试。
|
|
|
|
---
|
|
|
|
## 1. 顶层目录结构
|
|
|
|
```
|
|
星河湾星中星/
|
|
├── 源码/ # 可编辑的源码 (git submodule)
|
|
│ ├── backend/ # Maven 后端项目 (13 个)
|
|
│ │ ├── cw-elevator-application/ # 电梯应用 (主力迭代)
|
|
│ │ │ └── deploy/v2-maven/ # V2 部署目录 (JAR + config)
|
|
│ │ │ ├── cw-elevator-application-2.0.9.jar
|
|
│ │ │ └── application.properties / bootstrap.properties
|
|
│ │ ├── intelligent-cwoscomponent/ # 智能组件 (Feign 客户端定义)
|
|
│ │ │ └── intelligent-cwoscomponent-rest/
|
|
│ │ └── ... (其他 11 个 Maven 项目)
|
|
│ ├── frontend/ # 前端源码 (projects/, decompiled/, scripts/)
|
|
│ ├── scripts/ # 构建/工具脚本 (build/, tools/, test-env/)
|
|
│ └── docs/ # 文档中心 (本文所在)
|
|
│
|
|
├── runtime/ # 运行时部署包 (运行目录)
|
|
│ ├── elevator-v1/ # V1 电梯应用部署
|
|
│ ├── ninca-crk-std/ # CRK 人脸识别 GPU 后端
|
|
│ ├── cwos-manager/ # CWOS Manager (Docker)
|
|
│ ├── cwos-system-api/ # CWOS 系统 API
|
|
│ ├── ninca-qk-alarm/ # 报警服务
|
|
│ ├── ninca-crk-std-lib/ # CRK 标准库
|
|
│ └── frontend/ # 前端运行时
|
|
│
|
|
├── packages/ # 部署压缩包 (tar.gz)
|
|
│ ├── releases/
|
|
│ ├── ninca-common-component-organization/
|
|
│ └── *.tar.gz (13 个组件)
|
|
│
|
|
├── data-backups/ # 数据库 SQL 备份 (kebab-case)
|
|
├── archive/ # 历史/参考/遗留内容
|
|
│ ├── decompiled-sources/ # 反编译 JAR 源码 (22 个 .src.zip)
|
|
│ ├── frontend-backups/ # 前端 .bak 备份目录
|
|
│ └── miscellaneous/ # 其他 (cn, media, source-self-ref)
|
|
├── artifacts/ # 构建产物/证据
|
|
├── nginx/ # Nginx 配置
|
|
└── logs/ # 运行日志
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 服务发现架构
|
|
|
|
```
|
|
电梯应用 (V1 / V2) 服务发现设计:
|
|
|
|
bootstrap.properties:
|
|
spring.cloud.consul.discovery.enabled=false # Consul: 仅注册自身
|
|
dubbo.registry.address=zookeeper://... # Dubbo provider 注册
|
|
|
|
运行时服务发现:
|
|
Feign Client → Ribbon → ServerList → ConsulServerList (via consul-api) → 查询 Consul 获取上游服务地址
|
|
|
|
V1 和 V2 使用完全相同的架构 (spring-cloud-consul-discovery 1.3.5)
|
|
PersonService → RestPersonServiceImpl → PersonFeignClient → HTTP 调用
|
|
|
|
三个上游 Feign 客户端:
|
|
ninca-common-component-organization (组织组件)
|
|
ninca-crk-std (人脸识别 GPU)
|
|
ninca-common (公共组件)
|
|
```
|
|
|
|
### 2.1 关键依赖关系
|
|
|
|
| 组件 | 发现方式 | 运行时依赖 |
|
|
|------|----------|-----------|
|
|
| Consul | 注册自身, 不作为发现客户端 | `spring-cloud-starter-consul` |
|
|
| PersonService | ConsulServerList (Ribbon) | `spring-cloud-consul-discovery` |
|
|
| ninca-common-component-org | ConsulServerList 查询 | Consul 需注册该服务 |
|
|
|
|
### 2.2 架构设计文档
|
|
|
|
`docs/superpowers/specs/2026-05-01-service-discovery-architecture-design.md`
|
|
- 预期使用 Dubbo/ZooKeeper 做服务发现
|
|
- V2 需添加 `spring-cloud-starter-zookeeper-discovery` 实现 (2026-05-03 已添加至 POM)
|
|
- Edgware.SR3 与 ZK 1.1.0 存在 `Registration` bean 冲突, 需排除 `ZookeeperAutoServiceRegistrationAutoConfiguration`
|
|
- **注意:** 路径已更新: `maven-*` → `backend/*`, `星中心` → `runtime`, `部署包` → `packages`, `data_backup` → `data-backups`
|
|
|
|
---
|
|
|
|
## 3. 组件依赖关系
|
|
|
|
### 3.1 服务拓扑
|
|
|
|
```
|
|
Nginx (反向代理/静态文件)
|
|
├── /api/* → elevator-app:18081
|
|
├── /cwos-portal/* → cwos-portal
|
|
└── frontend SPAs
|
|
|
|
elevator-app (cw-elevator-application) ← 主力迭代组件
|
|
├── MySQL: cw-elevator-application DB
|
|
├── Redis: 缓存/序列号
|
|
├── Kafka: 事件总线
|
|
├── Consul: 注册 (discovery.enabled=false)
|
|
├── Feign → ninca-crk-std (CRK 人脸识别)
|
|
├── Feign → ninca-common-component-organization (组织组件)
|
|
└── Dubbo: provider (向 CRK 等导出服务)
|
|
```
|
|
|
|
### 3.2 V2 版本演进
|
|
|
|
| 版本 | 源码目录 | 核心变更 |
|
|
|------|---------|---------|
|
|
| V1.0.0 | `runtime/elevator-v1/` | 基线运行包 (参考对照) |
|
|
| V2.0.0-SNAPSHOT | `backend/cw-elevator-application/` | 源码重构 + Maven 化 |
|
|
| V2.0.9 | backend/cw-elevator-application/releases/ + deploy/ | 最新构建, 含 ZK 发现依赖 |
|
|
|
|
### 3.3 测试环境状态 (2026-05-03)
|
|
|
|
```
|
|
可用:
|
|
Docker: Consul(:9517) Redis(:6380) Nginx(:8090)
|
|
MySQL: 192.168.3.12:3307 (root/123456)
|
|
ZooKeeper: ybs-zookeeper:2181
|
|
Running: elevator V2(:18081) V1(:18080) component-org stub(:33011)
|
|
|
|
阻塞:
|
|
Feign + ConsulServerList 在 Docker Consul(1.22) + Consul-api(1.3.0) 间存在版本兼容问题
|
|
改进: 添加 ZK discovery 依赖, 移至 ZK 发现 (POM 已更新, 待排除 Registration 冲突后验证)
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 测试脚本
|
|
|
|
```
|
|
scripts/test-env/
|
|
├── setup.sh # 一键搭建 (6 Phase)
|
|
├── docker-compose.infra.yml # Docker 基础组件
|
|
├── stub-person-service.py # component-org 的 Python 模拟桩
|
|
├── config/env.sh # 统一环境变量
|
|
├── start-all.sh / stop-all.sh # 服务启停
|
|
├── health-check.sh # 探活检查
|
|
├── verify-functional.sh # 功能验证
|
|
├── prepare-db.sh # 数据库恢复 (幂等)
|
|
└── prepare-services.sh # 解压部署包
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 关键命令
|
|
|
|
```bash
|
|
# 一键搭建
|
|
bash scripts/test-env/setup.sh
|
|
|
|
# 启动 V2 电梯 (Feign URL 硬编码模式)
|
|
/usr/lib/jvm/java-8-openjdk-amd64/bin/java -jar \
|
|
backend/cw-elevator-application/deploy/v2-maven/cw-elevator-application-2.0.9.jar \
|
|
--server.port=18081 --spring.redis.port=6380 --spring.redis.password='1qaz!QAZ' \
|
|
--spring.cloud.consul.host=127.0.0.1 --spring.cloud.consul.port=9517 \
|
|
--spring.config.location=backend/cw-elevator-application/deploy/v2-maven/
|
|
|
|
# API 对拍测试
|
|
cd backend/cw-elevator-application/tools/elevator_api_parity
|
|
ELEVATOR_BASE_OLD=http://127.0.0.1:18080 ELEVATOR_BASE_NEW=http://127.0.0.1:18081 \
|
|
python3 -m pytest tests/ -v -p no:allure_pytest
|
|
|
|
# V1 vs V2 策略差异测试
|
|
curl -X POST http://127.0.0.1:18081/elevator/person/add/visitor \
|
|
-d '{"personId":"1072908835884208128","businessId":"2524639890ba4f2cba9ba1a4eeaa4015","visitorName":"test"}'
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Conventions & Anti-Patterns
|
|
|
|
### Conventions
|
|
- **JDK 8**: 所有 Maven 工程 + 运行环境强制 JDK 8
|
|
- **Spring Boot 1.5.17 + Spring Cloud Edgware.SR3**: V1/V2 一致
|
|
- **服务发现**: ConsulServerList (V1 运行时) + ZookeeperDiscoveryClient (POM 已加)
|
|
- **PersonService**: Feign HTTP 调用 component-org, 非 Dubbo
|
|
- **Dubbo 使用**: 仅用于 elevator 自身作为 PROVIDER 导出服务给 CRK
|
|
|
|
### Anti-Patterns
|
|
- **不要** `zip -g` 以压缩方式添加嵌套 JAR 到 fat JAR (必须 `zip -0`)
|
|
- **不要**混用 `openfeign.FeignClient` 与 `netflix.feign.FeignClient` — V2 运行时用 `org.springframework.cloud.netflix.feign.FeignClient`
|
|
- **不要**在测试 Consul (Docker) 上注册带 HTTP 健康检查的服务 — Docker 内 Consul 连不回主机 127.0.0.1
|
|
- **不要**同时启用 Consul 和 ZK 的 `ServiceRegistry` — 需排除 `ZookeeperAutoServiceRegistrationAutoConfiguration`
|
|
- `discovery.enabled=false` 只禁用 DiscoveryClient, 不影响 ConsulServerList (受 `spring.cloud.consul.ribbon.enabled` 控制)
|