@ddd-tool/domain-designer-cli 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-tool/domain-designer-cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "description": "",
   "type": "module",
@@ -61,7 +61,7 @@
     "dev:ui": "pnpm -F @ddd-tool/domain-designer-ui-component dev",
     "dev:page": "pnpm -F github-pages dev",
     "build": "pnpm syncver && pnpm -r build && pnpm fmt",
-    "fmt": "pnpm exec prettier --write \"**/*.{vue,ts}\"",
+    "fmt": "pnpm exec prettier --write \"**/*.{vue,ts,mjs}\"",
     "test": "pnpm -r test",
     "test:cli": "pnpm -F cli test",
     "verify": "pnpm -r verify",

package/packages/core/dist/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ddd-tool/domain-designer-core",
   "private": false,
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "main": "./index.js",
   "module": "index.js",

package/packages/playground/package.json

@@ -1,19 +1,19 @@
-{
-  "name": "playground",
-  "version": "0.3.1",
-  "private": true,
-  "description": "",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "test": "exit 0",
-    "build": "exit 0",
-    "verify": "vue-tsc -p ./tsconfig.json"
-  },
-  "devDependencies": {
-    "@primeuix/themes": "^2.0.3",
-    "primeicons": "^7.0.0",
-    "primevue": "^4.5.4",
-    "vue": "^3.5.27"
-  }
-}
+{
+  "name": "playground",
+  "version": "0.3.2",
+  "private": true,
+  "description": "",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "test": "exit 0",
+    "build": "exit 0",
+    "verify": "vue-tsc -p ./tsconfig.json"
+  },
+  "devDependencies": {
+    "@primeuix/themes": "^2.0.3",
+    "primeicons": "^7.0.0",
+    "primevue": "^4.5.4",
+    "vue": "^3.5.27"
+  }
+}

package/packages/playground/vite.config.ts

@@ -1,22 +1,27 @@
-import { fileURLToPath, URL } from 'node:url'
-
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import vueDevTools from 'vite-plugin-vue-devtools'
-
-export default defineConfig({
-  plugins: [vue(), vueDevTools()],
-  esbuild: {
-    drop: ['console', 'debugger'], // 移除 console 和 debugger 语句
-  },
-  dev: {},
-  resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url)),
-      '@ddd-tool/domain-designer-core': fileURLToPath(new URL('../core/dist', import.meta.url)),
-      '@ddd-tool/domain-designer-ui-component': fileURLToPath(
-        new URL('../ui-component/dist', import.meta.url),
-      ),
-    },
-  },
-})
+import { fileURLToPath, URL } from 'node:url'
+
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueDevTools from 'vite-plugin-vue-devtools'
+
+export default defineConfig({
+  plugins: [vue(), vueDevTools()],
+  esbuild: {
+    drop: ['console', 'debugger'], // 移除 console 和 debugger 语句
+  },
+  server: {
+    fs: {
+      // Allow accessing files from global installation directories
+      strict: false,
+    },
+  },
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+      '@ddd-tool/domain-designer-core': fileURLToPath(new URL('../core/dist', import.meta.url)),
+      '@ddd-tool/domain-designer-ui-component': fileURLToPath(
+        new URL('../ui-component/dist', import.meta.url),
+      ),
+    },
+  },
+})

package/packages/ui-component/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddd-tool/domain-designer-ui-component",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "main": "index.umd.cjs",

package/scripts/build-ts.mjs

