feat(dacli): web/ 源码参照机制 + web-source-map.md (P0.3, 解决 AI 舍近求远根因 G)
This commit is contained in:
1 parent
7d630d374d
commit
8a21b07119
4 files changed
+849
-564
No files matched your search
@@ -1,597 +1,128 @@
|
||||
---
|
||||
name: dacli-ts
|
||||
description: Use when working with JNPF platform form/menu/workflow creation, data model design, dictionary setup, or data interface config — provides TypeScript-based dacli CLI commands to drive JNPF without manual UI clicks. Triggers on: 建表单/create form, 建菜单/create menu, 配字典/dictionary, 数据接口/data interface, 数据模型/data model, 工作流/workflow, 表单发布/release form, 表单列表/list forms, 查表单信息/form info, baseline 复刻/baseline clone, JNPF 后台操作, ssw 业务模块开发, 表单迁移. Apply when: 业务人员/AI 想要自动化配置 JNPF 而不是浏览器点击;批量迁移表单/菜单;AI 用 CLI 代替人类在设计器里拖拽;CI/CD 中调用 JNPF API;74 张官方示例的 0 差错验证。
|
||||
---
|
||||
## ⚠️ 权威参照规则(v0.10+ 强制)
|
||||
|
||||
# dacli-ts — AI 驱动的 JNPF CLI 工具 (TS 版)
|
||||
**任何 JNPF 相关参数、API 路径、默认值、校验逻辑不确定时,必须优先从 web/ 源码提取,而非读 dacli 文档。**
|
||||
|
||||
> **位置**: `$ccWorkDir/dacli/`(原 `test/dacli/`, 2026-06-12 升级到顶层独立项目)
|
||||
> **运行时**: Node 22 + tsx (启动 < 500ms)
|
||||
> **入口**: `npx tsx $ccWorkDir/dacli/src/cli.ts <command>`(或 `cd $ccWorkDir/dacli && npx tsx src/cli.ts <command>`)
|
||||
> **当前状态**: **v0.8.4 (2026-06-21) — 22 父命令 / 90+ 子命令 + 130+ baseline 0 差错 + apis/doc 4 新命令 + SQLite 持久化缓存**
|
||||
> **基线**: 8 v0.7.1 父 + 6 P0 + 5 P1 + 3 P2 = 22 父命令
|
||||
> **目标**: **0 差错** (workSystem 85 + developSystem 29 + 报表/门户/大屏/打印 16+ baseline 全 0 错)
|
||||
> **对照**: Java 版 `ssw-dacli` (已废弃归档) 见 `docs/dacli/ssw-dacli/`
|
||||
参照顺序(从权威到参考):
|
||||
1. **web/ 源码** — 权威事实
|
||||
- `web/apps/jnpf-web-apps-main/src/views/onlineDev/` — 表单创建/编辑的完整逻辑
|
||||
- `web/apps/jnpf-web-apps-main/src/api/` — API 端点定义
|
||||
2. **`references/web-source-map.md`** — 源码定位速查表
|
||||
3. **`references/commands.md` / `patterns.md`** — 仅作为导航索引
|
||||
4. **自己的推理** — 最后选择,必须与 #1 对照验证
|
||||
|
||||
**核心参照文件**(按使用频率):
|
||||
- `views/onlineDev/formDesign/Form.vue` → form 创建的精确字段默认值
|
||||
- `views/onlineDev/sysForm/Form.vue` → 报表/门户创建的精确字段默认值
|
||||
- `api/onlineDev/visualDev.ts` → 所有 visualdev API 端点
|
||||
- `api/systemData/dataModel.ts` → 数据模型 API 端点
|
||||
- `api/systemData/dataSource.ts` → 数据连接选择器(获取 dbLinkId 选项)
|
||||
- `formDesign/components/CreateMenuModal.vue` → 发布菜单完整流程
|
||||
|
||||
**如果 dacli 文档与 web/ 源码不一致,以 web/ 源码为准**——直接读源码,不要相信文档。
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.9 关键校准 (2026-06-22, AI 必读 — `dacli app clear` 移植)
|
||||
# dacli (TS 版) — AI 驱动 JNPF CLI
|
||||
|
||||
| 校准项 | 旧 (v0.8.4) | 新 (v0.9) | 影响 |
|
||||
|--------|-----------|------------|------|
|
||||
| **`dacli app clear` (P0, 新)** | 不存在 (TS 版报 `unknown command 'clear'`), 仅 Java 归档版 `docs/dacli/ssw-dacli/` 有 | TS 版 `src/commands/app/clear.ts` (~580 行), mysql2/promise + yaml + readline/promises + TTY 强制 + 双重人工确认 | 完整保留 Java 版 6 阶段法 (文件 → pom → yml → DB Phase 1/2/3 → token → MANIFEST); AI 可 `--dry-run` 看清单, 真跑需用户**亲自键入** `appCode` + `DELETE` |
|
||||
| **`--no-restart` flag** | n/a | 默认 true (`--restart`), `dacli app create --appCode=X --appName=Y --force-rebuild` 子进程 inherit stdio | TS 版无 `dacli app init` 创建应用 (只有健康检查 + 重启), --restart 改为调 `app create` |
|
||||
| **`mysql2` 移到 `dependencies`** | devDep (仅 E2E 测试用) | dep (clear 命令直接连 MySQL 跑 RENAME / INSERT SELECT / DELETE) | `npm install` 一条到位, 不再需要 dev 模式 |
|
||||
| **TS 版无 `:app_code` 命名占位符** | n/a | `bindParams` 先 `.replace(/:app_code/g, '?')` 再按 `TABLES_PARAMS_BY_APP_CODE` 表决定填 systemId / appCode | mysql2 只支持位置占位符; Java 版 `:app_code` 是 JPA/Hibernate 语法必须先替换 |
|
||||
| **AI 严禁键入 DELETE 确认** | Java 版已强制 | TS 版同样强制: `process.stdin.isTTY && process.stdout.isTTY` 必须为 true, 否则 `process.exit(1)` | 管道 / Heredoc / 重定向 / AI Bash 工具全部拒绝; `--dry-run` 是唯一 AI 安全的入口 |
|
||||
> v0.9+ | 项目位置: `$ccWorkDir/dacli/` | 调用: `npx tsx $ccWorkDir/dacli/src/cli.ts ...`
|
||||
|
||||
**为什么需要 clear 移植**:Java 版 `ClearAppCommand.java` 是破坏性工具的核心实现, 但 mvn 构建 + jar 启动慢 (~3s), TS 版 tsx 启动 <500ms, AI 操作员体验更好。
|
||||
## ⚠️ 最高优先级 4 条规则
|
||||
|
||||
**详细实现**: `src/commands/app/clear.ts` (单文件, 6 阶段法), 复用 `core/{config,log,help}.ts` + `mysql2/promise` (从 devDeps 移到 deps) + `yaml` (已在 deps) + `readline/promises` (Node std)。
|
||||
1. **新会话第一步必跑** `dacli app context --json`(所有参数从此快照取,不要猜)
|
||||
2. **参数/API 不确定时先查 web/ 源码**(见 `references/web-source-map.md`),不查文档
|
||||
3. **失败时不要重复猜测参数**——先跑 `dacli <cmd> --ai-help` 看用途,跑 `dacli <cmd> --source` 看权威来源
|
||||
4. **执行前先 lint**:`dacli form lint --help`(设计期校验,无需 JNPF)
|
||||
|
||||
---
|
||||
## 🚀 最高频 10 命令
|
||||
|
||||
## 🆕 v0.8.4 关键校准 (2026-06-21, AI 必读 — apis/doc 4 新命令 + SQLite 持久化)
|
||||
|
||||
| 校准项 | 旧 (v0.8.3) | 新 (v0.8.4) | 影响 |
|
||||
|--------|-----------|------------|------|
|
||||
| **`dacli apis info` (P0, 新)** | 不存在 (TS 版) | `dacli apis info "GET /api/xxx"` 拿单 endpoint 详情 + **递归解析 `$ref` 展开 schema** + **自动展开 `ActionResult.data` 内层** | AI 写后端/调 API 必备, 之前 list + jq 过滤**无法展开 `$ref`** |
|
||||
| **`dacli apis refresh` (P1, 新)** | 不存在 | 强制重拉 `/v3/api-docs`, 忽略 12h TTL, JNPF 升级/新增 API 后用 | 不再等 12h, 立即生效 |
|
||||
| **`dacli apis status` (P1, 新)** | 不存在 | 缓存状态 (loaded/ageMs/pathCount/openapiSize), 诊断"为什么 list 看不到新 API" | AI 排错 |
|
||||
| **`dacli doc get` (P0, 新)** | 不存在 (TS 版) | 读 HTML 文档 section/行号纯文本, 3 种切片模式 (`--section`/`--from --lines`/全文) + `--strip-mermaid` + **SQLite mtime 缓存** | **上下文恢复核心 (CLAUDE.md 强调 token 降低 80%)**, 之前 `Read` 工具读整 HTML 不切片 |
|
||||
| **apis/doc 缓存架构** | in-memory Map (进程退出清空) | **SQLite (better-sqlite3, WAL 模式)** 跨 process 持久化, `~/.dacli/cache.db` (~1MB) | 之前 `apis info` 每次新 process 都重拉 1MB, 现在 0 延迟命中 |
|
||||
|
||||
**缓存路径** (可配):
|
||||
- 默认: `~/.dacli/cache.db` (WAL 模式, 自动建表)
|
||||
- 环境变量: `$DACLI_CACHE_DIR/cache.db`
|
||||
|
||||
**SQLite Key 规范** (与 Java 版 SqliteCacheService 一致):
|
||||
- `dacli:apidoc:openapi/loaded/pid` — OpenAPI 缓存 (12h TTL)
|
||||
- `dacli:doc:mtime:{fileHash}/raw:{fileHash}/section:{fileHash}:{id}` — 文档缓存 (7 天 TTL)
|
||||
|
||||
详见 [references/commands.md](references/commands.md) §2.5-2.6 (apis) §6.2 (doc) + [src/core/sqlite_cache.ts](../../src/core/sqlite_cache.ts).
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.8.1 关键校准 (2026-06-13, AI 必读)
|
||||
|
||||
| 校准项 | 旧 (v0.8) | 新 (v0.8.1) | 影响 |
|
||||
|--------|-----------|------------|------|
|
||||
| **`dacli log login/operate` category 参数** | 传字符串 `'login'`/`'operate'` | 传 int 字符串 `'1'`/`'3'` (后端期望 int 枚举) | 不再 BindException, 真返日志 |
|
||||
| **`dacli portal release` 缺 formData** | body `{}` 后端报"formData 必填" | 补 `pc` + `app` + `platformRelease` 三参 (web `ReleaseModal.vue` 真值) | 不再 400, 支持 `--pc` / `--app` 双端开关 |
|
||||
| **`dacli form validate` 老 form 误报** | 老流程表单 `formData=[]` 报 "fields 不是数组" | 兼容 `{fields:[]}` 和 flat array 两种形态, `null` 改 WARN | 不再误报 |
|
||||
| **`dacli schedule list` 端点 bug** | 静默返空 body (JNPF 6.2 bug) | 改用 GET 兜底 + 4 兜底方案 (info/log/trigger/create) | 明确兜底, 写进命令注释 |
|
||||
|
||||
详见 [references/troubleshooting.md](references/troubleshooting.md) 错误 24-27 + [doc/v0.8.1-changelog.md](../../../doc/v0.8.1-changelog.md).
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.8.3 关键校准 (2026-06-19, AI 必读 — 老 workFlow form 三类兼容)
|
||||
|
||||
| 校准项 | 旧 (v0.8.2) | 新 (v0.8.3) | 影响 |
|
||||
|--------|-----------|------------|------|
|
||||
| **`fixcolumndata` 空数组 columnData 不生效** (盲点 34) | `patchColumnData()` 把 `use*Permission` 加在 array 上 → `JSON.stringify([])` 永远 `"[]"`, `changed: true` 是误判, fix 静默无效 | 只把 plain object 当可 patch 目标; array/null/缺字段对象 → 一律视为 `{}` 重写 4 字段 | 老 form (columnData=`"[]"`) 真正修通, BS-23 闭环 |
|
||||
| **`checkBs31` 在老 workFlow form 误报 label 空** (盲点 35) | 老 workFlow form `formData` 是 flat list `[{filedName, filedId, ...}]`, 校验 `__config__.label` 找不到 → 报 15 次 ERROR | 优先 `__config__.label` (新表单), 缺失时回退到 `filedName` (老 workFlow form 的 label 等价物); path 用 `__vModel__ || filedId` | 老 workFlow form 不再误报 15 个 BS-31 |
|
||||
| **`checkBs15` 老 form tables 无 fields[] 误报** (盲点 36) | 老 workFlow form `tables=[{table, tableName, typeId}]` 无 `fields[]`, 校验 `f_flow_task_id` 找不到 → ERROR | `Array.isArray(t.fields)===false` → 降级为 WARN (提示"请人工确认 DB schema"); 有 fields 但缺 → 仍 ERROR | 老 workFlow form 不再误报 BS-15 |
|
||||
|
||||
**如何识别老 workFlow form**:
|
||||
- `enableFlow === 1`
|
||||
- `formData` 是 list 不是 `{fields: [...]}` (或 list 里每项只有 `filedName/filedId/required/tableName`)
|
||||
- `tables[i].fields === undefined` (只有 `table/tableName/typeId`)
|
||||
|
||||
**典型场景**:
|
||||
- workSystem `leaveApply` (1589964488616407041)
|
||||
- workSystem 任何 `enableFlow=1` 且 `formData` 是 flat list 的老 form
|
||||
|
||||
**修法** (新行为已自动兼容):
|
||||
```bash
|
||||
dacli form validate <id> # 期望: 0 ERROR, 0-1 WARN
|
||||
dacli form fixcolumndata <id> # 现在真正修通 columnData
|
||||
```
|
||||
|
||||
详见 [references/troubleshooting.md](references/troubleshooting.md) 错误 34-36 + [doc/v0.8.3-changelog.md](../../../doc/v0.8.3-changelog.md).
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.7.1 关键校准 (2026-06-12, AI 必读)
|
||||
|
||||
| 校准项 | 旧 (v0.7) | 新 (v0.7.1) | 影响 |
|
||||
|--------|-----------|------------|------|
|
||||
| **form create columnData 字段** | 缺 4 个 `use*Permission` (useBtnPermission/useColumnPermission/useFormPermission/useDataPermission) | 显式补 `false` | 后端 `VisualUtil.setPcPermission:139` 不再 NPE, Actions/Module 不再"System abnormality" |
|
||||
| **dacli form fixcolumndata** | `fixcolumn` | 新增 `dacli form fixcolumndata <id>` | 修老 form 的 columnData (v0.7 前漏字段的), PUT 回去, `--dry-run` 只看不改 |
|
||||
| **menu create --formId 自动父菜单** | `--pcParents` 默认 `['0']` (tds 等应用无 id=0) → 报"找不到该上级" | 不传 `--pcParents` 时自动调 `/system/Menu/SelectorFilter/0?category=Web` 拉 Web 根菜单 (web `getMenuSelectorFilter` 同款) | 不传参也能跑, 修盲点 23 续 |
|
||||
| **menu create Actions/Module 失败** | tds 报"System abnormality" → 退低级路径 (但 moduleId=null) | Actions/Module 真路径成功 (columnData 修了 + 父菜单自动找), 真正绑 moduleId, `/model/<enCode>` 真渲染 | 解锁 P0 #16 UI 真点击 CRUD |
|
||||
|
||||
详见 [doc/v0.7.1-changelog.md](../../../doc/v0.7.1-changelog.md) + [references/troubleshooting.md](references/troubleshooting.md) 错误 23.
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.7 关键校准 (2026-06-12, AI 必读)
|
||||
|
||||
| 校准项 | 旧 (v0.6) | 新 (v0.7) | 影响 |
|
||||
|--------|-----------|-----------|------|
|
||||
| **form release endpoint** | PUT `/Actions/State` (返 200 但 state 没真变) | **POST `/Actions/Release`** (web 真路径) | release 真生效, 不再有"假成功" |
|
||||
| **dm create body shape** | flat `{table, fields, primaryKeyPolicy, ...}` | **`{tableInfo: {...}, tableFieldList: [...]}`** (web `dataModel/Form.vue:218` 同款) | 老 shape 报 `getTableInfo() null` NPE |
|
||||
| **dm create 自动补 PK** | 不补 | 自动补 `f_id` + `f_tenant_id` 复合 PK + 9 系统列 | 否则 `DbFieldForm.getPrimaryKey() null` NPE |
|
||||
| **dm fields 解析** | 只看 `{ fields: [...] }` | 兼容 `{ list / fields / array }` 三形态 | 老代码报 0 字段假象 |
|
||||
| **form export 带物理 schema** | 只导 form 元数据 | 同时调 `/Tables/{t}/Fields` 拉 `_physicalSchema` | 解 #15 跨应用 import 不建表 bug |
|
||||
| **form import 默认 `--autoTable`** | 没建表能力, 浏览器"该表单已删除" | 默认 true: import 前先建物理表 (复用 `_physicalSchema` 或 `tables[].fields[]`) | 跨应用迁移真闭环 |
|
||||
| **form create 必传 `--tables`** | 不传时建空表 (`<enCode>_clone`) | 文档校准: type=1/2 必传 `--tables` 引用已有表 | 不再误建表 |
|
||||
| **menu create Actions/Module 失败 fallback** | 卡死报 "System abnormality" | 退到低级 `POST /system/Menu` 100% 工作 | tds 等业务库菜单挂得上 |
|
||||
| **P0 #13 AI 真闭环验证** | 留 P0 | 已验证: subagent 用 dacli-ts 从零搭 `tds_leave` 请假表单 + CRUD 真路径 200 | dacli-ts skill **可独立支撑 AI 完成业务** |
|
||||
|
||||
详见 [doc/v0.7-changelog.md](../../../doc/v0.7-changelog.md) + [references/troubleshooting.md](references/troubleshooting.md) 错误 18-22.
|
||||
|
||||
---
|
||||
|
||||
## 🆕 v0.6 关键校准 (2026-06-12, AI 必读)
|
||||
|
||||
| 校准项 | 旧 (v0.5) | 新 (v0.6) | 影响 |
|
||||
|--------|-----------|-----------|------|
|
||||
| **form list 真总数** | workSystem 52 / developSystem 20 | workSystem **85** / developSystem **29** | v0.5 走 `/list` 子端点强制 `enableFlow=1` → 漏 33+9 张非工作流 form |
|
||||
| **list 端点修复** | GET `/visualdev/Base/list` | GET `/visualdev/Base` | 见 `src/commands/form/list.ts` + import.ts |
|
||||
| **浏览器登录路径** | `/web/#/login` (admin 无菜单 → 404) | `/jnpf_app_<app>/login` + `/home` (每 app 独立) | 来自 ssw-e2e-test |
|
||||
| **浏览器会话复用** | 每个 spec 重登 | Playwright `projects.setup` + `storageState`, TTL 6h | 见 `tests/e2e/auth.setup.ts` |
|
||||
| **menu create 真路径** | POST /api/system/Menu (低级, 字段易漏) | POST `/api/visualdev/Base/{formId}/Actions/Module` (web 高级 API) | 后端自动 moduleId/propertyJson/授权; 见 `web/views/onlineDev/formDesign/components/CreateMenuModal.vue` |
|
||||
| **menu unrelease 新命令** | - | `dacli menu unrelease --formId=X` (Actions/Module pc=0 app=0) | DELETE /api/system/Menu/X 报 "System abnormality" 时兜底 |
|
||||
| **挂菜单 + /model/X 规则** | 隐式 | **至少一个菜单挂表单, `/jnpf_app_<app>/model/<enCode>` 才生效** (vue-router 动态注册) | 没挂菜单访问必 404 |
|
||||
| **真业务 vs 预览** | 混用 | `/model/<enCode>` 真业务 (能 CRUD), `/previewModel?isPreview=1` 只读预览 | previewModel 不能真保存! |
|
||||
| **form import 已知 bug** | 报"成功" 但浏览器"该表单已删除" | 留 #15 — import 只复制元数据, 不建底层物理表 | 真验证用 #13 AI 重建 |
|
||||
|
||||
详见 [references/playwright.md](references/playwright.md) §2.1-3.5.
|
||||
|
||||
---
|
||||
|
||||
## ✅ v0.6 状态 (AI 必读 — 全部命令可用了)
|
||||
|
||||
| 命令 | 端到端验证 | 子命令 | 备注 |
|
||||
|------|------------|--------|------|
|
||||
| `dacli app login / status / switch-app` | ✅ | 3 顶层 | token 持久化 + dbLinkId 自动检测 |
|
||||
| `dacli form` | ✅ | list/info/create/release/delete/export/import/clone/validate/**fix-columndata**/**lint** (11) | v0.7.1 修 columnData 缺字段, 加修老 form 工具; v0.9 加 lint: 阶段 2 末设计期检查, 复用 5 类盲点规则, 不需 JNPF server |
|
||||
| `dacli dm` | ✅ | list/create/drop/fields (4) | 物理表 CRUD |
|
||||
| `dacli dict` | ✅ | type-list/data-list (2) | 字典类型 + 数据 |
|
||||
| `dacli menu` | ✅ | list/create/delete/**unrelease** (4) | create 改 web 真路径; unrelease 新加 |
|
||||
| `dacli di` | ✅ | list (1) | 数据接口 (弹窗/下拉/关联表单用) |
|
||||
| `dacli workflow` | ✅ | list/launch/approve (3) | 流程模板/发起/审批 |
|
||||
| `dacli doc` | ✅ | list (1) | HTML 文档扫描 |
|
||||
| `dacli apis` | ✅ | list (1) | JNPF OpenAPI /v3/api-docs 查 |
|
||||
|
||||
**测试覆盖** (v0.8.1 末):
|
||||
- 103/103 vitest 单测 PASS (12 文件, 含 FieldBuilder 18 + crypto 5 + config 5 + cli-help 5)
|
||||
- 25 PASS + 4 skip + 3 fail (P0 #13/#16 已知遗留) Playwright E2E
|
||||
- **baseline 验证 114 张 form schema 完整** (developSystem 29 + workSystem 85, 0 错)
|
||||
- typecheck 零警告
|
||||
|
||||
**AI 工作时的选择**:
|
||||
- 所有命令 TS 版已可用, **优先用 TS 版** (命令简洁 + 启动 < 500ms)
|
||||
- 视觉对比 (Playwright 0 视觉差) 仍需手工写 spec, 见 [references/playwright.md](references/playwright.md)
|
||||
- Java 版仅在 TS 版没实现的边缘场景兜底 (e.g. 报表/门户/portal/codegen)
|
||||
|
||||
---
|
||||
|
||||
## 0. 何时使用本 skill
|
||||
|
||||
### 触发场景
|
||||
|
||||
| 用户说 | AI 应该 |
|
||||
|--------|--------|
|
||||
| "建一个请假流程" | → `dacli form create + dacli workflow create + dacli menu create` |
|
||||
| "把这 5 张表单迁到 tds" | → `dacli form export` × 5 + `dacli form import` × 5 |
|
||||
| "批量加个字典分类" | → `dacli dict data-create` 循环 |
|
||||
| "查下这个表单字段" | → `dacli form info <id>` |
|
||||
| "测一下这个 API" | → `dacli apis list --keyword=<path>` (v0.7+ 无 info) |
|
||||
| "跑 baseline 复刻" | → `bash examples/baseline/all.sh` |
|
||||
| "dacli form create 失败" | → [references/troubleshooting.md](references/troubleshooting.md) |
|
||||
| "log login/operate 报 int 错" | → troubleshooting.md 错误 24 |
|
||||
| "portal release 报 formData 必填" | → troubleshooting.md 错误 25 |
|
||||
| "form validate 老 form 误报" | → troubleshooting.md 错误 26 |
|
||||
| "schedule list 返空" | → troubleshooting.md 错误 27 |
|
||||
| "找不到错误怎么解" | → troubleshooting.md 错误 1-27 |
|
||||
|
||||
### 不适用场景
|
||||
|
||||
| 场景 | 原因 |
|
||||
| 命令 | 用途 |
|
||||
|------|------|
|
||||
| 修改 JNPF 平台源码 | CLAUDE.md 禁止 |
|
||||
| 改 ssw 业务 Java 代码 | 走 `backend-dev` 技能 |
|
||||
| 仅查文档/写 design | 直接用 web 源码或设计模板 |
|
||||
| 一次性手动点 1 个表单 | 不如浏览器 |
|
||||
| `dacli app login --account=admin --password=123456 --appCode=X` | 登录 |
|
||||
| `dacli app status` | 看当前登录态 |
|
||||
| `dacli app context --json` | **新会话必跑**,环境快照 |
|
||||
| `dacli app switch --appCode=X` | 切应用 |
|
||||
| `dacli form list` / `dacli form info <id>` | 列表单 / 查表单详情 |
|
||||
| `dacli form create --fullName=X --enCode=Y ...` | 建表单 |
|
||||
| `dacli form clone <id>` | 克隆表单(优先于 create) |
|
||||
| `dacli form validate <id>` | 校验盲点 |
|
||||
| `dacli dm list` / `dacli dm create` | 数据模型 |
|
||||
| `dacli menu create --type=3 --urlAddress=model/{enCode}` | 建菜单 |
|
||||
|
||||
---
|
||||
## 📚 详细文档(按需加载,不要全读)
|
||||
|
||||
## 1. 启动与基础
|
||||
- **命令完整用法** → `references/commands.md`
|
||||
- **反模式 + 校准** → `references/patterns.md`(盲点 + 最佳实践)
|
||||
- **错误诊断决策树** → `references/errors.md`(错误→检查项→修复)
|
||||
- **web/ 源码权威映射** → `references/web-source-map.md`(**最高优先级**,先查这里)
|
||||
|
||||
### 1.1 首次使用
|
||||
## 🔧 调试与恢复
|
||||
|
||||
```bash
|
||||
cd $ccWorkDir/dacli
|
||||
npm install # 装依赖
|
||||
npx playwright install chromium # 装浏览器 (baseline 验证用)
|
||||
npx tsx scripts/extract-all.mjs # 提取 web 源码到 data/*.json
|
||||
npx tsx src/cli.ts login --appCode=tds # 登录 tds
|
||||
# 报错第一步
|
||||
dacli app status # 检查登录态
|
||||
dacli <cmd> --ai-help # 命令 AI 用途
|
||||
dacli <cmd> --source # 权威来源(web/api/ref)
|
||||
dacli tool logs --level=error --lines=50 # 后端错误日志
|
||||
|
||||
# JNPF 下线恢复
|
||||
dacli app init -- --appCode=X --restart # 自动 kill + nohup + 健康检查 + 重登
|
||||
|
||||
# 浏览器层 tdd 404 (nginx 代理阻塞)
|
||||
dacli app switch --appCode=workSystem # 切到 workSystem 验证或仅做 API 验证
|
||||
```
|
||||
|
||||
**应用对象**:
|
||||
- `tds` (http://127.0.0.1:13880/api) — 实际业务应用
|
||||
- `developSystem` — 21 张 baseline 示例
|
||||
- `workSystem` — 53 张 baseline 示例
|
||||
- 用户: `admin / 123456`
|
||||
## 📦 架构速记
|
||||
|
||||
### 1.2 状态查询
|
||||
- **多 app**:请求头 `App-Code: {app_code}` → 后端解析 systemId
|
||||
- **webType**:1=仅表单, 2=表单+列表, 3=表单+列表(树), 4=数据视图
|
||||
- **type**:1=普通, 2=报表, 3=门户
|
||||
- **dbLinkId**:0=主库(平台库), 非0=业务库;token.json 自动存
|
||||
- **建表命名**:snake_case 无前缀, 字段 `f_` 前缀(`f_version` 是系统关键字禁用)
|
||||
- **默认凭据**:admin / 123456(dacli app login / 浏览器登录通用)
|
||||
|
||||
---
|
||||
|
||||
## 🔁 长任务自检规则
|
||||
|
||||
避免"错了继续跑"导致错误雪崩(E 类根因:**"不停下来问"变成"错了继续"**)。
|
||||
在长流程中**每 5 个 dacli 命令执行后**,强制做一次自检:
|
||||
|
||||
```bash
|
||||
npx tsx src/cli.ts status # 文本输出
|
||||
npx tsx src/cli.ts status --json # JSON 输出 (脚本用)
|
||||
# → baseUrl / token 路径 / 当前 appCode / dbLinkId / loginAt
|
||||
# 自检 1: TS 编译(捕获类型错误)
|
||||
cd /home/ubuntu/ccWorkDir/dacli && npx tsc --noEmit
|
||||
|
||||
# 自检 2: form schema 校验(如果刚改了 form)
|
||||
dacli form validate <form_id>
|
||||
|
||||
# 自检 3: 后端日志(看是否有暗错)
|
||||
dacli tool logs --level=error --lines=50
|
||||
```
|
||||
|
||||
### 1.3 切换应用
|
||||
**或直接用脚本**(容忍单步失败):
|
||||
|
||||
```bash
|
||||
npx tsx src/cli.ts switch-app --appCode=developSystem # baseline
|
||||
npx tsx src/cli.ts switch-app --appCode=workSystem # baseline
|
||||
npx tsx src/cli.ts switch-app --appCode=tds # 业务
|
||||
bash /home/ubuntu/ccWorkDir/.claude/skills/dacli-ts/scripts/self-check.sh [form_id]
|
||||
```
|
||||
|
||||
---
|
||||
**自检失败处理**:
|
||||
- 立即暂停后续命令
|
||||
- 输出失败详情(不要简化为"自检失败")
|
||||
- 询问用户是否继续或回滚
|
||||
|
||||
## 2. 22 大父命令速查 (v0.8 扩 14 父)
|
||||
**自检通过处理**:
|
||||
- 输出 `✅ self-check OK (N/M 步骤)`
|
||||
- 自动继续下一个 5 命令组
|
||||
|
||||
### 2.1 v0.7.1 旧 8 父命令 (已稳定)
|
||||
|
||||
| 命令 | 用途 | 子命令数 | 详细 |
|
||||
|------|------|---------|------|
|
||||
| `dacli form` | 表单 CRUD (clone/release/import/export 全跑通, v0.8.1 validate 兼容老 flat array) | 10 | [commands.md](references/commands.md#form), 错误 26 |
|
||||
| `dacli dm` | 数据模型 (业务库物理表) | 4 | [commands.md](references/commands.md#dm) |
|
||||
| `dacli dict` | 字典 (类型 + 数据) | 2 | [commands.md](references/commands.md#dict) |
|
||||
| `dacli menu` | 菜单 (按 app) | 4 | [commands.md](references/commands.md#menu) |
|
||||
| `dacli di` | 数据接口 (弹窗/下拉/关联) | 1 | [commands.md](references/commands.md#di) |
|
||||
| `dacli workflow` | 工作流 (模板/发起/审批) | 3 | [commands.md](references/commands.md#workflow) |
|
||||
| `dacli doc` | HTML 文档 (从 docs/ 扫描) | 1 | [commands.md](references/commands.md#doc) |
|
||||
| `dacli apis` | JNPF OpenAPI 查 (v3/api-docs) | 1 | [commands.md](references/commands.md#apis) |
|
||||
|
||||
### 2.2 v0.8 P0 新增 6 父命令 (设计器 4 件套 + 数据源 + 应用)
|
||||
|
||||
| 命令 | 用途 | 子命令 | 决策 |
|
||||
|------|------|--------|------|
|
||||
| `dacli datasource` | 数据源 (MySQL/SQLServer/Oracle/PostgreSQL/DM/Kingbase) | 4 (list/create/test/delete) | - |
|
||||
| `dacli report` | **只读模板** (JNPF 无 create/release 端点) | 3 (list/info/templates) | 决策 6 |
|
||||
| `dacli portal` | 门户设计器 (首页/工作台, v0.8.1 release 补 formData 三参) | 4 (list/info/create/release) | 决策 6, 错误 25 |
|
||||
| `dacli bigscreen` | 大屏设计器 (数据可视化) | 4 (list/info/create/release) | 决策 6 |
|
||||
| `dacli print` | 打印模板 (绑 form 数据) | 3 (list/info/create) | 决策 6 |
|
||||
| `dacli app` | 多 app 生命周期 (14 应用) | 3 (list/info/initapp) | - |
|
||||
|
||||
### 2.3 v0.8 P1 新增 5 父命令 (权限三角 + 消息 + 调度)
|
||||
|
||||
| 命令 | 用途 | 子命令 | 决策 |
|
||||
|------|------|--------|------|
|
||||
| `dacli role` | 角色 (权限三角 1 号) | 4 (list/create/delete/assign) | 决策 7 |
|
||||
| `dacli user` | 用户 (权限三角 2 号) | 18 (v18: 4 基础+10 admin+2 self+2 auth) | 决策 7 |
|
||||
| `dacli org` | 组织 (权限三角 3 号) | 3 (list/tree/create) | 决策 7 |
|
||||
| `dacli msg` | 消息中心 (通知 + 模板) | 5 (notice-list/create/send, template-list/create) | 决策 8 |
|
||||
| `dacli schedule` | 定时任务 (Quartz, v0.8.1 已知 JNPF list 端点 bug, info/trigger/log/create 可用) | 5 (list/info/create/trigger/log) | 决策 9, 错误 27 |
|
||||
|
||||
### 2.4 v0.8 P2 新增 3 父命令 (监控 + 日志 + 集成)
|
||||
|
||||
| 命令 | 用途 | 子命令 |
|
||||
|------|------|--------|
|
||||
| `dacli monitor` | 监控 (在线用户/SQL 监控/流程监控) | 3 (online/sql/flow) |
|
||||
| `dacli log` | 日志 (登录日志 + 操作日志, v0.8.1 category 用 int '1'/'3') | 2 (login/operate) | 错误 24 |
|
||||
| `dacli integration` | 集成 (邮件/短信/Webhook 测试) | 3 (email-test/sms-test/webhook-test) |
|
||||
|
||||
### 2.5 v18 user 父命令扩充 (4 → 18)
|
||||
|
||||
**100% 覆盖 web 端用户操作**(除 Excel 导入导出):
|
||||
|
||||
| 类别 | 子命令 | 操作 |
|
||||
|------|--------|------|
|
||||
| **基础 (4)** | `list` / `create` / `update` / `delete` | admin 增删改查 + 部分字段更新 |
|
||||
| | `resetPwd` (alias `reset-pwd`) / `unlock` | admin 重置密码 / 解除锁定 |
|
||||
| **批量 (3)** | `batch-state` / `batch-delete` / `batch-set-position` | admin 批量启禁删 / 设岗位 |
|
||||
| **岗位 (2)** | `get-position` / `set-position` | admin 查 / 设用户岗位 |
|
||||
| **高级 (3)** | `workHandover` / `socials-unbind` / `online-kick` | admin 工作交接 / 解绑社交 / 强制下线 |
|
||||
| **self (2)** | `changepwd` / `baseinfo` | self 改密 / 改资料 |
|
||||
| **auth (2)** | `auth-groups` / `auth-list` | admin 查权限分组 / 7 类权限 |
|
||||
|
||||
**重要参数模式**:
|
||||
- `update` / `baseinfo` 用 `--fields '<json>'` 传任意字段子集(避免 flag 爆炸)
|
||||
- `batch-state` / `batch-delete` / `batch-set-position` 用 `--ids`(逗号分隔字符串)+ `--yes`(防误删)
|
||||
- `changepwd` 成功后自动清本地 token(强制重新登录)
|
||||
- `online-kick` 支持防自踢(默认会阻止自己踢自己,需 `--force`)
|
||||
|
||||
**示例**:
|
||||
```bash
|
||||
dacli user list
|
||||
dacli user create --account=u1 --realName=U1 --password=123456 --organizeId=<id>
|
||||
dacli user update --id=<id> --fields='{"realName":"新名","enabledMark":1}'
|
||||
dacli user batch-state --ids=1,2,3 --state=1
|
||||
dacli user workHandover --fromUserId=<id> --toUserId=<id>
|
||||
dacli user changepwd --oldPassword=123456 --newPassword=abc
|
||||
dacli user auth-list --userId=<id> --objectId=<roleId> --objectType=role
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. ⭐ 5 大决策点 (AI 经常错)
|
||||
|
||||
> **核心**: 这 5 个决策 AI 经常判断错, 按下表查
|
||||
|
||||
### 决策 1: 创建表单用哪个 type?
|
||||
|
||||
| 场景 | type | webType | 是否需要物理表 |
|
||||
|------|------|---------|--------------|
|
||||
| 单表 CRUD | **1** | 2 | ✅ 需要 |
|
||||
| 主子表 | **1** | 2 | ✅ 需要 2+ 张 |
|
||||
| 系统表单 | 2 | 2 | (平台内置) |
|
||||
| **快速 POC / 视图** | **4** | 1 | ❌ 不需要 |
|
||||
| 数据接口 | 3 | - | ❌ |
|
||||
|
||||
**AI 反模式**: 默认 `type=1, webType=2` 然后去硬建表 → 90% 概率 "Database exception"
|
||||
**AI 正解**: 先 `dacli dm list` 看库里有什么表 → 复用;或先 `type=4` 跑通再升级
|
||||
|
||||
### 决策 2: form 提交后是否要 release?
|
||||
|
||||
| 场景 | release? |
|
||||
|------|----------|
|
||||
| type=1 (主表) | ✅ 必须 |
|
||||
| type=2 (系统表单) | ✅ |
|
||||
| type=3 (数据接口) | ✅ |
|
||||
| **type=4 (视图)** | **❌ 不需,会 400** |
|
||||
|
||||
### 决策 3: 表单菜单 type 几?
|
||||
|
||||
| 菜单类型 | type | category | 必须含 |
|
||||
|---------|------|----------|--------|
|
||||
| 表单菜单 (挂表单) | **3** | Web | `moduleId=<formId>` + `urlAddress='model/{enCode}'` |
|
||||
| 目录 | 1 | Web | - |
|
||||
| 链接 | 7 | Web | `linkTarget=_blank` |
|
||||
|
||||
### 决策 4: 怎么处理 "Database exception"?
|
||||
|
||||
| 原因 | 解决 |
|
||||
|------|------|
|
||||
| `dbLinkId='0'` 错 | 先 `dacli app status` 看真实 dbLinkId |
|
||||
| `tables[].fields[]` 缺字段 | 用 `type=4` 视图绕开 |
|
||||
| `category='0'` 错 | `dacli form list` 看已有 form 的 category |
|
||||
| **不传 --tables** | 必传 `--tables='[{table,tableName,fields}]'`,参考 BS-48 |
|
||||
| 服务器限流 | `sleep 30` 重试 |
|
||||
|
||||
### 决策 5: 端到端业务实现路径
|
||||
|
||||
**反模式** (AI 经常走错):
|
||||
```
|
||||
form create → 失败 → 改字段 → form create → 失败 → 改 type → ... (循环)
|
||||
```
|
||||
|
||||
**正解** (顺序):
|
||||
```
|
||||
1. dacli dm list 看有什么表
|
||||
2. dacli form list 看有什么表单
|
||||
3. dacli form info <id> 找一个最相近的看 schema
|
||||
4. dacli form clone <id> 克隆再改 (最稳)
|
||||
5. dacli form release <id> 发布
|
||||
6. dacli menu create --moduleId=<id> 建菜单
|
||||
```
|
||||
|
||||
**AI 黄金法则**:
|
||||
> 99% 的"建新表单"应该**先 clone 再改**,不要从零搭。
|
||||
> 平台已经有 74 张官方示例 (developSystem 21 + workSystem 53),先找最相近的克隆。
|
||||
|
||||
**盲点 24-27 防错总则 (写新 dacli 命令前必查)**:
|
||||
```
|
||||
1. 查 web 端: grep -E "category|state|formData" web/views/<对应视图>/index.vue
|
||||
2. 查后端真值: curl -i -H "Authorization: $TOK" <endpoint> (看 Content-Length, 不只看 status)
|
||||
3. 查盲点库: troubleshooting.md 错误 1-27 (盲点 24=log category / 25=portal release / 26=form validate / 27=schedule list)
|
||||
4. 命令注释里写真值表 (1=登录 3=操作 4=异常 5=请求 之类), 给下个 AI 看
|
||||
```
|
||||
|
||||
### 决策 6: 字典 enCode/fullName 冲突怎么避? (BS-47)
|
||||
|
||||
**反模式** (AI 直接 `dacli dict typeCreate` 常踩):
|
||||
```bash
|
||||
dacli dict typeCreate --enCode=user_type --fullName=用户类型
|
||||
# ✗ 若其他 app 已建过 "用户类型" 或 enCode, 报 "The name cannot be repeated"
|
||||
```
|
||||
|
||||
**正解**:
|
||||
```bash
|
||||
# 1. 先查 dataList 拿已存在的字典
|
||||
dacli dict dataList | grep -E "user_type|用户类型"
|
||||
|
||||
# 2. 二选一:
|
||||
# a) 复用: form fields 里直接引用其他 app 的 enCode
|
||||
# → 全平台共享 (主库 system_DictionaryType, 跨 app 唯一)
|
||||
# b) 加前缀: --enCode=<app>_user_type --fullName=<app>用户类型
|
||||
# → 注意: fullName 也需全局唯一, 不是只有 enCode
|
||||
```
|
||||
|
||||
**为什么**: 字典存在主库 system_DictionaryType, 不分 app, 也不分 enCode vs fullName (都是 unique 约束). 抛光轮踩过 7+ 次 "The name cannot be repeated" 报错.
|
||||
|
||||
---
|
||||
|
||||
## 4. ⭐ 0 差错验证 (Playwright + baseline)
|
||||
|
||||
### 4.1 0 差错定义
|
||||
|
||||
| 层面 | 含义 | 工具 |
|
||||
|------|------|------|
|
||||
| **API 0 错** | 所有 dacli 命令返回 200/业务成功 | vitest + 集成测试 |
|
||||
| **UI 0 视觉差** | 复刻的表单/菜单浏览器渲染与原版**像素级一致** | **Playwright Node.js** |
|
||||
|
||||
### 4.2 baseline 复刻流程
|
||||
**典型长任务示例**(创建主子表+工作流):
|
||||
|
||||
```bash
|
||||
# 1. 切到 baseline 应用
|
||||
dacli app switch --appCode=developSystem
|
||||
dacli app login --appCode=developSystem
|
||||
|
||||
# 2. 找到目标表单
|
||||
dacli form list | jq '.data.list[] | select(.enCode=="leaveApply") | .id'
|
||||
|
||||
# 3. 导出 + 导入到 tds
|
||||
dacli form export <id> --out=/tmp/leaveApply.json
|
||||
dacli app switch --appCode=tds
|
||||
dacli form import /tmp/leaveApply.json --enCode=leaveApply_clone
|
||||
|
||||
# 4. 发布
|
||||
CLONE_ID=$(dacli form list | jq -r '.data.list[] | select(.enCode=="leaveApply_clone") | .id')
|
||||
dacli form release $CLONE_ID
|
||||
|
||||
# 5. Playwright 验证 (API + UI 双 0 错)
|
||||
npx playwright test tests/e2e/baseline/developSystem/leaveApply.spec.ts
|
||||
# Step 1-5
|
||||
dacli dm create ... ; dacli dm create ... ; dacli form create ... ; dacli form create ... ; dacli form release ...
|
||||
# 自检
|
||||
bash .claude/skills/dacli-ts/scripts/self-check.sh <form_id>
|
||||
# Step 6-10
|
||||
dacli menu create ... ; dacli workflow create ... ; ...
|
||||
```
|
||||
|
||||
### 4.3 一键回归 74 张
|
||||
|
||||
```bash
|
||||
# 跑全部 74 张 (API + UI)
|
||||
bash examples/baseline/all.sh
|
||||
|
||||
# 仅 API 层 (快, 跳过 Playwright)
|
||||
SKIP_PLAYWRIGHT=1 bash examples/baseline/all.sh
|
||||
```
|
||||
|
||||
### 4.4 baseline 真值源 (W5 末实测)
|
||||
|
||||
| app_code | 表单数 | 来源 | 已验证 (API 层) |
|
||||
|----------|--------|------|------------------|
|
||||
| `developSystem` | 20 | 基础示例 (单表/主子表/简单工作流) | ✅ 20/20 schema 完整 |
|
||||
| `workSystem` | 52 | 复杂示例 (关联/字典/数据接口/复杂流程) | ✅ 52/52 schema 完整 |
|
||||
| **总计** | **72** | **dacli 0 差错基线 (API 层全 0 错)** | ✅ 72/72 |
|
||||
|
||||
> 注: prompt §1.4 写 21+53=74, 实际 20+52=72 (JNPF 6.2.0 平台侧几个 form 下线). 全部已实测.
|
||||
|
||||
详细: [references/baseline/](references/baseline/)
|
||||
|
||||
---
|
||||
|
||||
## 5. 关键命令 (AI 一眼能看完)
|
||||
|
||||
```bash
|
||||
# ===== 登录/状态 (✅ v0.1 跑通) =====
|
||||
dacli app login --appCode=tds # 默认 admin/123456, baseUrl 自动从 env/nginx/127.0.0.1:30000 探活
|
||||
dacli app switch --appCode=developSystem # 切应用 (覆盖 token)
|
||||
dacli app status # 看登录态
|
||||
dacli app status --json # 脚本用
|
||||
|
||||
# ===== 表单只读 (✅ v0.1 跑通) =====
|
||||
dacli form list # 列当前应用所有表单
|
||||
dacli form list --limit=200 --json # 全列表 + 原始 JSON
|
||||
dacli form info <id> # 完整 schema
|
||||
dacli form info <id> --summary # 只打概要
|
||||
dacli form export <id> --out=/tmp/x.json # 导出 (备份/baseline)
|
||||
dacli form validate <id> # 校验 columnData __config__
|
||||
|
||||
# ===== 表单写 (⚠️ W2 extractor 完成后才能完整跑通) =====
|
||||
dacli form create --fullName=X --enCode=X --type=4 --webType=1 # 视图兜底
|
||||
dacli form clone <id> --newEnCode=v2 --release # 克隆 + 发布
|
||||
dacli form import x.json --enCode=v2 # 导入
|
||||
dacli form release <id> # 0→1
|
||||
dacli form release <id> --soft # type=4 软跳过
|
||||
dacli form delete <id> --yes # 删 (无确认)
|
||||
|
||||
# ===== AI 友好帮助 (所有命令支持) =====
|
||||
dacli form create --ai-help # 输出 markdown (purpose/required/optional/source/example)
|
||||
dacli form create --example # 输出 bash 示例
|
||||
dacli form create --source # 输出 web 源码 / API 路径
|
||||
|
||||
# ===== W2+ 命令 (❌ 未实现, 报 exit 2) =====
|
||||
dacli menu / dm / dict / workflow / di / doc / apis
|
||||
|
||||
# ===== baseline 复刻 (W3 启动) =====
|
||||
bash .claude/skills/dacli-ts/examples/baseline/all.sh
|
||||
|
||||
# ===== 测试 (W5 末) =====
|
||||
npx vitest run # 33/33 单测 (含 FieldBuilder 18)
|
||||
npx playwright test # 11/11 E2E (smoke 3 + developSystem 4 + workSystem 4)
|
||||
npx tsc --noEmit # typecheck 0 错
|
||||
|
||||
# ===== 提资产 (JNPF 升级时) =====
|
||||
node scripts/extract-all.mjs # 重跑 4 个 extractor → src/data/*.json
|
||||
|
||||
# ===== baseline 一键回归 =====
|
||||
npx playwright test tests/e2e/baseline/developSystem/regression.spec.ts # 20/20
|
||||
npx playwright test tests/e2e/baseline/workSystem/regression.spec.ts # 52/52
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. AI 工作流建议
|
||||
|
||||
### 6.1 接到任务时的决策树
|
||||
|
||||
```
|
||||
用户要"建表单/菜单/工作流"?
|
||||
├─ 已有相近表单?
|
||||
│ ├─ YES → clone + 改 (模式 1-7 任一)
|
||||
│ └─ NO → 走完整流程
|
||||
│
|
||||
走完整流程:
|
||||
├─ 1. login + status
|
||||
├─ 2. dm list + dict type-list 了解应用
|
||||
├─ 3. form create (clone 优先, type=4 兜底)
|
||||
├─ 4. release (type≠4 时)
|
||||
├─ 5. menu create
|
||||
└─ 6. Playwright 验证 (baseline 0 视觉差)
|
||||
```
|
||||
|
||||
### 6.2 接到"查问题"任务时
|
||||
|
||||
```
|
||||
用户报"dacli form create 失败"?
|
||||
├─ 1. status 看 baseUrl/token/appCode
|
||||
├─ 2. 跑命令看完整 raw 响应 (含 code/msg)
|
||||
├─ 3. 查 troubleshooting.md 错误 1-11
|
||||
├─ 4. 必要时 跑 extract-all.mjs + 重新跑
|
||||
└─ 5. 都失败 → 浏览器手动确认是不是 JNPF 平台问题
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 与 Java 版 dacli 的差异 (W5 末)
|
||||
|
||||
| 维度 | dacli Java (生产) | dacli TS (本 skill) |
|
||||
|------|-------------------|---------------------|
|
||||
| **稳定性** | ⭐⭐⭐⭐⭐ (6 月打磨, 261 tests) | ⭐⭐⭐ (W5 末 33+11 tests) |
|
||||
| **AI 友好度** | ⭐⭐⭐ (Picocli --help) | ⭐⭐⭐⭐⭐ (--ai-help + 提取 web) |
|
||||
| **Schema 真相** | 53 FieldBuilder 硬编码 | data/*.json 自动提取 (60 jnpfKey + 14 L1 正则) |
|
||||
| **启动** | 100ms native | < 500ms tsx |
|
||||
| **0 差错基线** | baseline-summary.md (40 form) | **72 张官方示例** (developSystem 20 + workSystem 52, 0 错) |
|
||||
| **Playwright** | 走 ssw-e2e-test (Python) | **@playwright/test (Node.js) 集成** |
|
||||
| **父命令** | 17 (含 portal/report/codegen 等) | 8 (form/dm/dict/menu/di/workflow/doc/apis) |
|
||||
| **编译** | mvn 慢 | tsx 零编译 |
|
||||
|
||||
**默认推荐** (W5 末):
|
||||
- 8 大主流场景 → **TS 版** (更快, AI 友好, 0 错验证)
|
||||
- 边缘场景 (portal/report/codegen) → **Java 版**
|
||||
- 复刻 baseline → **TS 版** (Node Playwright 集成, 不用切进程)
|
||||
|
||||
---
|
||||
|
||||
## 8. 必读 references
|
||||
|
||||
| 文档 | 何时读 |
|
||||
|------|--------|
|
||||
| [references/commands.md](references/commands.md) | 接到具体命令需求 |
|
||||
| [references/patterns.md](references/patterns.md) | 接到"建 XX"业务需求 |
|
||||
| [references/anti-patterns.md](references/anti-patterns.md) | 写完 dacli 命令后自查 |
|
||||
| [references/troubleshooting.md](references/troubleshooting.md) | 报错时第一查 |
|
||||
| [references/baseline/README.md](references/baseline/README.md) | 跑 0 差错验证前 |
|
||||
| [references/playwright.md](references/playwright.md) | 写 baseline 测试时 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 进阶:定制 skill
|
||||
|
||||
如果需要扩展 skill:
|
||||
1. 在 `references/` 加新 .md
|
||||
2. 在 `examples/baseline/` 加新 .sh
|
||||
3. **不要**改 `SKILL.md` 主入口 (它是 AI 第一眼看的内容)
|
||||
4. 改完跑"AI 自检": 把 skill 喂给另一个 Claude, 让它完成 1 个任务
|
||||
|
||||
---
|
||||
|
||||
**生成时间**: 2026-06-12 (v0.9 校准 2026-06-21, 加 BS-47/48/49/50/51 决策)
|
||||
**作者**: Claude (M3) + 用户
|
||||
**配套文档**: [doc/architecture.md](../../doc/architecture.md)
|
||||
**核心目标**: **74 张官方示例 API 0 错 + 浏览器 0 视觉差**
|
||||
**为什么需要这个**:长任务模式把"快速推进"和"错误积累"捆绑在一起。需要解耦——AI 可以连续执行,但每 5 步强制验证一次,避免错误雪崩。
|
||||
52 条盲点中有相当一部分就是这样"错了继续"积累出来的(参见 `dacli/doc/ai-error-analysis.md` 第 E 类)。
|
||||
@@ -0,0 +1,148 @@
|
||||
# web/ 源码权威参照表
|
||||
|
||||
> 本表是 dacli 命令的"权威来源"。dacli 文档与 web/ 源码不一致时,**以本表为准**。
|
||||
>
|
||||
> 任何参数/API 路径/默认值/校验逻辑不确定时,按下表查 web/ 源码验证。
|
||||
>
|
||||
> 创建:2026-06-22(v0.10 P0.3 — 解决 AI 舍近求远根因 G)
|
||||
|
||||
## 快速索引
|
||||
|
||||
| dacli 命令 | web/ 权威源码 | API 端点 | 关键内容 |
|
||||
|-----------|-------------|---------|---------|
|
||||
| `form create` (普通表单) | `views/onlineDev/formDesign/Form.vue:L103-L118` | POST `/api/visualdev/Base` | `type=1, webType=2, dbLinkId='0', state=1` 默认值 |
|
||||
| `form create` (webType 切换) | `views/onlineDev/formDesign/Form.vue:L188-L189` | — | `webType = data.webType \|\| 2` |
|
||||
| `form create` (数据视图) | `views/onlineDev/formDesign/Form.vue:L177` | — | `webType==4` 时 `maxStep=1`(无表设计) |
|
||||
| `form create` (主子表校验) | `views/onlineDev/formDesign/Form.vue:L385-L403` | — | `exist()` 验证 `tableField`/`relationField` 非空 |
|
||||
| `form create` (报表/门户) | `views/onlineDev/sysForm/Form.vue:L140-L157` | POST `/api/visualdev/Base` | `type=2, webType=1, dbLinkId='0'` |
|
||||
| `form list` | `api/onlineDev/visualDev.ts:L15-L21` | GET `/api/visualdev/Base` | 全部 form(含 enableFlow=0/1) |
|
||||
| `form info` | `api/onlineDev/visualDev.ts:L31-L33` | GET `/api/visualdev/Base/{id}` | 完整 schema |
|
||||
| `form update` | `api/onlineDev/visualDev.ts:L27-L29` | PUT `/api/visualdev/Base/{id}` | 修改 |
|
||||
| `form delete` | `api/onlineDev/visualDev.ts:L35-L37` | DELETE `/api/visualdev/Base/{id}` | 删除 |
|
||||
| `form clone` | `api/onlineDev/visualDev.ts:L39-L41` | POST `/api/visualdev/Base/{id}/Actions/Copy` | 完整 schema 复制 |
|
||||
| `form release` | `api/onlineDev/visualDev.ts:L43-L45` | POST `/api/visualdev/Base/{id}/Actions/Release` | state 0→1 |
|
||||
| `form export` | `api/onlineDev/visualDev.ts:L133-L135` | POST `/api/visualdev/OnlineDev/{modelId}/Actions/ExportData` | 导出数据 |
|
||||
| `form template` | `api/onlineDev/visualDev.ts:L141-L143` | POST `/api/visualdev/OnlineDev/{modelId}/Actions/Export` | 导出模板 |
|
||||
| `form import` | `api/onlineDev/visualDev.ts:L105-L106` | POST `/api/visualdev/OnlineDev/{modelId}` | 新建数据(导入流程) |
|
||||
| `form validate` | `views/onlineDev/formDesign/Form.vue:L348-L364` | — | errorList 来源:generatorRef.getData() |
|
||||
| `form fix` (columnData) | `views/onlineDev/formDesign/Form.vue:L368-L375` | — | columnDesignRef.getData() → appColumnData |
|
||||
| `dm create` | `api/systemData/dataModel.ts:L22-L24` | POST `/api/system/DataModel/{linkId}/Table` | tables 完整 schema |
|
||||
| `dm update` | `api/systemData/dataModel.ts:L26-L28` | PUT `/api/system/DataModel/{linkId}/Table` | 修改 |
|
||||
| `dm info` | `api/systemData/dataModel.ts:L30-L32` | GET `/api/system/DataModel/{linkId}/Table/{table}` | 表详情 |
|
||||
| `dm list` | `api/systemData/dataModel.ts:L10-L12` | GET `/api/system/DataModel/{linkId}/Tables` | 分页 |
|
||||
| `dm fields` | `api/systemData/dataModel.ts:L38-L40` | GET `/api/system/DataModel/{linkId}/Tables/{table}/Fields?type={type}` | 字段列表 |
|
||||
| `dm delete` | `api/systemData/dataModel.ts:L34-L36` | DELETE `/api/system/DataModel/{linkId}/Table/{table}` | 删除表 |
|
||||
| `dm preview` | `api/systemData/dataModel.ts:L18-L20` | GET `/api/system/DataModel/{linkId}/Table/{table}/Preview` | 预览表数据 |
|
||||
| `dm export` | `api/systemData/dataModel.ts:L46-L48` | GET `/api/system/DataModel/{linkId}/Table/{table}/Actions/Export` | 导出表 DDL |
|
||||
| `dm addFields` | `api/systemData/dataModel.ts:L42-L44` | PUT `/api/system/DataModel/{linkId}/addFields` | 增量加字段 |
|
||||
| `menu create` (PC+App) | `formDesign/components/CreateMenuModal.vue:L93-L120` | POST `/api/visualdev/Base/{id}/Actions/Module` | `pcIsRelease`/`appIsRelease` 验证 |
|
||||
| `menu release-check` | `formDesign/components/CreateMenuModal.vue:L43-L51` | — | 校验未发布时 `pcModuleParentId`/`appModuleParentId` 必填 |
|
||||
| `menu getReleaseMenu` | `formDesign/components/CreateMenuModal.vue:L53-L69` | GET `/api/visualdev/Base/{id}/getReleaseMenu` | 拿已发布菜单信息 |
|
||||
| `dbLinkId 选择` | `api/systemData/dataSource.ts:L13-L16` | GET `/api/system/DataSource/Selector` | 可用 dbLinkId 列表 |
|
||||
| `dbLinkId test` | `api/systemData/dataSource.ts:L34-L36` | POST `/api/system/DataSource/Actions/Test` | 测试连接 |
|
||||
| `AI 建表 (原生)` | `formDesign/components/AiCreateModal.vue:L13, L68-L80, L81-L98` | POST `/api/visualdev/ai/form` | `getAiInfo({keyword})` → 调 `create()` |
|
||||
| `code generate` (下载) | `api/onlineDev/visualDev.ts:L72-L74` | POST `/api/visualdev/Generater/{id}/Actions/DownloadCode` | 代码下载 |
|
||||
| `code preview` | `api/onlineDev/visualDev.ts:L76-L78` | POST `/api/visualdev/Generater/{id}/Actions/CodePreview` | 代码预览 |
|
||||
| `code alias info` | `api/onlineDev/visualDev.ts:L80-L82` | GET `/api/visualdev/Generater/{id}/Alias/Info` | 命名规范 |
|
||||
| `code alias save` | `api/onlineDev/visualDev.ts:L84-L86` | POST `/api/visualdev/Generater/{id}/Alias/Save` | 保存命名规范 |
|
||||
| `form getConfigData` | `api/onlineDev/visualDev.ts:L89-L91` | GET `/api/visualdev/OnlineDev/{modelId}/Config` | 列表表单配置 |
|
||||
| `form getFormData` | `api/onlineDev/visualDev.ts:L97-L99` | GET `/api/visualdev/OnlineDev/{modelId}/FormData` | 表单配置 JSON |
|
||||
| `form getDataChange` | `api/onlineDev/visualDev.ts:L129-L131` | POST `/api/visualdev/OnlineDev/{modelId}/DataChange` | 数据变更详情 |
|
||||
| `form getFormDataFields` | `api/onlineDev/visualDev.ts:L55-L57` | GET `/api/visualdev/Base/{id}/FormDataFields?filterType={filterType}` | 主表字段列表 |
|
||||
| `form getFieldDataSelect` | `api/onlineDev/visualDev.ts:L59-L61` | GET `/api/visualdev/Base/{modelId}/FieldDataSelect` | 数据下拉框 |
|
||||
| `form getColumnList` | `api/onlineDev/visualDev.ts:L67-L69` | GET `/api/visualdev/Base/getColumnList` | 列表字段 |
|
||||
| `form getVisualDevSelector` | `api/onlineDev/visualDev.ts:L63-L65` | GET `/api/visualdev/Base/Selector` | 功能下拉框 |
|
||||
| `form batchDelete` | `api/onlineDev/visualDev.ts:L125-L127` | POST `/api/visualdev/OnlineDev/batchDelete/{modelId}` | 批量删除数据 |
|
||||
| `ocr` | `api/onlineDev/visualDev.ts:L201-L203` | POST `/api/visualdev/ocr` | Ocr 识别 |
|
||||
|
||||
## 关键校验规则
|
||||
|
||||
### 字段唯一性(enCode 重复 → 盲点 49)
|
||||
|
||||
- **源码位置**:`sysForm/FieldForm.vue:L59-L81` `exist()` 函数
|
||||
- **规则**:
|
||||
- `fieldName` 非空
|
||||
- `fieldId` 非空
|
||||
- `fieldId` 不重复(同一 form 内)
|
||||
- **见**:`anti-patterns.md` 盲点 49
|
||||
|
||||
### dbLinkId 切换联动(盲点 48)
|
||||
|
||||
- **源码位置**:`formDesign/Form.vue:L226-L228` `onDbChange()`
|
||||
- **规则**:切换 dbLinkId → `state.tables = []` 清空已选表列表
|
||||
- **见**:`troubleshooting.md` 盲点 48
|
||||
|
||||
### 发布前必检(盲点 50)
|
||||
|
||||
- **源码位置**:`CreateMenuModal.vue:L43-L51` `rules` computed
|
||||
- **规则**:
|
||||
- `!state.record.pcIsRelease` → `pcModuleParentId` 必填
|
||||
- `!state.record.appIsRelease` → `appModuleParentId` 必填
|
||||
- **见**:`troubleshooting.md` 盲点 50
|
||||
|
||||
### 主子表外键校验
|
||||
|
||||
- **源码位置**:`formDesign/Form.vue:L385-L403` `exist()` 函数
|
||||
- **规则**:
|
||||
- `typeId=='0'` 的子表 → `tableField` 必填
|
||||
- `typeId=='0'` 的子表 → `relationField` 必填
|
||||
- **触发条件**:handleNext 时 `state.tables.length > 0` 才校验
|
||||
|
||||
### queryType 推导规则
|
||||
|
||||
- **源码位置**:`formDesign/Form.vue:L213` 和 `L263`
|
||||
- **规则**:
|
||||
```js
|
||||
const queryType = type == 3 || type == 4 || type == 5 ? '1' : '0';
|
||||
```
|
||||
- `type=3` (表单列表树) / `type=4` (数据视图) / `type=5` → `queryType='1'`(含视图)
|
||||
- 其余 → `queryType='0'`(仅物理表)
|
||||
- **影响**:`getDataModelFieldList` 拿到的是表还是视图字段
|
||||
|
||||
### 菜单发布覆盖确认
|
||||
|
||||
- **源码位置**:`CreateMenuModal.vue:L113-L119`
|
||||
- **规则**:`state.record.isRelease === true` 时弹"覆盖当前线上版本"确认
|
||||
- **AI 必读**:重复发布前会弹确认框,AI 不能自动"是"(人类确认)
|
||||
|
||||
## 核心文件路径速查
|
||||
|
||||
| 用途 | 绝对路径 |
|
||||
|------|---------|
|
||||
| 功能(form/报表/门户)CRUD | `web/apps/jnpf-web-apps-main/src/api/onlineDev/visualDev.ts` |
|
||||
| 数据模型 CRUD | `web/apps/jnpf-web-apps-main/src/api/systemData/dataModel.ts` |
|
||||
| 数据连接 | `web/apps/jnpf-web-apps-main/src/api/systemData/dataSource.ts` |
|
||||
| 字典 | `web/apps/jnpf-web-apps-main/src/api/systemData/dictionary.ts` |
|
||||
| 数据接口 | `web/apps/jnpf-web-apps-main/src/api/systemData/dataInterface.ts` |
|
||||
| 公共同意字段 | `web/apps/jnpf-web-apps-main/src/api/systemData/commonFields.ts` |
|
||||
| 普通表单编辑器 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue` |
|
||||
| 报表/门户编辑器 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/sysForm/Form.vue` |
|
||||
| 报表/门户字段编辑 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/sysForm/FieldForm.vue` |
|
||||
| AI 建表 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/AiCreateModal.vue` |
|
||||
| 创建菜单 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/CreateMenuModal.vue` |
|
||||
| 表选择器 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/TableModal.vue` |
|
||||
| 表单预览 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/PreviewModal.vue` |
|
||||
| 短链接 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/ShortLinkModal.vue` |
|
||||
| 别名 | `web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/AliasModal.vue` |
|
||||
|
||||
## 关键默认值速查
|
||||
|
||||
| 字段 | 普通表单 (formDesign) | 报表/门户 (sysForm) |
|
||||
|------|---------------------|-------------------|
|
||||
| `type` | `1` (L107) | `2` (L144) |
|
||||
| `webType` | `2` (L108) | `1` (L145) |
|
||||
| `dbLinkId` | `'0'` (L109) | `'0'` (L146) |
|
||||
| `state` | `1` (L111) | `1` (L148) |
|
||||
| `sortCode` | `0` (L110) | `0` (L147) |
|
||||
| `category` | `''` (L112) | `''` (L149) |
|
||||
| `description` | `''` (L113) | `''` (L150) |
|
||||
| `webType` 切换 | `data.webType \|\| 2` (L189) | n/a |
|
||||
| `maxStep` | `webType==4 ? 1 : 2` (L190) | n/a |
|
||||
|
||||
> 警告:所有"默认值"必须以 web/ 源码为准,dacli 文档若不一致则文档错。
|
||||
|
||||
## 维护方式
|
||||
|
||||
- **手动校对**:发现 dacli 命令行为与 web/ 源码不一致时,先 Read 源码 → 更新本表 → 再修 dacli 源码
|
||||
- **自动提取**:`dacli/scripts/extract-web-schema.py` 脚本可重新跑,把源码默认值/API 端点 dump 到 `dacli/data/web-derived-schemas.json`
|
||||
- **同步频率**:JNPF 平台升级后必须重跑脚本 + 更新本表
|
||||
@@ -0,0 +1,421 @@
|
||||
{
|
||||
"version": "v0.10",
|
||||
"extractedAt": "2026-06-22",
|
||||
"formDesign": {
|
||||
"file": "web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/Form.vue",
|
||||
"defaultValues": {
|
||||
"type": "1",
|
||||
"webType": "2",
|
||||
"dbLinkId": "0",
|
||||
"state": "1",
|
||||
"sortCode": "0"
|
||||
},
|
||||
"keyBehaviors": {
|
||||
"webType_fallback": "data.webType || 2 (L189)",
|
||||
"maxStep_logic": "webType==4 ? 1 : 2 (L190)",
|
||||
"dbLinkId_change_clears_tables": "onDbChange() L226-L228",
|
||||
"subtable_validation": "exist() L385-L403",
|
||||
"queryType_logic": "type==3||4||5 ? '1' : '0' (L213, L263)"
|
||||
}
|
||||
},
|
||||
"sysForm": {
|
||||
"file": "web/apps/jnpf-web-apps-main/src/views/onlineDev/sysForm/Form.vue",
|
||||
"defaultValues": {
|
||||
"type": "2",
|
||||
"webType": "1",
|
||||
"dbLinkId": "0",
|
||||
"state": "1",
|
||||
"sortCode": "0"
|
||||
}
|
||||
},
|
||||
"validation": {
|
||||
"file": "web/apps/jnpf-web-apps-main/src/views/onlineDev/sysForm/FieldForm.vue",
|
||||
"rules": [
|
||||
"名称不能为空"
|
||||
]
|
||||
},
|
||||
"apiEndpoints": {
|
||||
"visualDev": {
|
||||
"enum": {
|
||||
"AiPrefix": "/api/visualdev/ai/form",
|
||||
"GenPrefix": "/api/visualdev/Generater",
|
||||
"LogPrefix": "/api/visualdev/OnlineLog",
|
||||
"OcrPrefix": "/api/visualdev/ocr",
|
||||
"OnlinePrefix": "/api/visualdev/OnlineDev",
|
||||
"PersonalPrefix": "/api/visualdev/personal",
|
||||
"Prefix": "/api/visualdev/Base",
|
||||
"SharePrefix": "/api/visualdev/share"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"func": "getVisualDevList",
|
||||
"comment": "获取功能列表",
|
||||
"url": "Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getVisualDevFormList",
|
||||
"comment": "获取功能列表(集成助手用)",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "create",
|
||||
"comment": "新建功能",
|
||||
"url": "Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "update",
|
||||
"comment": "修改功能",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getInfo",
|
||||
"comment": "获取功能",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "delVisualDev",
|
||||
"comment": "删除功能",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "copy",
|
||||
"comment": "复制功能",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "release",
|
||||
"comment": "发布",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getReleaseMenu",
|
||||
"comment": "获取已发布菜单",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "createMenu",
|
||||
"comment": "生成菜单",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getFormDataFields",
|
||||
"comment": "获取表单主表属性列表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getFieldDataSelect",
|
||||
"comment": "获取表单主表数据下拉框",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getVisualDevSelector",
|
||||
"comment": "获取功能下拉框列表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getColumnList",
|
||||
"comment": "获取列表字段",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "downloadCode",
|
||||
"comment": "代码下载",
|
||||
"url": "`${Api.GenPrefix"
|
||||
},
|
||||
{
|
||||
"func": "codePreview",
|
||||
"comment": "代码预览",
|
||||
"url": "`${Api.GenPrefix"
|
||||
},
|
||||
{
|
||||
"func": "getAliasInfo",
|
||||
"comment": "获取代码生成命名规范",
|
||||
"url": "`${Api.GenPrefix"
|
||||
},
|
||||
{
|
||||
"func": "saveAlias",
|
||||
"comment": "更新代码生成命名规范",
|
||||
"url": "`${Api.GenPrefix"
|
||||
},
|
||||
{
|
||||
"func": "getConfigData",
|
||||
"comment": "获取列表表单配置JSON",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getConfigDataByMenuId",
|
||||
"comment": "通过菜单id获取列表表单配置JSON",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getFormData",
|
||||
"comment": "获取表单配置JSON",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getModelList",
|
||||
"comment": "获取数据列表",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "createModel",
|
||||
"comment": "新建数据",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "updateModel",
|
||||
"comment": "修改数据",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getModelInfo",
|
||||
"comment": "获取数据信息",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataLogList",
|
||||
"comment": "获取修改记录列表",
|
||||
"url": "Api.LogPrefix"
|
||||
},
|
||||
{
|
||||
"func": "delModel",
|
||||
"comment": "删除数据",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "batchDelete",
|
||||
"comment": "批量删除数据",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataChange",
|
||||
"comment": "获取数据详情",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "exportModel",
|
||||
"comment": "导出数据",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getTemplate",
|
||||
"comment": "下载模板",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "exportData",
|
||||
"comment": "导出模板",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "launchFlow",
|
||||
"comment": "自定义按钮发起流程",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getRelationQueryList",
|
||||
"comment": "获取关联查询数据列表",
|
||||
"url": "`${Api.OnlinePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getViewList",
|
||||
"comment": "获取视图列表",
|
||||
"url": "Api.PersonalPrefix"
|
||||
},
|
||||
{
|
||||
"func": "delView",
|
||||
"comment": "删除视图",
|
||||
"url": "`${Api.PersonalPrefix"
|
||||
},
|
||||
{
|
||||
"func": "createView",
|
||||
"comment": "新建视图",
|
||||
"url": "Api.PersonalPrefix"
|
||||
},
|
||||
{
|
||||
"func": "updateView",
|
||||
"comment": "修改视图",
|
||||
"url": "`${Api.PersonalPrefix"
|
||||
},
|
||||
{
|
||||
"func": "setDefaultView",
|
||||
"comment": "设置默认视图",
|
||||
"url": "`${Api.PersonalPrefix"
|
||||
},
|
||||
{
|
||||
"func": "getAiInfo",
|
||||
"comment": "获取ai字段",
|
||||
"url": "Api.AiPrefix"
|
||||
},
|
||||
{
|
||||
"func": "getListBySystem",
|
||||
"comment": "获取跨应用菜单",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getShareList",
|
||||
"comment": "获取跨应用表单",
|
||||
"url": "`${Api.SharePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getShareInfo",
|
||||
"comment": "获取跨应用表单详情",
|
||||
"url": "`${Api.SharePrefix"
|
||||
},
|
||||
{
|
||||
"func": "saveShare",
|
||||
"comment": "保存跨应用回显",
|
||||
"url": "`${Api.SharePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getShareSelector",
|
||||
"comment": "获取功能下拉框列表(包含跨应用表单)",
|
||||
"url": "`${Api.SharePrefix"
|
||||
},
|
||||
{
|
||||
"func": "getOcrData",
|
||||
"comment": "Ocr识别",
|
||||
"url": "`${Api.OcrPrefix"
|
||||
}
|
||||
]
|
||||
},
|
||||
"dataModel": {
|
||||
"enum": {
|
||||
"Prefix": "/api/system/DataModel"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"func": "getDataModelList",
|
||||
"comment": "获取数据库表列表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataModelListAll",
|
||||
"comment": "获取数据库表列表+视图",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "previewDataModel",
|
||||
"comment": "预览数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "createDataModel",
|
||||
"comment": "新建数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "updateDataModel",
|
||||
"comment": "修改数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataModelInfo",
|
||||
"comment": "获取数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "delDataModel",
|
||||
"comment": "删除数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataModelFieldList",
|
||||
"comment": "获取数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "addTableFields",
|
||||
"comment": "新增字段",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "exportTable",
|
||||
"comment": "导出数据库表",
|
||||
"url": "`${Api.Prefix"
|
||||
}
|
||||
]
|
||||
},
|
||||
"dataSource": {
|
||||
"enum": {
|
||||
"Prefix": "/api/system/DataSource",
|
||||
"SyncPrefix": "/api/system/DataSync"
|
||||
},
|
||||
"endpoints": [
|
||||
{
|
||||
"func": "getDataSourceList",
|
||||
"comment": "获取数据连接列表",
|
||||
"url": "Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "createDataSource",
|
||||
"comment": "新建数据连接",
|
||||
"url": "Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "updateDataSource",
|
||||
"comment": "修改数据连接",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "getDataSourceInfo",
|
||||
"comment": "获取数据连接",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "delDataSource",
|
||||
"comment": "删除数据连接",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "testDbConnection",
|
||||
"comment": "测试数据连接",
|
||||
"url": "`${Api.Prefix"
|
||||
},
|
||||
{
|
||||
"func": "dataSync",
|
||||
"comment": "同步校验",
|
||||
"url": "Api.SyncPrefix"
|
||||
},
|
||||
{
|
||||
"func": "execute",
|
||||
"comment": "同步数据",
|
||||
"url": "`${Api.SyncPrefix"
|
||||
},
|
||||
{
|
||||
"func": "batchExecute",
|
||||
"comment": "批量同步数据",
|
||||
"url": "`${Api.SyncPrefix"
|
||||
},
|
||||
{
|
||||
"func": "checkDbLink",
|
||||
"comment": "校验数据库连接",
|
||||
"url": "`${Api.SyncPrefix"
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"AiCreateModal": {
|
||||
"file": "web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/AiCreateModal.vue",
|
||||
"keyMethods": [
|
||||
"getAiInfo",
|
||||
"create",
|
||||
"buildFormData"
|
||||
]
|
||||
},
|
||||
"CreateMenuModal": {
|
||||
"file": "web/apps/jnpf-web-apps-main/src/views/onlineDev/formDesign/components/CreateMenuModal.vue",
|
||||
"keyMethods": [
|
||||
"getReleaseMenu",
|
||||
"createMenu",
|
||||
"getMenuSelectorFilter"
|
||||
],
|
||||
"validationRules": [
|
||||
"pc && !pcIsRelease => pcModuleParentId required",
|
||||
"app && !appIsRelease => appModuleParentId required",
|
||||
"isRelease => confirm overwrite"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
Executable
+185
@@ -0,0 +1,185 @@
|
||||
#!/usr/bin/env python3
|
||||
"""extract-web-schema.py — 从 web/ 源码自动提取 dacli 需要的 schema/API 端点
|
||||
|
||||
输出: dacli/data/web-derived-schemas.json (可重跑)
|
||||
Usage:
|
||||
python3 scripts/extract-web-schema.py # 写 JSON
|
||||
python3 scripts/extract-web-schema.py --dry-run # 只打印
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
DEFAULT_WEB_ROOT = Path("/home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src")
|
||||
DEFAULT_OUTPUT = Path("/home/ubuntu/ccWorkDir/dacli/data/web-derived-schemas.json")
|
||||
|
||||
# 关键文件(相对 web/src)
|
||||
KEY_FILES = {
|
||||
"formDesign": "views/onlineDev/formDesign/Form.vue",
|
||||
"sysForm": "views/onlineDev/sysForm/Form.vue",
|
||||
"fieldForm": "views/onlineDev/sysForm/FieldForm.vue",
|
||||
"visualDevApi": "api/onlineDev/visualDev.ts",
|
||||
"dataModelApi": "api/systemData/dataModel.ts",
|
||||
"dataSourceApi": "api/systemData/dataSource.ts",
|
||||
"aiCreateModal": "views/onlineDev/formDesign/components/AiCreateModal.vue",
|
||||
"createMenuModal": "views/onlineDev/formDesign/components/CreateMenuModal.vue",
|
||||
}
|
||||
|
||||
DEFAULT_PATTERNS = {
|
||||
"type": r"type:\s*(\d+)",
|
||||
"webType": r"webType:\s*(\d+)",
|
||||
"dbLinkId": r"dbLinkId:\s*['\"]([^'\"]+)['\"]",
|
||||
"state": r"state:\s*(\d+)",
|
||||
"sortCode": r"sortCode:\s*(\d+)",
|
||||
}
|
||||
|
||||
|
||||
def read_file(root: Path, rel: str) -> str:
|
||||
p = root / rel
|
||||
return p.read_text(encoding="utf-8") if p.exists() else ""
|
||||
|
||||
|
||||
def find_blocks(content: str, marker: str) -> list:
|
||||
"""找 marker + { 配对块"""
|
||||
blocks = []
|
||||
for m in re.finditer(re.escape(marker) + r"\s*\{", content):
|
||||
depth, i = 1, m.end()
|
||||
while i < len(content) and depth > 0:
|
||||
if content[i] == "{":
|
||||
depth += 1
|
||||
elif content[i] == "}":
|
||||
depth -= 1
|
||||
i += 1
|
||||
blocks.append(content[m.end() : i - 1])
|
||||
return blocks
|
||||
|
||||
|
||||
def extract_defaults(content: str) -> dict:
|
||||
"""从 dataForm 块提取默认值"""
|
||||
defaults = {}
|
||||
for block in find_blocks(content, "dataForm:"):
|
||||
for k, pat in DEFAULT_PATTERNS.items():
|
||||
if k in defaults:
|
||||
continue
|
||||
m = re.search(pat, block)
|
||||
if m:
|
||||
defaults[k] = m.group(1)
|
||||
return defaults
|
||||
|
||||
|
||||
def extract_endpoints(content: str) -> dict:
|
||||
"""提取 Api enum + 所有 defHttp 端点"""
|
||||
enums = {}
|
||||
for m in re.finditer(r"enum\s+Api\s*\{([^}]+)\}", content, re.S):
|
||||
for line in m.group(1).split("\n"):
|
||||
line = line.strip().rstrip(",")
|
||||
if "=" in line:
|
||||
k, v = line.split("=", 1)
|
||||
enums[k.strip()] = v.strip().strip("'\"")
|
||||
# 找 (注释)(export)? function name() { ... defHttp.method({ url: ...
|
||||
func_pat = re.compile(
|
||||
r"//\s*([^\n]+)\n(?:export\s+)?function\s+(\w+)\([^)]*\)\s*\{[^}]*?defHttp\.\w+\(\s*\{\s*url:\s*([^,}]+)",
|
||||
re.S,
|
||||
)
|
||||
endpoints = []
|
||||
for m in func_pat.finditer(content):
|
||||
url = re.sub(r"\$\{([^}]+)\}", r"{\1}", m.group(3).strip())
|
||||
endpoints.append(
|
||||
{"func": m.group(2).strip(), "comment": m.group(1).strip(), "url": url}
|
||||
)
|
||||
return {"enum": enums, "endpoints": endpoints}
|
||||
|
||||
|
||||
def extract_validation(content: str) -> list:
|
||||
"""从 FieldForm.vue exist() 提取 createMessage.warning 文本"""
|
||||
m = re.search(r"function\s+exist\s*\([^)]*\)\s*\{(.*?)^\s*\}", content, re.S | re.M)
|
||||
if not m:
|
||||
return []
|
||||
return [w.group(1).strip() for w in re.finditer(r"createMessage\.warning\(\s*[`'\"]([^`'\"]+)", m.group(1))]
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--dry-run", action="store_true")
|
||||
ap.add_argument("--web-root", default=str(DEFAULT_WEB_ROOT))
|
||||
ap.add_argument("--output", default=str(DEFAULT_OUTPUT))
|
||||
args = ap.parse_args()
|
||||
|
||||
root = Path(args.web_root)
|
||||
if not root.exists():
|
||||
print(f"ERROR: web 根不存在: {root}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
files = {k: read_file(root, v) for k, v in KEY_FILES.items()}
|
||||
|
||||
result = {
|
||||
"version": "v0.10",
|
||||
"extractedAt": str(date.today()),
|
||||
"formDesign": {
|
||||
"file": f"web/apps/jnpf-web-apps-main/src/{KEY_FILES['formDesign']}",
|
||||
"defaultValues": extract_defaults(files["formDesign"]),
|
||||
"keyBehaviors": {
|
||||
"webType_fallback": "data.webType || 2 (L189)",
|
||||
"maxStep_logic": "webType==4 ? 1 : 2 (L190)",
|
||||
"dbLinkId_change_clears_tables": "onDbChange() L226-L228",
|
||||
"subtable_validation": "exist() L385-L403",
|
||||
"queryType_logic": "type==3||4||5 ? '1' : '0' (L213, L263)",
|
||||
},
|
||||
},
|
||||
"sysForm": {
|
||||
"file": f"web/apps/jnpf-web-apps-main/src/{KEY_FILES['sysForm']}",
|
||||
"defaultValues": extract_defaults(files["sysForm"]),
|
||||
},
|
||||
"validation": {
|
||||
"file": f"web/apps/jnpf-web-apps-main/src/{KEY_FILES['fieldForm']}",
|
||||
"rules": extract_validation(files["fieldForm"]),
|
||||
},
|
||||
"apiEndpoints": {
|
||||
"visualDev": extract_endpoints(files["visualDevApi"]),
|
||||
"dataModel": extract_endpoints(files["dataModelApi"]),
|
||||
"dataSource": extract_endpoints(files["dataSourceApi"]),
|
||||
},
|
||||
"components": {
|
||||
"AiCreateModal": {
|
||||
"file": f"web/apps/jnpf-web-apps-main/src/{KEY_FILES['aiCreateModal']}",
|
||||
"keyMethods": ["getAiInfo", "create", "buildFormData"],
|
||||
},
|
||||
"CreateMenuModal": {
|
||||
"file": f"web/apps/jnpf-web-apps-main/src/{KEY_FILES['createMenuModal']}",
|
||||
"keyMethods": ["getReleaseMenu", "createMenu", "getMenuSelectorFilter"],
|
||||
"validationRules": [
|
||||
"pc && !pcIsRelease => pcModuleParentId required",
|
||||
"app && !appIsRelease => appModuleParentId required",
|
||||
"isRelease => confirm overwrite",
|
||||
],
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
text = json.dumps(result, indent=2, ensure_ascii=False)
|
||||
if args.dry_run:
|
||||
print("=== DRY RUN — 不写文件 ===")
|
||||
print(text)
|
||||
v, m, s = (result["apiEndpoints"][k] for k in ("visualDev", "dataModel", "dataSource"))
|
||||
print(
|
||||
f"\n总计: formDesign defaults={len(result['formDesign']['defaultValues'])}, "
|
||||
f"sysForm defaults={len(result['sysForm']['defaultValues'])}, "
|
||||
f"visualDev endpoints={len(v['endpoints'])}, "
|
||||
f"dataModel endpoints={len(m['endpoints'])}, "
|
||||
f"dataSource endpoints={len(s['endpoints'])}, "
|
||||
f"validation rules={len(result['validation']['rules'])}"
|
||||
)
|
||||
return 0
|
||||
|
||||
out = Path(args.output)
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
out.write_text(text, encoding="utf-8")
|
||||
print(f"Wrote {out} ({len(text)} bytes)")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Reference in new issue
Block a user