Files
dacli/docs/cmd-review/_summary.md
T

11 KiB
Raw Blame History

Phase 1 总结报告: 23 个 dacli 父命令审计 (2026-06-25)

背景: 用户在 v0.11+ plan 中要求"逐个过 23 个 dacli 父命令", 看 web 端页面逻辑, 决定命令改/删/留. 方法: 5 批 × 5/批 派 Explore 子代理并行审计, 主代理汇总. 产出: dacli/docs/cmd-review/ 23 个 markdown 报告 + 本总结.

1. 审计覆盖 (23/23 完成)

批次 命令 web 路径修正
A apis, app, bigscreen, datasource, di bigscreen → jnpf/前端/jnpf-web-datascreen-vue3
B dict, dm, doc, form, integration —
C log, menu, monitor, msg, org —
D portal, print, report, role, schedule report → web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts (主 webapp)
E storage, user, workflow —

用户关键修正 (2026-06-25):

  1. bigscreen web 在独立子项目 jnpf-web-datascreen-vue3, 不是主 webapp
  2. report (v3 修正 2026-06-29): webapi 镜像源在 主 webapp web/apps/jnpf-web-apps-main/src/api/onlineDev/report.ts (Vue 3)
    • jnpf/前端/jnpf-web-datareport 是 jQuery 老设计器, 无 src/api/ 目录, 不可镜像
    • web/packages/jnpf/plugins/jnpf-univer 是 Vue 3 组件包, 无 api/ 目录, 也不可镜像
  3. 这两类命令审计 v2 已重新执行

2. 总体数据

维度 数据
总子命令数 116 (24 父命令)
webapi 镜像模块 6 (dataModel/dataSource/dict/menu/visualDev/workflow)
webapi 镜像函数 95
webapi 实际使用率 < 30% (大量 c.postJson/c.get 仍手写)
缺 [REFACTOR-WEBAPI] 的命令 12+ 父命令
缺 [NEW-CMD] P0 必补 30+ 个新命令
端点错误 (P0 假 PASS) 3 处 (integration emailTest/smsTest, msg templateCreate)

3. P0 优先级 Top 10 (按执行价值)

  1. dacli form update (高需求, 增量改 schema) — 改 schema 需 export → 改 → import, 无原子性
  2. dacli log exception (P0 必补) — AI 排查后端异常的唯一杀手锏, 当前完全缺失
  3. dacli di info/test/create/update/delete (5 个) — 当前 1 个 list, AI 完全无法闭环
  4. dacli role update/info/selector/authorize (4 个) — 权限管理闭环断裂
  5. dacli org update/delete/info + org position (5 子) + org selector — 闭环 + 岗位空白
  6. dacli msg noticeUpdate/Delete + templateUpdate/Delete (4 个) + 修端点错误
  7. dacli storage create/update/delete + upload/download/ls (6 个) — 阻塞附件调试
  8. dacli apis search --field= (P0) — 解决 AI 字段盲猜
  9. dacli bigscreen update/delete/category (3+ 个) — 补全 CRUD 闭环
  10. dacli report create/update/delete + preview + category (5+ 个) — 报表管理 3/8 = 12.5% 覆盖率

4. P0 [REFACTOR-WEBAPI] Top 5 (架构对齐)

  1. datasource 4 子命令 (100% 绕 webapi) — webapi/dataSource.ts 已镜像 11 函数, 使用率 0%
  2. dict 4 子命令 (100% 绕 webapi) — webapi/dict.ts 已镜像 15 函数, 使用率 0%
  3. menu 6/8 子命令 (1/15 = 6.7% 使用率) — 消除 ~120 行硬编码
  4. form import.ts (8 调用) + codegen.ts (4) + create.ts (4) + fixcolumndata.ts (3) — 22 调用待切
  5. dm create + drop — 切到 webapi/dataModel.ts

5. 端点错误 (P0 假 PASS, 立即修)

命令 当前错误端点 正确端点 影响
integration emailTest /message/SendMessageConfig/testSendConfig /message/AccountConfig/testSendMail 假 PASS
integration smsTest /system/SmsTemplate/testSent /message/AccountConfig/testSendSms 假 PASS
msg templateCreate /api/system/MessageTemplate /api/message/MessageTemplateConfig 调用失败