@@ -1,52 +1,52 @@
-import * as esbuild from 'esbuild'
-import fs from 'fs'
-import path from 'path'
-
-// 获取命令行参数
-const args = process.argv.slice(2) // 从第3个元素开始截取（跳过node和脚本路径）
-// 查找并解析 --source 参数
-let sourcePath = null
-for (const arg of args) {
-  if (arg.startsWith('--source=')) {
-    sourcePath = arg.split('=')[1] // 提取等号后面的值
-    break
-  }
-}
-if (!sourcePath) {
-  throw new Error('missing --source=<path>')
-}
-
-if (
-  !fs.existsSync(path.join(sourcePath, 'node_modules')) ||
-  !fs.statSync(path.join(sourcePath, 'node_modules')).isDirectory() ||
-  fs.existsSync(path.join(sourcePath, 'package.json'))
-) {
-  throw new Error('not a workspace: ' + sourcePath)
-}
-const esmPath = path.resolve(sourcePath, '.output', 'esm')
-if (fs.existsSync(esmPath)) {
-  fs.rmSync(esmPath, { recursive: true, force: true })
-}
-fs.mkdirSync(esmPath, { recursive: true })
-
-const files = fs.readdirSync(sourcePath)
-for (const file of files) {
-  if (file.endsWith('.ts')) {
-    console.log('compile', `${sourcePath.replaceAll('\\', '/')}/${file}`)
-    esbuild.build({
-      bundle: true,
-      entryPoints: [`${sourcePath.replaceAll('\\', '/')}/${file}`],
-      drop: ['debugger'],
-      minify: true,
-      outfile: `${esmPath.replaceAll('\\', '/')}/${file.replace(/\.ts$/, '.mjs')}`,
-      // sourcemap: true,
-      format: 'esm',
-      // format: 'cjs',
-      platform: 'node',
-      plugins: [],
-      target: 'node18',
-      // tsconfig: path.join(__dirname, '..', 'tsconfig.build-cli.json'),
-      tsconfig: path.join(__dirname, '..', 'tsconfig.json'),
-    })
-  }
-}
+import * as esbuild from 'esbuild'
+import fs from 'fs'
+import path from 'path'
+
+// 获取命令行参数
+const args = process.argv.slice(2) // 从第3个元素开始截取（跳过node和脚本路径）
+// 查找并解析 --source 参数
+let sourcePath = null
+for (const arg of args) {
+  if (arg.startsWith('--source=')) {
+    sourcePath = arg.split('=')[1] // 提取等号后面的值
+    break
+  }
+}
+if (!sourcePath) {
+  throw new Error('missing --source=<path>')
+}
+
+if (
+  !fs.existsSync(path.join(sourcePath, 'node_modules')) ||
+  !fs.statSync(path.join(sourcePath, 'node_modules')).isDirectory() ||
+  fs.existsSync(path.join(sourcePath, 'package.json'))
+) {
+  throw new Error('not a workspace: ' + sourcePath)
+}
+const esmPath = path.resolve(sourcePath, '.output', 'esm')
+if (fs.existsSync(esmPath)) {
+  fs.rmSync(esmPath, { recursive: true, force: true })
+}
+fs.mkdirSync(esmPath, { recursive: true })
+
+const files = fs.readdirSync(sourcePath)
+for (const file of files) {
+  if (file.endsWith('.ts')) {
+    console.log('compile', `${sourcePath.replaceAll('\\', '/')}/${file}`)
+    esbuild.build({
+      bundle: true,
+      entryPoints: [`${sourcePath.replaceAll('\\', '/')}/${file}`],
+      drop: ['debugger'],
+      minify: true,
+      outfile: `${esmPath.replaceAll('\\', '/')}/${file.replace(/\.ts$/, '.mjs')}`,
+      // sourcemap: true,
+      format: 'esm',
+      // format: 'cjs',
+      platform: 'node',
+      plugins: [],
+      target: 'node18',
+      // tsconfig: path.join(__dirname, '..', 'tsconfig.build-cli.json'),
+      tsconfig: path.join(__dirname, '..', 'tsconfig.json'),
+    })
+  }
+}

package/scripts/sync-version.mjs

@@ -1,22 +1,22 @@
-import fs from 'node:fs'
-import path from 'node:path'
-
-function syncVersion() {
-  const rootPath = path.resolve(import.meta.dirname, '..')
-  const packageInfo = JSON.parse(fs.readFileSync(path.join(rootPath, 'package.json'), 'utf-8'))
-  const version = packageInfo.version
-  if (!version) {
-    console.error('version not found')
-    process.exit(1)
-  }
-  fs.readdirSync(path.resolve(rootPath, 'packages')).forEach((pkgName) => {
-    const pkgPath = path.resolve(rootPath, 'packages', pkgName)
-    if (fs.existsSync(path.join(pkgPath, 'package.json'))) {
-      const pkgInfo = JSON.parse(fs.readFileSync(path.join(pkgPath, 'package.json'), 'utf-8'))
-      pkgInfo.version = version
-      fs.writeFileSync(path.join(pkgPath, 'package.json'), JSON.stringify(pkgInfo, null, 2) + '\n', 'utf-8')
-    }
-  })
-}
-
-syncVersion()
+import fs from 'node:fs'
+import path from 'node:path'
+
+function syncVersion() {
+  const rootPath = path.resolve(import.meta.dirname, '..')
+  const packageInfo = JSON.parse(fs.readFileSync(path.join(rootPath, 'package.json'), 'utf-8'))
+  const version = packageInfo.version
+  if (!version) {
+    console.error('version not found')
+    process.exit(1)
+  }
+  fs.readdirSync(path.resolve(rootPath, 'packages')).forEach((pkgName) => {
+    const pkgPath = path.resolve(rootPath, 'packages', pkgName)
+    if (fs.existsSync(path.join(pkgPath, 'package.json'))) {
+      const pkgInfo = JSON.parse(fs.readFileSync(path.join(pkgPath, 'package.json'), 'utf-8'))
+      pkgInfo.version = version
+      fs.writeFileSync(path.join(pkgPath, 'package.json'), JSON.stringify(pkgInfo, null, 2) + '\n', 'utf-8')
+    }
+  })
+}
+
+syncVersion()

