starRiverProperty/.sisyphus/plans/2026-05-01-ribbon-dubbo-restore.md

# Ribbon Dubbo 发现恢复 — 实施计划

## TL;DR
> **Summary**: 移除 ElevatorApplication 中两个多余的 `@RibbonClient` 注解，恢复 `ninca-common-component-organization` 和 `ninca-common` 的 Dubbo/ZooKeeper 动态发现，修复生产 `Load balancer does not have available server` 错误。
> **Deliverables**: 1 个修改文件 + 2 个废弃文件，无配置变更，无 DDL。
> **Effort**: Quick
> **Parallel**: 可并行（仅 Wave 1）
> **Critical Path**: Task 1 → Task 2 → Task 3

## Context
### Original Request
生产环境 `PersonRecordEventHandler` 调用 `ninca-common-component-organization` (Feign/Ribbon) 时报 `Load balancer does not have available server`。

### Root Cause
V2 代码在 `ElevatorApplication.java` 中为 `ninca-common-component-organization` 和 `ninca-common` 额外添加了 `@RibbonClient(configuration=ConfigurationBasedServerList)` 注解，但生产 `application.properties` 没有提供 `listOfServers`。V1 对这两个服务无显式 Ribbon 配置，依赖默认 Ribbon + Dubbo/ZooKeeper 动态发现。

### Design Spec
`.sisyphus/drafts/2026-05-01-ribbon-dubbo-restore-design.md`

## Work Objectives
### Core Objective
恢复 V1 的 Dubbo 发现路径：只有 `ninca-crk-std` 使用 `ConfigurationBasedServerList`，其余两个恢复默认 Ribbon。

### Deliverables
- `ElevatorApplication.java` — 删除 2 行 `@RibbonClient`
- `OrgServiceRibbonConfiguration.java` — 删除或废弃
- `CommonServiceRibbonConfiguration.java` — 删除或废弃

### Definition of Done
```bash
cd maven-cw-elevator-application && mvn clean install -DskipTests
cd maven-cw-elevator-application && mvn formatter:validate -Dformatter-maven-plugin.version=2.16.0
```
BUILD SUCCESS + 无格式化违规 = 完成。

### Must Have
- [x] `@RibbonClients` 注解只保留 `ninca-crk-std` 一条
- [x] `OrgServiceRibbonConfiguration` 和 `CommonServiceRibbonConfiguration` 不再被引用
- [x] 编译通过
- [x] 格式校验通过

### Must NOT Have
- 不动任何配置文件（`application.properties`、`bootstrap.properties` 保持不变）
- 不动 `NincaCrkStdRibbonConfiguration`（保留）
- 不动 Feign 客户端代码
- 不新增任何 Ribbon 属性

## Verification Strategy
> ZERO HUMAN INTERVENTION - all verification is agent-executed.
- Test decision: none (no test infra for this module) + QA via build verification
- QA policy: Every task has agent-executed validation via build commands

## Execution Strategy
### Parallel Execution Waves
Wave 1: Task 1 (edit ElevatorApplication) + Task 2 (deprecate configs) — 独立文件，可并行

### Dependency Matrix
| Task | Blocks | Blocked By |
|------|--------|------------|
| 1. ElevatorApplication edit | — | — |
| 2. Deprecate config classes | — | — |
| 3. Build + format + commit | — | 1, 2 |

## TODOs

