starRiverProperty/AGENTS.md

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 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 控制)