# `app/system` 到 `pkg` 复用性审查

审查范围：`app/system` 下全部 Go 文件，以及现有 `pkg` 目录。判断标准是：
公共包只能提供跨模块稳定的机制、协议或纯函数，不能依赖 `app/*/internal`，
也不承载 system 的业务表、用例、provider 生命周期或运行时配置。

## 本轮已抽取

| 原位置 | 公共位置 | 结论 |
|---|---|---|
| `internal/transport/httpx/response.go` | `pkg/httpx/response.go` | `Response`、`PageResult`、状态码和 Gin 响应助手是跨模块 HTTP 契约。system 原包保留别名/转发，兼容既有调用方。 |
| `internal/utils/configutil/json.go` | `pkg/protoutil/json.go` | protobuf JSON 局部合并、snake_case 到 lowerCamel 归一化与 system 业务无关，已由 system wrapper 转发。 |
| `internal/biz/payment.go` provider 常量 | `pkg/paymentkit/provider.go` | provider 标识、支付模式和支持列表是跨业务支付边界，system `biz` 保留兼容常量。 |
| `internal/biz/payment.go` 回调应答 | `pkg/paymentkit/callback.go` | 回调 ACK、回调错误和默认 provider 应答是跨模块协议，已由 system 类型别名兼容。 |

## `app/system` 逐目录结论

| 目录 | 结论 | 代表文件/原因 |
|---|---|---|
| `cmd` | 保留 system | `main.go`、`wire.go` 是组合根和启动生命周期，不能下沉。 |
| `internal/app`、`internal/module` | 保留 system | `catalog.go`、`definition.go` 绑定 system 迁移、菜单、路由和任务贡献。公共协议已在 `pkg/module`。 |
| `internal/biz` | 大部分保留；仅抽公共支付边界 | 用户、权限、菜单、审计、任务、支付订单和系统配置都是领域模型/用例；`payment.go` 中 provider 与 ACK 已兼容转发。 |
| `internal/conf` | 保留 system | 配置 proto 由 system 运行时和生成代码拥有，不能成为跨模块配置模型。 |
| `internal/data` | 保留 system | 数据库连接、迁移、PO、system 表、支付持久化和配置 watcher 都是 system 数据层。通用迁移/分页/GORM 能力已在 `pkg/database`。 |
| `internal/dto` | 保留 system | DTO 与 system API 形状绑定，不应跨模块共享。 |
| `internal/initialize` | 保留 system | 首次安装、兼容迁移、配置持久化和种子编排具有 system 语义。 |
| `internal/integration/cache` | 保留 system | Redis/cache 客户端生命周期和运行时配置属于 integration，不是 stateless utils。 |
| `internal/integration/email` | 保留 system | 邮件 provider 配置和发送生命周期属于 system integration。 |
| `internal/integration/payment` | 保留 system | `alipay.go`、`wechat_v3.go`、`paypal.go` 等是具体 provider SDK 适配器；不能搬到通用 pkg。纯金额、JSON、签名、状态函数已经在 `pkg/paymentkit`。 |
| `internal/integration/storage` | 保留 system | OSS/S3/本地存储客户端、重载和配置绑定属于 integration。 |
| `internal/repository` | 保留 system | 仓储实现、PO、Casbin、system 表和事务边界都不能跨模块复用。 |
| `internal/routeinfo` | 保留 system | 路由元数据包含 system 初始化与菜单语义。 |
| `internal/security/adminauth` | 保留 system | JWT claims、签发和后台认证策略属于 system 安全边界。 |
| `internal/service` | 保留 system | DTO 与 system DO 的转换和服务编排，不可放入公共包。 |
| `internal/transport/handler` | 保留 system | 每个 handler 都依赖 system service/DTO；只有 HTTP 响应协议抽到 `pkg/httpx`。 |
| `internal/transport/httpx` | 兼容层 | `response.go` 已转发到 `pkg/httpx`；`cookie.go` 的 token cookie 名称和认证策略仍是 system 专属。 |
| `internal/transport/middleware` | 保留 system | 审计、认证、数据权限、限流、system 错误记录和请求采集均带业务/配置语义。 |
| `internal/transport/router` | 保留 system | 路由注册指向 system handlers。 |
| `internal/utils/configutil` | 兼容层 | `json.go` 已转发到 `pkg/protoutil`；其余 system 专用工具应留在本目录。 |
| `internal/worker` | 保留 system | 任务执行器依赖 system task repo、runtime、日志和业务方法。跨模块任务注册协议已在 `pkg/task`。 |

## 现有 `pkg` 复核

- `pkg/database/*`：边界正确，继续保留。
- `pkg/logging/*`：边界正确，继续保留。
- `pkg/module/*`：跨模块迁移/路由/元数据协议，边界正确。
- `pkg/task/*`：跨模块任务注册协议，边界正确。
- `pkg/paymentkit/*`：本轮补齐 provider 与 callback 协议；具体渠道 SDK 仍留在 system。
- 新增 `pkg/httpx`、`pkg/protoutil`：均不引用 `app/*/internal`。

## 暂不抽取的后续候选

1. `internal/transport/httpx/cookie.go`：只有在多个 app 统一 token cookie 名称、SameSite 和反向代理策略后，才适合抽成公共 HTTP cookie 包。
2. `internal/transport/middleware/capture.go`：包含 operation-audit 脱敏字段和 system context key，当前不是通用中间件。
3. `internal/biz/pagination.go`：依赖 AIP filtering/ordering，且目前只服务 system 的仓储接口；若其他模块形成同样 DO 查询协议，再独立设计 `pkg/query`，不要直接搬 biz 类型。
4. `internal/biz/errors.go` 及认证/安全错误：错误 reason 与 system API 语义绑定，不应公共化。

## 验证

已运行：

```text
go test ./pkg/... ./app/system/...
```

结果：全部通过。