@yss123/cage-kernel 0.4.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -57
- package/dist/scope/index.d.ts +7 -1
- package/dist/scope/index.js +7 -3
- package/dist/scope/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,81 +1,41 @@
|
|
|
1
1
|
# @yss123/cage-kernel
|
|
2
2
|
|
|
3
|
-
Cage
|
|
3
|
+
Cage 的领域声明和执行核心：聚合、命令、读取、状态、范围、事务、审计、事件与 worker。普通业务通过这些声明表达规则，由内核统一提交变化。
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## 安装与最小声明
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```powershell
|
|
10
|
-
pnpm add @yss123/cage-kernel zod
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
新项目推荐 `pnpm create @yss123/cage-app my-app --template blank`，由模板配置 domain、API、worker、Web 与数据库连接。
|
|
14
|
-
|
|
15
|
-
## 最小业务声明
|
|
16
|
-
|
|
17
|
-
在 `packages/domain/src/modules/note/note.ts` 中声明便笺。声明本身不连接数据库；handler 返回业务变化，由内核负责真正写入。
|
|
7
|
+
在 domain 包安装 pnpm add @yss123/cage-kernel zod，框架包保持同版本，服务端需要 Node.js 24+ 和 PostgreSQL。下面是领域模块片段：
|
|
18
8
|
|
|
19
9
|
```ts
|
|
20
|
-
/** 部门便笺声明；经 domain 根入口注册，供 CLI 生成契约与 API 执行。 */
|
|
21
10
|
import { aggregate, command, ref, scope, states, text } from '@yss123/cage-kernel';
|
|
22
11
|
import { z } from 'zod';
|
|
23
12
|
|
|
24
|
-
/**
|
|
13
|
+
/** 部门便笺的身份、标题和生命周期；实际范围由角色授权决定。 */
|
|
25
14
|
export const Note = aggregate('Note', {
|
|
26
15
|
description: '部门便笺',
|
|
27
16
|
fields: {
|
|
28
|
-
title: text(120),
|
|
29
|
-
deptId: ref('Dept'),
|
|
30
|
-
createdBy: ref('User'),
|
|
17
|
+
title: text(120).describe('标题'),
|
|
18
|
+
deptId: ref('Dept').describe('部门'),
|
|
19
|
+
createdBy: ref('User').describe('创建人'),
|
|
31
20
|
},
|
|
32
|
-
states: states('active', '
|
|
33
|
-
scope: scope.
|
|
34
|
-
invariants: { titleNotBlank: (note) => note.title.trim().length > 0 },
|
|
21
|
+
states: states('active', { terminal: ['active'], labels: { active: '已创建' } }),
|
|
22
|
+
scope: scope.dept('deptId'),
|
|
35
23
|
});
|
|
36
24
|
|
|
37
|
-
/**
|
|
25
|
+
/** 创建有效便笺；持久化、归属、权限和审计由内核处理。 */
|
|
38
26
|
export const createNote = command(Note, {
|
|
39
|
-
name: 'create',
|
|
40
|
-
description: '创建部门便笺',
|
|
41
|
-
from: 'new',
|
|
42
|
-
to: 'active',
|
|
27
|
+
name: 'create', description: '创建便笺', from: 'new', to: 'active',
|
|
43
28
|
input: z.object({ title: z.string().trim().min(1).max(120) }),
|
|
44
|
-
handler:
|
|
29
|
+
handler: draft => draft,
|
|
45
30
|
});
|
|
46
31
|
```
|
|
47
32
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
```ts
|
|
51
|
-
/** 组合所有可注册声明；未从这里导出的业务不会进入生成器和运行注册表。 */
|
|
52
|
-
export * from '@yss123/cage-admin/domain';
|
|
53
|
-
export * from './modules/note/index.js';
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
随后在应用根目录执行 `pnpm exec cage check`、`pnpm gen`；审查迁移后执行 `pnpm migrate`。管理员为目标角色授予 `Note.create`、`Note.read` 及 `Note` 数据范围，前端通过生成的 `@app/contracts` 调用 `note.create({ title })`、`note.list()`。
|
|
57
|
-
|
|
58
|
-
## 主要能力与边界
|
|
59
|
-
|
|
60
|
-
| 入口 | 用途 |
|
|
61
|
-
| --- | --- |
|
|
62
|
-
| `aggregate`、字段工厂、`states`、`scope` | 定义对象字段、关系、生命周期与范围字段 |
|
|
63
|
-
| `command`、`event`、`emit` | 定义唯一业务写入口及成功后产生的事实 |
|
|
64
|
-
| `reaction`、`reactionEach`、`job` | 同事务或异步协作、有界集合处理和定时任务 |
|
|
65
|
-
| `query`、`ReadSide` | 通过只读账号与 `safe.*` 安全视图读取 |
|
|
66
|
-
| `buildRegistry`、`createKernel` | 服务端集成时构建注册表和执行内核；普通应用交给 HTTP 装配 |
|
|
67
|
-
| `@yss123/cage-kernel/worker` | 底层 worker 启停、消费者和健康状态 |
|
|
68
|
-
| `@yss123/cage-kernel/db` | 迁移、DDL 与数据库基础设施，供工具链使用 |
|
|
69
|
-
| `@yss123/cage-kernel/brands` | 框架声明标识 |
|
|
70
|
-
|
|
71
|
-
handler 的读取写入 `reads`，任务的读取和命令调用写入 `reads/calls`。handler 不直接执行 SQL、HTTP 或文件 IO；外呼使用连接器。`scope` 声明不自动授权，前端 `can()` 不代替后端检查。`ref/hasMany/manyToMany` 统一写在 `fields`，集合关系由命令修改并通过安全读侧分页读取。
|
|
33
|
+
沿模块入口导出到 domain，保留组织模型，执行 check/gen、审查迁移并 migrate。角色获得 Note.read/create 及相应范围后，页面使用生成契约。
|
|
72
34
|
|
|
73
|
-
|
|
35
|
+
## 使用边界
|
|
74
36
|
|
|
75
|
-
|
|
37
|
+
handler 的依赖写入 reads，任务调用写入 reads/calls；数据库、网络和文件 IO 由框架对应层执行。from/to 控制状态，约束在 handler 前检查，不变量检查最终对象，same 反应共同回滚。
|
|
76
38
|
|
|
77
|
-
|
|
78
|
-
- [原语、命令与查询](https://github.com/shunshunyue/cage/blob/main/docs/development/reference/primitives.md)
|
|
79
|
-
- [对象关系](https://github.com/shunshunyue/cage/blob/main/docs/development/guides/relations.md)
|
|
39
|
+
服务集成使用 createKernel/buildRegistry/ReadSide，数据库与 worker 另有 /db、/worker 子入口。浏览器使用 client 和 contracts。金额用十进制字符串，系统列由内核维护。
|
|
80
40
|
|
|
81
|
-
|
|
41
|
+
[完整入门课](https://github.com/shunshunyue/cage/blob/main/docs/development/getting-started/first-feature.md) · [原语参考](https://github.com/shunshunyue/cage/blob/main/docs/development/reference/primitives.md) · [执行边界](https://github.com/shunshunyue/cage/blob/main/docs/development/reference/execution.md)
|
package/dist/scope/index.d.ts
CHANGED
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 提供聚合的范围字段元数据，以及读写执行层共用的 SQL/内存范围判定。
|
|
3
|
+
* 聚合声明负责定位部门和所有者，角色 grants 决定实际组合子；本模块不加载授权或连接数据库。
|
|
4
|
+
* 各种匹配始终结合租户与真实主体，字段或所需上下文缺失时不能推断为全部可见。
|
|
5
|
+
*/
|
|
1
6
|
import { type RawBuilder } from 'kysely';
|
|
2
7
|
import type { Combinator, Ctx, ScopeGrant } from '../types.js';
|
|
3
8
|
export interface ScopeSpec {
|
|
@@ -13,7 +18,8 @@ export interface ScopeSpec {
|
|
|
13
18
|
* scope.deptSubtree('deptId') 部门字段是 deptId，创建人字段自动识别 createdBy
|
|
14
19
|
* scope.self('createdBy') 只有创建人字段
|
|
15
20
|
* scope.of({ dept: 'deptId', owner: 'ownerId' })
|
|
16
|
-
* scope.none()
|
|
21
|
+
* scope.none() 不提供范围字段；aggregate 仍会自动识别已有 createdBy
|
|
22
|
+
* none/all 的声明都不授予能力或全部范围；没有可用归属字段时，self/dept 无法匹配，需要实际 all 授权。
|
|
17
23
|
*/
|
|
18
24
|
export declare const scope: {
|
|
19
25
|
self: (ownerField?: string) => ScopeSpec;
|
package/dist/scope/index.js
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* 提供聚合的范围字段元数据，以及读写执行层共用的 SQL/内存范围判定。
|
|
3
|
+
* 聚合声明负责定位部门和所有者，角色 grants 决定实际组合子；本模块不加载授权或连接数据库。
|
|
4
|
+
* 各种匹配始终结合租户与真实主体，字段或所需上下文缺失时不能推断为全部可见。
|
|
5
|
+
*/
|
|
3
6
|
import { sql } from 'kysely';
|
|
4
7
|
import { snake } from '../util/names.js';
|
|
5
8
|
function spec(hint, deptField, ownerField) {
|
|
@@ -10,7 +13,8 @@ function spec(hint, deptField, ownerField) {
|
|
|
10
13
|
* scope.deptSubtree('deptId') 部门字段是 deptId，创建人字段自动识别 createdBy
|
|
11
14
|
* scope.self('createdBy') 只有创建人字段
|
|
12
15
|
* scope.of({ dept: 'deptId', owner: 'ownerId' })
|
|
13
|
-
* scope.none()
|
|
16
|
+
* scope.none() 不提供范围字段；aggregate 仍会自动识别已有 createdBy
|
|
17
|
+
* none/all 的声明都不授予能力或全部范围；没有可用归属字段时，self/dept 无法匹配，需要实际 all 授权。
|
|
14
18
|
*/
|
|
15
19
|
export const scope = {
|
|
16
20
|
self: (ownerField = 'createdBy') => spec('self', undefined, ownerField),
|
package/dist/scope/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scope/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scope/index.ts"],"names":[],"mappings":"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"}
|