@tier0/sdk-v2 0.1.0 → 0.2.2

package/skills/tier0-sdk-v2-uns/references/namespace.md

@@ -1,75 +0,0 @@
-# 目录和 Topic
-
-目录组织资源，Topic 是集合的 records/fields 视图，不是旧架构 Metric。增删改查使用 client.uns 的 directory*/topic*。
-
-| 操作 | 目录 | Topic | 关键参数 |
-| --- | --- | --- | --- |
-| 创建 | directoryCreate | topicCreate | dryRun、items；名称必填，Topic 另需 viewMode |
-| 查询 | directoryList/Get | topicList/Get | list 的 page/size/search/archived；get 的 id |
-| 改元数据 | directoryUpdate | topicUpdate | items[].id、expectedRevision、name/description/parentId |
-| 归档 | directoryArchive | topicArchive | items[].id、expectedRevision |
-| 恢复 | directoryRestore | topicRestore | 归档对象的 id 和当前 revision |
-| 改字段映射 | — | topicBindingsUpdate | 按 Topic 字段绑定契约 |
-
-创建/更新/归档/恢复均返回 Outcome；检查 committed、results[].error。目录/Topic 的删除语义是归档，不存在 directoryDelete/topicDelete。parentId=null 表示根；更新时省略则保持原位置。归档不能自行扩展成递归清空所有后代或关联集合。
-
-## 创建目录和集合视图
-
-以下函数独立调用；不要把创建目录后创建 Topic 说成一个原子事务。collectionId 先从集合查询取得。
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function createDirectory(
-  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const receipt = await client.uns.directoryCreate({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, name, parentId: null }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt, current: (await client.uns.directoryGet({ id })).data };
-}
-export async function createRecordTopic(
-  id: string, name: string, collectionId: string, parentId: string, intentKey: string,
-  client: Tier0Client = createClient(),
-) {
-  const receipt = await client.uns.topicCreate({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, name, viewMode: 'records', collectionId, parentId }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt, current: (await client.uns.topicGet({ id })).data };
-}
-```
-
-## 修改与归档 Topic
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function renameTopic(
-  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const current = await client.uns.topicGet({ id });
-  return client.uns.topicUpdate({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, name, expectedRevision: current.data.revision }],
-  });
-}
-export async function archiveTopic(
-  id: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const current = await client.uns.topicGet({ id });
-  return client.uns.topicArchive({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, expectedRevision: current.data.revision }],
-  });
-}
-```
-
-调用后检查 Outcome；修改后 get 核对名称，归档后 topicList({archived:true}) 遍历核对 ID。目录使用对应 directoryGet/Update/Archive；恢复从归档列表取得当前修订再 Restore，最后 get 核对。不要把 Topic 归档解释成底层 Record 已删除。

package/skills/tier0-sdk-v2-uns/references/read.md

