# 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 ` 输出 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/.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 张 │ │ │ ├── .spec.ts # 每张一个 │ │ │ └── ... │ │ └── workSystem/ # 53 张 │ │ ├── .spec.ts │ │ └── ... │ ├── api/ # API 层 0 错测试 │ │ ├── form.spec.ts │ │ ├── menu.spec.ts │ │ └── ... │ └── visual/ # 视觉对比 │ ├── -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/ │ │ │ ├── .sh │ │ │ └── ... │ │ └── workSystem/ │ │ ├── .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 --out=/tmp/-orig.json # 2. 拿到原表单的 dbLinkId / category / webType / type 等元数据 dacli form info # 3. import 到 tds (或新应用) dacli form import /tmp/-orig.json --enCode=_clone # 4. 拿克隆 id CLONE_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="_clone") | .id') # 5. release dacli form release $CLONE_ID # 6. Playwright 验证 (API + UI) npx playwright test e2e/baseline//.spec.ts # 7. 视觉对比 (0 差 = 像素级) npx playwright test e2e/visual/-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 视觉差**