kra-oa/docs/system-pkg-audit.md

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 语义绑定，不应公共化。

验证

已运行：

go test ./pkg/... ./app/system/...

结果：全部通过。