@yss123/cage-connectors 0.4.0 → 0.4.1

package/README.md

@@ -1,104 +1,35 @@
 # @yss123/cage-connectors
 
-Cage 的外部系统连接层。声明允许的主机、操作、请求/响应 schema、密钥名称和重试策略，把领域事件映射为出站请求，并把成功回执或验签回调映射回领域命令。适用于 ERP、外部接口和模型适配器的 IO 边界。
+管理应用与外部系统的协议边界：允许的主机、密钥名称、请求/响应 schema、fake、验签及出站执行。领域 handler 通过事件和命令连接外部效果。
 
-## 安装
+## 声明操作
 
-需要 Node.js 24+，与其他 Cage 包保持同版本。在 domain 包安装：
-
-```powershell
-pnpm add @yss123/cage-connectors zod
-```
-
-## 声明外部协议
-
-以下文件可放入 `packages/domain/src/integrations/erp.ts`。声明时不访问网络或读取密钥；`example.com` 主机需要替换为实际服务，并验证远端幂等协议。
+安装 pnpm add @yss123/cage-connectors zod，与 Cage 其余包保持同版本：
 
 ```ts
-/** ERP 协议声明；只列出允许传出的字段，实际 IO 交给 worker。 */
 import { connector, op } from '@yss123/cage-connectors';
 import { z } from 'zod';
 
-/** 外部单据写操作；retryableWrite 要求对方按请求幂等键去重。 */
-export const erp = connector('erp', {
-  hosts: { test: 'erp-sandbox.example.com', prod: 'erp.example.com' },
-  secret: 'ERP_API_TOKEN',
-  timeoutMs: 5000,
+/** 测试账务协议的声明；只有对方真实按键去重时才可使用 retryableWrite。 */
+export const ledger = connector('ledger', {
+  hosts: { test: 'ledger.example.test' },
+  secret: 'LEDGER_TOKEN',
   operations: {
-    pushOrder: op({
-      effect: 'retryableWrite',
-      method: 'POST',
-      path: '/api/purchase-orders',
-      request: z.object({
-        externalId: z.string(),
-        lines: z.array(z.object({ sku: z.string(), qty: z.number() })),
-      }),
-      response: z.object({ erpNo: z.string() }),
+    send: op({
+      method: 'POST', path: '/documents', effect: 'retryableWrite',
+      request: z.object({ externalId: z.string().uuid() }),
+      response: z.object({ number: z.string() }),
     }),
   },
 });
 ```
 
-在采购模板中可以继续加入事件映射；这里的事件和命令来自现有采购模块：
-
-```ts
-import { outbound } from '@yss123/cage-connectors';
-import { OrderApproved, recordErpNo } from '../modules/purchase/index.js';
-
-/** 审批事件提交后出站，回执通过 external 命令回写，不直接改表。 */
-export const pushToErp = outbound(OrderApproved, erp.operations.pushOrder, {
-  idempotencyKey: (event) => `po-${event.orderId}`,
-  map: (event) => ({
-    externalId: event.orderId,
-    lines: event.items.map((item) => ({ sku: item.sku, qty: item.qty })),
-  }),
-  onSuccess: {
-    command: recordErpNo,
-    map: (response, event) => ({ id: event.orderId, erpNo: response.erpNo }),
-  },
-});
-```
-
-将声明从 domain 根入口导出，运行 `cage check/gen`，按需迁移后启动 API 与 worker。部署通过环境或 `SecretProvider` 提供 `ERP_API_TOKEN` 的真实值；源码只保留密钥名称。
-
-## 本地 fake 与真实环境
-
-worker 启动入口注册模拟实现，业务声明仍使用同一协议：
-
-```ts
-import { fakeConnector, stage } from '@yss123/cage-connectors';
-import * as domain from '@app/domain';
-
-// 仅 fake 阶段使用固定响应；test/prod 阶段按声明连接真实主机。
-if (stage() === 'fake') {
-  fakeConnector(domain.erp, {
-    pushOrder: (request) => ({ erpNo: `DEMO-${request.externalId}` }),
-  });
-}
-```
-
-通过 `CAGE_STAGE` 选择阶段。fake 不代表第三方联调通过，生产必须验证协议、验签、超时和幂等性。密钥与本机日志不提交到源码。
-
-## 公开入口与保证范围
-
-| 入口 | 用途 |
-| --- | --- |
-| `connector`、`op` | 主机白名单、操作 schema、超时、限流和重试声明 |
-| `outbound` | 领域事件到事务外操作的映射，成功回写调用命令 |
-| `inbound`、`hmacSha256` | 原始正文验签、载荷校验及外部命令调用 |
-| `fakeConnector`、`fakeCalls` | 注册模拟处理器与检查模拟调用 |
-| `SecretProvider`、`setSecretProvider` | 替换服务端密钥来源，不能在浏览器调用 |
-| `call`、`streamJson` | 受控服务端适配器的外呼与流读取，不用于业务 handler 直接 IO |
-| `ConnectorError` | 区分外部协议、网络和执行失败 |
-
-`effect: 'read'`、`'retryableWrite'`、`'write'` 分别表示读取、远端支持幂等的可重试写、不可安全重试写。不要为方便重试而把任意写标为 `retryableWrite`。
+主机不带协议/路径，secret 是部署注入名称。声明本身不请求网络；outbound 将事件映射到操作，成功通过 external 命令回写。inbound 先验原始正文，再映射领域命令。
 
-出站 IO 与业务数据库不共享事务，框架保存执行租约和回执以支持恢复，但不能回滚远端。结果未知的不可安全重试写会隔离；当前没有通用确认远端回执或解除 unknown 的管理接口，普通死信重放不能替代业务核对。连接器限流是每进程预算，多实例共享限流需另行设计。
+## 重试与核对
 
-## 文档
+read、retryableWrite、write 依据远端真实效果选择。外部执行、持久回执和本地回写分阶段；不可重试写的未知结果会隔离，普通死信重放不解除 unknown。数据库事务不能回滚远端。
 
-- [事件、出站与事务边界](https://github.com/shunshunyue/cage/blob/main/docs/development/getting-started/architecture.md)
-- [采购 ERP 完整声明](https://github.com/shunshunyue/cage/blob/main/examples/purchase-admin/packages/domain/src/integrations/erp.ts)
-- [排错方法](https://github.com/shunshunyue/cage/blob/main/docs/development/tools/troubleshooting.md)
+fakeConnector 验证本地协议与映射，不能证明真实联调。当前没有通用确认远端回执/解除未知状态的管理入口，需按业务协议恢复或补偿。
 
-源码与反馈：[GitHub](https://github.com/shunshunyue/cage)。许可证：[MIT](https://github.com/shunshunyue/cage/blob/main/LICENSE)。
+[自动化与第三方](https://github.com/shunshunyue/cage/blob/main/docs/development/guides/automation.md) · [执行保证](https://github.com/shunshunyue/cage/blob/main/docs/development/reference/execution.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yss123/cage-connectors",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "第三方连接器原语与运行时",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
   "dependencies": {
     "zod": "^4.1.5",
     "kysely": "^0.28.5",
-    "@yss123/cage-kernel": "0.4.0"
+    "@yss123/cage-kernel": "0.4.1"
   },
   "license": "MIT",
   "repository": {