# 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 加载 (而非硬编码) ```ts // ❌ 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 嵌套类) ```ts // 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 ') .option('--enCode ') .option('--type <1|2|3|4>') .option('--webType <1|2|3>') .option('--dbLinkId ') .option('--category ') .option('--fields ') .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 友好的帮助体系 ```bash # 基础 (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` 输出格式**: ```markdown # 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/ │ │ ├── .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. 反向链接 - [plan.md](plan.md) — 6 周路线 - [baseline.md](baseline.md) — 0 差错验证 - [api.md](api.md) — 完整 API - [extractors.md](extractors.md) — 提取工具 - [help-system.md](help-system.md) — 帮助体系 - [../.claude/skills/dacli-ts/SKILL.md](../.claude/skills/dacli-ts/SKILL.md) — AI 技能 - [../prompt.md](../prompt.md) — 任务说明书