- [x] 1. 修改 ElevatorApplication.java — 移除多余的 @RibbonClient

  **What to do**: 删除 `@RibbonClients` 中 `ninca-common-component-organization` 和 `ninca-common` 对应的两行注解。同时删除 `OrgServiceRibbonConfiguration` 和 `CommonServiceRibbonConfiguration` 的 import 语句。

  **Must NOT do**: 不要删除或修改 `ninca-crk-std` 的 `@RibbonClient` 行。

  **修改前** (`ElevatorApplication.java:17-21`):
  ```java
  @RibbonClients({
      @org.springframework.cloud.netflix.ribbon.RibbonClient(name = "${feign.ninca-crk-std.name:ninca-crk-std}", configuration = NincaCrkStdRibbonConfiguration.class),
      @org.springframework.cloud.netflix.ribbon.RibbonClient(name = "${feign.component-organization.name:ninca-common-component-organization}", configuration = OrgServiceRibbonConfiguration.class),
      @org.springframework.cloud.netflix.ribbon.RibbonClient(name = "${feign.ninca-common.name:ninca-common}", configuration = CommonServiceRibbonConfiguration.class)
  })
  ```

  **修改后**:
  ```java
  @RibbonClients({
      @org.springframework.cloud.netflix.ribbon.RibbonClient(name = "${feign.ninca-crk-std.name:ninca-crk-std}", configuration = NincaCrkStdRibbonConfiguration.class)
  })
  ```

  **Import 清理**: 删除 import 行:
  ```java
  import cn.cloudwalk.ribbon.OrgServiceRibbonConfiguration;
  import cn.cloudwalk.ribbon.CommonServiceRibbonConfiguration;
  ```

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: single file, 4-line deletion only
  - Skills: `[]`
  - Omitted: `[]`

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: none | Blocked By: none

  **References**:
  - Pattern: `src/main/java/cn/cloudwalk/elevator/ElevatorApplication.java:17-21` — current @RibbonClients block to modify
  - V1 reference: Production `星中心/.../bootstrap.properties` line 16 (`dubbo.registry`) — confirms Dubbo-based discovery

  **Acceptance Criteria**:
  - [ ] `grep -c "OrgServiceRibbonConfiguration" ElevatorApplication.java` returns 0
  - [ ] `grep -c "CommonServiceRibbonConfiguration" ElevatorApplication.java` returns 0
  - [ ] `grep -c "NincaCrkStdRibbonConfiguration" ElevatorApplication.java` returns 1
  - [ ] `@RibbonClients` 块只包含 1 条 `@RibbonClient` 注解

  **QA Scenarios**:
  ```
  Scenario: @RibbonClients 只保留 ninca-crk-std
    Tool: Bash
    Steps:
      1. grep "RibbonClient" ElevatorApplication.java | grep -c "configuration"
    Expected: 1 (only ninca-crk-std has configuration)
    Evidence: .sisyphus/evidence/task-1-ribbon-clients-count.txt

  Scenario: 无残留 import
    Tool: Bash
    Steps:
      1. grep "OrgServiceRibbonConfiguration\|CommonServiceRibbonConfiguration" ElevatorApplication.java
    Expected: no output (zero matches)
    Evidence: .sisyphus/evidence/task-1-no-orphan-imports.txt
  ```

  **Commit**: YES | Message: `fix: remove redundant @RibbonClient for ninca-common and ninca-common-component-organization, restore Dubbo discovery` | Files: `ElevatorApplication.java`

- [x] 2. 废弃 OrgServiceRibbonConfiguration 和 CommonServiceRibbonConfiguration

  **What to do**: 删除这两个 Java 文件，或者在文件上标记 `@Deprecated` + 注释说明理由。推荐直接删除（不再被引用）。

  **Must NOT do**: 不要删除 `NincaCrkStdRibbonConfiguration.java`。

  **Files to delete**:
  - `maven-cw-elevator-application/cw-elevator-application-starter/src/main/java/cn/cloudwalk/ribbon/OrgServiceRibbonConfiguration.java`
  - `maven-cw-elevator-application/cw-elevator-application-starter/src/main/java/cn/cloudwalk/ribbon/CommonServiceRibbonConfiguration.java`

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: 2 file deletions, no logic change
  - Skills: `[]`

  **Parallelization**: Can Parallel: YES | Wave 1 | Blocks: none | Blocked By: none (different files from Task 1)

  **References**:
  - Pattern: `src/main/java/cn/cloudwalk/ribbon/OrgServiceRibbonConfiguration.java` — file to delete
  - Pattern: `src/main/java/cn/cloudwalk/ribbon/CommonServiceRibbonConfiguration.java` — file to delete

  **Acceptance Criteria**:
  - [ ] `ls OrgServiceRibbonConfiguration.java` returns "No such file"
  - [ ] `ls CommonServiceRibbonConfiguration.java` returns "No such file"
  - [ ] `ls NincaCrkStdRibbonConfiguration.java` exists (untouched)

  **QA Scenarios**:
  ```
  Scenario: 两个多余 RibbonConfig 类已删除
    Tool: Bash
    Steps:
      1. find cw-elevator-application-starter -name "OrgServiceRibbonConfiguration.java"
      2. find cw-elevator-application-starter -name "CommonServiceRibbonConfiguration.java"
    Expected: both return no output (files don't exist)
    Evidence: .sisyphus/evidence/task-2-configs-deleted.txt

  Scenario: NincaCrkStdRibbonConfiguration 未受影响
    Tool: Bash
    Steps:
      1. find cw-elevator-application-starter -name "NincaCrkStdRibbonConfiguration.java"
    Expected: returns file path (file exists)
    Evidence: .sisyphus/evidence/task-2-ninca-crk-std-intact.txt
  ```

  **Commit**: YES | Message: `chore: remove unused OrgServiceRibbonConfiguration and CommonServiceRibbonConfiguration` | Files: `OrgServiceRibbonConfiguration.java`, `CommonServiceRibbonConfiguration.java`

