用户拍板 (2026-06-25): dacli/doc/ 整个目录内容已废弃, 移到 dacli/docs/doc/deprecated/. 废弃原因: 1. v0.11+ webapi 镜像架构已替代所有 extract 脚本 + 静态 JSON 快照 (architecture.md api.md extractors.md 描述的方案过时) 2. 父 CLAUDE.md + dacli/CLAUDE.md 已合并, 不再需要独立 doc/ 维护 3. v0.11+ 30+ NEW-CMD + 18 webapi 模块, 旧 plan.md 描述的命令多数已废弃 22 文件全部 git mv (rename tracking 保留历史): - architecture.md / plan.md / api.md / extractors.md / baseline.md / help-system.md (架构 6) - ai-error-analysis.md / ai-optimization-plan.md (AI 分析 2) - audit-form-create-deviations.md / RESUME.md / verify-form-create-fix.mjs (实战 3) - v0.6 ~ v0.8.4-changelog.md (11 个版本变更日志) - v0.8-endpoints.md / v0.8-plan.md / v0.8-scan.md (v0.8 文档 3) 新增 docs/doc/deprecated/README.md 说明废弃原因 + 内容索引 + 下一步指引. 新文档统一写到 docs/ (cmd-review + skill-audit + web-patches + v0.11-next-steps-plan.md + source-analysis.md).
7.9 KiB
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/ 备查。
核心原则:
- 复用 web 源码 — 30 分钟跑脚本拿 53 控件 schema, 不手抄
- 0 差错基线 — developSystem 21 + workSystem 53 = 74 张官方示例
- Playwright 沉淀 —
@playwright/test(Node.js) 是基础设施, 不是可选 - 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. 反向链接
- plan.md — 6 周路线
- baseline.md — 0 差错验证
- api.md — 完整 API
- extractors.md — 提取工具
- help-system.md — 帮助体系
- ../.claude/skills/dacli-ts/SKILL.md — AI 技能
- ../prompt.md — 任务说明书