cisd/docs/plans/2026-03-11-controller-internal-convention-removal-plan.md

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.