Files
dacli/CLAUDE.md
T

12 KiB
Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目定位

dacli(TS 版)是 JNPF 低代码平台的命令行工具,当前主用 CLI。本项目从 JNPF web 源码直接提取控件 schema + FieldBuilder,避免 53 个手写 builder 的维护成本。

核心目标: 复刻 JNPF 官方示例 (workSystem + developSystem ) 到 API 0 错 + 浏览器 0 视觉差。 ** ../web/代码 和 官方示例 和 playwright 是 唯一可信源 **

详细设计: doc/architecture.md (6 个关键决策)、doc/plan.md (6 周路线)、doc/v0.7-changelog.md (最新校准)。

现状速览 (v0.10+, 2026-06-22)

  • 24 父命令 / 116 子命令(已超 Java 版的 24 命令总数 + 5 个 TS 新增)
  • Java 版全部命令已迁移(报表 / 门户 / portal / codegen 等"边缘场景"无遗漏)
  • 三层防御体系:L1 precheck + L2 guard (22 条高频盲点) + L3 diagnose
  • 新会话 4 步流程:app context → form/dm list → --ai-help/--source → self-check.sh
  • 权威参照:web/ 源码是事实,dacli 文档是导航

⚠️ v0.10+ AI 防御体系 (强制)

任何 AI 使用 dacli 前必读:根因 G(舍近求远,读文档不读源码)+ B/C/D(盲猜参数/状态)已通过三层防御拦截。

层级 触发时机 文件 失败行为
L1 precheck form/dm create 执行前 src/commands/_precheck.ts exit 2 + 错误清单 + 修复建议
L2 guard pre-check 通过后、API 调用前 src/commands/_blindspot_guards.ts ERROR → exit 2;WARN → 仅打印
L3 diagnose API 返回模糊错误时 src/core/client.ts:225 diagnoseError() log.warn 输出 3 类可能原因

新会话 4 步流程(AI 必跑):

# Step 1: 拉环境快照(消除 B 类根因:凭"经验"猜 dbLinkId/enCode)
dacli app context --json
# Step 2: 看懂已有什么
dacli form list && dacli dm list
# Step 3: 看命令 AI 用途 + 权威来源(不猜参数/API)
dacli <cmd> --ai-help      # 命令 AI 用途
dacli <cmd> --source       # 权威源码/API/ref 链接
dacli <cmd> --example      # JSON 参数示例
# Step 4: 执行 + 长任务自检(每 5 步)
bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/scripts/self-check.sh [form_id]

权威参照规则:参数/API/默认值不确定时,优先读 web/ 源码(web/apps/jnpf-web-apps-main/src/views/onlineDev/ + web/.../api/),不读 dacli 文档。dacli 文档是导航索引,web/ 源码是事实。

完整文档:.claude/skills/dacli-ts/SKILL.md + references/{errors,commands,patterns,web-source-map}.md

启动 & 常用命令

cd $ccWorkDir/dacli
npm install                              # 装依赖
npx playwright install chromium          # 装浏览器 (baseline E2E 用)

# CLI 调用
npx tsx src/cli.ts --help                # 入口 (启动 < 500ms)
npx tsx src/cli.ts app login --appCode=tds   # 登录 (v0.9 归入 app 命名空间)
npx tsx src/cli.ts app context --json    # ⭐ v0.10+ P0.1:AI 新会话第一步必跑
npx tsx src/cli.ts form list             # 列已有表单

# 提取 web 源码到 src/data/*.json
node scripts/extract-all.mjs
# v0.10+ 新增:从 web/ Vue 源码提取 schema/API → data/web-derived-schemas.json
python3 scripts/extract-web-schema.py

包脚本 (npm run ...):

  • dacli — tsx src/cli.ts (CLI 等价)
  • test — vitest run (单测)
  • test:e2e — playwright test (E2E)
  • extract — tsx scripts/extract-all.mjs (web 资产提取)
  • typecheck — tsc --noEmit (TS 校验)

架构

入口 → 命令分发

