实骨 shigu
0 Followers · 0 Following
  • Joined on 2026-08-12
Repositories Projects Packages Public Activity Starred Repositories

@tmxk-units/data-asset (0.1.0)

Published 2026-08-14 04:58:54 +00:00 by shigu

Installation

@tmxk-units:registry=https://gitea.cspy.site/api/packages/shigu/npm/
npm install @tmxk-units/data-asset@0.1.0
"@tmxk-units/data-asset": "0.1.0"

About this package

结构化数据资产的领域库，提供业务引用、Form Definition 驱动的记录校验、Schema View 和 Repository contract。它不是 TMXK 控制面、MCP SDK 或平台级数据代理。

TMXK Data Asset

结构化数据资产的领域库，提供业务引用、Form Definition 驱动的记录校验、Schema View 和 Repository contract。它不是 TMXK 控制面、MCP SDK 或平台级数据代理。

Repository 实现

  • createMemoryDataAssetRepositories()：内存实现，用于本地开发与契约测试。
  • 持久化 adapter：由使用该领域库的业务服务自行实现，并在自身数据边界内保存 Secret。

持久化映射约定：

  • 每个 scene 对应一个隔离集合：scene.{sceneKey | sceneId}；scene 元数据存于 asset_scenes。
  • record 的业务字段存于 data.fields，稳定元数据存于 data 根。
  • record.<field> 引用 record 顶层字段，data.<path> 引用记录数据内路径。
  • access 表达式必须来自业务服务验证后的 subject、tenant 和 policy，不能使用 caller 自报范围。

Repository 行为

  • Scene Key 在有效 Scene 中唯一；Schema Key 在所属 Scene 中唯一。
  • switchSceneKey 和 switchSchemaKey 必须原子完成目标切换和旧持有者归档，失败时不得留下部分修改。
  • Record 创建后的 revision 为 1。更新必须提交当前 expectedRevision，成功后 revision 加一；不匹配时抛出 reasonCode 为 version_conflict 的 DataAssetRepositoryError。
  • get、save、update 和 unbind 对不存在对象返回 null；delete 对不存在对象返回 false。
  • page 的 page 从 1 开始，pageSize 必须介于 1 和 100。未提供 sort 时按 updatedAt desc, id asc 稳定排序；自定义排序后仍必须追加 id asc 作为最终稳定排序键。
  • contains 是不区分大小写的文本包含；in 接受数组；between 接受 { from?, to? } 且边界闭合。adapter 不得接受 SQL、Mongo filter 或其他 driver 查询对象。
  • 行级策略由业务服务根据已验证 Token 和服务端 policy 计算。Repository 只接收受限的 JSON Logic DataAssetAccessExpression；adapter 必须在数据库查询中应用表达式，不得先读取全量记录再在内存中过滤。
  • adapter 必须将唯一性、版本、存储不可用和能力不支持错误翻译为 DataAssetRepositoryError，不得向调用方泄漏 driver 错误对象。
  • Date、attributes、data 和 Form Definition snapshot 必须按值返回，调用方修改返回对象不得直接改变持久化状态。

数据库 adapter 应对同一套 contract tests 运行创建、读取、稳定分页、唯一性冲突、版本冲突、原子 Key 切换、级联删除和失败回滚场景。具体 collection、table、索引和 migration 由使用它的业务服务负责。

import { defineDataAssetRepositoryContractTests } from "@tmxk-units/data-asset/contract-test";

defineDataAssetRepositoryContractTests("my adapter", async () => ({
  definitions: createDefinitionRepository(),
  records: createRecordRepository(),
}));

Dependencies

Development Dependencies

ID Version
@types/node ^24.0.13
typescript ^5.8.0
Details
npm
2026-08-14 04:58:54 +00:00
27
58 KiB
Assets (1)
data-asset-0.1.0.tgz 58 KiB
Versions (2) View all
0.1.1 2026-08-14
0.1.0 2026-08-14