# Controller Internal Convention Removal Implementation Plan > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. **Goal:** Remove the project-wide `controller/internal` and `*InternalController` convention for non-openapi APIs while keeping all request paths, authentication behavior, and Swagger exposure unchanged. **Architecture:** Rename internal API controllers to neutral `*Controller` names and place them under `modules/*/controller`, but leave all `@RequestMapping` values and `WebMvcConfig` interceptor rules untouched. Update tests and README so the repository no longer encodes the old naming convention as a rule. **Tech Stack:** Spring Boot MVC, springdoc-openapi, JUnit 5, MockMvc --- ### Task 1: Lock down URL and documentation invariants with tests **Files:** - Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/file/FileInternalControllerTest.java` - Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/executor/ConfigurableInitStepExecutorTest.java` - Test: `/Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/file/FileInternalControllerTest.java` - Test: `/Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/init/executor/ConfigurableInitStepExecutorTest.java` **Step 1: Write the failing tests** Adjust or add tests that assert: - file upload/query endpoints remain `/api/v1/files/**` - Swagger/OpenAPI docs still mention the same URLs - README no longer contains the hard rule `Internal API controllers only in */controller/internal` Do not rename production classes yet. **Step 2: Run tests to verify they fail** Run: `mvn -q -Dtest=FileInternalControllerTest,ConfigurableInitStepExecutorTest#shouldDocumentStandardInitScriptTemplateDeployment test` Expected: FAIL because tests will still reference old controller names and README still encodes the old convention. **Step 3: Keep the tests minimal** Limit assertions to: - unchanged routes - removed convention wording - continued `/home/tms/bin` deployment doc assertions already covered in existing tests **Step 4: Run tests again to confirm stable RED** Run: `mvn -q -Dtest=FileInternalControllerTest,ConfigurableInitStepExecutorTest#shouldDocumentStandardInitScriptTemplateDeployment test` Expected: FAIL for the intended naming/documentation reasons only. **Step 5: Commit** Skip commit in the current dirty workspace per user instruction. ### Task 2: Rename file and sign internal controllers first **Files:** - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/file/controller/internal/FileInternalController.java` - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/sign/controller/internal/InternalSignController.java` - Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/test/java/com/cisd/tms/modules/file/FileInternalControllerTest.java` **Step 1: Write the minimal rename** Rename and relocate: - `FileInternalController` -> `FileController` - `InternalSignController` -> `SignController` Move them into `modules/*/controller`. Keep: - package-level Spring scanning working - all request mappings unchanged **Step 2: Update tests/imports** Update MockMvc standalone setup and imports to use new class names. **Step 3: Run focused tests** Run: `mvn -q -Dtest=FileInternalControllerTest test` Expected: PASS **Step 4: Review for accidental URL changes** Check that no `@RequestMapping` strings changed. **Step 5: Commit** Skip commit in the current dirty workspace per user instruction. ### Task 3: Rename the remaining internal controllers **Files:** - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/auth/controller/AuthInternalController.java` - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/device/controller/DeviceInternalController.java` - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/device/controller/CryptoCardInternalController.java` - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/init/controller/InitInternalController.java` - Move/Modify: `/Users/waner/Work/CISD/文档/tms-framework/src/main/java/com/cisd/tms/modules/system/controller/HealthInternalController.java` - Modify: imports/usages that reference those class names **Step 1: Apply the rename set** Rename: - `AuthInternalController` -> `AuthController` - `DeviceInternalController` -> `DeviceController` - `CryptoCardInternalController` -> `CryptoCardController` - `InitInternalController` -> `InitController` - `HealthInternalController` -> `HealthController` Keep each class in `modules/*/controller`. **Step 2: Update all direct references** Use `rg` to find and fix: - imports - JavaDoc mentions - comments that name concrete classes **Step 3: Run focused compile/test checks** Run: `mvn -q -Dtest=InitServiceTest,TmsApplicationTests test` Expected: PASS **Step 4: Run compile if needed** Run: `mvn -q -DskipTests compile` Expected: PASS **Step 5: Commit** Skip commit in the current dirty workspace per user instruction. ### Task 4: Remove the repository-wide convention from README and docs **Files:** - Modify: `/Users/waner/Work/CISD/文档/tms-framework/README.md` - Modify: any design/plan/doc files that are actively used and explicitly enforce `controller/internal` **Step 1: Rewrite the structure guidance** Update README so it says: - default module layout is `controller + service + repository + entity + dto` - external APIs may additionally use `controller/openapi` Remove the hard rule: - `Internal API controllers only in */controller/internal` Replace it with a neutral rule: - `/api/**` controllers live under `controller` - `/openapi/**` controllers live under `controller/openapi` **Step 2: Update structure tree examples** Replace `controller/internal` entries in the README tree with `controller`. **Step 3: Run focused documentation regression** Run: `mvn -q -Dtest=ConfigurableInitStepExecutorTest#shouldDocumentStandardInitScriptTemplateDeployment test` Expected: PASS **Step 4: Manual diff review** Run: `git diff -- README.md` Expected: naming and structure guidance changes only, no API path changes. **Step 5: Commit** Skip commit in the current dirty workspace per user instruction. ### Task 5: Final verification **Files:** - Verify only **Step 1: Run controller-related tests** Run: `mvn -q -Dtest=FileInternalControllerTest,InitServiceTest,TmsApplicationTests test` Expected: PASS **Step 2: Run documentation regression tests** Run: `mvn -q -Dtest=ConfigurableInitStepExecutorTest#shouldDocumentStandardInitScriptTemplateDeployment test` Expected: PASS **Step 3: Run compile** Run: `mvn -q -DskipTests compile` Expected: PASS **Step 4: Review focused diff** Run: `git diff -- src/main/java/com/cisd/tms/modules README.md src/test/java/com/cisd/tms/modules/file/FileInternalControllerTest.java src/test/java/com/cisd/tms/modules/init/executor/ConfigurableInitStepExecutorTest.java docs/plans/2026-03-11-controller-internal-convention-removal-design.md docs/plans/2026-03-11-controller-internal-convention-removal-plan.md` Expected: only controller renames, import updates, and documentation rule changes. **Step 5: Commit** Skip commit in the current dirty workspace per user instruction.