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

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) — 任务说明书