优化结构

2026-08-21 10:29:14 +08:00
parent 56980c8087
commit 055f6811ca
340 changed files with 382 additions and 382 deletions
@@ -0,0 +1,51 @@
+# Integrations
+
+`internal/integration` contains adapters that talk to systems outside the
+application process. They may open sockets, create SDK clients, keep reloadable
+state, or translate provider-specific protocols into `biz` interfaces.
+
+## Packages
+
+- `cache`: Redis-backed cache with an in-memory fallback.
+- `email`: SMTP email repository.
+- `mq`: reloadable EMQX/MQTT client exposed through the shared `pkg/mq` interface.
+- `payment`: payment-channel SDKs and callback/signature handling.
+- `storage`: local and object-storage implementations of `biz.FileStorage`.
+- `websocket`: reloadable Melody endpoint exposed through the shared
+  `pkg/websocket` wrapper.
+
+These packages are not `utils`: they perform I/O and own external dependency
+lifecycles. Their constructors are exposed through `ProviderSet`; `cmd` binds
+the `cache.RedisProvider` implementation to the shared `data.Data` container.
+
+Stateless protocol helpers that do not own clients live in
+`pkg/paymentkit`. They are intentionally small and dependency
+light, while provider adapters remain here.
+
+## Shared WebSocket and MQ APIs
+
+Business modules depend on `websocket.Hub` and `mq.Client` from the shared
+`pkg/websocket` and `pkg/mq` packages; they do not construct
+Melody or Paho clients and do not read system configuration directly. The
+system integration packages own runtime refresh and shutdown. Registered
+WebSocket handlers and MQTT subscriptions are retained when database-backed
+configuration replaces a live client.
+
+```go
+ws.OnMessage(func(session *websocket.Session, payload []byte) {
+	_ = ws.Send(session, payload)
+})
+_ = ws.Broadcast([]byte(`{"type":"system.ready"}`))
+
+_ = mq.PublishJSON(ctx, mqClient, "orders/paid", event, mq.AtLeastOnce, false)
+_ = mqClient.Subscribe(ctx, "orders/+/paid", mq.AtLeastOnce, handler)
+```
+
+Integration configuration is stored in `sys_integration_configs`:
+
+- WebSocket: `kind=websocket`, `provider=melody`
+- EMQX: `kind=mq`, `provider=emqx`
+
+The YAML values are only migration/bootstrap inputs. After the integration
+table exists, the database is authoritative and runtime updates are applied
+without restarting the process. The WebSocket public path defaults to `/ws`.