src/cli.ts                       # Commander.js 入口, 顶层注册 24 父命令 (v0.10+)
└── commands/                   # 24 父命令 / 116 子命令
    ├── form/      13 子 (list/info/create/release/delete/export/import/clone/validate/fixcolumndata/codegen/bindflow/lint + ...)
    ├── app/        9 子 (login/status/switch/init/create/clear/info/list/context)
    ├── user/      18 子
    ├── menu/       7 子
    ├── storage/    6 子
    ├── schedule/   5 子
    ├── workflow/   5 子
    ├── dm/         4 子 / dict: 4 / datasource: 4 / apis: 4 / portal: 4 / bigscreen: 4 / role: 4
    ├── msg:        3 子 / print: 3 / integration: 3 / monitor: 3 / org: 3 / report: 3
    ├── log:        2 子 / doc: 2
    └── di:         1 子
    + form/_blindspots.ts (BS-23/31/32/15/v2) + _precheck.ts + _blindspot_guards.ts (22 条)

每个父命令 index.ts 用 new Command('xxx') 构造,链式 addCommand 子命令。所有命令必带 3 个 flag:

  • --ai-help — 拦截输出 markdown 用法(core/help.ts:maybeInterceptAiHelp)
  • --example — 真实可跑示例
  • --source — 链接到源 web 代码位置

核心模块 (src/core/)

文件 职责
cli.ts 顶层 DacliError + 主循环 + 错误退出码
config.ts token / baseUrl / appCode 持久化(路径: cwd 下 .dacli-token/token.json,与 Java 版兼容)
crypto.ts 1:1 复刻 web/.../cipher.ts 加密(crypto-js 字节级一致)
log.ts 统一输出(带 ANSI 颜色,注意: Python 解析时必须 strip 颜色码)
help.ts maybeInterceptAiHelp — 在 Commander parse 之前拦截 --ai-help
types.ts 共享 TS 类型 + DacliError 类

数据流

.env / 配置文件
  ↓
config.ts 读 .dacli-token/token.json
  ↓
core/kit.ts (JNPF API 调用 + 错误处理)
  ↓
commands/<parent>/<subcommand>.ts
  ↓
output (JSON / table / --ai-help markdown)

缓存层

  • Token: $ccWorkDir/.dacli-token/token.json(7 天有效,不是 ~/.dacli/)
  • APIs 缓存: ~/.dacli/cache.db (SQLite) — JNPF /v3/api-docs 拉 1000+ API + schema
  • Dacli 缓存: .dacli-cache.db (项目根)

0 差错基线验证

tests/e2e/baseline/ 跑 114 张官方示例 (workSystem/developSystem),分两层:

  • API 0 错: vitest + dacli 命令串行执行
  • UI 0 视觉差: Playwright 截图 + pixelmatch 像素对比

一键脚本: .claude/skills/dacli-ts/examples/baseline/all.sh(设 SKIP_PLAYWRIGHT=1 仅跑 API)。

关键设计约束

TS 编译配置 (tsconfig.json)

  • target: ES2022, module: ES2022, moduleResolution: bundler
  • noEmit: true(用 tsx 跑,不编译)
  • allowImportingTsExtensions: true(.ts 后缀 import)
  • strict: true

FieldBuilder 自动加载

不要手写 schema。src/schema/FieldBuilder.ts 从 src/data/field-schemas.json(vue SFC 提取产物)动态加载。schema 升级靠重跑 node scripts/extract-all.mjs。

AI 能力闭环

.claude/skills/dacli-ts/SKILL.md 是配套技能,不读它就不知道何时用哪个命令。两者缺一不可。

子项目 skill

  • .claude/skills/dacli-ts/SKILL.md — 主技能(v0.10+ 强制:三层防御体系 + 强制参照 web/ 源码 + 长任务自检)
  • .claude/skills/dacli-ts/references/ — 6 专题文档:
    • errors.md — 错误决策树(26 段,AI 报错唯一推荐入口)
    • commands.md — 命令完整用法(含 form→dm 字段映射 R5 表)
    • patterns.md — 反模式 + 校准
    • web-source-map.md — web/ 源码权威映射(最高优先级,参数不确定先查这里)
    • playwright.md — 浏览器层使用指南
    • troubleshooting.md — ⚠️ 历史归档(已全部吸收到 errors.md / 代码 guard,仅 debug 历史问题按编号查)
  • .claude/skills/dacli-ts/examples/ — 7+ 可复用脚本(baseline、create-simple-form、菜单挂载等)
  • .claude/skills/dacli-ts/scripts/self-check.sh — v0.10+ 长任务自检脚本(每 5 步跑一次)

