Files
dacli/prompt.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

20 KiB
Raw Blame History

TS 版 dacli — 主提示词 (开发任务说明书)

位置: $ccWorkDir/dacli/(原 test/dacli/, 2026-06-12 升级到顶层独立项目) 目标: 在 $ccWorkDir/dacli/ 内交付 两件套——

  1. dacli CLI 工具 (TypeScript) — 借鉴 Java 版架构 + 复用 JNPF web 源码
  2. .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 条不妥协):

  1. 0 差错 = API 0 错 + 浏览器 0 视觉差(详见 §5)
  2. 官方示例 baseline 必用(developSystem 21 + workSystem 53 = 74 张)
  3. Playwright Node.js 是基础设施(不是可选,每个 baseline 必跑)

1. 项目背景与目标

1.1 为什么做这件事

dacli (Java 版, docs/dacli/ssw-dacli/, 已废弃归档) 已成熟:17 父命令 + ~110 子命令、53 FieldBuilder、261/261 mvn test。

但 4 个痛点:

  1. AI 写 Java 累(类型 ceremony、编译慢)
  2. schema 翻译漂移(53 FieldBuilder 是从 web 翻译过来的,翻译即漂移)
  3. 升级耦合(JNPF 改一字段,53 builder 都要手改)
  4. 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 张的回归

详见 references/baseline/


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_asset vs tds_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 源码


生成时间: 2026-06-12 作者: Claude (M3) + 用户 状态: v1 计划冻结,进入执行 核心目标: 74 张官方示例 API 0 错 + 浏览器 0 视觉差