参考 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
269 lines
7.9 KiB
Markdown
269 lines
7.9 KiB
Markdown
# 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 <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 友好的帮助体系
|
|
|
|
```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/
|
|
│ │ ├── <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](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) — 任务说明书
|