参考 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
20 KiB
TS 版 dacli — 主提示词 (开发任务说明书)
位置:
$ccWorkDir/dacli/(原test/dacli/, 2026-06-12 升级到顶层独立项目) 目标: 在$ccWorkDir/dacli/内交付 两件套——
dacliCLI 工具 (TypeScript) — 借鉴 Java 版架构 + 复用 JNPF web 源码.claude/skills/dacli-ts/SKILL.md— AI 专用技能,告诉 AI 何时用哪个命令目标 0 差错: 以官方示例 (workSystem 85 + developSystem 29 = 114 张表单) 为基线,dacli 复刻必须 API 0 错 + 浏览器层 0 视觉差
应用对象:
tds(http://nginx/ ,你在容器内 后端api 代理到 http://nginx/api -> http://127.0.0.1:30000/api) |admin / 123456
0. 启动指令 (新会话第一句)
按 $ccWorkDir/dacli/prompt.md 在 $ccWorkDir/dacli/ 内交付 dacli + skill 两件套。
目标 0 差错: 以 developSystem/workSystem 官方示例为 baseline。
先读 $ccWorkDir/dacli/doc/architecture.md 了解设计, 再看 plan.md 拿当前任务。
核心约束 (3 条不妥协):
- 0 差错 = API 0 错 + 浏览器 0 视觉差(详见 §5)
- 官方示例 baseline 必用(developSystem 21 + workSystem 53 = 74 张)
- Playwright Node.js 是基础设施(不是可选,每个 baseline 必跑)
1. 项目背景与目标
1.1 为什么做这件事
dacli (Java 版, docs/dacli/ssw-dacli/, 已废弃归档) 已成熟:17 父命令 + ~110 子命令、53 FieldBuilder、261/261 mvn test。
但 4 个痛点:
- AI 写 Java 累(类型 ceremony、编译慢)
- schema 翻译漂移(53 FieldBuilder 是从 web 翻译过来的,翻译即漂移)
- 升级耦合(JNPF 改一字段,53 builder 都要手改)
- web 零复用(web 端 TS/TS,dacli Java 完全没复用)
1.2 TS 版定位
不是"重写 dacli 替代 Java 版"。 而是"AI-friendly 探索性实验"——验证"直接复用 web 源码 + 0 差错验证"的可行性。
1.3 目标 0 差错 (硬目标)
0 差错 = 两个层面都 0:
| 层面 | 含义 | 验证手段 |
|---|---|---|
| API 0 错 | 所有 dacli 命令调用 JNPF API 返回 200/业务成功 | 单元测试 + 集成测试 |
| 浏览器 0 视觉差 | 复刻的表单/菜单在浏览器渲染与原版像素级一致 | Playwright Node.js 截图对比 |
0 差错基线: 74 张官方示例 (developSystem 21 + workSystem 53)。 dacli 对这 74 张必须做到:
- ✅
dacli form export <id>输出 JSON →dacli form import输入 → 重建后结构 0 差 - ✅ Playwright 打开原版与复刻版,截图视觉 0 差 (允许 1 像素抗锯齿差)
- ✅ 所有字段、按钮、列表列正确渲染
- ✅ 表单可正常提交、菜单可正常跳转、工作流可正常发起
1.4 官方示例 (baseline 真值源)
| app_code | 表单数 | 工作流数 | 用途 |
|---|---|---|---|
developSystem |
21 | 3 | 基础示例(单表/主子表/简单工作流) |
workSystem |
53 | 多个 | 丰富示例(关联/字典/数据接口/复杂流程) |
tds |
0+ (本次新建) | - | 实际业务应用 |
baseline 文件:
references/baseline/developSystem.md— 21 张表单清单 + 特色references/baseline/workSystem.md— 53 张表单清单 + 特色examples/baseline/<enCode>.sh— 每张表单的复刻 + 验证脚本examples/baseline/all.sh— 一键跑完 74 张的回归
2. 架构设计 (核心)
2.1 复用 web 源码的 4 类资产
| 资产 | 来源 | TS 版如何用 | 价值 |
|---|---|---|---|
| 加密算法 | web/packages/jnpf/utils/src/helpers/cipher.ts |
crypto-js 1:1 复刻 |
字节级一致 |
| L1 正则库 | web/packages/jnpf/utils/src/helpers/formValidate.ts |
直接 import + 提 JSON |
14 条规则 |
| componentMap | web/.../components/FormGenerator/src/helper/componentMap.ts |
提 → component-map.json |
60+ jnpfKey → tag |
| Rxxx.vue template | web/.../components/FormGenerator/src/rightComponents/*.vue |
@vue/compiler-sfc parse 提 activeData.* |
39 控件 schema |
2.2 Playwright Node.js = 基础设施
不是"可选的 E2E 工具",是 0 差错验证的核心:
| 用途 | Playwright 角色 |
|---|---|
| baseline 截图对比 | 原版 vs 复刻版像素级 diff |
| 业务功能验证 | 提交表单/审批流程/翻页/搜索真实能跑 |
| API + UI 双层验证 | API 0 错 + 浏览器 0 视觉差 (双层 0 错) |
| 回归基线 | JNPF 升级时一键跑 74 张,5 分钟看出 regression |
| AI 自检 | AI 改完 dacli 后跑 Playwright 看实际效果 |
技术选型:
@playwright/test(Node.js) 而非 Playwright Python- 原因: 与 dacli 同 Node 进程,可直接 import dacli 模块做集成测试
- 浏览器: chromium (headless) + 截图 + DOM 比对
- 截图对比:
pixelmatch库像素级 diff
目录:
dacli/tests/
├── e2e/
│ ├── baseline/ # 114 张官方示例
│ │ ├── developSystem/ # 21 张
│ │ │ ├── <enCode>.spec.ts # 每张一个
│ │ │ └── ...
│ │ └── workSystem/ # 53 张
│ │ ├── <enCode>.spec.ts
│ │ └── ...
│ ├── api/ # API 层 0 错测试
│ │ ├── form.spec.ts
│ │ ├── menu.spec.ts
│ │ └── ...
│ └── visual/ # 视觉对比
│ ├── <form-enCode>-diff.spec.ts
│ └── screenshots/ # 截图 + diff 输出
└── unit/
├── crypto.test.ts
├── extractors.test.ts
└── schema.test.ts
2.3 目录结构 ($ccWorkDir/dacli/) - 更新
dacli/
├── prompt.md # 本文件
├── README.md # 项目入口
├── package.json # 加 @playwright/test
├── tsconfig.json
├── playwright.config.ts # Playwright 配置
│
├── src/ # ⭐ 第一件交付物: dacli CLI
│ ├── cli.ts # Commander.js 入口
│ ├── commands/ # 嵌套子命令
│ │ ├── login.ts
│ │ ├── status.ts
│ │ ├── form/{list,info,create,release,delete,export,import,clone,validate,fix}.ts
│ │ ├── menu/{list,create,update,delete}.ts
│ │ ├── dm/{list,table,create,update,drop}.ts
│ │ ├── dict/{type-list,type-create,data-list,data-create}.ts
│ │ ├── workflow/{list,create,launch,approve}.ts
│ │ ├── doc/{list,get,scan,refresh,clear}.ts
│ │ └── apis/{list,info,search,refresh,status}.ts
│ ├── core/
│ │ ├── client.ts
│ │ ├── crypto.ts
│ │ ├── config.ts
│ │ ├── cache.ts # better-sqlite3
│ │ ├── help.ts # --ai-help / --example / --source
│ │ └── log.ts
│ ├── extractors/ # web 源码提取工具
│ │ ├── fields.ts
│ │ ├── l1-rules.ts
│ │ ├── l2-rules.ts
│ │ ├── flow.ts
│ │ └── component-map.ts
│ ├── data/ # 提取 JSON (git-tracked)
│ │ ├── component-map.json
│ │ ├── field-schemas.json
│ │ ├── validation-rules.json
│ │ └── l2-rules.json
│ ├── schema/ # FieldBuilder (从 JSON 加载)
│ └── types.ts
│
├── .claude/skills/dacli-ts/ # ⭐ 第二件交付物: AI 专用 skill
│ ├── SKILL.md # 主入口
│ ├── references/
│ │ ├── commands.md # 完整命令清单
│ │ ├── patterns.md # 5+ 业务模式
│ │ ├── anti-patterns.md # 8+ 反模式
│ │ ├── troubleshooting.md # 8+ 排错
│ │ ├── baseline/ # ⭐ 官方示例 baseline
│ │ │ ├── README.md
│ │ │ ├── developSystem.md # 21 张表单清单
│ │ │ └── workSystem.md # 53 张表单清单
│ │ └── playwright.md # Playwright 使用指南
│ ├── examples/ # 可复制粘贴的示例
│ │ ├── create-simple-form.sh
│ │ ├── create-master-sub-form.sh
│ │ ├── create-workflow.sh
│ │ └── baseline/ # 74 张 baseline 复刻脚本
│ │ ├── all.sh
│ │ ├── developSystem/
│ │ │ ├── <enCode>.sh
│ │ │ └── ...
│ │ └── workSystem/
│ │ ├── <enCode>.sh
│ │ └── ...
│ └── scripts/ # AI 调用的辅助脚本
│
├── doc/ # 人类可读详细文档
│ ├── README.md
│ ├── architecture.md
│ ├── plan.md # 6 周路线
│ ├── api.md
│ ├── extractors.md
│ ├── help-system.md
│ └── baseline.md # ⭐ baseline 验证规范
│
├── tests/ # ⭐ Playwright + vitest 测试套件
│ ├── e2e/
│ │ ├── baseline/ # 74 张 baseline 复刻 + 验证
│ │ │ ├── developSystem/
│ │ │ └── workSystem/
│ │ ├── api/ # API 层 0 错
│ │ └── visual/ # 截图视觉对比
│ └── unit/ # vitest 单元测试
│
├── screenshots/ # baseline 截图 (gitignored)
│ ├── developSystem/
│ └── workSystem/
│
├── scripts/
│ ├── extract-all.mjs # 一键提取 web 源码
│ ├── verify-baseline.mjs # ⭐ baseline 一键回归
│ └── install-playwright.mjs # 一键装 playwright + chromium
│
└── .dacli-cache.db # SQLite 缓存 (gitignored)
3. 6 周路线 (Week 1-6: dacli + skill)
Week 1: 脚手架 + 核心管道 (登录 + form CRUD)
| Day | 任务 | 验收 |
|---|---|---|
| D1 | 初始化目录、package.json、tsconfig.json、Commander.js 入口、playwright 装好 | npx tsx src/cli.ts --help 跑通 |
| D2 | core/crypto.ts (从 web cipher.ts 移植 crypto-js) + 单元测试 |
'123456' → 与 web 同 96 hex |
| D3 | core/client.ts (JnpfClient: login + HTTP) + commands/login.ts |
login 成功 + token 持久化 |
| D4 | commands/form/{list,info}.ts + core/config.ts |
form list 返回 3+ 张 |
| D5 | commands/form/{create,release,delete}.ts |
端到端 demo 跑通 |
Week 1 必达 (0 差错第 1 步):
- tds 应用 login + form list 跑通
- developSystem / workSystem 也能 login + form list (验证多 app)
Week 2: 提取工具 + 53 控件 schema + Playwright 基础
| Day | 任务 | 验收 |
|---|---|---|
| D1 | extractors/component-map.ts |
data/component-map.json 60+ 映射 |
| D2 | extractors/fields.ts (vue SFC parse) |
data/field-schemas.json 39 控件 |
| D3 | extractors/l1-rules.ts + l2-rules.ts |
validation-rules + l2-rules |
| D4 | Playwright 配置 (playwright.config.ts + 装 chromium) |
npx playwright --version 跑通 |
| D5 | schema/index.ts 通用 FieldBuilder |
53 控件可调,无需硬编码 |
Week 2 必达: 提取 + Playwright 基础完成
Week 3: 5 父命令 + 第一批 baseline (developSystem 21)
| Day | 任务 | 验收 |
|---|---|---|
| D1 | commands/dm.ts (list/table/create) |
端到端 |
| D2 | commands/dict.ts (type-list/data-list/create) |
端到端 |
| D3 | commands/menu.ts (list/create) + commands/di.ts |
端到端 |
| D4 | 写 21 张 developSystem baseline 脚本 (export → import → Playwright 截图对比) | 21/21 API 0 错 |
| D5 | 21 张 baseline 浏览器 0 视觉差 | API + UI 双 0 错 |
Week 3 必达: developSystem 21 张 baseline 全 0 错
Week 4: workflow + 第二批 baseline (workSystem 53)
| Day | 任务 | 验收 |
|---|---|---|
| D1 | commands/workflow.ts (list/create/launch/approve) |
端到端 |
| D2-D4 | 写 53 张 workSystem baseline 脚本 | 53/53 API 0 错 |
| D5 | 53 张 baseline 浏览器 0 视觉差 | API + UI 双 0 错 |
Week 4 必达: workSystem 53 张 baseline 全 0 错
Week 5: 帮助体系 + skill 主体
| Day | 任务 | 验收 |
|---|---|---|
| D1 | core/help.ts + --ai-help / --example / --source |
全部命令支持 |
| D2 | commands/doc.ts (HTML 缓存) |
镜像 Java 版能力 |
| D3 | commands/apis.ts (OpenAPI 抓取) |
镜像 Java 版能力 |
| D4 | skill SKILL.md + references/commands.md |
AI 读后知道何时用 |
| D5 | skill references/patterns.md + anti-patterns.md |
5+ 模式 + 8+ 反模式 |
Week 5 必达: 帮助体系 + skill 主体
Week 6: skill examples + AI 自检 + 文档收尾
| Day | 任务 | 验收 |
|---|---|---|
| D1 | examples/create-simple-form.sh (单表) |
AI 复制粘贴能跑 |
| D2 | examples/create-master-sub-form.sh (主子表) |
同上 |
| D3 | examples/create-workflow.sh (工作流) |
同上 |
| D4 | AI 自检: 把 skill 喂给另一个 Claude, 让它 "用 dacli 完成一个请假流程" | 能跑通 |
| D5 | 文档收尾 + examples/baseline/all.sh 一键回归 |
74 张一键跑 |
Week 6 必达: skill 完整 + AI 自检通过 + 74 张 baseline 一键回归
4. 0 差错验证规范 (baseline.md)
4.1 验证金字塔
┌──────────────┐
│ Playwright │ ← 浏览器 0 视觉差
│ (E2E) │
├──────────────┤
│ dacli CLI │ ← API 0 错
│ (集成测试) │
├──────────────┤
│ vitest │ ← 函数 0 错
│ (单元测试) │
└──────────────┘
每一层都必须 0 错。
4.2 baseline 复刻流程 (每张表单)
# 1. export 原表单 JSON
dacli form export <original-id> --out=/tmp/<enCode>-orig.json
# 2. 拿到原表单的 dbLinkId / category / webType / type 等元数据
dacli form info <original-id>
# 3. import 到 tds (或新应用)
dacli form import /tmp/<enCode>-orig.json --enCode=<enCode>_clone
# 4. 拿克隆 id
CLONE_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="<enCode>_clone") | .id')
# 5. release
dacli form release $CLONE_ID
# 6. Playwright 验证 (API + UI)
npx playwright test e2e/baseline/<app>/<enCode>.spec.ts
# 7. 视觉对比 (0 差 = 像素级)
npx playwright test e2e/visual/<enCode>-diff.spec.ts
4.3 0 差错的精确含义
| 维度 | 0 差错标准 | 验证 |
|---|---|---|
| HTTP 状态码 | 200/业务成功 (无 4xx/5xx) | Playwright API fixture |
| 响应数据 | 重建后 form info 字段集与原版完全一致 (允许 id/enCode/state 不同) | 单元对比 |
| 字段渲染 | 浏览器看到的 input/select/textarea 数量、类型、默认值 0 差 | DOM 断言 |
| 按钮位置 | 保存/取消/审批按钮位置 0 差 | 截图 |
| 列表列 | 列表页列数/列名/列宽 0 差 | 截图 + DOM |
| 工作流节点 | 流程图节点数/连线 0 差 | 截图 |
允许差异 (不算错):
- id / enCode 必然不同
- 物理表名前缀 (e.g.
tds_assetvstds_asset_clone) - 时间戳 / 创建人
- 像素级抗锯齿差异 (1-2 像素)
4.4 不算 0 差错的常见 bug
- ❌ 字段缺失 (e.g. input 缺
maxlength属性) - ❌ 控件类型错 (e.g. select 被渲染成 input)
- ❌ 字典数据加载失败 (下拉框空白)
- ❌ 列表分页错 (pageSize 不一致)
- ❌ 工作流节点缺失
- ❌ 表单提交后跳错页
5. 关键命令 (AI 一眼能看完)
# ===== 登录/状态 =====
dacli login --appCode=tds
dacli switch-app --appCode=developSystem # 切到 baseline
dacli status
# ===== baseline 复刻 (74 张) =====
bash examples/baseline/all.sh # 一键全跑 74 张
bash examples/baseline/developSystem/leave.sh
bash examples/baseline/workSystem/contract.sh
# ===== 验证 =====
npx playwright test # 跑全部 E2E
npx playwright test e2e/baseline/developSystem # 跑 21 张
npx vitest run # 跑单元测试
# ===== 提取 (JNPF 升级时重跑) =====
node scripts/extract-all.mjs
# ===== 文档/API 查 =====
dacli doc list --dir=docs/tds
dacli doc get --file=docs/tds/plan.html
dacli apis list --tag=visualdev
dacli apis info "POST /api/visualdev/Base"
6. 已知陷阱 (踩过的坑 + 必防)
6.1 URL 重复
baseUrl 已含 /api,path 不含。/api/api/... → 404/401
6.2 加密字节级不一致
Hex.stringify(Base64.parse(result)) 是对 Base64 字符串做 hex,不是密文字节。用 crypto-js 严格 1:1 复刻 cipher.ts
6.3 表单 "Database exception"
dbLinkId='0'错(用/api/system/DataSource拉)tables[].fields[]缺autoIncrement/identity/columnName等category='0'错(用dacli form list查真实值)- type=4 (视图) 绕过 tables 问题
6.4 release 视图表失败
type=4 (视图) release 报 "System abnormality"。软跳过。
6.5 菜单 API 不回 data.id
响应只有 {code, msg}。解析时用 enCode 反查 list。
6.6 Playwright 浏览器层 tdd 应用 404
nginx 容器可能不通,dacli/login 失败。用 developSystem/workSystem 兜底验证(已通)。
6.7 baseline 表单的 dbLinkId
74 张表单的 dbLinkId 各异(不同业务库)。脚本里动态拉,不写死。
6.8 baseline 工作流的 formId
克隆工作流时 formId 失效(指向原 formId)。必须重建 formId 映射。
7. 与 Java 版的关系
7.1 v1 不替代
- Java 版
ssw-dacli是生产工具(6 月打磨,261 tests) - TS 版实验性,不作为生产依赖
7.2 验证收益(v1 完成后)
- 如果 baseline 74 张全 0 错 + AI 自检通过 → v2 把提取工具反向喂给 Java 版
- 如果 覆盖率 / 体验都好 → v3 全面替代
- 如果 一般 → 保留作为"快速原型工具"
7.3 提取工具沉淀
dacli/src/extractors/ 是通用资产。v2 可考虑:
- 移到
.claude/skills/dacli-web-extract/给 Java 版用 - Java 版
dacli form validate也消费data/*.json
8. 上下文恢复指引
新会话第一句:
按 $ccWorkDir/dacli/prompt.md 继续。当前周次/任务查 doc/plan.md。
目标 0 差错: developSystem 21 + workSystem 53 baseline 全跑通。
关键文件:
doc/plan.md— 当前进度doc/architecture.md— 设计决策doc/baseline.md— 0 差错验证规范references/baseline/developSystem.md+workSystem.md— 74 张清单examples/baseline/all.sh— 一键回归src/data/*.json— 提取的资产tests/e2e/baseline/— 74 张的 Playwright 测试test/ddcc/— 上一轮实验
关键命令:
cd $ccWorkDir/dacli
npx tsx src/cli.ts --help
npx tsx src/cli.ts login --appCode=tds
bash examples/baseline/all.sh # 74 张一键回归
npx playwright test # 跑全部 E2E
npx vitest run # 跑单元测试
node scripts/extract-all.mjs # 提取 web 源码
9. 反向链接 (Related)
- doc/architecture.md — 架构设计
- doc/plan.md — 6 周路线
- doc/baseline.md — 0 差错验证规范
- doc/api.md — API 完整列表
- doc/implementation.md — 实现细节
- doc/extractors.md — 提取工具
- doc/help-system.md — 帮助体系
- SKILL.md — AI 技能主入口
- references/baseline/developSystem.md
- references/baseline/workSystem.md
- examples/baseline/all.sh — 一键回归
- ../ddcc/ — 上一轮实验
生成时间: 2026-06-12 作者: Claude (M3) + 用户 状态: v1 计划冻结,进入执行 核心目标: 74 张官方示例 API 0 错 + 浏览器 0 视觉差