父项目约定

本项目从属于 $ccWorkDir/(含 JNPF 后端、前端、平台源码)。父项目规则:

  • 凭据 admin / 123456, 入口容器内 http://nginx/ http://nginx/api代理到 http://127.0.0.1:30000/api
  • 后端日志 $ccWorkDir/log/jnpf-java-boot/
  • 表名 snake_case 无前缀,字段 f_ 前缀(f_version 系统关键字禁用)
  • 修改范围: 仅本项目文件 + .claude/;禁止 改 ../jnpf/ ../web/ ../uniapp/
  • git dacli/ 独立 git 仓库

完整规则见 $ccWorkDir/.claude/CLAUDE.md。

已知盲点与兜底 (v0.10+, AI 必看)

v0.10+ 升级:高频 22 条盲点已从文档 → 代码 guard(src/commands/_blindspot_guards.ts),AI 不需要"记住",dacli 在执行时自动检查(详见 SKILL.md "三层防御体系")。

完整错误决策树: .claude/skills/dacli-ts/references/errors.md(26 段,按错误关键词查修复步骤) 历史归档: .claude/skills/dacli-ts/references/troubleshooting.md(52 条盲点流水账,仅 debug 历史问题按编号查)

高频盲点速查(v0.10+ 三层防御已自动覆盖)

# 盲点 触发场景 自动兜底
48 dbLinkId=0 或未设置 dacli form create --type=1 → "Database exception" L2 guard BS-48: exit 2 + 从 context 取正确 dbLinkId
49 enCode 重复 form create 失败后再用同 enCode → "Encoding cannot be repeated" L1 pre-check 拒绝 + L2 guard BS-49 提示改名 _v2/clone/delete
50 menu --formId 报 "主表不存在" form schema 缺主表信息 L2 guard BS-50: 提示走低级 --type=3 --urlAddress=model/{enCode}
51 浏览器层 list 白屏 dacli 简化 columnList 缺完整 schema 字段 L2 guard BS-51: 提示 dacli form clone / --tables / no-spa-page
47 dict 全平台唯一 dacli dict typeCreate 报 "The name cannot be repeated" L2 guard BS-47: 提示 <app>_ 前缀
5 AppContext 空 AI 凭猜测操作 L2 guard BS-5: 强制先跑 dacli app context --json
8 token 过期 JNPF 下线后操作 L2 guard BS-8: 提示 dacli app init -- --appCode=X --restart
38 f_description 系统列冲突 dm create 字段重名 L2 guard BS-38: 提示改名 f_desc/f_remark
39 f_version 关键字 form create 业务字段用 f_version L2 guard BS-39: 提示改名 f_version_no
28 bare flag 不生效 --autoRelease 看似生效但 state=0 L2 guard BS-28: WARN 提示 v12+ 已修

完整 22 条: src/commands/_blindspot_guards.ts (449 行, ERROR + WARN 两级) 集成测试: tests/integration/blindspot_guards.spec.ts (16/16 PASS)

详细反模式 + 完整代码示例见 .claude/skills/dacli-ts/references/anti-patterns.md。

# 盲点 触发 兜底
47 dict fullName/enCode 全平台唯一 dacli dict typeCreate 报 "The name cannot be repeated" 先 dacli dict dataList 查重,复用或加 <app>_ 前缀
48 form create 缺 --tables dacli form create --type=1/2 不传 --tables → "Database exception" 必传 --tables='[{table,tableName,fields}]'
49 enCode 失败残留 form create 失败后再用同 enCode → "Encoding cannot be repeated" 三选一:加 _v2 / form delete / form clone 重建
50 menu --formId + Actions/Module 失败 form schema 缺主表信息 → "主表不存在" 不传 --formId,走低级模式 --type=3 --urlAddress=model/{enCode}
51 浏览器层 list 白屏 dacli 简化 columnList 缺完整 schema 字段 dacli form clone <workSystem_id> 拿完整 schema,或用 no-spa-page 静态页兜底
52 dacli app clear mysql2 不支持 :app_code 报 "syntax error near ':app_code'" bindParams 先 .replace(/:app_code/g, '?') 再填 ?

详细反模式 + 完整代码示例见 .claude/skills/dacli-ts/references/anti-patterns.md。