common_agent/docs/superpowers/plans/2026-05-24-enum-value-transport-and-sys-enum-sync.md

Enum Value Transport And SysEnum Sync Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Unify long-lived structured text fields to use enum values for transport, and rebuild sys_enum from enum definitions through a delete-then-insert synchronization flow.

Architecture: Add a shared enum definition contract in the backend, let existing enums implement it, and refactor enum initialization to rebuild each catalog + type group from code. Update the RAG parse request and frontend page to submit enum values instead of enum names.

Tech Stack: Java 21, Spring Boot, MyBatis-Plus, JUnit 5, Vue 3, TypeScript, Vitest

---

Task 1: Lock Request Protocol With Failing Tests

Files:

• Modify: src/test/java/com/bruce/rag/RagDocumentParseServiceImplTests.java

• Modify: frontend/src/pages/rag/__tests__/RagDocumentsPage.spec.ts

• Step 1: Write the failing test

• Step 2: Run targeted backend and frontend tests to verify they fail because the old string protocol is still in place

• Step 3: Update assertions to require integer enum values for chunkStrategy

• Step 4: Re-run targeted tests and keep them red until implementation exists

Task 2: Implement Backend Enum Definition Contract

Files:

• Create: src/main/java/com/bruce/common/enums/PersistableSysEnumDefinition.java

• Modify: src/main/java/com/bruce/common/enums/EnableStatusEnum.java

• Modify: src/main/java/com/bruce/common/enums/CommonStatusEnum.java

• Modify: src/main/java/com/bruce/rag/enums/RagParseStatusEnum.java

• Modify: src/main/java/com/bruce/rag/enums/RagIndexStatusEnum.java

• Modify: src/main/java/com/bruce/rag/enums/RagChunkStrategyEnum.java

• Modify: src/test/java/com/bruce/common/enumconfig/EnumDefinitionTests.java

• Step 1: Write or extend failing tests for enum metadata access and stable value lookup

• Step 2: Run backend enum tests to verify failure

• Step 3: Implement the shared enum definition contract and make existing enums implement it

• Step 4: Add fromValue(Integer) support where needed and rerun tests to green

Task 3: Rebuild SysEnum Initialization Flow

Files:

• Modify: src/test/java/com/bruce/common/enumconfig/SysEnumDataInitTests.java

• Create or Modify: src/test/java/com/bruce/common/enumconfig/... supporting tests as needed

• Modify: src/main/java/com/bruce/common/service/ISysEnumService.java

• Modify: src/main/java/com/bruce/common/service/impl/SysEnumServiceImpl.java

• Step 1: Write failing tests for duplicate catalog + type, duplicate value detection, and delete-then-insert rebuild behavior

• Step 2: Run targeted backend tests to verify failure

• Step 3: Add service support for removing and rebuilding a whole enum group

• Step 4: Refactor enum init test to register enum groups, validate uniqueness, delete old rows, and batch insert the new rows

• Step 5: Re-run targeted backend tests to green

Task 4: Switch RAG Parse Request To Integer Enum Values

Files:

• Modify: src/main/java/com/bruce/rag/dto/request/RagDocumentParseRequest.java

• Modify: src/main/java/com/bruce/rag/parse/RagChunkCommand.java

• Modify: src/main/java/com/bruce/rag/service/impl/RagDocumentParseServiceImpl.java

• Modify: src/test/java/com/bruce/rag/RagDocumentParseServiceImplTests.java

• Step 1: Confirm failing backend parse tests expect integer values

• Step 2: Change DTOs and validation logic to use enum values

• Step 3: Re-run targeted backend parse tests to green

Task 5: Update Frontend To Use Enum Values

Files:

• Modify: frontend/src/api/ragDocuments.ts

• Modify: frontend/src/pages/rag/RagDocumentsPage.vue

• Modify: frontend/src/pages/rag/__tests__/RagDocumentsPage.spec.ts

• Step 1: Confirm frontend parse request test is red for numeric enum values

• Step 2: Change API typing, page defaults, options, and comparisons to numeric enum values

• Step 3: Re-run targeted frontend tests to green

Task 6: Record Project Convention

Files:

• Modify: AGENT.md

• Modify: docs/ARCHITECTURE.md

• Step 1: Add the long-term convention that stable structured text uses enum values for transport

• Step 2: Add the rule that enum changes must be synchronized into sys_enum through the initialization test

• Step 3: Do a final focused verification run