first commit

rules/cross-service-sdk.mdc

@@ -0,0 +1,55 @@
+---
+description: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连
+alwaysApply: true
+---
+
+# 跨服务通信（slot_sdk）
+
+**slot_sdk** 是跨服务 HTTP 客户端库（`composer` 包 `slot/sdk`，命名空间 `slotsdk\`），用于**调用方服务**访问**被调服务**的 `innerapi/*` 或 `api/*` 接口。它不是独立部署的微服务。
+
+术语：说「**跨服务 HTTP 调用**」「**经 slot_sdk 调用**」，不说「服务间中转」或「通过 slot/sdk 中转」（库是客户端，被调服务仍直接处理请求）。
+
+## 适用范围
+
+- 一个 Webman 服务需要 HTTP 访问另一个服务的 `innerapi` / `api` 时，**调用方**必须通过 slot_sdk。
+- **被调服务**实现 Controller / Logic / Model，**不**为「被别人调」而引入 `slot/sdk`。
+- **调用方**若需访问第三个服务，禁止在业务代码里手写 Guzzle/curl 或拼接 `host + path`。
+
+## 标准调用方式
+
+```php
+use slotsdk\Config as SDKConfig;
+use slotsdk\service\wallet\WalletClient;
+
+$config = new SDKConfig([
+    'host' => ShareConfigService::get('walletApiHost'),
+    'headers' => ['server-name' => config('app.server_name')],
+]);
+$result = (new WalletClient($config))->service()->getStatistics($uids, $currency);
+```
+
+- 调用链：`new {Domain}Client($config)->service()->{method}(...)`
+- Host 来自 center 下发的 `*ApiHost`（如 `walletApiHost`、`userApiHost`）。
+- 请求头 `server-name` 为**当前调用方**服务名。
+- 响应 `code !== 0` 时抛出 `slotsdk\exception\ApiException`，在 Logic 或 Gateway 层处理。
+
+## 新增 / 变更远程接口
+
+1. 先在 `slot_sdk/src/service/{domain}/` 增加 `{Domain}Service` 方法、路径、必要时 `entity/*Entity`。
+2. 再在调用方 Logic 或 `*GatewayService` 中调用；Controller 保持薄。
+3. **禁止**在 `slot_admin`、`slot_agent` 等多仓库重复写同一路径字符串。
+
+## 与单服务分层的关系
+
+跨服务访问落在调用方的 **Service** 或 **`*GatewayService`**，Logic 编排用例；HTTP 细节不散落在 Controller。与 [backend-layering](backend-layering.mdc) 中「Service 可承载 sdk」一致；分层职责见该规则，此处只约束**跨服务边界**。
+
+## 命名与混淆规避
+
+| 类型 | 约定 |
+| --- | --- |
+| SDK 客户端 | `slotsdk\service\{domain}\{Domain}Client` |
+| SDK 方法类 | `slotsdk\service\{domain}\{Domain}Service` |
+| SDK DTO | `entity\{Name}Entity`、`{Name}RequestEntity` |
+| 本地服务 | `app\service\*`（本地 WalletService ≠ slotsdk WalletService） |
+
+同名时：`use slotsdk\Config as SDKConfig` 或完整 namespace。消费方对重复跨服务调用可封装为 `*GatewayService`（如 `UserReferralGatewayService`）。