Files
dacli/doc/architecture.md
T
ssw c98ad4f425 init: TS 版 dacli v0.7 baseline (8 父命令/26+ 子命令, 0.4MB, .claude/skills/dacli-ts)
参考 boot/ 仓库结构初始化, 同步到 gitea:3000/ssw/dacli (private).

包括:
- src/  8 父命令 (form/menu/dm/dict/di/apis/doc/workflow + login/status) + core (client/crypto/help/log/types/config)
- src/schema/ FieldBuilder (从 JNPF web 源码提取, 避免 53 个手写 builder)
- tests/ vitest 单元 + playwright E2E (含 workSystem/developSystem baseline regression)
- scripts/ extract-all.mjs (从 jnpf-web 源码生成 schema) + seed-tds-baseline.ts
- doc/  architecture/plan/api/extractors/baseline/RESUME/help-system + v0.6/v0.7 changelog
- .claude/skills/dacli-ts/  Claude 集成 skill (SKILL.md + 5 references + 7 examples + 3 baseline)
- CLAUDE.md (项目说明) + README.md + prompt.md (开发任务说明书)
- 配置文件: package.json/lock, tsconfig, vitest.config, playwright.config
2026-06-12 18:26:39 +08:00

7.9 KiB

architecture.md — TS 版 dacli 架构设计

位置: $ccWorkDir/dacli/doc/architecture.md(原 test/dacli/, 2026-06-12 升级到顶层) 目标: 让接手的人理解 6 个关键设计决策

1. 总览

TS 版 dacli 是当前主用 CLI,在 $ccWorkDir/dacli/ 独立运行。Java 版 ssw-dacli 已废弃归档到 docs/dacli/ssw-dacli/ 备查。

核心原则:

  1. 复用 web 源码 — 30 分钟跑脚本拿 53 控件 schema, 不手抄
  2. 0 差错基线 — developSystem 21 + workSystem 53 = 74 张官方示例
  3. Playwright 沉淀 — @playwright/test (Node.js) 是基础设施, 不是可选
  4. AI 友好 — --ai-help 输出 markdown, SKILL.md 教 AI 何时用

2. 6 个关键决策

2.1 复用 web 源码 (而非重写)

对比:

路线 工作量 维护 升级
Java 版 dacli (现状) 6 月手写 53 builder 53 builder 硬编码 改 53 文件
TS 版 dacli (本项目) 30 分钟跑 extract 脚本 data/*.json 自动 重跑 extract

复用清单 (4 类资产):

资产 来源 提取工具 输出
加密 web/.../cipher.ts crypto-js 1:1 复刻 core/crypto.ts
L1 正则 web/.../formValidate.ts extract-l1.ts data/validation-rules.json
componentMap web/.../componentMap.ts extract-component-map.ts data/component-map.json
Rxxx.vue schema web/.../rightComponents/R*.vue extract-fields.ts (vue SFC parse) data/field-schemas.json

2.2 Node.js 生态 (而非 Python/Java)

选型:

  • 运行时: Node 22 内置 fetch (零依赖)
  • CLI: Commander.js (TS 生态最成熟, 嵌套子命令链)
  • 缓存: better-sqlite3 (同步 API, TS 类型完整)
  • 加密: crypto-js (与 web cipher.ts 字节级一致)
  • E2E: @playwright/test (Node, 同 dacli 进程)

避免:

  • ❌ 不用 Python Playwright (跨语言, 不能 import dacli 模块)
  • ❌ 不用 tsc (tsx 零编译, 探索性开发更快)
  • ❌ 不用 axios (Node 22 fetch 够用)
  • ❌ 不用 yargs (API 笨重)

2.3 FieldBuilder 从 JSON 加载 (而非硬编码)

// ❌ Java 版: 53 个硬编码 builder
class InputFieldBuilder {
  buildSchema() {
    return { /* 43 字段硬编码 */ }
  }
}

// ✅ TS 版: 1 个通用 builder + 39 个 JSON schema
class FieldBuilder {
  loadSchema(jnpfKey: string) {
    return fieldSchemas[jnpfKey]  // 从 data/field-schemas.json
  }
}

好处:

  • JNPF 升级时: npm run extract 重跑, 自动更新
  • 测试时: 改 JSON 即改 builder, 不用编译
  • 维护时: 1 个文件管 39 控件, 不 53 个

2.4 嵌套子命令 (参考 Java 嵌套类)

// src/commands/form.ts
import { Command } from 'commander'

const formCmd = new Command('form')
  .description('表单管理')

formCmd
  .command('list')
  .description('列表单')
  .action(async () => { /* ... */ })