- [x] 3. 构建验证 + 格式校验 + 提交

  **What to do**: 全量编译 + formatter 校验。如果通过，统一提交所有变更。

  **Must NOT do**: 不要运行测试（`-DskipTests`），不要修改 pom.xml。

  **Recommended Agent Profile**:
  - Category: `quick` — Reason: build + format + commit only
  - Skills: `[]`

  **Parallelization**: Can Parallel: NO | Wave 2 | Blocks: none | Blocked By: 1, 2

  **References**:
  - Build command: `cd maven-cw-elevator-application && mvn clean install -DskipTests`
  - Format validation: `cd maven-cw-elevator-application && mvn formatter:validate -Dformatter-maven-plugin.version=2.16.0`

  **Acceptance Criteria**:
  - [ ] `mvn clean install -DskipTests` → BUILD SUCCESS
  - [ ] `mvn formatter:validate` → 无违规
  - [ ] `git status` 显示 3 个文件变更（1 modified + 2 deleted），无 untracked

  **QA Scenarios**:
  ```
  Scenario: BUILD SUCCESS
    Tool: Bash
    Steps:
      1. cd maven-cw-elevator-application && mvn clean install -DskipTests 2>&1 | tail -5
    Expected: output contains "BUILD SUCCESS"
    Evidence: .sisyphus/evidence/task-3-build-output.txt

  Scenario: formatter 校验通过
    Tool: Bash
    Steps:
      1. cd maven-cw-elevator-application && mvn formatter:validate -Dformatter-maven-plugin.version=2.16.0 2>&1 | tail -10
    Expected: no FAILED or violation messages
    Evidence: .sisyphus/evidence/task-3-formatter-output.txt
  ```

  **Commit**: YES (合并 Task 1+2 的所有变更) | Message: `fix: restore Dubbo discovery for ninca-common and ninca-common-component-organization`

## Final Verification Wave (MANDATORY — after ALL implementation tasks)
> 4 review agents run in PARALLEL. ALL must APPROVE.
- [x] F1. Plan Compliance Audit — oracle
- [x] F2. Code Quality Review — unspecified-high
- [x] F3. Real Manual QA — unspecified-high
- [x] F4. Scope Fidelity Check — deep

## Commit Strategy
- Task 1 独立提交：`fix: remove redundant @RibbonClient annotations`
- Task 2 独立提交：`chore: remove unused Ribbon configuration classes`
- Task 3 提交：确认编译和格式通过后，git status 干净

## Success Criteria
1. `mvn clean install -DskipTests` BUILD SUCCESS
2. `mvn formatter:validate` 无违规
3. `ninca-crk-std` 的 `@RibbonClient` 保留，另外两个已删除
4. 生产部署后不再出现 `Load balancer does not have available server for client: ninca-common-component-organization`