package/templates/CLAUDE.md

@@ -18,6 +18,37 @@ import { createDomainDesigner } from '@ddd-tool/domain-designer-core'
 const d = createDomainDesigner()
 ```
 
+### Initialization Options
+
+Optional parameters for `createDomainDesigner()`:
+
+```typescript
+const d = createDomainDesigner({
+  moduleName: 'order', // Module name for code generation
+  ignoreValueObjects: ['time'], // Value object names to ignore during code generation
+})
+```
+
+| Parameter            | Type     | Description                                       | Default Value                                                                                                                                     |
+| -------------------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `moduleName`         | string   | Module name for code bundling                     | File name                                                                                                                                         |
+| `ignoreValueObjects` | string[] | Value object names to skip during code generation | ['time', 'id', 'pid', 'name', 'state', 'status', 'version', 'code', 'message', 'type', 'result', 'data', 'payload', 'meta', 'context', 'sorting'] |
+
+**Why `ignoreValueObjects`?** Generic names like `time` or `name` have weak business meaning. During code generation, they should be treated as primitive types rather than value objects.
+
+### Common Pattern: `const i = d.info`
+
+It's common to alias `d.info` as `i` for brevity:
+
+```typescript
+const d = createDomainDesigner()
+const i = d.info
+
+// Now you can use i instead of d.info
+const userId = i.id('userId')
+const userName = i.valueObj('userName', '用户名')
+```
+
 ### Available Methods
 
 | Method                | Purpose                                              |
@@ -47,6 +78,32 @@ const workflowName = d.startWorkflow('CreateOrder')
 actor.command(createOrder).agg(orderAgg).event(orderCreated)
 ```
 
+### Node Method Reference
+
+Each type of node has specific methods that can be called in a workflow:
+
+| Node Type         | Available Methods                                      | Description                              |
+| :---------------- | :----------------------------------------------------- | :--------------------------------------- |
+| **Actor**         | `.command()`, `.facadeCmd()`, `.readModel()`           | Initiates commands or reads data         |
+| **Command**       | `.agg()`                                               | Targets an aggregate                     |
+| **FacadeCommand** | `.agg()`, `.service()`                                 | Targets aggregate or calls service       |
+| **Aggregate**     | `.event()`, `.command()`                               | Emits event or creates nested command    |
+| **Event**         | `.policy()`, `.system()`, `.readModel()`, `.command()` | Triggers policy/system/readModel/command |
+| **Policy**        | `.command()`, `.facadeCmd()`, `.service()`             | Issues commands or calls service         |
+| **Service**       | `.command()`, `.facadeCmd()`, `.agg()`                 | Issues commands or targets aggregate     |
+| **System**        | `.command()`, `.facadeCmd()`, `.event()`               | Issues commands or emits events          |
+
+**Important**: Each method call in a workflow returns a reference to the target node, allowing you to continue chaining:
+
+```typescript
+d.startWorkflow('Example')
+//      Actor       →    Command    →  Aggregate  →   Event
+customer.command(createOrder).agg(orderAgg).event(orderCreated)
+//                                                      ↓
+//                                            Event → Policy
+//                                              orderCreated.policy(autoConfirmPolicy)
+```
+
 ### Complete Example
 
 ```typescript
@@ -114,14 +171,15 @@ For larger domains, split into modules:
 // common.ts - Shared setup
 import { createDomainDesigner } from '@ddd-tool/domain-designer-core'
 export const d = createDomainDesigner({ moduleName: 'my-domain' })
+export const i = d.info
 
 // user.ts - User domain
-import { d } from './common'
+import { d, i } from './common'
 const user = d.actor('用户')
 // ... more definitions
 
 // book.ts - Book domain
-import { d } from './common'
+import { d, i } from './common'
 const book = d.agg('图书')
 // ... more definitions
 
@@ -132,14 +190,193 @@ import './book'
 export default d
 ```
 