6. AI 痛点 Top 5 跨命令

  1. webapi 一致性差 — 12+ 父命令 100% 绕 webapi, 大量 c.postJson/c.get 手写
  2. CRUD 闭环断裂 — 大量命令缺 update/info/delete, 改名/修改/清理需 delete+create
  3. selector 缺失 — 多个命令缺选择器 (role/org/dict type/storage/menu), AI 引用 ID 需 list 拉全表
  4. P0 端点错误 (假 PASS) — 3 处端点错, AI 调用成功但实际不生效
  5. 子项目 web 路径未知 — bigscreen/report 是独立子项目, 需特殊处理

7. Phase 2 执行建议

立即执行 (P0 端点错误)

  • 修 integration emailTest/smsTest 端点
  • 修 msg templateCreate 端点
  • 加 @deprecated 标记
  • 执行时间: 半天

短期 (P0 必补 [NEW-CMD])

  • form update (2 周)
  • log exception (1 周)
  • di info/test/create/update/delete (1 周)
  • role update/info/selector/authorize (1 周)
  • org position + selector (1 周)
  • msg noticeUpdate/Delete + templateUpdate/Delete (3 天)
  • 总时间: ~6 周

短期 (P0 必补 [REFACTOR-WEBAPI])

  • datasource 4 子命令 (2 天)
  • dict 4 子命令 (2 天)
  • menu 6 子命令 (3 天)
  • form import/codegen/create/fixcolumndata (1 周)
  • 总时间: ~2 周

中期 (P1 增强)

  • apis search (3 天)
  • storage CRUD (1 周)
  • bigscreen update/delete/category (1 周)
  • report CRUD (2 周)

8. 不建议做的事 (基于审计)

  1. ❌ 不建议补 schedule pause/resume/start/stop — JNPF 无对应 API, 用 update --enabledMark 替代
  2. ❌ 不建议把 schedule log 移到 monitor — 数据源不同
  3. ❌ 不建议命令化 bigscreen/report 设计器 drag-drop — UI 复杂操作, 命令化收益低
  4. ❌ 不建议补 app init --restart 实际功能 — 现有 dry-run 已说明, 改用 app use <code> 替代
  5. ❌ 不建议 dict dataList 改名 — 现有 4 子命令命名清晰

9. 下一步

Phase 2 开始: 按 P0 优先级执行

  1. Day 1-2: 修 3 处端点错误 + 加 @deprecated
  2. Week 1: form update + log exception
  3. Week 2-3: di/role/org/msg P0 必补
  4. Week 4-5: webapi 镜像化 (datasource/dict/menu/form)
  5. Week 6+: P1 增强 (apis search / storage / bigscreen / report)

作者: 2026-06-25 派 25 个 Explore 子代理审计 (5 批 × 5) 审计者: 23 个 dacli 父命令 (apis/app/bigscreen/datasource/di/dict/dm/doc/form/integration/log/menu/monitor/msg/org/portal/print/report/role/schedule/storage/user/workflow) 关键修正: bigscreen/report 是独立子项目, web 路径已修正 下一步: Phase 2 按 P0 优先级执行


v0.13+ 阶段 2 推进: webapi 化 (2026-07-01)

背景: Phase 1 审计完成, 但发现大量命令文件未真正用 webapi 镜像 (镜像建了但没用). 用户反馈 form/workflow 类 bug 频发, 根因是 dacli 自写逻辑 (LLM prompt, BPMN 解析, field 映射) 与 web 端漂移. 决策: 全模块按 webapi 模式统一, 删自写, 走 web 端源码镜像.

1. v0.13+ 已完成改造

模块 旧 → 新 关键改动
form 1424 → 1117 行 (-307) 删 --ai-json 块 + 删自写 LLM 路径, 走 NCPF backend AI + web buildFormData + 默认 autoRelease
workflow 347 → 466 行 (重写) 6 步 webapi 路径 (getAiInfo → create → getVersionList → buildFlowNodes(含 global) → save type=1)
form/_ai.ts 608 → 118 行 (-490) 删 callDirectAi* / parseAi* / LLM HTTP 客户端, 保留 NCPF backend 透传
form/_ai_prompts.ts 76 → 0 (删) 自写 LLM prompt 必与 NCPF backend 漂移, 整个文件删
workflow/_webapi_helpers.ts 0 → 187 (新建) defaultGlobalForm 模板 (镜像 web/.../FlowProcess/src/helper/config.ts:13-58) + parseFlowXml + buildFlowNodes
总计 -870 行自写逻辑 净减, 同时消除所有 LLM prompt / response parser 漂移源

