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

33 KiB
Raw Blame History

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/


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/
│   ├── seed-tds-baseline.ts      # seed 测试数据
│   # 注: v0.11+ 无 extract-all.mjs (webapi 直接 dynamic import web 端源码)
│
└── .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 复刻流程 (每张表单)

# 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 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                           # 跑单元测试

# 注: v0.11+ 无 extract-all.mjs (webapi 直接 dynamic import web 端源码, 自动同步)

# ===== 文档/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 版通用资产. 用法:

  • v0.11+: webapi/ 直接 dynamic import web 端源码 (替换 extract 脚本), 自动同步无需手动提取
  • FieldBuilder 加载 src/data/*.json 仍是 component-map / field-schemas 等基础控件 schema 的来源

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 启动用)

关键命令:

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                            # 跑单元测试

# v0.11+ 无 extract-all.mjs, webapi 自动同步

# 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


生成时间: 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 视觉差