11 lines
18 KiB
JSON
11 lines
18 KiB
JSON
{"role":"user","message":{"content":[{"type":"text","text":"<user_query>\n我现在要给cursor加一个用户级别的约束。 后端服务之间的调用，现在统一通过slot/sdk来中转。 帮我优化这个术语，加入约束里面\n</user_query>"}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"梳理现有 Cursor 规则与 `slot/sdk` 的用法，以便拟定准确的用户级约束术语。\n\n[REDACTED]"},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/.cursor/skills-cursor/create-rule/SKILL.md"}},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/.cursor/rules/backend-layering.mdc"}},{"type":"tool_use","name":"Task","input":{"description":"Explore slot_sdk usage patterns","prompt":"Explore how slot_sdk (or slot/sdk) is used for inter-service communication in the slot monorepo. Find:\n1. What is slot_sdk - package structure, main purpose\n2. Examples of services calling other services via SDK vs direct HTTP/internal calls\n3. Any existing documentation about this pattern\n4. Naming conventions (Sdk classes, client methods, etc.)\n\nSearch in: /Users/ray/Documents/project/www/slot/slot_sdk, and grep across slot_wallet, slot_user, slot_center, slot_pay, backend for Sdk usage.\n\nReturn: concise summary with key file paths, typical call pattern (code snippet), and recommended terminology for a Cursor rule.","subagent_type":"explore","readonly":true}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"[REDACTED]"},{"type":"tool_use","name":"Glob","input":{"target_directory":"/Users/ray/.cursor/rules","glob_pattern":"**/*"}},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/Documents/project/www/slot/slot_agent/doc/feature_agent.md","limit":80}},{"type":"tool_use","name":"Grep","input":{"pattern":"slot/sdk|slot_sdk|slotsdk","path":"/Users/ray/Documents/project/www/slot/docs","head_limit":20}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"已梳理 `slot_sdk` 用法与现有用户级规则；拟新增独立规则文件，与 `backend-layering` 分工明确。\n\n[REDACTED]"},{"type":"tool_use","name":"AskQuestion","input":{"title":"跨服务约束规则范围","questions":[{"id":"legacy_policy","prompt":"对存量 InnerCurlService / slot_lib 直连，规则里希望怎么表述？","options":[{"id":"avoid_new","label":"新代码禁止；改到相关区域时逐步迁到 slot_sdk（推荐）"},{"id":"strict","label":"一律禁止，任何改动都必须先迁到 slot_sdk"},{"id":"document_only","label":"只写「新代码用 slot_sdk」，不提及 legacy"}]}]}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"[REDACTED]"},{"type":"tool_use","name":"CreatePlan","input":{"name":"跨服务 slot_sdk 约束","overview":"在用户级 Cursor 规则目录新增一条「跨服务通信」约束，用统一、可操作的术语规定：业务服务之间的 HTTP 互调必须经 `slot/sdk`（`slotsdk`）完成，并与现有 `backend-layering` 规则互补而不重复。","plan":"# 跨服务通信 Cursor 用户级约束\n\n## 背景与目标\n\n当前用户级规则在 [`/Users/ray/.cursor/rules/`](file:///Users/ray/.cursor/rules/) 已有：\n\n- [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) — 单服务内 Controller / Logic / Service 分层\n- [`dev-environment.mdc`](file:///Users/ray/.cursor/rules/dev-environment.mdc) — Docker 本地开发\n- [`php-doc.mdc`](file:///Users/ray/.cursor/rules/php-doc.mdc) — PHPDoc 规范\n\n[`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) 仅在 Service 层职责里顺带提到「sdk」，**没有**规定跨服务 HTTP 的入口、命名与新增 API 的流程。本次新增**独立规则**（单一职责，符合 create-rule 实践），`alwaysApply: true`，与现有三条规则一致。\n\n代码库事实（供规则用语对齐）：\n\n- 包名：`slot/sdk`，命名空间 `slotsdk\\`，仓库 [`slot_sdk`](file:///Users/ray/Documents/project/www/slot/slot_sdk)\n- 典型消费方：`slot_admin`、`slot_agent`、`slot_console`、`slot_pwa`（composer 依赖 `slot/sdk`）\n- 典型被调方：`slot_wallet`、`slot_user`、`slot_center` 等，对外暴露 `innerapi/*`、`api/*`\n- 推荐调用链：`new {Domain}Client($config)->service()->{method}(...)`\n- 项目内已有表述：[`slot_agent/doc/feature_agent.md`](file:///Users/ray/Documents/project/www/slot/slot_agent/doc/feature_agent.md) —「代理服不直连用户域表，统一通过 `slot_sdk` 调用户服 innerapi」\n\n按你的选择：**规则只约束新代码走 slot_sdk，不写 InnerCurlService / slot_lib 等 legacy 迁移条款。**\n\n---\n\n## 术语优化（写入规则正文）\n\n| 避免说法 | 推荐说法 | 说明 |\n| --- | --- | --- |\n| 后端服务之间调用 / 中转 | **跨服务 HTTP 调用** | 明确是进程间 HTTP，不是本地 Logic/Service |\n| 通过 slot/sdk 中转 | **经 slot_sdk 调用** | `slot_sdk` = 客户端库；被调服务仍直接处理请求，库不做业务中转 |\n| SDK / 封装 | **slot_sdk（`slot/sdk`）** | 与 composer 包名、仓库目录一致 |\n| 各服务自己拼 URL | **在 slot_sdk 增加 `{Domain}Service` 方法** | 路径与 DTO 单点维护 |\n| `app\\service\\WalletService` | **本地 WalletService** vs **slotsdk WalletService** | 防止与 SDK 类名混淆 |\n\n核心定义（规则开篇 1 段）：\n\n> **slot_sdk** 是跨服务 HTTP 客户端库（`composer` 包 `slot/sdk`，命名空间 `slotsdk\\`），用于**调用方服务**访问**被调服务**的 `innerapi/*` 或 `api/*` 接口。它不是独立部署的微服务。\n\n---\n\n## 拟新增文件\n\n**路径：** [`/Users/ray/.cursor/rules/cross-service-sdk.mdc`](/Users/ray/.cursor/rules/cross-service-sdk.mdc)\n\n**Frontmatter：**\n\n```yaml\n---\ndescription: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连\nalwaysApply: true\n---\n```\n\n**正文结构（约 35–45 行，中文为主）：**\n\n### 1. 适用范围\n\n- 一个 Webman 服务需要 HTTP 访问另一个服务的 `innerapi` / `api` 时适用。\n- **被调服务**自身实现 Controller/Logic/Model，**不**为「被别人调」而引入 `slot/sdk`。\n- **调用方**若需调第三个服务，必须通过 `slot/sdk`（不在业务代码里手写 Guzzle/curl/拼 host+path）。\n\n### 2. 标准调用方式\n\n```php\nuse slotsdk\\Config as SDKConfig;\nuse slotsdk\\service\\wallet\\WalletClient;\n\n$config = new SDKConfig([\n 'host' => ShareConfigService::get('walletApiHost'),\n 'headers' => ['server-name' => config('app.server_name')],\n]);\n$result = (new WalletClient($config))->service()->getStatistics($uids, $currency);\n```\n\n要点：\n\n- Host 来自 center 下发的 `*ApiHost`（如 `walletApiHost`、`userApiHost`）。\n- 请求头带 `server-name`，值为**当前调用方**服务名。\n- 非零 `code` 由 `slotsdk\\exception\\ApiException` 抛出，调用方在 Logic/Gateway 层处理。\n\n### 3. 新增 / 变更远程接口的流程\n\n1. 在 [`slot_sdk/src/service/{domain}/`](file:///Users/ray/Documents/project/www/slot/slot_sdk/src/service/) 增加 `{Domain}Service` 方法、路径常量、必要时 `entity/*Entity`。\n2. 在调用方 Logic 或 `*GatewayService` 中调用；Controller 保持薄。\n3. **禁止**在 `slot_admin` / `slot_agent` 等多仓库重复写同一路径字符串。\n\n### 4. 与 backend-layering 的衔接（1–2 句）\n\n- 跨服务访问在调用方落在 **Service 或 `*GatewayService`**，Logic 编排用例；不把 HTTP 细节散落在 Controller。\n- 与 [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc) 中「Service 可承载 sdk」一致；本规则专门约束**跨服务边界**，不重复写分层表。\n\n### 5. 命名与混淆规避\n\n- SDK：`slotsdk\\service\\{domain}\\{Domain}Client`、`{Domain}Service`、`entity\\{Name}Entity`。\n- 本地：`app\\service\\*`；若同名，用 `SDKConfig`、完整 namespace 或 import alias。\n- 消费方封装重复调用：`UserReferralGatewayService` 这类 `*GatewayService` 模式。\n\n---\n\n## 与现有规则的关系\n\n```mermaid\nflowchart LR\n subgraph userRules [用户级 .cursor/rules]\n layering[backend-layering]\n crossSdk[cross-service-sdk 新增]\n docker[dev-environment]\n phpdoc[php-doc]\n end\n layering -->|\"单服务内分层\"| Logic\n crossSdk -->|\"服务间 HTTP\"| slot_sdk\n slot_sdk --> innerapi[被调服务 innerapi/api]\n```\n\n- **不修改** [`backend-layering.mdc`](file:///Users/ray/.cursor/rules/backend-layering.mdc)：避免一条规则过长；仅在 `cross-service-sdk` 末尾用交叉引用衔接。\n- **不修改** [`dev-environment.mdc`](file:///Users/ray/.cursor/rules/dev-environment.mdc) / [`php-doc.mdc`](file:///Users/ray/.cursor/rules/php-doc.mdc)。\n\n---\n\n## 实施步骤（确认计划后执行）\n\n1. 创建 [`cross-service-sdk.mdc`](/Users/ray/.cursor/rules/cross-service-sdk.mdc)，填入上述 frontmatter 与正文。\n2. 通读四条 `alwaysApply` 规则，确认无矛盾表述（尤其 Service 层与 Gateway 分工）。\n3. （可选）在 [`slot_sdk/readme.md`](file:///Users/ray/Documents/project/www/slot/slot_sdk/readme.md) 补 5–10 行架构说明并链到 Cursor 规则 — **仅当你希望仓库内也有文档镜像**；非本次必需。\n\n---\n\n## 验收标准\n\n- 新开 Cursor 会话、编辑任意 slot PHP 文件时，Agent 应自动带上「跨服务须经 slot_sdk、新 API 先改 slot_sdk」约束。\n- 术语统一使用：**跨服务 HTTP**、**调用方 / 被调方**、**slot_sdk**，避免「中转」「服务间随便 HTTP」等模糊说法。\n- 规则正文不含 legacy 迁移条款（按你的选择）。\n","todos":[{"id":"create-mdc","content":"新建 /Users/ray/.cursor/rules/cross-service-sdk.mdc（alwaysApply + 术语与调用规范）"},{"id":"consistency-check","content":"对照 backend-layering.mdc 确认交叉引用一致、无重复分层表"},{"id":"optional-readme","content":"（可选）在 slot_sdk/readme.md 增加简短架构说明"}]}}]}}
|
||
{"role":"user","message":{"content":[{"type":"text","text":"<user_query>\n跨服务通信 Cursor 用户级约束\n\nImplement the plan as specified, it is attached for your reference. Do NOT edit the plan file itself.\n\nTo-do's from the plan have already been created. Do not create them again. Mark them as in_progress as you work, starting with the first one. Don't stop until you have completed all the to-dos.\n</user_query>"}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"开始实施计划：创建用户级跨服务通信规则，并对照现有规则做一致性检查。\n\n[REDACTED]"},{"type":"tool_use","name":"TodoWrite","input":{"todos":[{"id":"create-mdc","content":"新建 /Users/ray/.cursor/rules/cross-service-sdk.mdc（alwaysApply + 术语与调用规范）","status":"in_progress"},{"id":"consistency-check","content":"对照 backend-layering.mdc 确认交叉引用一致、无重复分层表","status":"pending"},{"id":"optional-readme","content":"（可选）在 slot_sdk/readme.md 增加简短架构说明","status":"pending"}],"merge":true}},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/.cursor/rules/backend-layering.mdc"}},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/Documents/project/www/slot/slot_sdk/readme.md"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"[REDACTED]"},{"type":"tool_use","name":"Write","input":{"path":"/Users/ray/.cursor/rules/cross-service-sdk.mdc","contents":"---\ndescription: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连\nalwaysApply: true\n---\n\n# 跨服务通信（slot_sdk）\n\n**slot_sdk** 是跨服务 HTTP 客户端库（`composer` 包 `slot/sdk`，命名空间 `slotsdk\\`），用于**调用方服务**访问**被调服务**的 `innerapi/*` 或 `api/*` 接口。它不是独立部署的微服务。\n\n术语：说「**跨服务 HTTP 调用**」「**经 slot_sdk 调用**」，不说「服务间中转」或「通过 slot/sdk 中转」（库是客户端，被调服务仍直接处理请求）。\n\n## 适用范围\n\n- 一个 Webman 服务需要 HTTP 访问另一个服务的 `innerapi` / `api` 时，**调用方**必须通过 slot_sdk。\n- **被调服务**实现 Controller / Logic / Model，**不**为「被别人调」而引入 `slot/sdk`。\n- **调用方**若需访问第三个服务，禁止在业务代码里手写 Guzzle/curl 或拼接 `host + path`。\n\n## 标准调用方式\n\n```php\nuse slotsdk\\Config as SDKConfig;\nuse slotsdk\\service\\wallet\\WalletClient;\n\n$config = new SDKConfig([\n 'host' => ShareConfigService::get('walletApiHost'),\n 'headers' => ['server-name' => config('app.server_name')],\n]);\n$result = (new WalletClient($config))->service()->getStatistics($uids, $currency);\n```\n\n- 调用链：`new {Domain}Client($config)->service()->{method}(...)`\n- Host 来自 center 下发的 `*ApiHost`（如 `walletApiHost`、`userApiHost`）。\n- 请求头 `server-name` 为**当前调用方**服务名。\n- 响应 `code !== 0` 时抛出 `slotsdk\\exception\\ApiException`，在 Logic 或 Gateway 层处理。\n\n## 新增 / 变更远程接口\n\n1. 先在 `slot_sdk/src/service/{domain}/` 增加 `{Domain}Service` 方法、路径、必要时 `entity/*Entity`。\n2. 再在调用方 Logic 或 `*GatewayService` 中调用；Controller 保持薄。\n3. **禁止**在 `slot_admin`、`slot_agent` 等多仓库重复写同一路径字符串。\n\n## 与单服务分层的关系\n\n跨服务访问落在调用方的 **Service** 或 **`*GatewayService`**，Logic 编排用例；HTTP 细节不散落在 Controller。与 [backend-layering](backend-layering.mdc) 中「Service 可承载 sdk」一致；分层职责见该规则，此处只约束**跨服务边界**。\n\n## 命名与混淆规避\n\n| 类型 | 约定 |\n| --- | --- |\n| SDK 客户端 | `slotsdk\\service\\{domain}\\{Domain}Client` |\n| SDK 方法类 | `slotsdk\\service\\{domain}\\{Domain}Service` |\n| SDK DTO | `entity\\{Name}Entity`、`{Name}RequestEntity` |\n| 本地服务 | `app\\service\\*`（本地 WalletService ≠ slotsdk WalletService） |\n\n同名时：`use slotsdk\\Config as SDKConfig` 或完整 namespace。消费方对重复跨服务调用可封装为 `*GatewayService`（如 `UserReferralGatewayService`）。\n"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"[REDACTED]"},{"type":"tool_use","name":"TodoWrite","input":{"todos":[{"id":"create-mdc","content":"新建 /Users/ray/.cursor/rules/cross-service-sdk.mdc（alwaysApply + 术语与调用规范）","status":"completed"},{"id":"consistency-check","content":"对照 backend-layering.mdc 确认交叉引用一致、无重复分层表","status":"in_progress"}],"merge":true}},{"type":"tool_use","name":"Read","input":{"path":"/Users/ray/.cursor/rules/cross-service-sdk.mdc"}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"一致性检查通过：与 `backend-layering` 无冲突。正在更新 `slot_sdk/readme.md`。\n\n[REDACTED]"},{"type":"tool_use","name":"Write","input":{"path":"/Users/ray/Documents/project/www/slot/slot_sdk/readme.md","contents":"# slot_sdk（`slot/sdk`）\n\n跨服务 HTTP 客户端库：供**调用方** Webman 服务访问**被调服务**的 `innerapi/*`、`api/*` 接口（Guzzle + 统一 `{code, data}` 处理）。\n\n- 命名空间：`slotsdk\\`\n- 典型消费方：`slot_admin`、`slot_agent`、`slot_console`、`slot_pwa`（`composer require slot/sdk`）\n- 典型被调方：`slot_wallet`、`slot_user`、`slot_center` 等（对外提供 API，一般不在本库内再依赖 `slot/sdk`）\n\n## 调用方式\n\n```php\nuse slotsdk\\Config as SDKConfig;\nuse slotsdk\\service\\wallet\\WalletClient;\n\n$config = new SDKConfig([\n 'host' => $walletApiHost,\n 'headers' => ['server-name' => 'agent'],\n]);\n$result = (new WalletClient($config))->service()->getStatistics($uids, $currency);\n```\n\n新增远程接口：先在 `src/service/{domain}/{Domain}Service.php` 增加方法与路径，再在消费方 Logic 或 `*GatewayService` 中调用。\n\nCursor 用户级约束见 `~/.cursor/rules/cross-service-sdk.mdc`（与 `backend-layering.mdc` 互补）。\n\n## 单元测试\n\n```bash\nvendor/bin/phpunit --color=always src/tests/agent\n```\n"}},{"type":"tool_use","name":"TodoWrite","input":{"todos":[{"id":"consistency-check","content":"对照 backend-layering.mdc 确认交叉引用一致、无重复分层表","status":"completed"},{"id":"optional-readme","content":"（可选）在 slot_sdk/readme.md 增加简短架构说明","status":"completed"}],"merge":true}}]}}
|
||
{"role":"assistant","message":{"content":[{"type":"text","text":"已完成，变更如下。\n\n### 1. 新增用户级规则\n\n[`/Users/ray/.cursor/rules/cross-service-sdk.mdc`](/Users/ray/.cursor/rules/cross-service-sdk.mdc)（`alwaysApply: true`）\n\n- 定义 **slot_sdk** 为跨服务 HTTP 客户端库（非独立微服务）\n- 统一术语：**跨服务 HTTP 调用**、**调用方 / 被调方**、**经 slot_sdk 调用**\n- 约束：调用方必须走 slot_sdk；被调方不为对外暴露 API 而引入该包\n- 标准调用链、Host/`server-name`、新增 API 先改 `slot_sdk` 的流程\n- 与 [`backend-layering.mdc`](/Users/ray/.cursor/rules/backend-layering.mdc) 交叉引用，不重复分层表\n\n### 2. 一致性检查\n\n- 与 `backend-layering` 中「Service 可承载 sdk」一致\n- `*GatewayService` 用于封装重复跨服务调用，与「禁止无封装中转 Service」不冲突\n- 未修改 `backend-layering`、`dev-environment`、`php-doc`\n\n### 3. 仓库文档\n\n[`slot_sdk/readme.md`](/Users/ray/Documents/project/www/slot/slot_sdk/readme.md) 补充架构说明，并指向 Cursor 规则路径。\n\n新开 Cursor 会话后会自动加载该约束。若要验证，可在任意 slot PHP 文件中让 Agent 实现一次跨服务调用，应会优先建议先改 `slot_sdk` 再消费。\n\n[REDACTED]"}]}} |