# Controller Internal Convention Removal Design

**Date:** 2026-03-11

## Goal

去掉“非 openapi 接口必须使用 `controller/internal` 包和 `*InternalController` 命名”的项目约定，将内部业务接口控制器统一收敛到中性 `controller` 包和 `*Controller` 类名，同时保持现有 URL、鉴权和 Swagger 暴露行为完全不变。

## Scope

本设计覆盖：
- `controller/internal` -> `controller` 的包路径调整
- `*InternalController` -> `*Controller` 的类名调整
- 测试引用、README、结构说明、命名约定同步更新

本设计不覆盖：
- `/api/**` 与 `/openapi/**` 路径变更
- DTO 包结构调整
- 鉴权规则变更
- `openapi` 控制器命名风格调整
- service/repository 结构重构

## Current State

当前仓库对内部接口有一套强命名约定：
- 内部业务接口通常命名为 `*InternalController`
- 其中部分模块控制器位于 `controller/internal`
- README 明确规定：`Internal API controllers only in */controller/internal`

实际代码状态并不统一：
- `auth`、`device`、`init`、`system` 使用 `controller` 包，但类名仍为 `*InternalController`
- `file` 使用 `controller/internal` 包，类名为 `FileInternalController`
- `sign` 模块同时存在 `controller/internal` 和 `controller/openapi`

这意味着“internal controller”已经被项目文档和部分代码固化，但在包结构上并未完全一致。

## Design Choice

采用：`统一改为 controller + *Controller`

不采用：`只改文档，不改代码`

原因：
- 用户目标是去掉该设定本身，而不是仅仅弱化描述
- 如果只改文档，现有类名和包名仍然持续强化旧约定

不采用：`只改类名，不改包路径`

原因：
- `controller/internal` 目录仍会继续表达旧分层含义
- 无法真正完成约定清理

不采用：`新增一套中性 Controller，保留旧类做代理`

原因：
- 没有兼容性收益
- 会引入重复 Bean 或重复请求映射风险

## Naming Rule After Change

调整后的规则：
- `/api/**` 控制器放在 `modules/*/controller`
- `/openapi/**` 控制器继续放在 `modules/*/controller/openapi`
- 内部控制器类名使用中性 `*Controller`
- 对外接口控制器命名不强制带 `Open` 前缀，但当前已有 `OpenSignController` 可暂时保留

## Class Rename Plan

建议重命名如下：
- `AuthInternalController` -> `AuthController`
- `DeviceInternalController` -> `DeviceController`
- `CryptoCardInternalController` -> `CryptoCardController`
- `InitInternalController` -> `InitController`
- `HealthInternalController` -> `HealthController`
- `InternalSignController` -> `SignController`
- `FileInternalController` -> `FileController`

对应包路径调整：
- `modules/file/controller/internal` -> `modules/file/controller`
- `modules/sign/controller/internal` -> `modules/sign/controller`

其余当前已在 `controller` 包下的类，仅改类名即可。

## Compatibility Boundary

以下内容必须保持不变：
- `@RequestMapping` 路径
- 所有 `/api/v1/**` 路径
- 所有 `/openapi/**` 路径
- `WebMvcConfig` 的拦截规则
- Swagger/OpenAPI 文档访问路径
- 前端、脚本、curl 示例调用路径

也就是说，这次是纯 Java 命名与项目约定调整，不是 API 行为调整。

## Security Impact

鉴权策略不变：
- `/api/**` 继续走内部 token 拦截器
- `/openapi/**` 继续走 openapi 签名拦截器

因为拦截器是基于 URL 前缀，而不是控制器类名或包名，所以控制器重命名不会影响运行时鉴权行为。

## Testing Strategy

需要验证三类内容：

1. 编译与导入
- 测试类中的 import、`standaloneSetup(...)`、构造器引用都更新完成

2. 运行时边界不变
- 控制器路径不变
- 鉴权拦截配置不变

3. 文档约定更新
- README 中模块结构和 API Boundary Rules 不再要求 `controller/internal`
- 示例结构改为 `controller + controller/openapi`

## Risks

1. 类名和文件路径同时重命名，容易遗漏测试 import 或文档引用。
2. 如果存在基于类名扫描或人工 grep 的脚本，需要同步更新引用。
3. `sign` 与 `file` 模块同时涉及包移动，若未同步修改 package 声明会导致编译失败。

## Recommendation

先做最小一致性改造：
- 统一内部控制器类名为 `*Controller`
- 去掉 `controller/internal` 包
- 更新 README、测试和约定文档

不在这一轮处理：
- `openapi` 控制器风格统一
- DTO 包命名统一
- 额外的模块结构重构