From 4f4627fdb33d5d48716f1c812fa16932361ce371 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8F=8D=E7=BC=96=E8=AF=91=E5=B7=A5=E4=BD=9C=E5=8C=BA?= Date: Sun, 3 May 2026 20:11:28 +0800 Subject: [PATCH] docs: update AGENTS.md with architecture and discovery details Former-commit-id: 8c461e527ca6a9297a8ccf8fd6ea2546a6de1ec7 --- AGENTS.md | 180 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..126c2155 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,180 @@ +# AGENTS.md — 星河湾星中星 (starRiverProperty) + +**Last updated:** 2026-05-03 +**Branch:** release/cw-elevator-v1-lib-min-risk + +## OVERVIEW + +CloudWalk (云从科技) 电梯/门禁/报警/人脸识别系统。Maven 多模块单体仓库 + 独立部署运行包。 +- **源码/**: 可编辑的 Maven 源码树 (主要迭代区) +- **星中心/**: 运行时部署包 + 配置文件 (生产/预发镜像) +- **部署包/**: 13 个组件的完整 tar.gz 压缩包 (7.2 GB) +- **data_backup/**: 各服务数据库备份 (SQL gz) + +当前重心: **电梯应用 v2 (cw-elevator-application) 后端服务** 的功能测试环境搭建与 V1/V2 对比测试。 + +--- + +## 1. 顶层目录结构 + +``` +星河湾星中星/ +├── 源码/ # 可编辑的 Maven 源码+文档 (本文所在) +│ ├── docs/ # 文档中心 (架构/业务/构建/风格/运维/测试) +│ ├── scripts/test-env/ # 测试环境搭建脚本 (setup.sh, start-all.sh, etc.) +│ ├── AGENTS.md # ← 本文件 +│ ├── maven-cw-elevator-application/ # 电梯应用 (主力迭代) +│ │ └── deploy/v2-maven/ # V2 部署目录 (JAR + config) +│ │ ├── cw-elevator-application-2.0.9.jar # V2 fat JAR +│ │ └── application.properties / bootstrap.properties +│ └── maven-intelligent-cwoscomponent/ # 智能组件 (Feign 客户端定义) +│ └── intelligent-cwoscomponent-rest/ # RestPersonServiceImpl + PersonFeignClient +│ +├── 星中心/ # 运行时部署包 (运行目录) +│ ├── cw-elevator-application-V1.0.0.20211103/ # V1 电梯应用部署 +│ ├── ninca_crk_std_01-ninca_crk_std_backend/ # CRK 人脸识别 GPU 后端 +│ └── cwos_manager_01-cwos_manager/ # CWOS Manager (Docker) +│ +└── data_backup/ # 数据库 SQL 备份 (11 个库) +``` + +--- + +## 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` + +--- + +## 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 | `cw-elevator-application-V1.0.0.20211103/` | 基线运行包 (参考对照) | +| V2.0.0-SNAPSHOT | `maven-cw-elevator-application/` | 源码重构 + Maven 化 | +| V2.0.9 | 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 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=deploy/v2-maven/ + +# API 对拍测试 +cd maven-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` 控制)