Files
dacli/CLAUDE.md
T

216 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <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`
## 启动 & 常用命令
```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/<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`。