# 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**