Files
dacli/CLAUDE.md
T

6.5 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 (最新校准)。

启动 & 常用命令

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 form list             # 列已有表单

# 提取 web 源码到 src/data/*.json
node scripts/extract-all.mjs

包脚本 (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 入口, 顶层注册 8 父命令
└── commands/
    ├── form/      index.ts + list/info/create/release/delete/export/import/clone/validate
    ├── dm/        list/create/drop/fields         (物理表 CRUD)
    ├── dict/      type-list/data-list             (字典)
    ├── menu/      list/create/delete/unrelease
    ├── di/        list                            (数据接口)
    ├── workflow/  list/launch/approve             (Flowable)
    ├── doc/       list                            (HTML 文档扫描)
    └── apis/      list                            (JNPF /v3/api-docs 缓存)

每个父命令 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.7 校准:form release 改 /Actions/Release 端点、dm create 改 web 真路径 dataModel/Form.vue:218 形态、menu create 退到低级 API 兜底等)
  • .claude/skills/dacli-ts/references/ — 6+ 专题文档(commands、playwright、troubleshooting、extraction 等)
  • .claude/skills/dacli-ts/examples/ — 7+ 可复用脚本(baseline、create-simple-form、菜单挂载等)

父项目约定

本项目从属于 $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.9+, AI 必看)

# 盲点 触发 兜底
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。