# 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 必跑): ```bash # Step 1: 拉环境快照(消除 B 类根因:凭"经验"猜 dbLinkId/enCode) dacli app context --json # Step 2: 看懂已有什么 dacli form list && dacli dm list # Step 3: 看命令 AI 用途 + 权威来源(不猜参数/API) dacli --ai-help # 命令 AI 用途 dacli --source # 权威源码/API/ref 链接 dacli --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` ## 启动 & 常用命令 ```bash 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//.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: 提示 `_` 前缀 | | 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` 查重,复用或加 `_` 前缀 | | 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 ` 拿完整 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`。