@@ -1,32 +0,0 @@
-# 查询集合与记录
-
-| 方法 | 必要输入 | 返回 data |
-| --- | --- | --- |
-| collectionList | 可选 page、size、search、archived | list、total、hasMore、nextPage |
-| collectionGet | id | kind、id、revision、data（Schema/元数据） |
-| collectionDescribe | collectionId | 集合结构和数据能力 |
-| recordFind | collectionId；可选 filter、sort、limit、cursor | items、pageInfo |
-| recordCount | collectionId；可选 filter | 计数结果 |
-
-集合详情有两层 data：响应.data 是资源，响应.data.data 才是集合定义。记录行是 `{id,data,revision,…}`，过滤业务路径用 name，系统字段用 _id、_meta.revision；不要写 data.name。
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function readDevices(collectionId: string, client: Tier0Client = createClient()) {
-  const collection = await client.uns.collectionGet({ id: collectionId });
-  const records = await client.uns.recordFind({
-    collectionId, filter: { enabled: true }, sort: [['name', 1]], limit: 20,
-  });
-  return { schema: collection.data.data.recordSchema, items: records.data.items,
-    pageInfo: records.data.pageInfo };
-}
-export async function readDevice(collectionId: string, id: string, client: Tier0Client = createClient()) {
-  const result = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  return result.data.items[0] ?? null;
-}
-```
-
-recordFind 的 limit 为 1–200；按 pageInfo.hasMore/nextCursor 继续，完整循环见[数据工作流](data-workflows.md)。不要把第一页当全量，sort 是数组，不是 MongoDB 对象。
-
-App 使用 dataAppContext 精确选择授权 alias；Workspace 集成使用 dataDiscover/collectionList。数据访问授权不等于集合管理授权。网络/权限错误必须传播，不能返回空数组掩盖错误。

package/skills/tier0-sdk-v2-uns/references/restore.md

@@ -1,41 +0,0 @@
-# 恢复集合与记录
-
-| 方法 | 输入 | 返回 |
-| --- | --- | --- |
-| collectionRestore | dryRun、items[{id,expectedRevision}]、可选 mode/idempotencyKey | Outcome |
-| recordRestore | collectionId、ids（1–100）、可选 dryRun/idempotencyKey | restoredCount、restoredIds、status、replayed |
-
-集合 ID 和修订从 collectionList({archived:true,…}) 的实际归档项取得；不要使用归档前的旧修订。
-
-```ts
-import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
-
-export async function restoreCollection(
-  id: string, expectedRevision: NonNullable<UnsV2Request<'collectionRestore'>['items'][number]['expectedRevision']>,
-  intentKey: string, client: Tier0Client = createClient(),
-) {
-  const receipt = await client.uns.collectionRestore({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, expectedRevision }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt, current: (await client.uns.collectionGet({ id })).data };
-}
-export async function restoreDevice(
-  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const receipt = await client.uns.recordRestore({
-    collectionId, ids: [id], dryRun: false, idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed' || !receipt.data.restoredIds.includes(id)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  if (!found.data.items[0]) throw new Error('恢复有回执，读回未确认');
-  return { state: 'committed' as const, receipt, current: found.data.items[0] };
-}
-```
-
-Record 恢复重新校验当前 Schema 和有效唯一索引，冲突整批回滚；revision 递增。删除记录时关联 Sample 已物理删除，恢复不会重建历史。幂等键每个新意图独立，未知结果不要换键重试。

package/skills/tier0-sdk-v2-uns/references/update.md

@@ -1,86 +0,0 @@
-# 修改记录、集合元数据和 Schema
-
-| 方法 | 关键输入 | 语义 |
-| --- | --- | --- |
-| recordUpdateOne | collectionId、filter、update、expectedRevision | 修改一个精确目标 |
-| collectionUpdate | dryRun、items[].id/name/description/parentId/expectedRevision | 修改元数据 |
-| collectionSchemaUpdate | dryRun、items[].id/recordSchema/expectedRevision | 替换 recordSchema |
-
-写前读取 revision；冲突后重新比较并决策。省略 expectedRevision 可能覆盖最新状态，示例始终携带。
-
-## 修改一条设备记录
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function renameDevice(
-  collectionId: string, id: string, name: string, intentKey: string,
-  client: Tier0Client = createClient(),
-) {
-  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  const current = found.data.items[0];
-  if (!current) throw new Error('记录不存在或不可见');
-  const receipt = await client.uns.recordUpdateOne({
-    collectionId, filter: { _id: id }, expectedRevision: current.revision,
-    update: { $set: { name } }, upsert: false, dryRun: false, idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed' || String(receipt.data.matchedCount) !== '1') {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  if (after.data.items[0]?.data.name !== name) throw new Error('读回名称与目标不一致');
-  return { state: 'committed' as const, receipt, current: after.data.items[0] };
-}
-```
-
-data 返回 matchedCount、modifiedCount、status、replayed。modifiedCount=0 可能是值未变化；不能据此断言请求失败。upsert=false 避免不存在时意外创建。批量修改只在明确筛选范围和授权内使用。
-
-## 修改集合名称
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function renameCollection(
-  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const { data: current } = await client.uns.collectionGet({ id });
-  const receipt = await client.uns.collectionUpdate({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, name, expectedRevision: current.revision }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt, current: (await client.uns.collectionGet({ id })).data };
-}
-```
-
-## 扩展 Schema：添加可选位置字段
-
-```ts
-import { createClient, type Tier0Client, type Schema } from '@tier0/sdk-v2';
-
-export async function addDeviceLocation(
-  id: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const { data: current } = await client.uns.collectionGet({ id });
-  if (current.data.recordSchema.type !== 'object') throw new Error('此示例仅支持对象 Schema');
-  if (current.data.recordSchema.properties?.location) throw new Error('location 已定义，应先比较原 Schema');
-  const recordSchema: Schema = {
-    ...current.data.recordSchema,
-    properties: { ...current.data.recordSchema.properties, location: { type: 'string' } },
-  };
-  const item = { id, expectedRevision: current.revision, recordSchema };
-  const preview = await client.uns.collectionSchemaUpdate({ dryRun: true, mode: 'sync', items: [item] });
-  if (preview.data.status !== 'validated') throw new Error('Schema 预检未通过');
-  const receipt = await client.uns.collectionSchemaUpdate({
-    dryRun: false, mode: 'sync', allowPartial: false, items: [item], idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt, current: (await client.uns.collectionGet({ id })).data };
-}
-```
-
-recordSchema 是完整替换，不是 merge patch，也不自动迁移记录。新 Schema 必须接受已有数据并满足相关引用约束。sampleSchema/indexes 省略时保留；不要为了添加一个字段顺手清空它们。收紧类型、增加必填或删除采样 Schema 需额外评估已有数据。