@tier0/sdk-v2 0.9.1 → 0.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/SKILL.md

@@ -7,6 +7,8 @@ description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App
 
 `@tier0/sdk-v2/data` 是 App 自有业务数据的服务端入口：用 `defineCollection` 声明集合，`createDataClient` 在首次访问时一次性 ensure 全部声明，然后用 Mongo 驱动风格的集合句柄读写 UNS 记录。没有 SQL、ORM、连接串或迁移步骤；Preview 与部署后的 App 共用同一批集合和记录。
 
+这里创建的集合以 `ownerAppId` 标识唯一所属 App。使用已有或其他 App 共享的集合时，直接走 [UNS](../tier0-sdk-v2-uns/SKILL.md) 的 `client.uns.recordFind`、`recordInsertOne` 等 collectionId 接口，不再用 defineCollection/ensure 声明它；无需服务端 alias，仍须当前 App 已有相应集合授权，复用不改变所属关系。
+
 数据读写只在服务端代码（业务 service）里用 `@tier0/sdk-v2/data`：该入口依赖 Node 内置模块，浏览器打包会直接失败。组件和 route 的客户端代码只能从 `@tier0/sdk-v2/data/define` 取集合声明和类型（`defineCollection`、`Doc`、`NewDoc` 等），它不加载数据运行时，可以进浏览器包。需要 `zod` 4。底层调用 SDK 生成的 UNS 操作（`appCollectionsEnsure`、`recordFind`、`recordTransactionExecute` 等），凭证读取平台注入的 TIER0_API_HOST / TIER0_API_KEY。
 
 集合声明必须分别填写业务名称 `name` 与稳定程序标识 `alias`，例如 `name: '生产工单'`、`alias: 'production_orders'`。name 是唯一界面名称，没有 displayName 或 alias 回退；ensure 通过 alias 找回原集合，不覆盖用户改名。

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md

@@ -2,12 +2,14 @@
 
 | 方法 | POST 路径 | 必要参数 |
 | --- | --- | --- |
-| programs.deploy | /openapi/v2/uns/streams/program/deploy | id；dryRun 默认 false，建议 expectedRevision |
-| programs.rollback | /openapi/v2/uns/streams/program/rollback | id、versionId、dryRun；建议 expectedRevision |
+| programs.deploy | /openapi/v2/uns/streams/program/deploy | id；dryRun 默认 false，建议 expectedRevision 和发布状态守卫 |
+| programs.rollback | /openapi/v2/uns/streams/program/rollback | id、versionId、dryRun；建议 expectedRevision 和发布状态守卫 |
 | documents.disable | /openapi/v2/uns/streams/documents/disable | id、expectedRevision、expectedActiveRelease、dryRun |
 
 全部写操作使用各自的 idempotencyKey。expectedSourceRevision 只适用于恰好一个 Source 依赖，且同时保护草稿冻结修订与当前 Source head；多源不能塞入单个修订值。原生文档没有 documents.deploy，当前云端 program 模型发布走 programs.deploy。
 
+发布和回滚有可选并发守卫：有生效发布时传入正整数 `expectedActiveRelease`；没有生效发布时传入 `expectedReleaseState: 'inactive'`，两者不能同时使用。服务端在事务内比较当前状态，变化时返回版本冲突；重新读取并决策后才能使用新的业务意图。守卫比较当前值，不记录中间发生的全部切换。
+
 发布、停用和回滚需要 uns.stream.manage；相关 Source 访问还受各自授权约束。保存回执中的 revision、发布回执中的 activeVersion 与 activeRelease 分别用于不同目的：
 
 | 字段 | 含义与用途 |
@@ -25,6 +27,7 @@ export async function deployStream(current: CloudStreamDocumentView, intentKey:
   const sources = current.document.sources ?? [];
   const request = {
     id: current.id, expectedRevision: current.revision,
+    ...(String(current.activeRelease) === '0' ? { expectedReleaseState: 'inactive' as const } : { expectedActiveRelease: current.activeRelease }),
     ...(sources.length === 1 ? { expectedSourceRevision: sources[0]!.configRevision } : {}),
   };
   const receipt = await client.stream.programs.deploy({
@@ -64,11 +67,13 @@ export async function disableStream(
 import { createClient, type Tier0Client, type CloudStreamStopView } from '@tier0/sdk-v2';
 
 export async function rollbackStream(
-  current: Pick<CloudStreamStopView, 'id' | 'revision'>, versionId: string, intentKey: string, client: Tier0Client = createClient(),
+  current: Pick<CloudStreamStopView, 'id' | 'revision' | 'activeRelease'>, versionId: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
   // versionId 使用已知发布回执的 activeVersion，或从 programs.versions.list 选定。
   return client.stream.programs.rollback({
-    id: current.id, versionId, expectedRevision: current.revision, dryRun: false, idempotencyKey: intentKey,
+    id: current.id, versionId, expectedRevision: current.revision,
+    ...(String(current.activeRelease) === '0' ? { expectedReleaseState: 'inactive' as const } : { expectedActiveRelease: current.activeRelease }),
+    dryRun: false, idempotencyKey: intentKey,
   });
 }
 ```

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/SKILL.md

@@ -21,17 +21,14 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 
 ## 找到正确数据上下文
 
-托管 App 使用 dataAppContext，按业务 alias 精确选择授权集合；它同时给出每个集合的 revision、索引就绪状态（indexStatus）、TTL 和平台限额（limits）。App 凭证不能调用 metadataFind/FindOne、async 模式与 jobs 查询；Workspace 集成（会话、personal / agent Key）用 dataDiscover/metadataFind，不强制 App 上下文。通用元数据管理写入不向 App 凭证开放。App 自有业务数据优先用 [App 数据层](../tier0-sdk-v2-data/SKILL.md)（`@tier0/sdk-v2/data`），变更订阅只在那里提供（`data.subscribe`）。
+托管 App 从配置或 dataAppContext 取得实际 collectionId；alias 是可选的查找便利。dataAppContext 同时给出授权、revision、索引就绪状态（indexStatus）、TTL 和平台限额（limits）。已有或共享集合直接用 collectionId 调用记录接口，无需先 ensure 或配置服务端 alias；App Key 必须已有该集合及操作的授权，不以 Workspace 权限替代 App 授权。App 凭证不能调用 metadataFind/FindOne、async 模式与 jobs 查询；Workspace 集成（会话、personal / agent Key）用 dataDiscover/metadataFind，不强制 App 上下文。通用元数据管理写入不向 App 凭证开放。App 自有业务数据优先用 [App 数据层](../tier0-sdk-v2-data/SKILL.md)（`@tier0/sdk-v2/data`），变更订阅只在那里提供（`data.subscribe`）。
 
 ```ts
 import { createClient } from '@tier0/sdk-v2';
 
-export async function findAppCollection(alias: string) {
+export async function readAppRecords(collectionId: string) {
   const client = createClient();
-  const context = await client.uns.dataAppContext({});
-  const collection = context.data.collections.find(item => item.alias === alias);
-  if (!collection) throw new Error('当前 App 未获得目标集合授权');
-  return client.uns.collectionDescribe({ collectionId: collection.collectionId });
+  return client.uns.recordFind({ collectionId, limit: 20 });
 }
 ```