+### Value Pool Pattern ("常量池")
+
+For domains with multiple related aggregates, organize reusable values into "value pools":
+
+```typescript
+// book.ts
+import { d, i } from './common'
+
+export const bookValues = {
+  ISBN: i.id('isbn', '国际标准书号 - 一书一码'),
+  图书名称: i.valueObj('bookName', '图书名称'),
+  图书价格: i.valueObj('bookPrice', '图书价格'),
+}
+
+const 图书聚合 = d.agg('BookAgg', [bookValues.ISBN, bookValues.图书名称], '图书聚合')
+
+// order.ts
+import { d, i } from './common'
+import { bookValues } from './book'
+
+export const orderValues = {
+  订单流水号: i.id('orderSequence', '订单流水号'),
+  订购数量: i.valueObj('quantity', '订购数量'),
+  最终价格: i.func(
+    '最终价格',
+    [bookValues.图书价格, orderValues.订购数量],
+    '最终价格 = 图书价格 * 订购数量',
+  ),
+}
+
+// Cross-reference values using d.note()
+const 全局流水号 = i.valueObj('globalSequence', d.note`全局流水号由${上游系统}接口统一生成`)
+```
+
+**Benefits of value pools:**
+
+- Avoids repeated definitions
+- Serves as a "glossary" for domain terms
+- Makes cross-references explicit using `d.note()`
+
 ## Value Object Types
 
 ```typescript
 d.info.id('name') // ID type
-d.info.document('name') // Document type
-d.info.func('name') // Function type
+d.info.document('name') // Document type (experimental)
+d.info.func('name') // Function type (experimental)
 d.info.valueObj('name') // Value Object type
-d.info.version('name') // Version type
+d.info.version('name') // Version type (experimental)
+```
+
+### Naming Conventions
+
+**Variable names**: Use Chinese/native language for better domain understanding:
+
+```typescript
+const 图书价格 = i.valueObj('bookPrice', '图书价格')
+const 用户名 = i.valueObj('userName', '用户名')
+```
+
+**Type/Node names**: Use English for the first parameter (actual code name), Chinese for documentation:
+
+```typescript
+// First parameter = code name (English)
+// Second parameter = documentation (Chinese)
+const 图书价格 = i.valueObj('bookPrice', '图书价格')
+d.command('CreateUser', [用户名, 邮箱], '创建用户')
+d.agg('UserAgg', [用户id], '用户聚合')
+d.event('UserCreated', [用户id], '用户已创建')
+```
+
+### Shorthand Syntax
+
+All nodes accept plain strings as parameters. The shorthand `['fieldName', '备注']` syntax is equivalent to `i.valueObj('fieldName', '备注')`:
+
+```typescript
+// Both are equivalent - use d.info functions for clarity
+d.command('CreateUser', [i.valueObj('userName'), i.valueObj('email'), i.valueObj('gender', '性别')])
+
+// Shorthand form
+d.command('CreateUser', ['userName', 'email', ['gender', '性别']])
+```
+
+**Recommendation**: Prefer `d.info` functions for explicit type marking, especially for value objects that have business meaning. Use shorthand only for generic fields like `time` or `id`.
+
+### Experimental Features
+
+The following value types are experimental and their necessity is still being evaluated:
+
+- **`document`** - For document or binary file values
+- **`func`** - For values computed by functions
+- **`version`** - For version numbers with business meaning
+
+## Adding Documentation (Notes)
+
+Most node functions accept a **last parameter** for documentation:
+
+```typescript
+// Simple documentation using a string
+const orderCreated = d.event('OrderCreated', [orderId], '订单已创建')
+const orderAgg = d.agg('OrderAgg', [orderId], '订单聚合')
+const createOrder = d.command('CreateOrder', [orderId], '创建订单')
+```
+
+### Advanced Documentation with `d.note()`
+
+`d.note()` is an advanced form of documentation that enables:
+
+1. **Referencing other nodes** using `${node}` syntax (creates traceability)
+2. **Multi-line business rules** with numbered lists
+3. **Cross-module references** between domain concepts
+
+#### When to Use `d.note()`
+
+**Use simple strings** for basic descriptions:
+
+```typescript
+const addBook = d.command('AddToAvailableBooksCmd', [isbn, qrCode], '添加可预订书')
+```
+
+**Use `d.note()` when you need to:**
+
+- Reference other nodes/values in the domain
+- Document complex business rules
+- Explain domain-specific concepts
+
+#### Referencing Other Nodes
+
+Use the `${node}` syntax to create explicit links between concepts:
+
+```typescript
+// In user.ts
+export const userValues = {
+  用户id: i.id('userId'),
+  逾期次数: i.valueObj('overdueCount', '逾期次数'),
+}
+
+// In book.ts - reference using ${userValues.逾期次数}
+const timeoutCommand = d.command(
+  'TimeOutBorrowing',
+  ['借书id'],
+  d.note`逾期
+    1. 书被借出，且1个月未还
+    2. 增加借书会员的${userValues.逾期次数}`,
+)
+
+// Creates traceability - shows which value is being modified
+const suspendPolicy = d.policy('SuspendAccountWhenTimeOut', d.note`增加账户${userValues.逾期次数}`)
+```
+
+#### Business Rules with Lists
+
+```typescript
+const reserveBook = d.command(
+  'ReserveBook',
+  [isbn, 'userId'],
+  d.note`预定书
+    1. 有可预定的书
+    2. 会员账户没有被暂停
+    3. 会员已预定或者借出的书小于3本`,
+)
+
+const borrowService = d.service(
+  'BorrowBookService',
+  d.note`借书服务
+    书可预定则可借出
+    书已预定时借书人是预定则可借`,
+)
+```
+
+#### Complex Value Objects
+
+For domain-specific or complex types:
+
+```typescript
+const qrCodeSet = i.valueObj('二维码集合', d.note`${bookValues.二维码} // 一书一码，业务唯一标识`)
+
+const isbn = i.valueObj('isbn', d.note`国际标准书号 (ISBN-13)`)
+```
+
+**Key Point**: `d.note()` creates traceability. When a business rule mentions another concept, reference it explicitly:
+
+```typescript
+// Good - Creates explicit link
+d.note`增加${userValues.逾期次数}`
+
+// Avoid - No traceability
+d.note`增加逾期计数`
 ```
 
 ## Modeling Guidelines
@@ -191,20 +428,44 @@ const orderCreated = d.command('订单已创建') // Avoid - sounds like an even
 Policies automate business rules:
 
 ```typescript
