6.5 KiB
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: bundlernoEmit: 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。