2. v0.14 推进计划 (见 v0.14-webapi-rollout-plan.md)

模块 端点问题 改造工期
bigscreen (P0) 3 个文件 (list/info/release) 仍用错误的 webapi/bigscreen.ts (只镜像 dataV.ts 的 Selector, 其他手写 /api/blade-visual/visual/*, 违反 webapi 镜像原则). 切到 webapi/visualdata.ts (镜像 jnpf/前端/jnpf-web-datascreen-vue3/src/api/visual.js, 走 /api/visual/* nginx 代理 32000) 0.5 天 (基础切换) + 3 天 (完整构造, 用户 2026-07-01 强要求, 详见 v0.13 §8.2) + 1.5 天 (TC-C + TC-B 升级, 详见 v0.13 §8.3)
report (P0) 镜像已建但 0 文件用, 全部走 c.get/postJson 0.5 天
role (P0) 9 文件全未用 webapi, 镜像已建但未切 0.5 天
portal (P1) Bug 5: category 字段 silently drop, 类似 form 旧版问题 1 天
print (P1) 镜像已建但未切 0.5 天
di (P2) 5/8 已 webapi 化, 审计剩余 3 文件 0.5 天
总计 3.5 天

3. 核心方法论 (v0.13+ 沉淀)

webapi 化标准模式 (4 步):

  1. 删自写: 删 LLM prompt, LLM response parser, BPMN/JSON 解析, 字段映射启发式
  2. 用 webapi: import { initWebapi, loadXxx } from '../../webapi/xxx.ts'
  3. 初始化: await initWebapi(c) (一次性)
  4. 调用: await loadXxx.<func>(args) 替代 c.get/postJson

镜像源选择 (权威参照顺序, 用户 2026-07-01 强化):

  1. 业务子项目独立 webapp (jnpf-web-datascreen-vue3 / jnpf-web-datareport / jnpf-univer 等) — 优先于主 webapp
  2. web/apps/jnpf-web-apps-main/src/views/... — Vue 3 组件逻辑 (formData/columnData/flowConfig 构造)
  3. web/apps/jnpf-web-apps-main/src/api/ — Vue 3 主 webapp API 客户端 (注意: 某些模块 API 客户端不完整, 如 dataV.ts 只有 Selector)
  4. jnpf/后端/.../FlowUtil.java 等 — 后端权威 (作为最终验证, 不是首选 webapi 源)

绝对禁止 (drift 源, 用户 2026-07-01 强化):

  • ❌ 自写 LLM prompt 模板 (NCPF backend 已有, 两份必漂移)
  • ❌ 自写 LLM HTTP 客户端 (跟 NCPF backend 实现漂移)
  • ❌ 自写 LLM response 解析器 (web buildFormData 才是权威)
  • ❌ 自写 BPMN/JSON 解析 (跟 web FlowProcess/FlowXmlUtil 漂移)
  • ❌ 自写字段类型硬编码 (强制 jnpfKey='input' 丢组件类型)
  • ❌ 自写"启发式" relationForm 注入 (web 端不这么干, 误判多)
  • ❌ 镜像 web 端"残缺" API 客户端 + 手写其他端点直调后端 (例: 镜像 dataV.ts 的 Selector + 手写 /api/blade-visual/visual/list 直调, 看似 webapi 化实际是自写拼数据接后端 API, 绕开前端成熟能力) — 用户 2026-07-01 警告: 这个问题在 bigscreen 审计中重复出现, 每次按 webapi 镜像模式推, 慢慢又滑到自己拼接数据接后端 API
  • ❌ 选错 webapi 模块 (例: 业务有完整 visualdata.ts 镜像独立子项目, 却选了 bigscreen.ts 这种"残缺"模块) — 应按"镜像源最完整"原则选, 不是按"哪个存在"选

核心原则 (用户原话): "如果没有价值/且易干扰/漂移就去掉"; "使用 webapi 镜像 step machine 使用官方成熟能力, 不是直接构造数据请求后端 api".