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.