From c968f9f24e9faa326da55bc91baee46916eeb2ce Mon Sep 17 00:00:00 2001 From: Yvan <8574526@qq,com> Date: Fri, 21 Aug 2026 00:31:43 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/system/internal/biz/payment.go | 113 +++++++---------------------- docs/system-pkg-audit.md | 66 +++++++++++++++++ internal/README.md | 31 -------- internal/modules/README.md | 32 -------- pkg/README.md | 4 +- pkg/httpx/response_test.go | 33 +++++++++ pkg/paymentkit/callback.go | 8 -- pkg/paymentkit/provider.go | 36 +++++++++ 8 files changed, 164 insertions(+), 159 deletions(-) create mode 100644 docs/system-pkg-audit.md delete mode 100644 internal/README.md delete mode 100644 internal/modules/README.md create mode 100644 pkg/httpx/response_test.go create mode 100644 pkg/paymentkit/provider.go diff --git a/app/system/internal/biz/payment.go b/app/system/internal/biz/payment.go index de1f775..05e1822 100644 --- a/app/system/internal/biz/payment.go +++ b/app/system/internal/biz/payment.go @@ -12,39 +12,37 @@ import ( "sync" "time" + "kra/pkg/paymentkit" + "github.com/google/uuid" ) const ( - PaymentAlipay = "alipay" - PaymentAlipayV3 = "alipay-v3" - PaymentWechatV2 = "wechat-v2" - PaymentWechatV3 = "wechat-v3" - PaymentApple = "apple-iap" - PaymentChinaums = "chinaums" - PaymentSFT = "sft" - PaymentSuperPay = "supper-pay" - PaymentWechatGame = "wechat-game-pay" - PaymentDouyinGame = "douyin-game-pay" + PaymentAlipay = paymentutil.ProviderAlipay + PaymentAlipayV3 = paymentutil.ProviderAlipayV3 + PaymentWechatV2 = paymentutil.ProviderWechatV2 + PaymentWechatV3 = paymentutil.ProviderWechatV3 + PaymentApple = paymentutil.ProviderApple + PaymentChinaums = paymentutil.ProviderChinaums + PaymentSFT = paymentutil.ProviderSFT + PaymentSuperPay = paymentutil.ProviderSuperPay + PaymentWechatGame = paymentutil.ProviderWechatGame + PaymentDouyinGame = paymentutil.ProviderDouyinGame // GoPay-backed providers. These are kept separate from the existing // configuration-driven game/aggregator protocols above. - PaymentDouyin = "douyin" - PaymentQQ = "qq" - PaymentAllinPay = "allinpay" - PaymentLakala = "lakala" - PaymentPayPal = "paypal" - PaymentSaobei = "saobei" - PaymentInternal = "internal" + PaymentDouyin = paymentutil.ProviderDouyin + PaymentQQ = paymentutil.ProviderQQ + PaymentAllinPay = paymentutil.ProviderAllinPay + PaymentLakala = paymentutil.ProviderLakala + PaymentPayPal = paymentutil.ProviderPayPal + PaymentSaobei = paymentutil.ProviderSaobei + PaymentInternal = paymentutil.ProviderInternal - PaymentModeExternal = "external" - PaymentModeInternal = "internal" + PaymentModeExternal = paymentutil.ModeExternal + PaymentModeInternal = paymentutil.ModeInternal ) -var SupportedPaymentProviders = []string{ - PaymentAlipay, PaymentAlipayV3, PaymentWechatV2, PaymentWechatV3, PaymentApple, - PaymentChinaums, PaymentSFT, PaymentSuperPay, PaymentWechatGame, PaymentDouyinGame, - PaymentDouyin, PaymentQQ, PaymentAllinPay, PaymentLakala, PaymentPayPal, PaymentSaobei, -} +var SupportedPaymentProviders = paymentutil.SupportedProviders() var ( ErrPaymentProviderNotFound = errors.New("支付渠道未配置") @@ -190,74 +188,15 @@ type PaymentResult struct { FailureAck PaymentCallbackAck `json:"-"` } -type PaymentCallbackAck struct { - StatusCode int - ContentType string - Body []byte -} - -type PaymentCallbackError struct { - Cause error - Ack PaymentCallbackAck -} - -func (e *PaymentCallbackError) Error() string { - if e == nil || e.Cause == nil { - return "支付回调处理失败" - } - return e.Cause.Error() -} - -func (e *PaymentCallbackError) Unwrap() error { - if e == nil { - return nil - } - return e.Cause -} +type PaymentCallbackAck = paymentutil.CallbackAck +type PaymentCallbackError = paymentutil.CallbackError func CallbackFailure(err error, fallback PaymentCallbackAck) PaymentCallbackAck { - var callbackErr *PaymentCallbackError - if errors.As(err, &callbackErr) && callbackErr.Ack.StatusCode != 0 { - return callbackErr.Ack - } - return fallback + return paymentutil.CallbackFailure(err, fallback) } func DefaultPaymentCallbackAck(provider string, success bool) PaymentCallbackAck { - status := 200 - if !success { - status = 500 - } - switch provider { - case PaymentAlipay, PaymentAlipayV3: - body := "success" - if !success { - body = "failure" - } - return PaymentCallbackAck{StatusCode: status, ContentType: "text/plain; charset=utf-8", Body: []byte(body)} - case PaymentWechatV2: - code, message := "SUCCESS", "OK" - if !success { - code, message = "FAIL", "FAIL" - } - body := fmt.Sprintf("", code, message) - return PaymentCallbackAck{StatusCode: status, ContentType: "application/xml; charset=utf-8", Body: []byte(body)} - case PaymentWechatV3: - code, message := "SUCCESS", "成功" - if !success { - code, message = "FAIL", "失败" - } - body, _ := json.Marshal(map[string]string{"code": code, "message": message}) - return PaymentCallbackAck{StatusCode: status, ContentType: "application/json; charset=utf-8", Body: body} - case PaymentApple: - return PaymentCallbackAck{StatusCode: status} - default: - body := "success" - if !success { - body = "failure" - } - return PaymentCallbackAck{StatusCode: status, ContentType: "text/plain; charset=utf-8", Body: []byte(body)} - } + return paymentutil.DefaultCallbackAck(provider, success) } type PaymentCallback struct { diff --git a/docs/system-pkg-audit.md b/docs/system-pkg-audit.md new file mode 100644 index 0000000..5e0c91b --- /dev/null +++ b/docs/system-pkg-audit.md @@ -0,0 +1,66 @@ +# `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/... +``` + +结果：全部通过。 diff --git a/internal/README.md b/internal/README.md deleted file mode 100644 index f563e98..0000000 --- a/internal/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Internal Architecture - -本项目采用参考 Kratos beer-shop 的模块化单体结构：先按业务边界垂直拆分，再在 -模块内部保持 Kratos 的 `service -> biz <- data` 依赖方向。 - -```text -internal/ - app/ 应用组合根，只决定启用哪些模块 - conf/ 运行配置 - logging/ 公共日志基础设施 - modules/ - system/ 稳定的后台系统能力 - biz/ 领域对象、用例、仓储接口 - data/ PO、仓储实现、系统持久化 - service/ DTO 与 DO 转换 - transport/ HTTP handler、router、middleware - initialize/ system 首次安装编排 - integration/ 外部服务适配器 - worker/ system 后台任务 - platform/ 不含业务语义的跨模块机制 - database/ - module/ - task/ -``` - -依赖方向：`cmd -> app -> modules -> platform`。`platform` 不得引用业务模块；业务 -模块之间优先通过 `biz` 接口协作，不直接引用对方的 `data` 或 `transport`。 - -新增模块时，在 `internal/modules/` 内完成自己的分层，并在 -`internal/app/catalog.go` 注册迁移、菜单/API、默认任务、任务实现和路由。组合根 -是唯一允许同时知道多个模块具体类型的位置。 diff --git a/internal/modules/README.md b/internal/modules/README.md deleted file mode 100644 index b05c72d..0000000 --- a/internal/modules/README.md +++ /dev/null @@ -1,32 +0,0 @@ -# Internal Modules - -参考 Kratos beer-shop 的垂直业务拆分方式，业务代码按模块组织在 -`internal/modules/` 下。当前项目是模块化单体，因此共享一个进程和组合根， -但每个模块仍独立拥有 `biz`、`data`、`service`、`transport` 和初始化贡献。 - -## 当前模块 - -`system` 是模板自带的后台管理模块，包含用户、权限、菜单、API、公告、部门、 -字典、文件、审计、定时任务、支付和系统初始化等现有表与逻辑。 - -## 新增业务模块 - -新增业务请创建 `internal/modules/`，不要把领域模型、仓储或 HTTP -处理器继续添加到 `internal/biz`、`internal/data`、`internal/service` 等根目录。 -数据库表和迁移由业务模块自己的 `data` 包负责；只有数据库连接生命周期和通用 -迁移执行器属于 `internal/platform/database`。 - -模块通过 `internal/app/catalog.go` 接入组合根： - -- `module.Definition.Migrations`：模块自己的表结构迁移 -- `module.Definition.Surface`：菜单和 API 元数据，首次初始化时统一写入系统表 -- `module.Definition.TimedTasks`：模块默认定时任务记录 -- `module.Definition.Tasks`：无状态的进程内任务方法 -- `module.RouteRegistrar`：需要依赖 Handler 的路由注册器，在 `app.Runtime` 中组合 - -无依赖的任务方法可以放进 `Definition.Tasks`。需要仓储或用例依赖的任务方法由 -模块实现 `task.Contributor`，再由 `internal/app` 激活。新增模块只修改应用组合根， -不修改 `system` 的初始化、worker、路由或数据层。 - -`integration` 是外部系统适配器，不是通用工具；只有实现了稳定跨模块协议的能力 -才上移到 `platform`。`utils` 仅保留无状态、无业务语义且确实被本模块复用的函数。 diff --git a/pkg/README.md b/pkg/README.md index dacc4ae..c77dd28 100644 --- a/pkg/README.md +++ b/pkg/README.md @@ -8,7 +8,9 @@ - `module`：模块迁移、后台元数据和路由注册协议 - `task`：跨模块共享的进程内任务注册表和贡献协议 - `logging`：跨 app 复用的结构化日志能力 -- `paymentkit`：支付金额、签名、状态和报文处理纯函数 +- `httpx`：跨 HTTP 模块共享的 JSON 响应结构、分页结构和状态码 +- `paymentkit`：支付金额、签名、状态、provider 标识和回调应答纯函数 +- `protoutil`：与业务无关的 protobuf JSON 局部合并工具 `pkg` 只能提供机制和稳定协议，不能引用任何 `app/*/internal`。数据库配置加载、 系统集成配置、系统表和 provider 生命周期仍由 `app/system` 负责。 diff --git a/pkg/httpx/response_test.go b/pkg/httpx/response_test.go new file mode 100644 index 0000000..710c475 --- /dev/null +++ b/pkg/httpx/response_test.go @@ -0,0 +1,33 @@ +package httpx + +import ( + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" +) + +func TestResponseHelpers(t *testing.T) { + gin.SetMode(gin.TestMode) + r := gin.New() + r.GET("/ok", OK) + r.GET("/fail", func(c *gin.Context) { Fail(c, "bad") }) + r.GET("/auth", func(c *gin.Context) { NoAuth(c, "login") }) + + for _, tc := range []struct { + path string + statusCode int + body string + }{ + {"/ok", 200, `{"code":0,"data":{},"msg":"操作成功"}`}, + {"/fail", 200, `{"code":7,"data":{},"msg":"bad"}`}, + {"/auth", 401, `{"code":7,"data":null,"msg":"login"}`}, + } { + req := httptest.NewRequest("GET", tc.path, nil) + w := httptest.NewRecorder() + r.ServeHTTP(w, req) + if w.Code != tc.statusCode || w.Body.String() != tc.body { + t.Fatalf("%s: status=%d body=%q", tc.path, w.Code, w.Body.String()) + } + } +} diff --git a/pkg/paymentkit/callback.go b/pkg/paymentkit/callback.go index 3fac0d7..d398209 100644 --- a/pkg/paymentkit/callback.go +++ b/pkg/paymentkit/callback.go @@ -6,14 +6,6 @@ import ( "fmt" ) -const ( - ProviderAlipay = "alipay" - ProviderAlipayV3 = "alipay-v3" - ProviderWechatV2 = "wechat-v2" - ProviderWechatV3 = "wechat-v3" - ProviderApple = "apple-iap" -) - // CallbackAck is the provider-facing HTTP acknowledgement returned after a // payment notification is processed. type CallbackAck struct { diff --git a/pkg/paymentkit/provider.go b/pkg/paymentkit/provider.go new file mode 100644 index 0000000..003c952 --- /dev/null +++ b/pkg/paymentkit/provider.go @@ -0,0 +1,36 @@ +package paymentutil + +const ( + ProviderAlipay = "alipay" + ProviderAlipayV3 = "alipay-v3" + ProviderWechatV2 = "wechat-v2" + ProviderWechatV3 = "wechat-v3" + ProviderApple = "apple-iap" + ProviderChinaums = "chinaums" + ProviderSFT = "sft" + ProviderSuperPay = "supper-pay" + ProviderWechatGame = "wechat-game-pay" + ProviderDouyinGame = "douyin-game-pay" + ProviderDouyin = "douyin" + ProviderQQ = "qq" + ProviderAllinPay = "allinpay" + ProviderLakala = "lakala" + ProviderPayPal = "paypal" + ProviderSaobei = "saobei" + ProviderInternal = "internal" + + ModeExternal = "external" + ModeInternal = "internal" +) + +var externalProviders = [...]string{ + ProviderAlipay, ProviderAlipayV3, ProviderWechatV2, ProviderWechatV3, ProviderApple, + ProviderChinaums, ProviderSFT, ProviderSuperPay, ProviderWechatGame, ProviderDouyinGame, + ProviderDouyin, ProviderQQ, ProviderAllinPay, ProviderLakala, ProviderPayPal, ProviderSaobei, +} + +// SupportedProviders returns a copy so callers cannot mutate the process-wide +// provider catalog. +func SupportedProviders() []string { + return append([]string(nil), externalProviders[:]...) +}