-const paymentPolicy = d.policy('支付超时取消规则')
+const paymentTimeoutPolicy = d.policy('支付超时取消规则')
 const cancelOrder = d.command('取消订单')
+const orderCancelled = d.event('订单已取消')
+const orderAgg = d.agg('订单聚合', [d.info.id('订单号')])
 
-// When payment timeout event occurs, trigger cancellation
-paymentTimeout.event(cancelOrder)
+// When payment timeout event occurs, policy triggers cancellation
+d.startWorkflow('支付超时取消流程')
+paymentTimeout.policy(paymentTimeoutPolicy).command(cancelOrder).agg(orderAgg).event(orderCancelled)
 ```
 
-### External Systems
+### Event to External Systems
 
-Integrate with external systems:
+Events can trigger actions in external systems:
 
 ```typescript
 const emailSystem = d.system('邮件系统')
-orderCreated.event(emailSystem)
+const smsSystem = d.system('短信系统')
+
+// In a workflow, connect events to systems
+d.startWorkflow('订单创建通知流程')
+orderCreated.system(emailSystem)
+orderCreated.system(smsSystem)
+```
+
+### Event to Read Models
+
+Events update read models:
+
+```typescript
+const orderSummary = d.readModel('订单汇总读模型', [
+  d.info.id('订单号'),
+  d.info.document('商品信息'),
+  d.info.version('订单状态'),
+])
+
+// In a workflow, connect events to read models
+d.startWorkflow('订单查询流程')
+orderCreated.readModel(orderSummary)
 ```
 
 ### Read Models
@@ -265,7 +526,7 @@ When helping with domain modeling:
 
 If you see errors like:
 
-```
+```text
 The requested module does not provide an export named 'X'
 ```
 

package/templates/complex-example-detail/book.ts

@@ -144,19 +144,22 @@ const 逾期 = d.command(
   ['借书id'],
   d.note`逾期
     1.书被借出，且1个月未还
-    2.增加借书会员的逾期次数`,
+    2.增加借书会员的${userValues.逾期次数}`,
 )
 
 const 书聚合 = d.agg('BookAgg', [bookValues.二维码], '书聚合')
 
 const 用户占用书聚合 = d.agg('UserOcuppyBookAgg', [userValues.用户id, '占用数量'], '用户占用书聚合')
 
-const 增加账户逾期次数规则 = d.policy('SuspendAccountWhenTimeOut', d.note`增加账户逾期次数`)
+const 增加账户逾期次数规则 = d.policy(
+  'SuspendAccountWhenTimeOut',
+  d.note`增加账户${userValues.逾期次数}`,
+)
 
 const 增加逾期次数 = d.command(
   'IncreaseAccountTimeOutCount',
   [userValues.用户id],
-  d.note`增加逾期次数
+  d.note`增加${userValues.逾期次数}
     1.会员累计逾期达到3次暂停账户
     2.会员账户当前是启用才能被暂停`,
 )

package/templates/node_modules/version.txt

@@ -1 +1 @@
-0.3.1
+0.3.2