Files
dacli/README.md
T
ssw ccd9c8d124 chore(v0.11+): Phase 4 历史残留清理 - 删 v0.10 静态快照 + 更新 README/prompt
清理:
1. 删除 data/web-derived-schemas.json (v0.10 静态快照, v0.11+ webapi 自动同步无需保留)
2. README.md: 移除 extract-all.mjs / extractors 引用, 加 v0.11+ webapi 段, 修正 .claude/skills/dacli-ts 路径 → ../.claude/skills/dacli-ts
3. prompt.md: 移除 extract-all.mjs 引用 (3 处), 改写 v0.8 '提取 JSON' 段为 v0.11+ 'webapi 自动同步'

未清理项 (按 plan §13 保留):
- src/data/*.json (component-map/field-schemas/validation-rules/form_type_rules 等 9 个 JSON) — 仍被 FieldBuilder.ts 加载, 有 3 个 unit 测试覆盖
- src/commands/_precheck.ts / _blindspot_guards.ts / form/_simplify.ts / form/_blindspots.ts / form/validate.ts / form/fixcolumndata.ts — 上一个 commit 已移除 LEGACY 误标头, 这些文件仍实际使用
- doc/v0.x-changelog.md 等 11 个版本历史 — 合法历史归档, 保留

Phase 4 完成度: A (盲点表整合) + B (deprecated 误标清理) + C (已删资源引用清理) + E (dacli 自有 schema 保留) + G (architecture.md 已 v0.11+ 更新) - 全部 PASS
未做: D (22 条盲点表整合到 _blindspot_guards.ts 单一权威) - 后续 P1 任务
2026-06-25 16:11:41 +08:00

155 lines
6.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# dacli — TS 版 dacli (当前主用)
> **位置**: `$ccWorkDir/dacli/`(原 `test/dacli/`, 2026-06-12 升级到顶层独立项目)
> **目标**: TypeScript 重写 dacli,**直接复用 JNPF web 源码** + **0 差错验证**
> **状态**: v0.7 (8 父命令 / 26+ 子命令,启动 < 500ms)
> **总目标**: workSystem 85 + developSystem 29 = **114 张官方示例 API 0 错 + 浏览器 0 视觉差**
## 这是什么
`dacli` 是 JNPF 平台的 CLI 工具,让 AI/开发者用命令行**代替**浏览器拖拽,自动化配置 JNPF 平台。
**Java 版** (`docs/dacli/ssw-dacli/`) 已**废弃**,源码归档备查(无 `target/`,需手动 `mvn package` 跑 jar)。
**TS 版** (本项目) 是当前**主用** CLI:
1. **直接复用 web 源码** — 30 分钟跑 extract 脚本拿 53 控件 schema, 不手抄
2. **Playwright Node.js 集成** — `@playwright/test` 与 dacli 同进程, 0 视觉差验证
3. **AI 友好帮助体系** — `--ai-help` 输出 markdown, `SKILL.md` 教 AI 何时用
## 两件套交付
| 交付物 | 位置 | 用途 |
|--------|------|------|
| **`dacli` CLI 工具** | `src/` | 给 AI/开发者用, 执行命令 |
| **`.claude/skills/dacli-ts/SKILL.md`** | `.claude/skills/dacli-ts/` | 教 AI 何时用哪个命令 |
**两者缺一不可**: 没 skill 工具躺地上, 没工具 skill 纸上谈兵。
## 0 差错定义
**0 差错 = API 0 错 + 浏览器 0 视觉差**。
| 层面 | 含义 | 工具 |
|------|------|------|
| **API 0 错** | 所有 dacli 命令返回 200/业务成功 | vitest + 集成测试 |
| **UI 0 视觉差** | 复刻的表单/菜单浏览器渲染与原版**像素级一致** | Playwright Node.js |
**0 差错基线**: **74 张官方示例** (developSystem 21 + workSystem 53)。
dacli 对这 74 张必须做到:
- ✅ `dacli form export <id>` → `dacli form import` → 重建后**结构 0 差**
- ✅ Playwright 打开原版与复刻版,**截图视觉 0 差**
- ✅ 所有字段、按钮、列表列正确渲染
- ✅ 表单可正常提交、菜单可正常跳转、工作流可正常发起
## 快速开始
```bash
cd $ccWorkDir/dacli
npm install # 装依赖
npx playwright install chromium # 装浏览器 (baseline 验证用)
# v0.11+ 无需 extract 脚本: webapi/ 直接 dynamic import web 端源码
npx tsx src/cli.ts app login --appCode=tds # 登录 tds
npx tsx src/cli.ts form list # 列已有表单
```
## 跑 baseline 一键回归
```bash
# 74 张一键回归 (API + UI)
bash .claude/skills/dacli-ts/examples/baseline/all.sh
# 仅 API 层 (快, 跳过 Playwright)
SKIP_PLAYWRIGHT=1 bash .claude/skills/dacli-ts/examples/baseline/all.sh
```
## 目录结构
```
dacli/ # 顶层独立项目 ($ccWorkDir/dacli)
├── prompt.md # 任务说明书 (开发这个项目的 AI 看的)
├── README.md # 本文件 (项目入口)
├── package.json
├── tsconfig.json
├── playwright.config.ts # Playwright 配置
│
├── src/ # ⭐ dacli CLI 工具
│ ├── cli.ts
│ ├── commands/ # 24 父命令 / 116 子命令
│ ├── core/ # 基础设施 (client/kit/help/log)
│ ├── webapi/ # ⭐ v0.11+ webapi 镜像 (18 模块, 100+ 函数)
│ ├── data/ # FieldBuilder JSON (component-map / field-schemas / ...)
│ └── schema/ # FieldBuilder
│
├── ../.claude/skills/dacli-ts/ # ⭐ AI 专用 skill (父项目, v0.11+ 已合并)
│ ├── SKILL.md # 主入口
│ ├── references/ # 8 专题文档
│ └── examples/ # 14 可复用脚本
│
├── doc/ # 人类详细文档
│ ├── architecture.md
│ ├── plan.md # 6 周路线
│ ├── baseline.md # 0 差错验证
│ ├── api.md
│ ├── extractors.md
│ └── help-system.md
│
├── tests/ # Playwright + vitest
│ ├── e2e/baseline/ # 114 张 baseline
│ ├── e2e/api/
│ ├── e2e/visual/
│ └── unit/
│
├── screenshots/ # 截图 (gitignored)
├── scripts/ # seed-tds-baseline.ts
└── .dacli-cache.db # SQLite 缓存
```
## 6 周路线
| Week | 任务 | 必达 |
|------|------|------|
| W0 准备 | doc + skill | ✅ 已完成 |
| W1 脚手架 | login + form list/create | tds/dev/work 都能登录 |
| W2 提取 | 5 个 extractor + Playwright | data/*.json 全部就位 |
| W3 developSystem | 21 张 baseline | 21/21 API 0 错 |
| W4 workSystem | 53 张 baseline | 53/53 API 0 错 |
| W5 帮助体系 | --ai-help + doc/apis | 镜像 Java 版 |
| W6 skill 完整 | AI 自检 + 文档 | AI 1 次对话完成请假流程 |
详见 [doc/plan.md](doc/plan.md)。
## 与 Java 版的关系
| 维度 | Java 版 (生产) | TS 版 (实验) |
|------|----------------|---------------|
| 稳定 | ⭐⭐⭐⭐⭐ (6 月打磨) | ⭐⭐ |
| AI 友好 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Schema 真相 | 53 builder 硬编码 | data/*.json 自动 |
| Baseline | 40 form | **74 form** |
| Playwright | ssw-e2e-test (Python) | **@playwright/test (Node)** |
| 启动 | 100ms native | < 500ms tsx |
| 定位 | 生产 | 实验 |
**v1 不替代**。v2 评估后再决定。
## 反向链接
- [prompt.md](prompt.md) — 完整任务说明书
- [doc/architecture.md](doc/architecture.md) — 设计决策
- [doc/plan.md](doc/plan.md) — 6 周路线
- [doc/baseline.md](doc/baseline.md) — 0 差错验证
- [doc/api.md](doc/api.md) — 完整 API
- [doc/extractors.md](doc/extractors.md) — 提取工具
- [doc/help-system.md](doc/help-system.md) — 帮助体系
- [.claude/skills/dacli-ts/SKILL.md](.claude/skills/dacli-ts/SKILL.md) — AI 技能主入口
- [.claude/skills/dacli-ts/references/](.claude/skills/dacli-ts/references/) — 6+ 文档
- [.claude/skills/dacli-ts/examples/](.claude/skills/dacli-ts/examples/) — 7+ 脚本
- [../ddcc/](../ddcc/) — 上一轮实验 (验证可行性)
---
**生成时间**: 2026-06-12
**作者**: Claude (M3) + 用户
**核心目标**: **74 张官方示例 API 0 错 + 浏览器 0 视觉差**