formCmd
  .command('create')
  .description('建表单')
  .option('--fullName <n>')
  .option('--enCode <e>')
  .option('--type <1|2|3|4>')
  .option('--webType <1|2|3>')
  .option('--dbLinkId <id>')
  .option('--category <c>')
  .option('--fields <json>')
  .option('--autoTable')
  .option('--autoRelease')
  .action(async (opts) => { /* ... */ })

// 在 cli.ts 注册
program.addCommand(formCmd)

对比 Java 嵌套类:

  • Java: @Command(subcommands = {FormCommand.ListCommand.class, ...})
  • TS: formCmd.command('list').action(...)

优势: 同一文件管同一父命令, 不用 109 个文件 (Java 阶段 6 重构后是 19 个, TS 模式类似)。

2.5 AI 友好的帮助体系

# 基础 (Commander.js 自动)
dacli form create --help

# AI 专用 (核心增强)
dacli form create --ai-help
# → 输出可喂给 LLM 的 markdown 块

# 例子
dacli form create --example
# → 输出 JSON 示例

# 调试
dacli form create --source
# → 指向 web 源文件 (Form.vue:444-465)

--ai-help 输出格式:

# dacli form create

## 用途
创建一张 JNPF 功能表单

## 必传参数
- `--fullName` (string): 表单中文名
- `--enCode` (string): 表单英文编码
- `--type` (1|2|3|4): 1=自定义 2=系统 3=接口 4=视图
...

## 来源
- web 源码: web/.../formDesign/Form.vue:444-465
- API: POST /api/visualdev/Base

## 例子
\`\`\`bash
dacli form create --fullName="请假" --enCode=leave --type=4 --webType=1
\`\`\`

2.6 Playwright Node.js 集成 (而非外挂)

为什么 Node.js 而不是 Python:

  • 同语言: 与 dacli 都是 TS, 可直接 import
  • 同进程: import { FormService } from '../src/commands/form.js'
  • 同 tsconfig: 共享类型
  • 一个 Node.js 生态搞定

集成方式:

dacli/
├── src/                    # dacli 源码
├── tests/e2e/             # Playwright 测试
│   └── baseline/          # 114 张 baseline
│       ├── developSystem/
│       │   ├── <enCode>.spec.ts
│       │   └── ...
│       └── workSystem/
└── playwright.config.ts   # 共用配置

3. 目录结构 (完整)

dacli/
├── prompt.md                     # 任务说明书
├── README.md
├── package.json
├── tsconfig.json
├── playwright.config.ts
│
├── src/                          # dacli CLI
│   ├── cli.ts
│   ├── commands/                 # 嵌套子命令
│   ├── core/                     # 基础设施
│   ├── extractors/               # web 源码提取
│   ├── data/                     # 提取的 JSON
│   └── schema/                   # FieldBuilder
│
├── .claude/skills/dacli-ts/      # AI skill
│   ├── SKILL.md
│   ├── references/               # 6+ 文档
│   └── examples/                 # 7+ 可复用脚本
│
├── doc/                          # 人类详细文档
│   ├── architecture.md           # 本文件
│   ├── plan.md
│   ├── baseline.md
│   ├── api.md
│   ├── extractors.md
│   └── help-system.md
│
├── tests/                        # Playwright + vitest
│   ├── e2e/baseline/             # 74 张
│   ├── e2e/api/                  # API 层
│   ├── e2e/visual/               # 视觉对比
│   └── unit/                     # 单元
│
├── screenshots/                  # 截图 (gitignored)
├── scripts/                      # extract-all / verify-baseline
└── .dacli-cache.db               # SQLite 缓存

4. 数据流

JNPF web 源码
  ├─ cipher.ts
  ├─ formValidate.ts
  ├─ componentMap.ts
  └─ Rxxx.vue
       │
       ▼ (extractors/*.ts, tsx 一键跑)
       │
data/*.json (git-tracked)
  ├─ component-map.json (60+ jnpfKey → tag)
  ├─ field-schemas.json (39 控件 schema)
  ├─ validation-rules.json (14 L1 正则)
  └─ l2-rules.json (30+ L2 错误消息)
       │
       ▼ (FieldBuilder 加载)
       │
dacli form create (动态生成 form JSON)
       │
       ▼ (HTTP 调用 JNPF API)
       │
JNPF 后端 (新建/修改/发布表单)
       │
       ▼ (Playwright 验证)
       │
74 张 baseline 0 视觉差 ✓

5. 与 Java 版的关系

维度 Java 版 TS 版
稳定 ⭐⭐⭐⭐⭐ ⭐⭐
AI 友好 ⭐⭐⭐ ⭐⭐⭐⭐⭐
Schema 真相 53 builder 硬编码 data/*.json 自动
Baseline 40 form 74 form
Playwright ssw-e2e-test (Python) @playwright/test (Node)
定位 生产 实验

v1 不替代。v2 评估后再决定。

6. 反向链接