Files
dacli/prompt.md
T

707 lines
33 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.
# TS 版 dacli — 主提示词 (开发任务说明书, v0.8 长任务模式)
> **位置**: `$ccWorkDir/dacli/`
> **目标**: 在 `$ccWorkDir/dacli/` 内交付 **两件套**——
> 1. **`dacli` CLI 工具** (TypeScript) — **唯一生产工具**
> 2. **`.claude/skills/dacli-ts/SKILL.md`** — AI 专用技能,告诉 AI **何时用哪个命令**
>
> **当前状态**: v0.7.1 (2026-06-12) — **8 父命令 / 27 子命令**, 114 baseline 0 差错 (developSystem 29 + workSystem 85)
> **v0.8 目标 (本轮长任务)**: 把 jnpf web 剩下的 25+ 顶级模块整合进 dacli, 目标 **22 父命令 / 80+ 子命令 / 130+ baseline 0 差错**
> **应用对象**: `tds` (http://nginx/ ,你在容器内 后端api 代理到 http://nginx/api -> http://127.0.0.1:30000/api) | `admin / 123456`
---
## ⛔ 长任务模式 (LONG-RUN MODE)
> **用户校准**: 本轮是长任务, **非必要不要中断, 自己驱动完成**. 不要中途问 "是否继续" / "要不要确认" / "先停下问个问题". 自己决策, 自己跑, 自己验证, 自己 commit. 真的卡死才回头.
### 硬约束 (5 条)
1. **不停下来问** — AI 自己决策 (改 type / 改 schema / 加 patch / 拆子命令 / 加缓存), 走不通就 `git commit --no-verify` + 写"已知盲点"段, 继续往下走
2. **每完成一段就 commit** — 不攒改动, 一段一提交 (`git add -A && git commit -m "..."`). 出问题好回滚
3. **失败不绕路** — 跑 `npx vitest run` 红了, 直接看 stacktrace 修代码, **不**问"要不要把这条 test 跳过"
4. **跑通才算完** — 一段子命令的"完工"定义: `npx tsc --noEmit` 0 错 + `npx vitest run` 全 PASS + `npx playwright test` 全 PASS + `examples/baseline/all.sh` 全 0 错. 缺一不可
5. **真错了才回头** — 编译/测试/集成三关全过, 才算"完成". 没过的标"已知遗留", 不回头改 — 留给下一段
### 不算"中断"的事
- 改源码 + 跑 typecheck + 跑 test + 跑 baseline + commit (正常流程)
- 改 prompt.md / RESUME.md / v0.8-*.md 段 (记进度)
- 跑 `git log` / `git diff` / `git status` 查状态
- 跑 `dacli app status` / `dacli form list` / `dacli apis list` 查真实数据
- 跑 `npx playwright install chromium` 装环境
- 跑 `npm install` 装新依赖
- 写 vitest 单测 / Playwright spec
- 跑 `git add -A && git commit` 一段一提交
### 真的卡死才回头 (3 件事)
- JNPF 后端报 500, 真实 bug (有 stacktrace, 不是 NPE 兜底 "System abnormality")
- 浏览器层 E2E 一直 fail, 3 次以上重试还红
- 缺依赖 / 缺环境 / 配置文件坏 (非代码问题)
---
## 0. 启动指令 (新会话第一句)
```
按 $ccWorkDir/dacli/prompt.md 在 $ccWorkDir/dacli/ 内交付 dacli + skill 两件套。
目标 0 差错: 以 developSystem/workSystem 官方示例为 baseline。
先读 $ccWorkDir/dacli/doc/architecture.md 了解设计, 再读 doc/RESUME.md 拿当前任务。
```
**v0.7.1 跳过** (本轮不重做, 留"已知遗留"段): P0 #16 收尾 (tds_leave fix-columndata) 用户手动, AI 不动
**v0.8 启动** (本轮主任务): 见 `doc/RESUME.md` §5 (jnpf web 25+ 顶级模块整合清单 + W7-W12 详细日程) + `doc/v0.8-scan.md` (扫描快照: 94 web 入口 + 100+ Controller + 22 模块端点)
**核心约束 (3 条不妥协)**:
1. **0 差错 = API 0 错 + 浏览器 0 视觉差**(详见 §5)
2. **官方示例 baseline 必用**(developSystem 21 + workSystem 53 = 74 张;v0.8 起追加报表/门户/大屏样例 8+ 张 = 122+)
3. **Playwright Node.js 是基础设施**(不是可选,每个 baseline 必跑)
---
## 1. 项目背景与目标
### 1.1 为什么做这件事
`dacli` (TypeScript 版) 是 JNPF 平台的命令行工具. 早期曾有 mvn/Java 版探索 (`docs/dacli/ssw-dacli/`, 现已归档), TS 版以"AI-friendly + 直接复用 web 源码 + 0 差错验证"为设计核心, 已稳定.
**4 个设计决策 (TS 版成立的关键)**:
1. **AI 写 TS 不累** (vs Java ceremony + 慢编译)
2. **schema 0 漂移** (从 web SFC 自动提取, 不再 53 FieldBuilder 翻译)
3. **升级松耦合** (JNPF 改字段, 重跑 extractor 即同步)
4. **web 源码复用** (web 端 TS/TS, dacli TS 直接 1:1 复刻 cipher/validate/componentMap)
### 1.2 TS 版定位
**是** dacli 的**唯一生产工具** (v0.7.1 已 8 父命令 / 27 子 / 114 baseline 0 差错).
**也是**"**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/](../../references/baseline/README.md)
---
## 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
│ │ # ↓ v0.8+ 新增 extractor
│ │ ├── report-schemas.ts # [P0] 报表组件 schema (W8)
│ │ ├── portal-schemas.ts # [P0] 门户布局 schema (W8)
│ │ ├── bigdata-schemas.ts # [P0] 大屏图表 schema (W8)
│ │ └── datasource-drivers.ts # [P0] 数据源 driver 列表 (W8)
│ ├── 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 缓存) | TS 版独立能力 |
| D3 | `commands/apis.ts` (OpenAPI 抓取) | TS 版独立能力 |
| 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 一键回归
---
## 3.5 v0.8 路线 (Week 7-12: jnpf web 剩余主要功能整合)
> **目标**: 把 jnpf web 剩下的 25+ 顶级模块整合进 dacli, 从 8 父命令扩到 **22 父命令 / 80+ 子命令**, baseline 从 114 张扩到 **130+ 张** (新增报表/门户/大屏/打印/打印模板样例 16+ 张).
>
> **扫描快照** (web 94 入口 + 后端 100+ Controller + 22 模块端点): 见 `doc/v0.8-scan.md`.
> **详细盘点** (按 AI 业务价值排序, 25+ 子功能): 见 `doc/RESUME.md` §5.1.
> **详细路线** (W7-W12): 见 `doc/RESUME.md` §5.2-5.7.
### Week 7: 整合基础设施 (情报收集 + 脚手架)
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | 扫 `web/views/` 全部 25+ 顶级模块, 整理 6.1 表格 | `/tmp/jnpf-web-views.txt` ≥ 25 行 |
| D2 | `dacli apis refresh` + 拉新 API 缓存, 找新模块端点 | apis list 含 report/portal/codegen 等新 tag |
| D3 | 4 个新父命令脚手架 (datasource / report / portal / codegen) | 全部 `npx tsx src/cli.ts <新命令> --help` 跑通 |
| D4 | 新 extractor 脚手架 (report-schemas / portal-schemas / bigdata-schemas / datasource-drivers) | 4 个 extractor 各跑出 JSON |
| D5 | `doc/v0.8-plan.md` (从 RESUME.md §6.1/6.2 抄), `doc/v0.8-changelog.md` 框架 | 2 文档就位 |
**Week 7 必达**: 4 父命令占位 + 4 extractor 跑通 + 8 父命令基线 (v0.7.1 收尾) 全 PASS
### Week 8: P0 第 1 波 (数据源 + 报表 + 门户)
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | `dacli datasource list/create/delete/test` (dataSource 4 子) | 端到端 |
| D2 | `dacli report list/info/create/release` (onlineDev/report 4 子) | workSystem 报表样例 2+ 张 0 错 |
| D3 | `dacli portal list/info/create` (visualPortal 3 子) | workSystem 门户样例 1+ 张 0 错 |
| D4 | baseline 验证: 报表 + 门户样例 5+ 张 (API 层 0 错) | 5+ 张 schema 完整 |
| D5 | Playwright 视觉对比 (报表 / 门户 0 视觉差) | UI 层 0 错 |
**Week 8 必达**: 3 父命令 (datasource / report / portal) + 5+ 样例 API 0 错
### Week 9: P0 第 2 波 (代码生成 + 大屏 + 打印)
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | `dacli codegen module/list/import` (从 form 模板生成 ssw-后端模块 3 子) | Java 模块生成跑通 |
| D2 | `dacli bigscreen list/info/create` (extend/bigData 3 子) | 大屏样例 2+ 张 0 错 |
| D3 | `dacli print template list/info/create` (printDev 3 子) | 打印模板 1+ 张 0 错 |
| D4 | baseline 验证: 大屏 + 打印样例 3+ 张 (API 层 0 错) | 3+ 张 schema 完整 |
| D5 | Playwright 视觉对比 (大屏 / 打印 0 视觉差) | UI 层 0 错 |
**Week 9 必达**: 3 父命令 (codegen / bigscreen / print) + 3+ 样例 API 0 错; **P0 全部完成, 11 父命令 / 27+13=40 子命令**
### Week 10: P1 权限三角 (role + user + organize)
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | `dacli role list/create/delete/assign` (4 子) | 角色 CRUD + 赋权 |
| D2 | `dacli user list/create/delete/reset-pwd` (4 子) | 用户 CRUD + 密码重置 |
| D3 | `dacli org list/tree/create` (组织/部门/岗位 3 子) | 组织树 CRUD |
| D4 | 联动验证: 建用户 → 分配组织 → 赋角色 → 登录 tds 看菜单 | 端到端 1 套 |
| D5 | AI 自检 1: 跑通"权限三角"完整流程 | subagent 验证 |
**Week 10 必达**: 3 父命令 (role / user / org) + 权限闭环
### Week 11: P1 消息中心 + 调度 + 应用管理
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | `dacli msg notice list/create/send` + `dacli msg template` (5 子) | 通知公告 + 模板 |
| D2 | `dacli schedule list/create/pause/trigger/log` (定时任务 5 子) | Quartz job CRUD |
| D3 | `dacli app list/create/delete/initapp` (应用管理 4 子, initapp 升级) | 多 app 生命周期 |
| D4 | 端到端: 通知公告真发出 + 定时任务真触发 | 2 套验证 |
| D5 | AI 自检 2: 跑通"建通知 + 触发定时任务"完整流程 | subagent 验证 |
**Week 11 必达**: 3 父命令 (msg / schedule / app) + 闭环验证; **14 父命令 / 60+ 子命令, P0+P1 全部完成**
### Week 12: P2 收尾 + 全量回归
| Day | 任务 | 验收 |
|-----|------|------|
| D1 | `dacli monitor online/sql/flow` (3 子) | 监控查 |
| D2 | `dacli log login/operate` (2 子) | 日志查 |
| D3 | `dacli integration email/sms/webhook test` (集成测试 3 子) | 集成渠道 |
| D4 | `dacli import excel/... --template=X` (批量导入 1 子) | Excel 导入 |
| D5 | **全量回归**: 14 父命令 vitest + 11 父命令 Playwright (新父命令 W8-W11 跑通回归) | 0 错 |
**Week 12+ 必达**: 14 父命令 / 60+ 子命令 + **122+ baseline 0 差错** + v0.8 完整交付
### v0.8 末交付 (硬目标)
- ✅ **22 父命令** / 80+ 子命令 (v0.7.1 的 8 → v0.8 的 22, 翻 2.7 倍)
- ✅ **130+ baseline** 0 差错 (114 + 报表/门户/大屏/打印/打印模板 16+)
- ✅ **3 个 AI 自检** (权限三角 / 通知调度 / v0.8 总体闭环)
- ✅ **`doc/v0.8-changelog.md`** 详 v0.8 全部变更
- ✅ **`.claude/skills/dacli-ts/SKILL.md` v0.8 校准**: 加 P0/P1/P2 命令速查 + 4 大新决策点
### v0.8 关键决策点 (AI 必读, 决策错率高的 4 点)
#### 决策 6: 报表/门户/大屏用哪个 type?
| 场景 | webType | 是否需要物理表 | 镜像命令 |
|------|---------|--------------|----------|
| 普通报表 | 1-2 (报表设计器) | ❌ 不需要 (走数据接口拉) | `dacli report create` |
| 大屏/仪表盘 | 3-4 (大屏设计器) | ❌ 不需要 | `dacli bigscreen create` |
| 门户 (经典/全屏) | 5-6 (门户设计器) | ❌ 不需要 | `dacli portal create` |
| 打印模板 | 1-2 (printDev) | ❌ 不需要 (绑 form 数据) | `dacli print template create` |
**AI 反模式**: 给报表/门户硬建物理表 → 100% "Database exception" (它们走 di / dataInterface 拉数据)
**AI 正解**: 先 `dacli di list` 看有什么数据接口 → 报表直接 bind dataInterfaceId
#### 决策 7: 权限三角优先级
| 角色 | 优先级 | 必含字段 |
|------|--------|---------|
| **角色 (role)** | 1 | name, enCode, type (0业务/1系统), organizeIds, positionIds, userIds |
| **用户 (user)** | 2 | account, realName, password, organizeId, positionId, roleId, enabled |
| **组织 (org)** | 3 | name, enCode, parentId, category (公司/部门/岗位), sortCode |
**AI 反模式**: 先建用户再建组织 → 用户 organizeId=null 报 "组织不存在"
**AI 正解**: 先建组织树 → 再建用户绑组织 → 最后建角色赋权
#### 决策 8: 通知/消息发送通道怎么选?
| 场景 | 通道 | dacli 命令 |
|------|------|-----------|
| 站内信 (tds 内部) | msgCenter 站内信 | `dacli msg notice send --type=site` |
| 邮件 | integrationCenter/email | `dacli integration email send` |
| 短信 | integrationCenter/sms | `dacli integration sms send` |
| 钉钉/企微/微信 | integrationCenter | `dacli integration <渠道> send` |
| Webhook (自定义) | integrationCenter/webhook | `dacli integration webhook send --url=...` |
**AI 反模式**: 邮件配置直接改 `application.yml` → 走不到 JNPF 通知管理
**AI 正解**: 先 `dacli integration email config` 在 JNPF 配 → 再用通知发送命令
#### 决策 9: 定时任务 vs 工作流调度?
| 场景 | 用什么 | 触发 |
|------|--------|------|
| 定时报表生成 / 数据清理 / 缓存刷新 | **schedule (Quartz)** | cron 表达式 |
| 业务审批流程 (请假/报销/合同) | **workflow (Flowable)** | 人工发起 / 事件触发 |
| 数据同步 (外部接口) | **schedule (Quartz)** | cron 表达式 |
| 多步审批 + 条件分支 | **workflow (Flowable)** | 流程引擎 |
**AI 反模式**: 用工作流做"每天凌晨跑一次" → 流程引擎不适合 cron
**AI 正解**: 用 schedule, cron="0 0 0 * * ?"
---
## 4. 0 差错验证规范 (baseline.md)
### 4.1 验证金字塔
```
┌──────────────┐
│ Playwright │ ← 浏览器 0 视觉差
│ (E2E) │
├──────────────┤
│ dacli CLI │ ← API 0 错
│ (集成测试) │
├──────────────┤
│ vitest │ ← 函数 0 错
│ (单元测试) │
└──────────────┘
```
**每一层都必须 0 错**。
### 4.2 baseline 复刻流程 (每张表单)
```bash
# 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 一眼能看完)
```bash
# ===== 登录/状态 =====
dacli app login --appCode=tds
dacli app switch --appCode=developSystem # 切到 baseline
dacli app 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"
# ===== v0.8 启动预研 (新增) =====
# 扫 web 端所有顶级模块入口
find /home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src/views \
-maxdepth 2 -name "index.vue" | sort > /tmp/jnpf-web-views.txt
wc -l /tmp/jnpf-web-views.txt
# 拉新 API 缓存 (报表/门户/大屏端点)
dacli apis refresh
dacli apis list --tag=visualReport # 报表 (待 v0.8 W8 实测 tag)
dacli apis list --tag=visualPortal # 门户 (待 v0.8 W8 实测 tag)
# 列 developSystem/workSystem 现有报表/门户样例 (作 baseline)
dacli app switch --appCode=workSystem
dacli form list | jq -r '.data.list[] | "\(.id) \(.category) \(.fullName)"' | head -50
```
---
## 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. 提取工具 (TS 版通用资产)
`dacli/src/extractors/` (component-map / field-schemas / l1-rules / l2-rules / **v0.8+ report-schemas / portal-schemas / bigdata-schemas / datasource-drivers**) 是 TS 版通用资产. 用法:
- TS 版 `FieldBuilder` 加载 `data/*.json` 自动构建表单/报表/门户/大屏字段
- 提取脚本 `scripts/extract-all.mjs` JNPF 升级时重跑 (出新版字段)
- 提取 JSON 入 git (跟版本, 可对比 diff)
- v0.8 新增 4 个 extractor 直接跑出 `data/report-schemas.json` / `data/portal-schemas.json` / `data/bigdata-schemas.json` / `data/datasource-drivers.json`
---
## 8. 上下文恢复指引
**新会话第一句**:
```
按 $ccWorkDir/dacli/prompt.md 继续。当前周次/任务查 doc/RESUME.md (v0.7.1 收尾 + v0.8 启动)。
目标 0 差错: developSystem 21 + workSystem 53 baseline 全跑通 (v0.8 起追加报表/门户/大屏 8+ 张).
```
**关键文件** (按恢复时阅读顺序):
- `doc/RESUME.md` — **第一份读** (v0.7.1 状态 + v0.8 启动盘点, §6 路线最关键)
- `doc/v0.7.1-changelog.md` — 本轮 (盲点 23 闭环)
- `doc/v0.7-changelog.md` — 上轮 (P0 #13 + P1 #15)
- `doc/plan.md` — 6 周路线 + v0.6 段 (v0.8 路线见 prompt §3.5)
- `doc/v0.8-plan.md` — **待写** (v0.8 路线展开)
- `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/` — 上一轮实验
- `/tmp/jnpf-web-views.txt` — **下次会话第一波扫出的 web 模块入口清单** (v0.8 启动用)
**关键命令**:
```bash
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 源码
# v0.7.1 收尾 (第一波)
npx tsx src/cli.ts form fix-columndata 835168490678657989
npx tsx src/cli.ts menu create --fullName="员工请假申请" --formId=835168490678657989
# v0.8 启动预研 (第二波)
find /home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src/views \
-maxdepth 2 -name "index.vue" | sort > /tmp/jnpf-web-views.txt
npx tsx src/cli.ts apis refresh
```
---
## 9. 反向链接 (Related)
- [doc/RESUME.md](doc/RESUME.md) — **会话恢复指引** (v0.7.1 收尾 + v0.8 启动盘点)
- [doc/architecture.md](doc/architecture.md) — 架构设计
- [doc/plan.md](doc/plan.md) — 6 周路线 (W1-W6)
- [doc/v0.8-plan.md](doc/v0.8-plan.md) — **待写** v0.8 路线 (W7-W12)
- [doc/baseline.md](doc/baseline.md) — 0 差错验证规范
- [doc/api.md](doc/api.md) — API 完整列表
- [doc/implementation.md](doc/implementation.md) — 实现细节
- [doc/extractors.md](doc/extractors.md) — 提取工具
- [doc/help-system.md](doc/help-system.md) — 帮助体系
- [doc/v0.7.1-changelog.md](doc/v0.7.1-changelog.md) — 本轮详细 (盲点 23 闭环)
- [doc/v0.7-changelog.md](doc/v0.7-changelog.md) — 上轮 (P0 #13 + P1 #15)
- [doc/v0.6-changelog.md](doc/v0.6-changelog.md) — 上上轮 (Playwright + 浏览器会话)
- [SKILL.md](.claude/skills/dacli-ts/SKILL.md) — AI 技能主入口 (v0.7.1 校准)
- [references/baseline/developSystem.md](.claude/skills/dacli-ts/references/baseline/developSystem.md) — 21 张清单
- [references/baseline/workSystem.md](.claude/skills/dacli-ts/references/baseline/workSystem.md) — 53 张清单
- [examples/baseline/all.sh](.claude/skills/dacli-ts/examples/baseline/all.sh) — 一键回归
- [../ddcc/](../ddcc/) — 上一轮实验
---
**生成时间**: 2026-06-12
**作者**: Claude (M3) + 用户
**状态**: v0.7.1 完工, v0.8 启动准备就绪
**v0.7.1 目标**: 8 父命令 / 27 子命令, 72 baseline 0 差错 ✅
**v0.8+ 目标**: 14 父命令 / 60+ 子命令, 122+ baseline 0 差错 (本轮)
**核心目标**: **jnpf web 主要功能 90% 整合进 dacli + API 0 错 + 浏览器 0 视觉差**