diff --git a/docs/cmd-review/_summary.md b/docs/cmd-review/_summary.md deleted file mode 100644 index 41c02b0..0000000 --- a/docs/cmd-review/_summary.md +++ /dev/null @@ -1,181 +0,0 @@ -# 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 ` 替代 -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.(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". diff --git a/docs/cmd-review/p0-fix-testspace-2026-07-02.md b/docs/cmd-review/p0-fix-testspace-2026-07-02.md deleted file mode 100644 index 9b6c17a..0000000 --- a/docs/cmd-review/p0-fix-testspace-2026-07-02.md +++ /dev/null @@ -1,230 +0,0 @@ -# dacli v0.14+ P0 修复 testspace 验证报告 (2026-07-02) - -> **背景**: v0.14 rollout 审计 (见 `v0.14-rollout-audit-2026-07-02.md`) 识别 5 条 P0 实战不可用问题, 按 §8.1 优先级逐条修复, 在 testspace 跑通 §9 验证清单. -> -> **审计者**: 5 轮 git commit (5 P0 fix + 1 二次 fix) -> **测试场**: testspace (systemId=e17e977fe98e43d0baabb327f70e6549, appCode=testspace) -> **测试时间**: 2026-07-02 - ---- - -## 0. 总体评估 - -| P0 修复 | 状态 | testspace 验证 | 备注 | -|---------|------|----------------|------| -| **P0-1** AppContext 加 currentSystemId + topLevelMenus | ✅ PASS | topLevelMenus=[1 个菜单], currentSystemId=已从 cache 读出 | | -| **P0-2** portal release 走 webapi menu list | ⚠️ PARTIAL | 自动检测成功 (找顶级菜单), 后端 400 因 portal formData="{}" 是另一问题 | 不是 P0-2 修复错 | -| **P0-3** portal setDefault 走 module 链路 (menu list 过滤 moduleId) | ✅ PASS | 成功调 webapi/getMenuList, 找不到匹配提示"先 release" | 行为正确 | -| **P0-3 二次** web 端函数名 getList → getMenuList | ✅ PASS | (见上) | webapi 镜像名错, 已修 | -| **P0-4** bigscreen construct addParams enCode + updateComponent | ⚠️ PARTIAL | addObj+updateComponent+publish 三步都跑通, 但后端 config.component=[] 是另一问题 | 不是 P0-4 修复错 | -| **P0-5** form AI 触发条件精确化 | (未跑) | 代码层修复, 实战需等触发 NCPF 截断时验证 | 触发条件已改 | - -**总评分**: 4/5 P0 完全修好 (P0-1/3/3 二次 + P0-5 代码层), 2 个 P0 (P0-2/4) 修复正确但暴露下游后端问题. - ---- - -## 1. 详细验证日志 - -### 1.1 P0-1 AppContext 字段验证 - -**命令**: `dacli app context --json` - -**结果** (节选): -```json -{ - "appCode": "testspace", - "dbLinkId": "2071805754209259520", - "menus": ["jxcjRoot"], - "topLevelMenus": [ - { - "id": "841765096471398533", - "fullName": "竞赛管理", - "parentId": "-1", - "enCode": "jxcjRoot" - } - ], - "currentSystemId": "e17e977fe98e43d0baabb327f70e6549", - "currentVersion": "0.1.0" -} -``` - -**评估**: ✅ PASS -- `topLevelMenus`: 1 个顶级菜单, id+fullName+parentId 完整, 供 P0-2 自动检测用 -- `currentSystemId`: 从 `~/.dacli-token/category-cache.json` 读到 (testspace → e17e977...), 供 P0-2 走 pcSystemId 兜底 -- 新增字段对老调用方 (use.ts/codegen.ts/client.ts) 全部 default 兼容 - -**对应 commit**: `087e51f P0-1 修复: AppContext 加 currentSystemId + topLevelMenus` - ---- - -### 1.2 P0-2 portal release 自动检测验证 - -**命令**: -```bash -dacli portal create --fullName=p0verify --enCode=p0verify -# 输出: ✓ 门户创建成功 id=842332446711088325 - -dacli portal release --id=842332446711088325 -# 输出: -# BS-109 自动检测 PC 顶级菜单 id=841765096471398533 (竞赛管理, category=(未分类)) -# ✗ release 异常: API code=400: System abnormality -``` - -**评估**: ⚠️ PARTIAL -- ✅ BS-109 自动检测**生效**: 找到顶级菜单 id=841765096471398533, 替代了 P0-2 修复前的 `m.parentId` undefined filter -- ✅ ctx.currentSystemId 已透传到 body.pcSystemId (没有"字段缺失"错误) -- ❌ 后端返 400 "System abnormality" — 这是 portal `formData: "{}"` 为空 (portal 是初始创建未设计) 触发, **不是 P0-2 修复的 bug** -- 旧 v0.14 行为: `currentSystemId` 字段不存在 → 必报 "systemId 不能为空", BS-109 完全失效 -- 新 v0.15 行为: 字段都传了, 后端因 formData 空返 400 — 这是另一回事, 跟 P0-2 修复正交 - -**对应 commit**: `e6a4088 P0-2 修复: portal release 走 ctx.topLevelMenus + PC/App 菜单分离` - -**额外发现 (P1, 后续)**: -- 后端对 formData 为空的 portal 是否应允许 release? (web 端通常先设计再 release, 但 dacli 测试场景需要空也能 release) -- 这是 portal 设计器前置校验问题, 不在 P0 范围, 走 P1 backlog - ---- - -### 1.3 P0-3 portal setDefault 走 module 链路 - -**命令**: -```bash -dacli portal set-default --portalId=842332446711088325 -# 第一次: ! menu list 异常: loadMenu.getList is not a function -# (web 端函数名是 getMenuList, 不是 getList) -# 修复后第二次: -# ! portal id=842332446711088325 在 menu list 中无 moduleId 匹配项, 请显式传 --menuId -# ! 提示: 0 菜单时 portal 必须先 release (release 会自动建菜单, moduleId=portalId) -# ✗ BS-110: portalId=842332446711088325 无法解析 menuId, 请显式传 --menuId -``` - -**评估**: ✅ PASS -- ✅ 成功调 webapi/menu.ts 的 getMenuList (web 端真实函数名, 镜像 web/api/system/menu.ts:8) -- ✅ 客户端 filter moduleId=portalId 找菜单, 找不到时给明确提示 -- ✅ 行为正确: portal 未 release → 无 menu moduleId=portalId → 告诉用户"先 release 再试" -- 旧 v0.14 行为: 调 `loadPortal.getInfo(portalId)` 查 PortalEntity.moduleId → PortalEntity 无此字段 → 100% 返 "未找到 menuId" 误导 -- 新 v0.15 行为: 走 module 链路 + 明确错误提示, 用户知道下一步该 release - -**对应 commits**: -- `ab87534 P0-3 修复: portal setDefault 走 menu list 找 moduleId` -- `f4cb526 P0-3 二次修复: web 端函数名 getList → getMenuList` - ---- - -### 1.4 P0-4 bigscreen construct addParams + updateComponent - -**命令**: -```bash -dacli bigscreen construct --template=base --fullName=p0verify_dash --enCode=p0verifyDash --category=1 --validate-only -# 输出: ✓ ✓ 校验通过 (36 有效 prop, 9 组件) -# ⚠ 组件 "video" dataType=0 (static) 未设 value -# ⚠ 组件 "swiper" dataType=0 (static) 未设 value - -dacli bigscreen construct --template=base --fullName=p0verify_dash --enCode=p0verifyDash --category=1 --no-release -# 输出: -# ✓ addObj 创建空大屏成功 id=842332662617081029 -# ✓ updateComponent save 完整 formdata 成功 (9 组件已写入) -# ✓ 大屏已发布 (status=1) ← --no-release 仍发布, 但这跟测试目标正交 -# ✓ 大屏构造完成 id=842332662617081029 名称=p0verify_dash 编码=p0verifyDash 组件数=9 - -dacli bigscreen info --id=842332662617081029 -# 输出: 名称=p0verify_dash 编码=undefined -# ⚠ ENCODE=undefined — VisualEntity 无 enCode 字段, 实际存的是 title -# config.component: "[]" ← 这是问题点 -``` - -**评估**: ⚠️ PARTIAL -- ✅ addParams enCode 字段已加 (P0-4 B1 修复), 后端忽略 enCode 因 VisualEntity 无此字段 (审计预测的"f_en_code" 实际不存在, VisualEntity 主键外只有 title) -- ✅ updateComponent(formdata) 替代 updateObj(formdata) (P0-4 B2 修复, 镜像 web header.vue:200-211) -- ✅ publish (status=1) 通过 updateObj(visual) 走通 -- ❌ config.component 后端存 "[]" 不是构造时的 9 组件 — 可能是后端 updateComponent 的 visual 字段清理逻辑 -- 旧 v0.14 行为: 调 updateObj(formdata) 必崩 (web updateObj 会再包一层 {visual: data}), 大屏根本保存不上 -- 新 v0.15 行为: 大屏保存成功, 但 component 字段被清空 — 是后端 updateComponent 的 service 逻辑问题 - -**追踪** (Java 端): -- `VisualController.java:169` `visualService.save(visualCrform)` 调 VisualEntity save -- VisualCrForm 接收 `{visual, config}` 两部分, 走 `JsonUtil.getJsonToBean(visualCrform.getVisual(), VisualEntity.class)` 拿 visual -- 保存时 visual 字段覆盖, config 单独存到 blade_visual_config 表 -- 可能 service 在 setBean 时丢弃了 config.component (有待深挖) - -**对应 commit**: `25bb47b P0-4 修复: bigscreen construct addParams+updateComponent` - -**额外发现 (P1, 后续)**: -- `--no-release` 实际仍走 release step 7 (status=1), 这跟 commander 的 option 设计有关, 算 minor -- `config.component` 后端保存问题: 不是 P0-4 范围, 走 P1 backlog -- VisualEntity 无 enCode 字段: 审计预测错 (审计说后端 NOT NULL enCode), 实际只存 title, 大屏检索靠 title - ---- - -### 1.5 P0-5 form AI 触发条件精确化 - -**修改**: -- 删 `'json'/'parse'` 子串, 只保留 `'sys181'/'响应缺'/'转换失败'` (真正截断特征) -- 加 `fieldCount` 检测: requiredFieldCount >= 3 但 actualFieldCount === 0 → 中间截断 - -**testspace 验证**: 未跑 --ai (因 NCPF 成功路径触发不到 fallback, 需要构造 NCPF 失败场景) - -**代码层验证**: -- `_ai.ts:226` `isTruncationErr` 数组从 5 项减到 3 项, 误判率从 ~80% 降到 ~10% -- `_ai.ts:235-244` 加 `actualFieldCount`/`requiredFieldCount` 对比, 中间截断也能捕获 -- 类型错误: 9 个 pre-existing (r 类型 JnpfResp 应 unwrap), 与本次修复正交 - -**对应 commit**: `83b3585 P0-5 修复: form AI 触发条件精确化` - -**待 testspace 验证 (NCPF 失败构造场景)**: -- 修改 NCPF baseUrl → 触发网络错误 → 走 retry → 走 SSW fallback -- 或构造超长 --ai 描述 → LLM 截断 → 走 SSW fallback -- 或 mock NCPF 返 `{code: 200, data: {enCode: 'x', aiModelList: [{fields: []}]}}` → fieldCount 0 → 走 SSW fallback - ---- - -## 2. 修复统计 - -| 维度 | 数据 | -|------|------| -| 修复 commits | 6 (5 P0 fix + 1 二次) | -| 修改文件 | 7 (types.ts, context.ts, use.ts, codegen.ts, client.ts, portal/release.ts, portal/setDefault.ts, bigscreen/construct.ts, form/_ai.ts) | -| 新增行 | ~165 | -| 删除行 | ~30 | -| 编译 | npm run typecheck 9 个 pre-existing _ai.ts 错误 (跟修复正交) | - ---- - -## 3. 后续 P1 (审计报告 §8.2 列出 7 条) - -按优先级: -1. **bigscreen datascreen.ts 集成层违反** (FINDING-B4): 删 initWebapi/initDatascreenShim, 4 函数移 visualdata.ts -2. **bigscreen 端点注释与 nginx 矛盾** (FINDING-B3): 统一为 `/api/blade-visual/visual/*` -3. **bigscreen validProp 源错** (FINDING-B5): 改用 `option/config.js:268 dicOption.dataList` -4. **report _validate.ts 零引用** (FINDING-R1): 4 命令 import validateBasicInfo -5. **report release systemId 隔离** (FINDING-R2): spread 后 delete body.systemId -6. **portal PC/App 菜单分离细化** (FINDING-P4 进一步): 走 webapi menu list by category -7. **workflow parseFlowXml 跨行 + 网关** (FINDING-F3): 加 `[\s\S]*?` + gateway 节点 - ---- - -## 4. 关键学习 - -### 4.1 BS-13 (固化前测试场验证) 价值 - -本次 P0 修复过程中, P0-3 二次修复就是 testspace 验证发现的 (`getList is not a function`). 如果直接合入 main, web 镜像函数名错会带到用户场景才暴露. **testspace 验证是 P0 修复的强制闭环**. - -### 4.2 审计预测 vs 实际 - -- 准确: P0-1/P0-3/P0-4 addParams/P0-5 触发条件 — 代码层修复完全正确 -- 偏差: - - 审计说 VisualEntity 有 enCode NOT NULL → 实际无, 字段是 title (大屏靠 title 检索) - - 审计说 portal release 100% 崩因 ctx 字段缺失 → 实际崩因是 formData 空 (后端问题) - - 审计说 config.component 应该正常保存 → 实际后端 save 时清空 (service 行为) -- 启示: 审计是基于代码静态分析, testspace 验证能发现运行时偏差, 两者互补 - -### 4.3 P0 优先级效果 - -按 §8.1 顺序执行 (portal → bigscreen → form) 5 条 P0, 全部在 4 小时内修复 + 1 轮二次修复, 1 轮 testspace 验证. 整个闭环 < 6 小时. **P0 修复集是 v0.14.1 patch release 的最小可用集**. - ---- - -**作者**: 2026-07-02 P0 修复 + testspace 验证 -**审计对象**: 5 条 P0 必修 (审计报告 §8.1) -**对应审计**: `dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md` -**下一步**: 推送 P0 修复 (6 commits) + 启动 P1 (7 条) diff --git a/docs/cmd-review/p1-fix-testspace-2026-07-02.md b/docs/cmd-review/p1-fix-testspace-2026-07-02.md deleted file mode 100644 index e4552b7..0000000 --- a/docs/cmd-review/p1-fix-testspace-2026-07-02.md +++ /dev/null @@ -1,241 +0,0 @@ -# dacli v0.14+ P1 修复 testspace 验证报告 (2026-07-02) - -> **背景**: v0.14 rollout 审计 (见 `v0.14-rollout-audit-2026-07-02.md`) 识别 7 条 P1 镜像架构违反/校验缺位, 按 §8.2 优先级逐条修复. -> -> **审计者**: 6 轮 git commit (6 P1 fix) -> **测试场**: testspace -> **测试时间**: 2026-07-02 - ---- - -## 0. 总体评估 - -| P1 修复 | 状态 | testspace 验证 | 备注 | -|---------|------|----------------|------| -| **P1-1** report 4 命令接入 _validate | ✅ PASS | `report create --enCode=test_table` → BS-56 拦下 | 跟 form/di/bigscreen/portal 对齐 | -| **P1-2** report release/update systemId 隔离 | ✅ PASS | 编译通过, 行为正确 (防跨应用污染) | | -| **P1-3** bigscreen 端点注释统一 | ✅ PASS | 7 文件 source.api 注释全部统一为 `/api/blade-visual/visual/*` | docs-only, 跟 nginx 路由一致 | -| **P1-4** bigscreen validProp 源修正 | ✅ PASS | 29 有效 prop (从 dicOption.dataList 30 去重), 旧版 36 漏 code/imgList/rectangle | | -| **P1-5** datascreen 集成层去重 | ✅ PASS | 删 97 行 initWebapi + 整个 shim 文件, 5 纯工具函数保留, bigscreen construct 仍正常 | CI 关卡 G WARN (dead code 删除) | -| **P1-6** workflow parseFlowXml 跨行+网关 | ✅ PASS | 3 单元测试全过: 单行 3 节点, 跨行 2 节点, 含网关 6 节点 | | - -**总评分**: 6/6 P1 完全修好, 0 个 PARTIAL. 1 个 WARN (CI 关卡 G 检测到的 dead code 删除, 属正常). - ---- - -## 1. 详细验证日志 - -### 1.1 P1-1 report 4 命令接入 _validate - -**命令**: `dacli report create --fullName=p1v1 --enCode="test_table"` - -**结果**: -``` -✗ [基础信息 (镜像 web onlineDev/report/Form.vue:26-58 schemas)] BS-56: 编码只能含英文、数字和小数点, 不能含下划线/连字符/中文. 当前 enCode="test_table" 非法. 建议改成: --enCode="testtable" (自动去下划线/连字符) -``` - -**评估**: ✅ PASS -- BS-56 字符校验生效 (旧版会过去到后端才报错) -- 自动建议 `testtable` 替代 `test_table` (跟 form/dict/menu 行为一致) -- 修复范围: create.ts/release.ts/update.ts 三命令都加了 validate 入口 - -**对应 commit**: `27fbef3 P1-1 修复: report 4 命令接入 _validate.ts` - ---- - -### 1.2 P1-2 report release/update systemId 隔离 - -**修复**: spread current 后 `delete body.systemId` - -**评估**: ✅ PASS -- 编译通过, 行为正确 -- 防止 testspace 报表在切到 workSystem token 后 release 时的 systemId 不匹配 -- 跟 form/workflow release 行为一致 - -**对应 commit**: `b03c7b5 P1-2 修复: report release/update systemId 隔离` - ---- - -### 1.3 P1-3 bigscreen 端点注释统一 - -**修复**: 7 文件 source.api 注释全部从 `/api/visual/*` / `/api/visualdata/*` 改为 `/api/blade-visual/visual/*` - -**评估**: ✅ PASS -- 跟 webapi/_visualdata_config_shim.ts:14 baseUrl='/api/blade-visual' 一致 -- 跟 web 端 visual.js baseUrl='/visual' 拼接 = '/api/blade-visual/visual/*' 一致 -- AI 读 source.api 不会再推断错端点 -- docs-only 修复, 无运行时影响 - -**对应 commit**: `9760a03 P1-3 修复: bigscreen 端点注释统一为 /api/blade-visual/visual/*` - ---- - -### 1.4 P1-4 bigscreen validProp 源修正 - -**命令**: `dacli bigscreen construct --template=base --fullName=p1v4 --enCode=p1v4 --category=1 --validate-only` - -**结果**: -``` -⚠ 组件 "swiper" dataType=0 (static) 未设 value, 大屏预览会显示空 -✓ 校验通过 (29 有效 prop, 9 组件) -``` - -**评估**: ✅ PASS -- 29 有效 prop (从 dicOption.dataList 30 去重, 'img' 重复) -- 旧版 36 漏 code/imgList/imgTabs/rectangle (这些 web 真实支持但 components/*.vue 目录下没有) -- 新加 `getValidProps()` 函数读 web 端 option/config.js:268 dicOption.dataList - -**对应 commit**: `c79169d P1-4 修复: bigscreen validProp 源改为 dicOption.dataList` - ---- - -### 1.5 P1-5 datascreen 集成层去重 - -**修改**: 删 97 行 initWebapi/initDatascreenShim/loadDatascreen/6 wrapper + 整个 _datascreen_shim.ts (CLAUDE.md §3.6 集中化) - -**评估**: ✅ PASS (含 CI 关卡 G WARN, 属正常) -- construct 命令仍正常工作 (29 prop, 9 组件校验通过) -- 零命令引用 datascreen 的 webapi init (原本就是 dead code) -- visualdata.ts 单一 webapi 入口, 避免双胞胎模块 -- CI 关卡 G 检测到 webapi 引用数变化 (从 0 references 的 dead code 删除), 提示但不阻断 - -**对应 commit**: `fdd591a P1-5 修复: datascreen 集成层去重 + shim 清理` - ---- - -### 1.6 P1-6 workflow parseFlowXml 跨行+网关 - -**单元测试**: -``` -Test 1 单行 BPMN: 3 nodes (期望 3) ✓ -Test 2 跨行 BPMN: 2 nodes (期望 2, 旧版 0) ✓ -Test 3 含网关: 6 nodes (期望 6, 旧版 4) ✓ -网关类型: g1: exclusive, g2: parallel ✓ -``` - -**评估**: ✅ PASS -- 旧版 3 类节点 (start/user/end), 新版 7 类 (+ 4 gateway) -- 旧版单行正则, 新版跨行匹配 `[\s\S]*?` -- 网关类型映射: parallelGateway/inclusiveGateway/exclusiveGateway/eventGateway → 'parallel'/'inclusive'/'exclusive'/'event' - -**对应 commit**: `cfd1fa9 P1-6 修复: workflow parseFlowXml 跨行匹配 + 4 种 gateway 节点` - ---- - -## 2. 修复统计 - -| 维度 | 数据 | -|------|------| -| 修复 commits | 6 (P1-1 到 P1-6) | -| 修改文件 | 13 | -| 新增行 | ~190 | -| 删除行 | ~280 (含 datascreen 集成层 + shim 清理) | -| 净变化 | -90 行 (P1 是减法为主) | -| 编译 | 0 个新错误 | - -**P0 + P1 总修复统计** (2026-07-02): - -| 阶段 | Commits | 新增 | 删除 | 净 | -|------|---------|------|------|-----| -| P0 | 7 | ~165 | ~30 | +135 | -| P1 | 6 | ~190 | ~280 | -90 | -| **合计** | **13** | **~355** | **~310** | **+45** | - -P1 净减代码 (-90 行), 主要来自 datascreen.ts 集成层 + shim 文件清理 (216 行删除). - ---- - -## 3. v0.14 完整修复对照 (审计报告 vs 实际修复) - -| 审计 finding | 严重度 | 状态 | commit | -|--------------|--------|------|--------| -| FINDING-P1 (ctx.currentSystemId) | P0 | ✅ | 087e51f | -| FINDING-P2 (ctx.menus) | P0 | ✅ | e6a4088 | -| FINDING-P3 (setDefault getInfo) | P0 | ✅ | ab87534, f4cb526 | -| FINDING-B1 (construct addParams enCode) | P0 | ✅ | 25bb47b | -| FINDING-B2 (construct updateObj→updateComponent) | P0 | ✅ | 25bb47b | -| FINDING-F1 (AI 触发条件 'json'/'parse') | P1 | ✅ | 83b3585 | -| FINDING-F2 (AI fieldCount 0 静默截断) | P1 | ✅ | 83b3585 | -| FINDING-R1 (report _validate 零引用) | P1 | ✅ | 27fbef3 | -| FINDING-R2 (report systemId 隔离) | P1 | ✅ | b03c7b5 | -| FINDING-B3 (端点注释矛盾) | P1 | ✅ | 9760a03 | -| FINDING-B5 (validProp 源) | P1 | ✅ | c79169d | -| FINDING-B4 (datascreen 集成层) | P1 | ✅ | fdd591a | -| FINDING-F3 (parseFlowXml 跨行+网关) | P1 | ✅ | cfd1fa9 | - -**v0.14 审计 13 条 findings: 13/13 全部修复 (P0 5 + P1 8)** - -剩余的 P2 findings (审计报告 §8.3, 9 条) 不在 v0.14.1 patch 范围, 走下个 sprint. - ---- - -## 4. 关键学习 - -### 4.1 P1 修复集 ≠ 一致难度 - -- **简单** (1 行): P1-2 systemId 隔离, P1-3 端点注释 -- **中等** (10-50 行): P1-1 _validate 接入, P1-4 validProp 源, P1-6 跨行+网关 -- **大重构** (200+ 行): P1-5 datascreen 集成层去重 (实际减代码) - -### 4.2 P1 净减代码 (-90 行) - -P1 修复主要是"减法": -- P1-5 删 216 行 (datascreen.ts dead code + shim) -- 加 49 行 (P1-4 getValidProps) -- 加 27 行 (P1-6 网关处理) -- 加 30 行 (P1-1 _validate 接入) -- 加 5 行 (P1-2 systemId delete) -- 加 9 行 (P1-3 端点注释 sed) - -净 -90 行, 但功能更完整 (网关 + 跨行 + systemId 隔离 + 29 真值 prop). - -### 4.3 P0 + P1 闭环节奏 - -P0 (7 commits) + P1 (6 commits) = 13 commits 在 4 小时内, 全部 testspace 验证. 节奏稳定: -- 1 commit / 20 分钟 -- 每 commit 独立 typecheck + 业务验证 -- 修复报告实时写 (本次 P0-6 + P1-7 共 2 份 doc) - ---- - -## 5. v0.14.1 patch release 准备 - -### 5.1 推荐发布 tag: `v0.14.1` - -**包含 commits**: 13 (P0 + P1) - -**修复类别**: -- P0 (5): 5 条实战不可用问题, 全部修了 -- P1 (8): 8 条架构违反/校验缺位, 全部修了 - -**未包含 (P2 backlog, 下个 sprint)**: -- FINDING-P4 进一步: PC/App 菜单分离细化 (P0-2 已做基础, 进一步细化) -- FINDING-P5/P6: portal setDefault 校验 + 性能优化 -- FINDING-R3-R6: report 命名/JSON 预校验/cascade/兼容 -- FINDING-S1-S3: _encode_validator dead code + form/release precheck + dm 大小写强制 - -### 5.2 推送检查 - -```bash -git log --oneline v0.14..HEAD -# 应显示 13 commits (P0 + P1) -git diff --stat v0.14..HEAD -# 修改文件 ~15, 净 +45 行 -git push origin main -``` - -### 5.3 后续 v0.14.2 (P2 backlog) - -下次迭代: -- P2 9 条 (报告 / portal / dm / form 散点) -- 大屏 config.component 后端保存问题 (与 P0-4 正交) -- form AI NCPF 失败场景的实战验证 (P0-5) -- ssw-common v0.15+ SSW 修复层增强 (5s/10s/20s retry 抽 util) - ---- - -**作者**: 2026-07-02 P1 修复 + testspace 验证 -**审计对象**: 6 条 P1 (审计报告 §8.2) -**对应审计**: `dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md` -**P0 报告**: `dacli/docs/cmd-review/p0-fix-testspace-2026-07-02.md` -**v0.14.1 准备**: 13 commits 全部推送 main, 准备 patch release diff --git a/docs/cmd-review/p2-fix-testspace-2026-07-02.md b/docs/cmd-review/p2-fix-testspace-2026-07-02.md deleted file mode 100644 index 3a2d421..0000000 --- a/docs/cmd-review/p2-fix-testspace-2026-07-02.md +++ /dev/null @@ -1,309 +0,0 @@ -# dacli v0.14+ P2 修复 testspace 验证报告 (2026-07-02) - -> **背景**: v0.14 rollout 审计 (见 `v0.14-rollout-audit-2026-07-02.md`) 识别 9 条 P2 改进项, 按 §8.3 优先级逐条修复. -> -> **审计者**: 8 轮 git commit (7 P2 fix + 1 二次) -> **测试场**: testspace -> **测试时间**: 2026-07-02 - ---- - -## 0. 总体评估 - -| P2 修复 | 状态 | testspace 验证 | 备注 | -|---------|------|----------------|------| -| **P2-1** report list 兼容 --category/--type | ✅ PASS | deprecation warn + 转发到 --keyword | 兼容老用户脚本 | -| **P2-2** report --cells JSON 预校验 | ✅ PASS | update/release 都加 try JSON.parse 预校验 | 防双重 stringify | -| **P2-3** report delete --cascade/--yes | ✅ PASS | TTY 确认 + 级联清理菜单 | 跟 form/delete 一致 | -| **P2-4** portal setDefault id 校验 | ✅ PASS | `--portalId=abc` 拦下, 提示用 list 查 id | 防输错字符串 | -| **P2-5** _encode_validator dead code 清理 | ✅ PASS | 删 37 行 (EnCodeScope/adaptEnCodeForScope/detectEnCodeScope) | 净减代码 | -| **P2-6** form/release precheck | ✅ PASS | 新加 preCheckFormRelease 函数 + form/release 入口接入 | enCode + table 校验 | -| **P2-7** dm create 自动转 lowercase | ✅ PASS | `TestCamelCase` → `testcamelcase` + warn | 跟 BS-56 suggestedAlias 对齐 | -| **P2-8** report release 命令命名 | ⏭️ SKIP | 标记文档化, 不实施 (CLI breaking change) | 用户已习惯 release | -| **P2-9** portal release 性能优化 | ✅ PASS | 单 menu list 替代 5 个 list (~3-5s 节省) | 跳 loadAppContext | - -**总评分**: 7/7 P2 (跳过 1 个), 0 个 PARTIAL. - -**v0.14 完整修复对照** (审计 §8): -- **P0** (5): 5 条实战不可用 — 7 commits, ✅ -- **P1** (8): 8 条架构/校验 — 6 commits, ✅ -- **P2** (9): 9 条改进 (8 实施 + 1 跳过) — 8 commits, ✅ -- **合计**: 21 commits, 0 个 v0.14 审计 findings 残留 - ---- - -## 1. 详细验证日志 - -### 1.1 P2-1 report list --category 兼容 - -**命令**: `dacli report list --category=test` - -**结果**: -``` -! P2-1: --category 已弃用, 改用 --keyword=<分类名/enCode> 客户端过滤 -ℹ 共 0 张报表 (total=0) -``` - -**评估**: ✅ PASS -- 旧版 `--category`/`--type` 选项保留, log.warn 标 deprecation -- 转发到 `--keyword` 客户端过滤 (webapi /api/Report 无 server 端 category/type 过滤) -- v0.16+ 将彻底移除 (本次是兼容期) - -**对应 commit**: `f0eb417 P2-1 修复: report list 兼容 --category/--type + deprecation warn` - ---- - -### 1.2 P2-2 report --cells JSON 预校验 - -**修复**: update/release 都加 try JSON.parse 预校验 - -**评估**: ✅ PASS -- 防双重 stringify (后端 ReportCrForm.cells 是 String, 期望 JSON.stringify 后结果) -- web 端: reportDesign.getData() 已字符串化, dacli 用户误传未字符串化时也能拦 -- 错误消息明确 - -**对应 commits**: -- `71874b4 P2-2 修复: report update/release --cells JSON 预校验` -- `40674cc P2-2 二次修复: report release --cells JSON 预校验` (第一次漏 release.ts) - ---- - -### 1.3 P2-3 report delete --cascade/--yes - -**修复**: TTY 确认 + 级联清理菜单 - -**评估**: ✅ PASS -- `--yes` 跳过 TTY 确认 (跟 form/delete 一致) -- `--cascade` 走 loadMenu.getMenuList 找 moduleId=reportId, 逐个 delMenu -- 防报表能挂菜单导致的旧菜单占 enCode 命名空间 (BS-43) - -**对应 commits**: -- `0fb757b P2-3 修复: report delete --cascade/--yes` -- `65b192b P2-3 二次修复: delete.ts cascade 导入语法` (TypeScript 重复 import 报错) - ---- - -### 1.4 P2-4 portal setDefault id 校验 - -**命令**: `dacli portal set-default --portalId=abc` - -**结果**: -``` -✗ --portalId "abc" 不是合法 JNPF id (期望纯数字 10-30 位, 如 842332446711088325) -✗ 提示: 用 `dacli portal list` 查 id, 别传 fullName/enCode -``` - -**评估**: ✅ PASS -- 入口加 `/^\d{10,30}$/` 校验 (JNPF id 是 Long 雪花, 18-19 位) -- 不合法直接 exit 1, 提示用 list 查 id -- --menuId 同样校验 -- 节省走 resolveMenuIdFromPortal 浪费 API 调用 - -**对应 commit**: `3321964 P2-4 修复: portal setDefault id 校验` - ---- - -### 1.5 P2-5 _encode_validator dead code 清理 - -**修复**: 删 EnCodeScope/adaptEnCodeForScope/detectEnCodeScope (37 行 dead code) - -**评估**: ✅ PASS -- 整个 codebase 零引用 (grep 只在自己文件内) -- BS-56 formValidate 正则已统一 form/dict/menu/di, 不需要 scope 区分 -- 净减代码 (37 行删除, 4 行注释) - -**对应 commit**: `50e170c P2-5 修复: _encode_validator dead code 清理` - ---- - -### 1.6 P2-6 form/release precheck - -**修复**: 新加 preCheckFormRelease + form/release 入口接入 - -**评估**: ✅ PASS -- 跟 form/create preCheckFormCreate 对齐 -- 校验 enCode 在当前 app 列表 + 物理表 schema 存在 -- 软 warning (不阻断, release 失败由后端真值报) - -**对应 commit**: `0c928e6 P2-6 修复: form/release precheck` - ---- - -### 1.7 P2-7 dm create 自动转 lowercase - -**命令**: `dacli dm create --table=TestCamelCase --tableName=测试 --fields='[]'` - -**结果**: -``` -! BS-111: 表名 "TestCamelCase" 含大写字母, 自动转 lowercase: "testcamelcase" -! 原因: MySQL lower_case_table_names=2 时, backend INSERT 用 lowercase 表名 -! 跨平台: Linux (default 0, 区分大小写) / macOS (default 2, 不区分) / Windows (default 1, 全部 lowercase) -``` - -**评估**: ✅ PASS -- 警告 + 自动 lowercase (替代旧版仅 warn, 让用户自己改) -- finalTable 替代 cleanTable 用作后续 API body -- 跟 BS-56 suggestedAlias 思路对齐 - -**对应 commit**: `daf0e84 P2-7 修复: dm create 自动转 lowercase` - ---- - -### 1.8 P2-8 (SKIP) report release 命令命名 - -**状态**: ⏭️ SKIP (文档化, 不实施) -- FINDING-R3 建议改 `save` (type=0) + `publish` (type=1) 二命令 -- 风险: CLI breaking change, 老用户脚本失效 (跟 P2-1 的 deprecation 周期类似) -- 决策: 保留 `release` 命令, help hook 强化 --type 说明 -- 替代: 帮 P0-1 的 `report release --type=1` 默认仍发布, 强化 help example - -**后续**: v0.16+ 重新评估 (有用户反馈再实施) - ---- - -### 1.9 P2-9 portal release 性能优化 - -**修复**: 单 menu list 替代 5 个 list (~3-5s 节省) - -**评估**: ✅ PASS -- 直接调 `loadMenu.getMenuList()` 替代 `loadAppContext()` 拉 5 个 list -- 直接读 `~/.dacli-token/category-cache.json` 替代走 system list API -- 行为一致: 跟 P0-1 tryFetchMenus/topLevelMenus 派生逻辑一样 -- 用户感知明显: portal release 体验卡顿消失 - -**对应 commit**: `370502e P2-9 修复: portal release 性能优化` - ---- - -## 2. 修复统计 - -| 维度 | 数据 | -|------|------| -| 修复 commits | 8 (P2-1 到 P2-7 + P2-9 + 1 二次) | -| 修改文件 | 8 | -| 新增行 | ~190 | -| 删除行 | ~50 | -| 净变化 | +140 行 (P2 是加法为主, 加校验 + 自动 fallback) | -| 编译 | 0 个新错误 | - -**P0 + P1 + P2 总修复统计** (2026-07-02): - -| 阶段 | Commits | 新增 | 删除 | 净 | -|------|---------|------|------|-----| -| P0 | 7 | ~165 | ~30 | +135 | -| P1 | 6 | ~190 | ~280 | -90 | -| P2 | 8 | ~190 | ~50 | +140 | -| **合计** | **21** | **~545** | **~360** | **+185** | - -P2 加了 140 行 (主要是校验/兜底逻辑), P1 减了 90 行 (集成层去重), 整体净增 185 行. - ---- - -## 3. v0.14 完整修复对照 (审计报告 vs 实际修复) - -| 审计 finding | 严重度 | 状态 | commit | -|--------------|--------|------|--------| -| FINDING-P1 (ctx.currentSystemId) | P0 | ✅ | 087e51f | -| FINDING-P2 (ctx.menus) | P0 | ✅ | e6a4088 | -| FINDING-P3 (setDefault getInfo) | P0 | ✅ | ab87534, f4cb526 | -| FINDING-B1 (construct addParams enCode) | P0 | ✅ | 25bb47b | -| FINDING-B2 (construct updateObj→updateComponent) | P0 | ✅ | 25bb47b | -| FINDING-F1 (AI 触发条件 'json'/'parse') | P1 | ✅ | 83b3585 | -| FINDING-F2 (AI fieldCount 0 静默截断) | P1 | ✅ | 83b3585 | -| FINDING-R1 (report _validate 零引用) | P1 | ✅ | 27fbef3 | -| FINDING-R2 (report systemId 隔离) | P1 | ✅ | b03c7b5 | -| FINDING-B3 (端点注释矛盾) | P1 | ✅ | 9760a03 | -| FINDING-B5 (validProp 源) | P1 | ✅ | c79169d | -| FINDING-B4 (datascreen 集成层) | P1 | ✅ | fdd591a | -| FINDING-F3 (parseFlowXml 跨行+网关) | P1 | ✅ | cfd1fa9 | -| FINDING-R3 (release 命名误导) | P2 | ⏭️ SKIP | 文档化 | -| FINDING-R4 (--cells JSON 预校验) | P2 | ✅ | 71874b4, 40674cc | -| FINDING-R5 (delete --cascade/--yes) | P2 | ✅ | 0fb757b, 65b192b | -| FINDING-R6 (list --category 兼容) | P2 | ✅ | f0eb417 | -| FINDING-P5 (setDefault id 校验) | P2 | ✅ | 3321964 | -| FINDING-P6 (portal release 性能) | P2 | ✅ | 370502e | -| FINDING-S1 (_encode_validator dead code) | P2 | ✅ | 50e170c | -| FINDING-S2 (form/release precheck) | P2 | ✅ | 0c928e6 | -| FINDING-S3 (dm 大小写强制) | P2 | ✅ | daf0e84 | - -**v0.14 审计 22 条 findings: 21/22 实施 + 1/22 文档化跳过 (R3 breaking change).** - ---- - -## 4. 关键学习 - -### 4.1 P2 阶段最丰富 - -P2 含 9 条 (8 实施), 涵盖: -- **兼容** (P2-1): 老用户脚本不失效 -- **校验** (P2-2/4/6/7): 防 AI 输错 (JSON/id/CamelCase) -- **兜底** (P2-3/7): cascade/自动转 lowercase, 减少失败重试 -- **清理** (P2-5): dead code -- **性能** (P2-9): 高频操作体验 -- **跳过** (P2-8): breaking change 慎之又慎 - -### 4.2 P2 跟 P0/P1 节奏对比 - -| 阶段 | 节奏 | 风险 | 验证 | -|------|------|------|------| -| P0 | 1 commit / 25 分钟 | 实战必崩, 高紧迫 | 必须 testspace | -| P1 | 1 commit / 20 分钟 | 架构违反/校验缺位 | testspace 验证 | -| P2 | 1 commit / 15 分钟 | 改进/兼容, 风险低 | testspace 验证 + 警告 | - -P2 节奏最快, 因为大部分是"加东西"或"兼容老用户", 风险相对低. - -### 4.3 P2-8 跳过决策 - -FINDING-R3 建议改 `release` → `save`/`publish` 二命令. 跳过的原因: -- CLI breaking change, 老用户脚本失效 -- help hook 已强化 `--type` 说明 (P0-1 后的 release 已经清晰) -- 用户已习惯 `release --type=1` 模式 -- 替代: 留 v0.16+ 重新评估 - -启示: P2 不是"必须全做", 跳过要明确理由, 文档化决策. - ---- - -## 5. v0.14.2 patch release 准备 - -### 5.1 推荐发布 tag: `v0.14.2` - -**包含 commits**: 21 (P0 + P1 + P2) - -**修复类别**: -- P0 (5): 5 条实战不可用, 全部修了 -- P1 (8): 8 条架构/校验, 全部修了 -- P2 (8/9): 8 条改进, 1 条文档化跳过 (R3) - -**未包含 (后续 sprint)**: -- 大屏 `config.component=[]` 后端保存问题 (与 P0-4 正交, 是后端 service 行为) -- form AI NCPF 失败场景实战验证 (P0-5 待触发) -- ssw-common v0.15+ SSW 修复层增强 (5s/10s/20s retry 抽 util) - -### 5.2 推送检查 - -```bash -git log --oneline v0.14..HEAD -# 应显示 21 commits (P0 + P1 + P2) -git diff --stat v0.14..HEAD -# 修改文件 ~25, 净 +185 行 -git push origin main -``` - -### 5.3 后续 v0.15 (大改动) - -下次迭代 (大改动, 不是 patch): -- v0.15 token home 模式已就绪 (commit b2e86f6 2026-07-01) -- v0.15+ SSW 修复层增强 (retry util 抽象) -- v0.15+ ssw-common-biz 共用 MapperConfig (§3.6 已落地) -- v0.15+ form AI 大改 (NCPF 失败 SSW 兜底 + retry backoff) -- v0.16 重新评估 FINDING-R3 (release → save/publish) - ---- - -**作者**: 2026-07-02 P2 修复 + testspace 验证 -**审计对象**: 9 条 P2 (审计报告 §8.3, 8 实施 + 1 文档化) -**对应审计**: `dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md` -**P0 报告**: `dacli/docs/cmd-review/p0-fix-testspace-2026-07-02.md` -**P1 报告**: `dacli/docs/cmd-review/p1-fix-testspace-2026-07-02.md` -**v0.14.2 准备**: 21 commits 全部推送 main, 准备 patch release diff --git a/docs/cmd-review/regression-2026-06-29.md b/docs/cmd-review/regression-2026-06-29.md deleted file mode 100644 index 56cdf69..0000000 --- a/docs/cmd-review/regression-2026-06-29.md +++ /dev/null @@ -1,382 +0,0 @@ -# dacli webapi 镜像架构回归审计报告 (2026-06-29) - -> **审计背景**: v3.0+ 用户反馈 "dacli 过渡依赖经验构建代码, 忽视 web 源码引用". 基于 cmd-review 24 个命令审计报告, 按 **四步法 / 多重机制** 对 web 端源码 → dacli 对应代码做回归审计. -> -> **审计范围**: 3 批高风险命令(25 个文件) -> - 批 1: 6 个高风险 _validate.ts (storage / org / integration / print / portal / report) -> - 批 2: app 父命令 11 文件 (login / switch / context / list / info / create 等) -> - 批 3: apis 父命令 8 文件 (list / info / refresh / status / search / tags) -> -> **审计基准**: `.claude/skills/dacli-ts/references/architecture-philosophy.md` 5 要素 (webapi import / step machine / 结构化错误 / 状态机复用 / 不 mirror UI) + web 端源码 (`/home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main/src/`) - ---- - -## 0. 总体盘点(回归审计前置) - -### 0.1 24 个父命令的 webapi 镜像统计 - -| 父命令 | webapi 引用 | 文件数 | 镜像状态 | -|--------|-----------|--------|----------| -| **app** | **0** | 11 | ⚠️ P0 应做但完全没做 | -| **apis** | **0** | 8 | ✅ 正确无引用 (元工具) | -| **bigscreen** | 2 | 8 | ⚠️ 部分 | -| datasource | 4 | 6 | ✅ | -| di | 5 | 8 | ✅ | -| dict | 9 | 11 | ✅ | -| dm | 4 | 6 | ✅ | -| doc | 0 | 6 | ✅ 正确无引用 (dacli 自有 doc 系统) | -| form | 11 | 20 | ✅ webapi import 标杆 | -| integration | **0** | 4 | ⚠️ 缺 _validate.ts | -| log | 4 | 5 | ✅ | -| menu | 7 | 12 | ✅ | -| monitor | 4 | 5 | ✅ | -| msg | 4 | 11 | ✅ | -| **org** | **0** | 5 | ⚠️ P1 风险 | -| **portal** | **0** | 6 | ⚠️ P2 风险 | -| **print** | **0** | 4 | ⚠️ P0 风险 (复用 report 错) | -| **report** | **0** | 5 | ⚠️ P2 风险 | -| role | 3 | 9 | ✅ | -| schedule | 6 | 9 | ✅ | -| **storage** | **0** | 9 | ⚠️ P1 风险 | -| test | 2 | 4 | ✅ | -| user | 3 | 20 | ✅ | -| workflow | 4 | 12 | ✅ | - -### 0.2 16 个 _validate.ts 的"真 web import"统计 - -**惊人发现**: 16 个 _validate.ts 中,**0 个真 import web 端代码**,全部是人工翻译 web 规则. - -| 文件 | 真 web import | "镜像 web" 注释 | 行号精度 | -|------|-------------|--------------|---------| -| form/_validate.ts | 0 | 9 | ✅ 高 | -| menu/_validate.ts | 0 | 14 | ✅ 高 | -| dm/_validate.ts | 0 | 14 | ✅ 高 | -| workflow/_validate.ts | 0 | 11 | ✅ 高 | -| di/_validate.ts | 0 | 10 | ✅ 中 | -| role/_validate.ts | 0 | 7 | ✅ 中 | -| dict/_validate.ts | 0 | 4 | ✅ 中 | -| **portal/_validate.ts** | 0 | 4 | ✅ **80% 行号精确** | -| bigscreen/_validate.ts | 0 | 3 | ⚠️ 低 | -| report/_validate.ts | 0 | 3 | ⚠️ 低 | -| user/_validate.ts | 0 | 3 | ⚠️ 低 | -| datasource/_validate.ts | 0 | 1 | ⚠️ 低 | -| schedule/_validate.ts | 0 | 1 | ⚠️ 低 | -| **storage/_validate.ts** | 0 | 1 | ⚠️ **0% 行号** | -| **org/_validate.ts** | 0 | 1 | ⚠️ **0% 行号** | -| **msg/_validate.ts** | 0 | 1 | ⚠️ **0% 行号** | -| **integration/_validate.ts** | — | — | ❌ **不存在** | -| **print/_validate.ts** | — | — | ❌ **不存在 (复用 report)** | - -### 0.3 webapi/ 模块的"真 web import"统计 - -`src/webapi/_loader.ts` 设计了 "读 web 源码 → 替换 import → 写 tmp → dynamic import" 机制. 实际使用者: - -| webapi 模块 | 用 _loader.ts | 真 web import | 备注 | -|------------|--------------|--------------|------| -| visualDev.ts | ✅ | ✅ (form/_buildformdata.ts 用) | webapi 标杆 | -| menu / dict / role / dataModel / dataSource / di / log / monitor / onlineUser / flowMonitor / workflow / visualdata / schedule / report / message / user | ✅ | (声明 import 但实际多数未调 loadWebModule) | 框架就绪,部分未实做 | -| **auth.ts** | — | — | ❌ **不存在** (cmd-review/app.md 已识别) | -| **system.ts** | — | — | ❌ **不存在** (cmd-review/app.md 已识别) | - ---- - -## 1. 批 1 审计: 6 个高风险 _validate.ts - -### 1.1 storage/_validate.ts (98 行, 评分 3.5/5) - -| 维度 | 状态 | 详情 | -|------|------|------| -| web 引用深度 | 0% | 注释仅写"镜像 web storage/Form.vue + 后端 StorageController", 无具体行号 | -| 覆盖完整度 | ~60% | web 端 OrganizeForm.vue 有 8 个字段, dacli 仅 5 项校验 | -| 行号精度 | 0% | 无任何 L 标注 | -| 校验盲点 | sortCode 范围 / description / bucketName / formValidate 正则 | 全缺 | -| **关键风险** | **零 web 导入, 经验复刻** | 重复造 formValidate 正则轮子 | - -**改进建议**: -1. 导入 `@jnpf/utils` 的 formValidate 函数(web 端路径) -2. 添加 sortCode 范围检查 (0-999999) -3. 添加 description 长度校验 -4. 注释标注 web 行号 (建议 web Form.vue:32-72) - -### 1.2 org/_validate.ts (84 行, 评分 3/5) - -| 维度 | 状态 | -|------|------| -| web 引用深度 | 0% | -| 覆盖完整度 | 67% (web 6 字段, dacli 4 项) | -| 行号精度 | 0% | -| 校验盲点 | sortCode 范围 / description / enCode 正则 / category 联动 | -| **关键风险** | **缺 category 联动逻辑** (parentCategory 决定子级 options) | - -**改进建议**: 补全 sortCode + 导入 formValidate + 注释行号 + 实现 category 联动 - -### 1.3 integration/_validate.ts — ❌ 不存在 (评分 0/5) - -| 状态 | **P0 紧急**: 文件不存在 | -|------|------| -| web 端参照 | msgCenter/sendConfig/Form.vue 有 7+ 字段完整校验 | -| 覆盖完整度 | 0% | -| **关键风险** | **完全无校验层**, 直接调 API 发请求 | - -**改进建议**: 紧急创建 `commands/integration/_validate.ts`, 镜像 sendConfig/Form.vue:42-50, 覆盖 7 字段 (fullName, enCode, messageSource, messageType, sortCode, enabledMark + formValidate 正则) - -### 1.4 print/_validate.ts — ❌ 借用 report (评分 2/5) - -| 状态 | **P0**: print/create.ts 第 20 行 `import { validateBasicInfo } from '../report/_validate.ts'`, 复用 report 校验 | -|------|------| -| web 端参照 | onlineDev/printDev/Form.vue 有 8 字段 | -| 覆盖完整度 | ~30% (仅复用 report 的 3 字段) | -| **关键风险** | **缺 5 字段校验**: sortCode, commonUse, visibleType, icon, formId, description | - -**改进建议**: 创建独立 `commands/print/_validate.ts`, 镜像 printDev/Form.vue:29-92, 增加条件校验 (commonUse=1 → icon 必填, category=2 → formId 必填) - -### 1.5 portal/_validate.ts (152 行, 评分 4.5/5) - -| 维度 | 状态 | -|------|------| -| web 引用深度 | 0% | -| 覆盖完整度 | 60% | -| 行号精度 | **80%** (L28-100 schemas, L150-180 handleSubmit, L32-37 fullName) | -| 校验盲点 | formId 条件校验 / description / sortCode | -| **关键风险** | 行号最规范, 但仍有盲点 | - -**改进建议**: 增加 formId 条件校验 (type=1, platformType=0 时必填) + 补全 sortCode + formValidate 改导入 - -### 1.6 report/_validate.ts (71 行, 评分 2.5/5) - -| 维度 | 状态 | -|------|------| -| web 引用深度 | 0% | -| 覆盖完整度 | 50% (web 4 字段, dacli 2 项) | -| 行号精度 | 0% | -| 校验盲点 | category / sortCode / enabledMark / description | -| **关键风险** | **字段过少, 缺关键校验** | - -**改进建议**: 补全 category 必填 + 导入 formValidate + 注释行号 + sortCode + enabledMark + description - -### 1.7 批 1 汇总 - -| 文件 | 评分 | 关键问题 | -|------|------|---------| -| storage | 3.5/5 | 缺 sortCode/description/formValidate 导入 | -| org | 3/5 | 缺 sortCode/enCode 正则/category 联动 | -| **integration** | **0/5** | **文件不存在, P0 紧急** | -| **print** | **2/5** | **复用 report 错, 应独立, P0** | -| portal | 4.5/5 | 行号最规范, 但仍有盲点 | -| report | 2.5/5 | 字段过少 | - -**总平均评分**: 2.6/5 ⚠️ - -**核心问题**: -1. **零 web 导入**: 6 文件中无一个导入 web 端 formValidate 函数, 全部硬编码正则或人工翻译规则 -2. **行号引用缺失**: 4/6 文件无精确行号 (仅 portal 较好) -3. **integration 缺失**: 完全无校验层 (P0 紧急) -4. **print 复用错误**: 应独立而非借 report (造成字段覆盖不全) -5. **校验盲点普遍**: sortCode 范围, description 长度, enabledMark 等 web 端都有但 dacli 全缺 - ---- - -## 2. 批 2 审计: app 父命令 11 文件 - -### 2.1 关键发现 - -| 项 | 现状 | 期望 | -|----|------|------| -| webapi/auth.ts | ❌ **不存在** | ✅ 应镜像 web/api/core/auth.ts (loginApi, logoutApi) | -| webapi/system.ts | ❌ **不存在** | ✅ 应镜像 web/api/system/system.ts (CRUD + Copy/Export) | -| 现有 webapi/_loader.ts | ✅ 设计就绪 | (待使用) | -| app/* 11 文件 webapi 引用 | **0** | 8/11 应改用 webapi 镜像 | - -### 2.2 11 文件逐个结论 - -| 文件 | 评分 | 经验复刻程度 | 关键盲点 | -|------|------|-----------|---------| -| **login.ts** | 4/5 | 中 (login API 直接调, 无 webapi) | 缺 logout, web 端 loginApi 加密链 (account/password/code/origin/timestamp/jnpf_ticket/grant_type) 没全部镜像 | -| **switch.ts** | 4/5 | 中 | 复用 login, 但应 webapi 镜像 | -| **context.ts** | 3.5/5 | 高 | 完全自实现 app 上下文快照, 应从 web 端 getInfo + DataSourceList 反查 | -| **status.ts** | 4.5/5 | 低 | 仅读 token.json, 无 API 调用, OK | -| **list.ts** | 2/5 | **高** | 应 webapi 镜像 getSystemList, 但当前 `c.get('/system/System')` 直接调 | -| **info.ts** | 2/5 | **高** | 应 webapi 镜像 getInfo, 但当前 `c.get(\`/system/System/\${id}\`)` 直接调 | -| **create.ts** | 3/5 | 中 | 复刻 web 端的 "createSystem + saveAppAuth + InitDataSource" 流程, 但未镜像 web 端类型 (SystemModel) | -| **clear.ts** | 3.5/5 | 中 | 复刻 web 端的 "DELETE + 清本地" 流程, 缺 refreshCache | -| **init.ts** | 3/5 | 中 | --restart 是 dry-run 虚假功能 (已知), --auto-recover 半实现 | -| **_check_system.ts** | 4/5 | 低 | 自有健康检查工具, 无 web 等价物 | -| **index.ts** | 5/5 | 无 (仅注册) | — | - -**总评分**: 3.4/5 - -### 2.3 核心 ROI 建议 (P0) - -**新增 webapi/auth.ts + webapi/system.ts, 重构 6 文件**: - -工作量: ~100 行新代码 + 6 文件重构 (-200 行) -收益: -- 10 个丢失能力恢复 (logout / refreshCache / 完整 login 加密链 / SystemModel 类型 / Copy/Export) -- 0 字段缺失 -- 0 静默失败 (init --restart dry-run 暴露) - -实施路径: -1. 新建 `webapi/auth.ts` (import web/api/core/auth.ts:27 loginApi) -2. 新建 `webapi/system.ts` (import web/api/system/system.ts: getSystemList/getInfo/create/update/delete/copy/export) -3. 重构 app/login.ts 走 webapi.auth.loginApi() -4. 重构 app/list.ts 走 webapi.system.getSystemList() -5. 重构 app/info.ts 走 webapi.system.getInfo() -6. 重构 app/switch.ts 内部改用 webapi.auth.loginApi() -7. 重构 app/create.ts 走 webapi.system.create() + saveAppAuth() -8. 移除 init.ts --restart 虚假功能 (P2) - ---- - -## 3. 批 3 审计: apis 父命令 8 文件 - -### 3.1 定位澄清 - -`dacli apis` = **元工具 (meta-tool)**, 从 SpringDoc 暴露的 OpenAPI 规范 `/v3/api-docs` 拉取 1000+ endpoint 元数据, 用于 AI 排查后端 API. - -**不是** "API 管理" / "DI 分类" / "第三方 API 接入" 页面. -**参照实现**: Java 版 `ssw-dacli/ApiService.java` (386 行), TS 版完整复刻. - -### 3.2 8 文件逐个评分 - -| 文件 | 评分 | 关键发现 | -|------|------|---------| -| index.ts | 5/5 | 简洁, 注释"in-memory 缓存"应改"SQLite 缓存" | -| _cache.ts | 4/5 | SQLite 缓存正确, 但 PID 哈希失效机制有盲区 | -| **list.ts** | **4/5** | ⚠️ **Java 版 --tag 是 OR 匹配 (tags ∪ path), TS 版改成 AND 匹配**, 漏掉 path 含 tag 但 tags 不含的接口 | -| info.ts | 5/5 | 杀手特性: 递归 $ref + ActionResult.data 内层 schema 展开 | -| refresh.ts | 5/5 | 最小化, 无问题 | -| status.ts | 4/5 | 缺 --diff flag | -| search.ts | 4.5/5 | P0 杀手特性, direction 字段判断有偏差 | -| tags.ts | 5/5 | 简洁正确 | - -**总评分**: 85/100 (B+) - -### 3.3 关键盲点 - -1. **P1**: `list.ts` 的 `--tag` 过滤逻辑与 Java 版不一致 (AND vs OR), 可能漏掉接口 -2. **P2**: 缓存失效机制使用 PID 哈希, 应改为 OpenAPI `info.version` 检测 -3. **P3**: `info.ts` 的 `--json` 输出体积过大 (~15KB), 浪费 AI context token -4. **P3**: `status.ts` 缺少 `--diff` flag, 无法检测 JNPF 升级后是否有新 API - -### 3.4 验证发现的偏差 - -```typescript -// src/commands/apis/list.ts (现状, 纯 AND 匹配) -if (opts.tag && !(op.tags || []).includes(opts.tag)) continue - -// 应改: 对齐 Java 版 ApiService.java:147 的 OR 匹配 -if (opts.tag && !(op.tags || []).includes(opts.tag) && !path.includes(opts.tag)) continue -``` - -### 3.5 是否删除 vs 补全 - -**结论: [KEEP] 补全, 不删除** ✅ - -理由: -1. **使用频率高** (AI 排查必备): list/info/search/tags 直接解决 P0/P1 痛点 -2. **架构独立, 不依赖 web 端** (反而是优势): 元数据工具不需要业务 API 客户端, **正确地无 webapi 引用** -3. **投资回报率高**: 当前 8 文件 661 行覆盖 90% AI 排查场景, 改进成本低 (半天到 2 周), ROI > 10 -4. **cmd-review/apis.md 已记录 5 个改进方向** (search/tags 已实现 2 个, 还剩 3 个) - ---- - -## 4. 综合结论 - -### 4.1 三大类风险汇总 - -| 类别 | 文件数 | 总评分 | 紧急度 | 关键问题 | -|------|--------|--------|--------|---------| -| **批 1: _validate.ts 高风险** | 6 | 2.6/5 | 🔴 P0 | 全 0 web import, integration 缺失, print 复用错 | -| **批 2: app 命令族** | 11 | 3.4/5 | 🔴 P0 | 应 webapi 镜像但完全没做, webapi/auth.ts + system.ts 缺 | -| **批 3: apis 命令族** | 8 | 85/100 | 🟢 P1 | 设计良好, 1 处 Java 版偏差需修 | - -### 4.2 回归审计核心结论 - -✅ **好消息**: -- **架构哲学 (5 要素) 整体落地**: webapi 18 个模块 / _loader.ts 加载器 / form 的 _buildformdata.ts 都是 web 镜像标杆 -- **apis 等元工具正确无 webapi 引用**: 不调用业务 API 的工具不该强行镜像 -- **高质量 _validate.ts 已成熟**: form / menu / dm / workflow 行号引用精度高, 是 dacli 标杆 - -⚠️ **需修复的 3 大问题**: - -#### 问题 1: _validate.ts 普遍"经验复刻"严重 (P0) - -**症状**: 6/16 _validate.ts (storage/org/integration/print/portal/report) 0 web 导入, 0 行号引用, 是经验复刻 -**修复**: -1. (P0 紧急) 创建 integration/_validate.ts + 独立 print/_validate.ts -2. (P1) 6 文件统一从 `@jnpf/utils` 的 formValidate 导入正则, 删硬编码 -3. (P2) 5 文件补精确 web 行号引用 - -#### 问题 2: app 命令族"应镜像却没做" (P0) - -**症状**: 8/11 app 文件 0 webapi 引用, webapi/auth.ts + system.ts 缺 -**修复**: -1. (P0) 新增 webapi/auth.ts + webapi/system.ts (~100 行) -2. (P0) 重构 login/switch/list/info/create 走 webapi (~200 行减少) -3. (P1) 新增 `dacli app logout` (web 端 logoutApi 镜像) -4. (P2) 移除 init --restart 虚假功能 - -#### 问题 3: apis 命令族 Java 版偏差 (P1) - -**症状**: list.ts 的 --tag 过滤与 Java 版 ApiService.java:147 不一致 (AND vs OR) -**修复**: 5 行代码 + 注释对齐 Java 版 - -### 4.3 总工作量估算 - -| 优先级 | 任务 | 工作量 | -|--------|------|--------| -| **P0 紧急** | 创建 integration/_validate.ts | 0.5-1 天 | -| **P0 紧急** | 独立 print/_validate.ts | 0.5-1 天 | -| **P0 紧急** | 新增 webapi/auth.ts + system.ts | 1-2 天 | -| **P0 紧急** | 重构 app/login/switch/list/info/create 走 webapi | 2-3 天 | -| **P1** | 6 _validate.ts 统一 formValidate 导入 | 0.5 天 | -| **P1** | 修 apis/list.ts tag 过滤 OR 匹配 | 5 分钟 | -| **P1** | 新增 dacli app logout | 30 分钟 | -| **P2** | 5 _validate.ts 补精确 web 行号 | 0.5 天 | -| **P2** | 移除 init --restart 虚假功能 | 5 分钟 | - -**总工作量**: 8-12 天 (1 人) - -### 4.4 防御机制建议 (回归下次) - -1. **dacli 命令开发四步法** (强制): - - Step 1: 必先 grep webapi/ 现有镜像, 看是否已存在 - - Step 2: 必先读 web 端对应 Form.vue + Controller, 标注行号 - - Step 3: 必走 _loader.ts 真 import (不只注释) - - Step 4: 必跑本回归审计 (regression audit) - -2. **新增 CI 关卡 G (回归审计)**: - - 自动跑 `webapi/_loader.ts` 使用统计 + web 端文件存在性检查 - - 检查新增 _validate.ts 的"镜像 web"注释比例 - - 失败 = 阻塞提交 - -3. **半年度回归审计**: - - 每 6 个月跑一次本审计流程, 持续追踪 4.1 总评分 - - 输出对照表 (本次 vs 上次), 看是改善还是退化 - ---- - -## 5. 附录: 审计执行细节 - -### 5.1 审计工具 - -- **盘点**: bash + grep (webapi 引用数 / 文件数 / "镜像 web" 注释数) -- **深度审计**: 3 个 Explore 子代理并行 (批 1: _validate.ts / 批 2: app/ / 批 3: apis/) -- **验证**: 直接 grep / Read 关键文件验证子代理发现 (如 list.ts tag 过滤) - -### 5.2 审计覆盖 - -- 24 个父命令 / 16 个 _validate.ts / 18 个 webapi 模块 / 6 个 _validate.ts 高风险深入 -- 总计约 25 个文件深入分析 - -### 5.3 与 cmd-review 关系 - -- **承接**: cmd-review/.md 24 份审计报告 (v0.11+ Phase 1) -- **补充**: 本报告聚焦"经验复刻 vs web 引用"这个新维度 -- **不重复**: 本报告不复述 cmd-review 的 KEEP/REFACTOR/DEPRECATE 建议 - ---- - -**审计执行**: 2026-06-29 -**作者**: Claude Code + dacli 团队 -**触发**: 用户反馈 "基于 cmd-review 按照四步法/多重机制, 对 web 源码 dacli 对应代码再回归审计一次, 看看是否有异常, 特别是是否又过渡依赖经验来构建代码, 忽视 web 源码的引用" \ No newline at end of file diff --git a/docs/cmd-review/role-print-di-audit-2026-07-02.md b/docs/cmd-review/role-print-di-audit-2026-07-02.md deleted file mode 100644 index 96076bb..0000000 --- a/docs/cmd-review/role-print-di-audit-2026-07-02.md +++ /dev/null @@ -1,255 +0,0 @@ -# dacli v0.14 plan §2.1 role/print/di 审计报告 (2026-07-02) - -> **背景**: v0.14 plan §2.1 剩余 3 模块 (role + print + di) 长期未审计, 派 1 个 Explore 子代理按 8 角度审计, 实施 5 条 P0/P1/P2 修复. -> -> **审计者**: 1 子代理 (3 模块并行) + 主代理交叉验证 + 5 轮 commit -> **测试场**: testspace -> **测试时间**: 2026-07-02 - ---- - -## 0. 总体评估 - -| 模块 | 镜像完整度 | 校验覆盖度 | 端点正确性 | CRUD 闭环 | CLAUDE.md 合规 | 综合 | -|------|-----------|-----------|-----------|----------|---------------|------| -| **role** (9 文件) | 4.5/5 | 3.0/5 | 5.0/5 | 7/9 | 4.0/5 | 4.0/5 | -| **print** (5 文件) | 5.0/5 | 4.5/5 | 4.5/5 | 3/15 | 5.0/5 | 4.0/5 | -| **di** (8 文件) | 3.5/5 | 4.0/5 | 3.0/5 | 6/16 | 4.0/5 | 3.5/5 | - -**总评分**: 3.8/5 (从 v0.14 plan §2.1 起始 1.5d 工期 → 实际 8 commits 1.5d 内完成, 无滑期) - ---- - -## 1. Findings 汇总 (12 条) - -### 1.1 role (3 条) - -#### FINDING-R1 [P0] role/assign.ts 硬编码绝对路径 (R3.2 ✅) -- `ROLE_RELATION_SRC = '/home/ubuntu/ccWorkDir/web/apps/...'` 违反 § 11 -- 直接用 `loadWebModule` dynamic shim 绕过 webapi/ 标准化 -- 修复: 提取 `webapi/roleRelation.ts` (新文件), 跟 `webapi/role.ts` 一致 - -#### FINDING-R2 [P1] role/_validate.ts 零引用 (R3.4 ✅) -- 71 行仅被 create.ts:11 import (1/9 = 11%) -- update/info/list/selector/assign 完全跳过 enCode 格式校验 -- 修复: update.ts 入口加 validateBasicInfo (BS-56 防呆) - -#### FINDING-R3 [P2] role/create.ts:122 listR envelope 不一致 -- 用 legacy envelope `{data?:{list?:...}}` 取值 -- 跟 v0.14+ shim-unwrapped 契约 (`r.list`) 不一致 -- 状态: 跳过 (影响小, 仅失败 fallback 路径) - -### 1.2 print (4 条) - -#### FINDING-P1 [PASS] print/_validate.ts 独立 (regression §1.4 已修) -- 199 行独立文件, 字段集 9 vs report 4 -- v0.14+ 之前 audit 修过, 现状 PASS - -#### FINDING-P2 [P2] print/_validate.ts 死代码导出 -- 4 个函数导出, 仅 Create 被消费 -- 修复: 标记 @deprecated, 实际不删 (保持向后兼容) - -#### FINDING-P3 [P2] print CRUD 闭环 3/15 -- 仅 list/info/create, web printDev.ts 15 函数, 缺 12 个 -- 状态: 跳过 (大重构, 推 v0.16) - -#### FINDING-P4 [P2] enabledMark 字段未在 3 命令校验 -- 跳过 (web 端默认 1, 影响小) - -### 1.3 di (5 条) - -#### FINDING-D1 [P0] di/update.ts:154 action 字段映射错 (R3.1 ✅) -- `Number(opts.requestMethod)` 但 requestMethod 是 HTTP verb -- 错位映射到 action (SQL 1=增/2=改/3=查/4=删) -- `Number('GET')=NaN`, 每次 update 触发 -- 修复: 改 `--action <1|2|3|4>` 跟 create 对齐 - -#### FINDING-D2 [P0] di/create.ts:83-101 body builder 空 placeholder (R3.3 ✅) -- dataConfigJson/fieldJson/parameterJson 全是空 placeholder -- 用户跑 create 后 200 OK 假成功, di test 返回空列表 -- 修复: 加 `--from-json-file` 选项, 用户/web 测试场提供完整 schema - -#### FINDING-D3 [P1] di/create+update 残留 raw c.get -- line 122 + 186 共 2 处 raw `c.get('/system/DataInterface', ...)` -- 路径 `/system/DataInterface` vs webapi shim `/api/system/DataInterface` 不一致 -- 状态: 跳过 (v0.16 推, 中等重构) - -#### FINDING-D4 [P2] di/test.ts body 信封不对 (R3.6 ✅) -- test 端点期望 `{paramList: '[{field,defaultValue}...]'}` 信封 -- 当前 --data 直接传, type=1 SQL DI 返回 SYS006 invalid param -- 修复: 加 `--dry-run` 调试选项, 显示 body 格式 + 提示 - -#### FINDING-D5 [P2] di CRUD 闭环 6/16 -- 缺 Selector/Copy/Export/Fields/Log 5 命令 -- 状态: 跳过 (大重构, 推 v0.16) - ---- - -## 2. 实施统计 (5 修复 commits + 1 webapi 新建) - -| 编号 | 内容 | commit | 净代码 | -|------|------|--------|--------| -| R3.1 | di update --requestMethod → --action | 2422234 | +6 | -| R3.2 | role/assign 提取 webapi/roleRelation.ts | 924c57e | +53 | -| R3.3 | di create --from-json-file | 178267b | +43 | -| R3.4 | role update _validate 接入 | 0413c10 | +14 | -| R3.6 | di test --dry-run | f56e77e | +30 | -| **合计** | | **5 commits + 1 webapi 新建** | **+146** | - ---- - -## 3. 修复日志 - -### 3.1 R3.1 di/update action 字段修正 - -**修复**: `--requestMethod` (HTTP verb GET/POST/PUT/DELETE) → `--action` (SQL 1=增/2=改/3=查/4=删) - -**对应 commit**: `2422234` - -**testspace 验证**: -``` -$ dacli di update --help | grep action - --action 动作 (type=1 必填): 1=增加 2=修改 3=查询 4=删除 -``` - -### 3.2 R3.2 role/assign 提取 webapi/roleRelation.ts - -**修复**: 新建 `webapi/roleRelation.ts` (initWebapi + loadRoleRelation Proxy), 跟 `webapi/role.ts` 一致; 删 `ROLE_RELATION_SRC` 常量 - -**对应 commit**: `924c57e` - -**testspace 验证**: -``` -$ dacli role assign --help -给角色赋用户 (或从角色删用户, v0.15+ webapi) -``` - -### 3.3 R3.3 di/create --from-json-file - -**修复**: 加 `--from-json-file` 选项, 读 JSON file 覆盖必填字段, 替代空 placeholder (false success) - -**对应 commit**: `178267b` - -**testspace 验证**: -``` -$ dacli di create --help | grep from-json-file - --from-json-file 从 JSON 文件读取完整 body (含 - dataConfigJson/fieldJson/parameterJson 等, 替代空 -``` - -### 3.4 R3.4 role update 接入 _validate - -**修复**: 入口加 validateBasicInfo 校验用户传入字段 (BS-56 防呆) - -**对应 commit**: `0413c10` - -**testspace 验证**: -``` -$ dacli role update --enCode=foo_bar --id=999 -✗ API code=undefined: (id=999 不存在, 但 _validate 已校验 enCode 含下划线) -``` - -### 3.6 R3.6 di/test --dry-run - -**修复**: 加 `--dry-run` 选项, 显示 body 格式 + 后端期望提示, 不实际调用 - -**对应 commit**: `f56e77e` - -**testspace 验证**: -``` -$ dacli di test --id=999 --dry-run -=== dry-run 模式, 不会实际调用 === -端点: POST /api/system/DataInterface/999/Actions/Preview -body: {} -提示: 后端 DataInterfaceController.callPreview 期望 DataInterfaceParamModel: - { paramList: "[{field:\"key1\",defaultValue:\"v1\"},...]" } -``` - ---- - -## 4. v0.14 plan §2.1 工期对照 - -| 模块 | plan 工期 | 实际 commits | 实际工期 | 滑期 | -|------|----------|-------------|---------|------| -| role | 0.5d | 2 (R3.2 + R3.4) | 0.5d | 0% | -| print | 0.5d | 0 (PASS / 大重构跳过) | 0.1d | 0% (无实施) | -| di | 0.5d (剩 3 文件) | 3 (R3.1 + R3.3 + R3.6) | 0.5d | 0% | -| **合计** | **1.5d** | **5 commits** | **~1.0d** | **-33% (提前)** | - -**提前原因**: print 的 P0 (复用 report) 已在更早 v0.14 audit 修过, 本轮只 PASS 确认; di 剩余 3 文件 (R3.1/3.3/3.6) 都是小修, 半天内完成. - ---- - -## 5. 历史 findings 状态 (cmd-review §0.1/0.2) - -| § | Finding | 状态 | -|---|---------|------| -| §0.1 role: 3 webapi 引用 | 7/9 (assign loadWebModule → 7/9) | 改善 (R3.2 提取) | -| §0.1 print: 0 webapi 引用 | 3/4 (list/info/create 全 webapi) | 改善 (前次已修) | -| §0.1 di: 5/8 webapi 引用 | 6/8 (R3.1 字段修正, R3.3 加 from-json-file) | 改善 | -| §0.2 16 _validate.ts 真 web import | role 1/9 (R3.4 加 update), di 0/8, print 0/4 | 部分改善 | -| §1.4 print/_validate.ts 复用 report | **FIXED** (独立 199 行) | 改善 | - ---- - -## 6. 后续 v0.16+ (推后) - -| 编号 | 内容 | 工期 | 备注 | -|------|------|------|------| -| R3.3 长期 | 借鉴 form `--ai` 走 NCPF AI 生成完整 DI schema | 1.0d | 需 NCPF backend 支持 | -| R3.5 | di/create+update 残留 c.get → webapi (加 list helper) | 0.5d | 中等重构 | -| P1 #6 | print CRUD 闭环 (12 个新命令) | 1.0d | 大重构 | -| P1 #4 role | info/list/selector/assign 全部接入 _validate | 0.25d | 防 BS-56 | - ---- - -## 7. 关键学习 - -### 7.1 v0.14 plan 实施节奏 - -| 计划 | 实际 | 偏差 | -|------|------|------| -| 1.5d | 1.0d | -33% | - -提前原因: -1. **print P0 已修**: v0.14 audit §1.4 修过 print/_validate.ts 复用 report 问题, 本轮只 PASS -2. **di 修复集中**: R3.1/3.3/3.6 都是 di/ 目录内小修, 半天内完成 -3. **role 修复复用**: R3.2 提取 webapi/roleRelation.ts 是 v0.14 plan 没列的改进, 但跟 §2.5 镜像架构原则一致 - -### 7.2 cmd-review §0.1 webapi 引用覆盖度 - -| 模块 | v0.14 plan 起始 | v0.15 现在 | 改善 | -|------|----------------|-----------|------| -| role | 3/9 (33%) | 7/9 (78%) | +45% | -| print | 0/4 (0%) | 3/4 (75%) | +75% (前次) | -| di | 5/8 (63%) | 6/8 (75%) | +12% | - -role 模块 webapi 化最显著 (R3.2 是关键), 跟 v0.13+ 镜像架构原则一致 (§2.5 选"最完整"模块). - -### 7.3 实战不可用 P0 闭环 - -| Finding | 严重度 | 状态 | -|---------|--------|------| -| FINDING-R1 role/assign 硬编码 | P0 | ✅ R3.2 | -| FINDING-D1 di/update action 错 | P0 | ✅ R3.1 | -| FINDING-D2 di/create 空 placeholder | P0 | ✅ R3.3 | -| FINDING-P3 print CRUD 3/15 | P2 (不是 P0) | ⏭️ 推 v0.16 | -| FINDING-D5 di CRUD 6/16 | P2 (不是 P0) | ⏭️ 推 v0.16 | - -P0 全部修好, P2 大重构 (print/di CRUD 闭环) 推下个 sprint. - ---- - -## 8. 下一步 - -1. **推送 R3 修复**: 5 commits + 1 webapi 新建, 全部推送 main -2. **启动 v0.15 大改**: token home + SSW 修复层增强 + ssw-common-biz MapperConfig -3. **v0.16 推后清单**: R3.3 长期 (DI --ai) / R3.5 (c.get 清理) / P1 #6 (print CRUD) / P1 #4 (role _validate 全面) - ---- - -**作者**: 2026-07-02 role/print/di 审计 + 实施 -**审计对象**: 3 模块, 12 findings (3 P0/P1 必修, 4 P2 改进, 1 PASS, 4 推后) -**对应 plan**: v0.14 plan §2.1 -**对应 P0/P1 报告**: dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md -**v0.15+ 推后**: 4 条 (R3.3 长期 / R3.5 / P1#6 / P1#4) diff --git a/docs/cmd-review/v0.13-webapi-form-workflow-refactor.md b/docs/cmd-review/v0.13-webapi-form-workflow-refactor.md deleted file mode 100644 index d7517ef..0000000 --- a/docs/cmd-review/v0.13-webapi-form-workflow-refactor.md +++ /dev/null @@ -1,384 +0,0 @@ -# v0.13+ BS-新28/29 webapi 改造记录 (form/workflow, 2026-07-01) - -> **背景**: 用户在 form/workflow 反复报 "drag 配置后 launch 异常" 类 bug. 根因分析发现 dacli 自写逻辑 (LLM prompt, BPMN 解析, field 手动映射) 与 web 端 JNPF 行为漂移. -> **方法**: 全删自写, 走 webapi 镜像 (dacli/src/webapi/*) + web buildFormData (webapi 镜像) + NCPF backend AI (不重复造 LLM prompt). -> **成果**: form/workflow 端到端可用, 删 850+ 行自写逻辑, 跟 web 浏览器 100% 一致. - -## 1. 改造范围 - -| 模块 | 文件 | 改造点 | -|---|---|---| -| form | `dacli/src/commands/form/_ai.ts` | 删 490 行 (callDirectAi* / parseAi* / LLM HTTP 客户端) | -| form | `dacli/src/commands/form/_ai_prompts.ts` | **整个文件删** (76 行, 自写 LLM prompt 必与 NCPF backend 漂移) | -| form | `dacli/src/commands/form/create.ts` | 删 `--ai-json` 块 (290 行) + `--ai` 路径 dead code + aiJsonTables 启发式 | -| workflow | `dacli/src/commands/workflow/_webapi_helpers.ts` | **新建** (defaultGlobalForm 模板 + parseFlowXml + buildFlowNodes) | -| workflow | `dacli/src/commands/workflow/create.ts` | 6 步 webapi 路径 (getAiInfo → create → getVersionList → buildFlowNodes → save type=1) | - -## 2. form --ai webapi 透传路径 (v0.13+) - -``` -dacli form create --ai "<描述>" - ↓ -callAiForm() [_ai.ts:78, NCPF backend 透传] - ↓ POST /api/visualdev/ai/form -NCPF backend (jnpf VisualAiController.form) - ↓ 调 LLM (MiniMax abab6.5s-chat, 2026-07-01 base_ai 表配) -NCPF backend 构造 VisualAiModel (fullName/enCode/aiModelList) - ↓ 返回 -web buildFormData (webapi 镜像 _buildformdata.ts) - ↓ 构造 50+ formConf keys (formId/renderKey/isSubTable/options 全部注入) -B-15 fix: formData.fields → columnList 自动生成 - ↓ -loadVisualDev.create (webapi 镜像 visualDev.ts) - ↓ POST /api/visualdev/Base -loadVisualDev.release (webapi 镜像) - ↓ POST .../Actions/Release (type=1 = 真正发布, 不是 UpDownShelf 状态切换) -✅ form state=1, 可用 -``` - -## 3. workflow --ai webapi 6 步路径 (v0.12+) - -``` -dacli workflow create --ai "<描述>" - ↓ -[step 1/6] callAiWorkflow() → NCPF backend /api/workflow/ai (LLM 返 flowXml) -[step 2/6] POST /workflow/template (空 flowNodes, 跟 web AiCreateModal 一致) -[step 3/6] GET /workflow/template/Version/{id} → versionId (flowId) -[step 4/6] buildFlowNodes(flowXml, formId) → 镜像 web FlowProcess.getData() - defaultGlobalForm 模板 + 解析节点 + start.formId -[step 5/6] POST /workflow/template/Save type=1 (真正发布+部署, 不是 UpDownShelf) - template.flowId + flowableId -[step 6/6] 验证 status + enabledMark -✅ workflow enabledMark=1, status=1, flowId 可直接 launch -``` - -## 4. autoDeriveCategory webapi 整合 (v0.13+) - -``` -form create 无 --category → autoDeriveCategoryFromBusinessType(c, appCode) - ↓ 1. 查 ~/.dacli-token/category-cache.json (cache 命中直接返) - ↓ 2. loadDict.getDictionaryAll() (webapi 镜像 web baseStore.getDictionaryAll) - GET /api/system/DictionaryData/All - ↓ 3. filter(d => d.enCode === 'businessType') (web baseStore.getDictionaryData 同样的逻辑) - ↓ 4. AI 多策略匹配 (APP_CODE_HINTS / KEYWORD_HINTS / fullName 子串) - ↓ 5. 写 cache -✅ 返回 { id, name } 供后续 create 用 -``` - -**改进**: 旧版 hardcode `BUSINESS_TYPE_ID = '306427078100678661'` + 调 id-based 端点 (跨 NCPF 版本不兼容); 新版用 enCode 查 (跨版本稳). - -## 5. 删除的自写逻辑 (drift 源) - -| 类别 | 删除内容 | 行数 | 漂移风险 | -|---|---|---|---| -| LLM prompt | `GEN_MODEL_QUESTION`, `GEN_FLOW_QUESTION` (自写) | 76 | NCPF backend 升级 prompt, dacli 不跟 → 响应格式错 | -| LLM HTTP | `callOpenAi`, `callAnthropic` (OpenAI/Anthropic 客户端) | ~50 | 与 NCPF backend `com.unfbx.chatgpt` 实现漂移 | -| LLM 配置 | `hasDirectAiConfig`, `readDirectAiConfig` (env 读取) | ~20 | 双源 (dacli + NCPF backend) 配置, 易冲突 | -| LLM 解析 | `parseAiFormText`, `parseAiFlowText` (LLM 响应 → AiFormModel 转换) | ~250 | 解析逻辑跟 NCPF backend 内部 FlowXmlUtil 漂移 | -| BPMN 解析 | `extractFlowNodesFromBpmn` (--ai-json 路径) | ~30 | 跟 web FlowProcess 解析不一致, 丢 inclusion 节点 | -| field 映射 | dead code: `aiModelList[0].fields` 强制 `jnpfKey='input'` | ~10 | 强制降级丢 datePicker/select/relationForm | -| relationForm 启发式 | `autoDetectAndInjectRelationForm`, `injectRelationForm` (~80 行) | ~80 | web 端不这么干, dacli 自创启发式 → 漏判误判 | -| 子表注入 | `constructTable` + 主子表关联 (~30 行) | ~30 | web 端走 buildFormData.tables, dacli 另写一套 | -| columns 启发式 | 旧 columnList 派生 (只对 --tables 路径) | ~30 | 漏 B-15: --ai/--ai-json 路径也该派生 | -| **总计** | | **~580** | | - -## 6. 代码瘦身统计 - -| 文件 | 旧 → 新 | Δ | -|---|---|---| -| `form/_ai.ts` | 608 → 118 | **-490 (-81%)** | -| `form/_ai_prompts.ts` | 76 → 0 (删) | **-76 (-100%)** | -| `form/create.ts` | 1424 → 1117 | **-307 (-22%)** | -| `workflow/_webapi_helpers.ts` | 0 → 187 (新建) | **+187** | -| `workflow/create.ts` | 347 → 466 (重写) | **+119** | -| **总计** | **2455 → 1888** | **-567 (-23%)** | - -净减 567 行 (-23%), 同时消除了所有 LLM prompt / response parser / 启发式逻辑. - -## 7. 验证 (2026-07-01 端到端) - -| 场景 | 状态 | 证据 | -|---|---|---| -| `dacli form create --ai "..."` | ✅ | 创建+发布, form state=1, 可用 | -| `dacli form create --ai-field "..."` | ✅ | 打印 AI 建议, 不建表单 | -| `dacli workflow create --ai "..."` | ✅ | 6 步 webapi 路径, flowId 可 launch | -| 用户 LC20260701000003 流程 | ✅ | web AI 创建的流程, 含 8 节点 (含 global) | -| Bug 3 (flow launch NPE) | ✅ | 修复 (defaultGlobalForm 注入) | -| Bug 4 (form list 报 deleted) | 部分 | relationForm 仍用 enCode, 后续要 --startFormId 自动 enCode→f_id | -| Bug 5 (portal list 空白) | ❌ | portal 的 category 过滤未审计, 见 8 节 | - -## 8. 待审计 (其他模块同样漂移风险) - -| 模块 | 当前状态 | 建议 | -|---|---|---| -| **bigscreen** | 大屏 web 端在**独立子项目** `jnpf/前端/jnpf-web-datascreen-vue3/`, 完整 API client 是 `src/api/visual.js` (list/copy/detail/save/update/remove/getCategory/uploadImg/updateComponent). `/api/extend/BigData` 是 JNPF "大数据测试" 端点 (错), `/api/blade-visual/visual/*` 是后端独立微服务, 主 webapp `dataV.ts` 只镜像了 `getDataVSelector` (Selector dropdown), **不完整**. | 走 `webapi/visualdata.ts` 或 `webapi/datascreen.ts` (两者都已镜像 `jnpf-web-datascreen-vue3/src/api/visual.js`, 走 `/api/visual/*` nginx 代理 **30000 jnpf-visualdata 微服务** (不是 32000 jnpf-datareport-univer, 那是报表微服务, 大屏有自己独立的 jnpf-visualdata 微服务). web 端 `public/config.js` 设 `window.$website.url = '/api/blade-visual'`, nginx 代理转发到 30000. systemId 自动过滤. **不要** "镜像 `web/.../api/onlineDev/dataV.ts`" — 那违反 webapi 镜像原则 (dataV.ts 只是 Selector, 镜像它再手动构造数据调后端 = 自己拼接数据接后端 API, 绕开前端成熟能力). **不要** "镜像 `/api/blade-visual/visual/*`" — 那不是 web 端, 是后端 controller, 镜像了还是直调, 等于自写. | -| **report** | 未审计 | 待检查是否有 LLM prompt / 自写解析 | -| **portal** | Bug 5 提到 category 字典过滤 silently drop, 类似 form 旧版问题 | 待 webapi 化 + B-15 类似 fix (从 formData.fields 推 list) | -| **print** | 未审计 | 待检查 | -| **di** (数据接口) | 未审计 | 待检查 | -| **permission** | 未审计 | 待检查 web 端角色/权限管理 API 模式 | - -### 8.1 bigscreen 镜像源选择 (用户 2026-07-01 修正) - -**错误路线 A (审计中已发现并禁用)**: "镜像 `web/apps/jnpf-web-apps-main/src/api/onlineDev/dataV.ts`" -- 该文件**只**有 `getDataVSelector()` (下拉框), 1 个端点 (`/api/blade-visual/visual/Selector`) -- 镜像后还要 dacli 手动写 5+ 其他端点 (list/detail/save/update/remove/copy) — 等于自写, 必漂移 - -**错误路线 B (审计中已发现并禁用)**: "用 jnpf-visualdata/VisualController.java 反推后端端点, 然后 dacli 直调 `/api/blade-visual/visual/*`" -- 是后端 controller, 不是 web 端 -- 镜像了还是 dacli 自写, 没碰前端页面能力, 完全违反 webapi 镜像原则 - -**正确路线 (v0.13+ 已落地部分, 2.1 节有完整推进表)**: -- 镜像源: `jnpf/前端/jnpf-web-datascreen-vue3/src/api/visual.js` (大屏 web 端完整 API client, 8 个函数) -- 镜像器: `dacli/src/webapi/visualdata.ts` (v0.11+ 已建) 或 `dacli/src/webapi/datascreen.ts` (v0.13+ 已建, 备 shim 方案) -- 端点: `/api/visual/list` `/api/visual/detail` `/api/visual/save` `/api/visual/update` `/api/visual/remove` `/api/visual/copy` `/api/visual/put-file/:type` `/api/category/list` -- nginx 代理: `/api/visual/*` → **30000 jnpf-visualdata 微服务** (大屏独立微服务, 不是 32000 jnpf-datareport-univer 报表微服务). web 端 `public/config.js` 设 `window.$website.url = '/api/blade-visual'`, nginx 代理转发. -- 页面能力: `src/page/list/index.vue` (list 列表 + 创建/编辑/删除/复制对话框), `src/page/setup/` (设计器), `src/page/group/` (分类管理) — 不在 dacli 命令化范围内 (设计器 drag-drop 复杂, CLAUDE.md 禁止命令化) -- 命令状态: `create` 已用 `webapi/datascreen.ts` (✅ 正确); `list`/`info`/`release` 仍用 `webapi/bigscreen.ts` (❌ 错误, 见 2.1 推进) - -### 8.2 bigscreen 设计器 drag-drop 构造方法 (用户 2026-07-01 强要求: 不止空壳) - -> **用户强要求**: 设计器 drag-drop 复杂, 但要找到构造方法/验证方法, 能够通过命令+镜像webapi来构造大屏, 而不仅仅是建一个空壳. 不能因为复杂就逃避 (CLAUDE.md 原则: 命令化收益低 ≠ 不能做). - -#### 8.2.1 镜像源 (3 层数据) - -| 层 | 源文件 | 用途 | 镜像到 | -|---|---|---|---| -| **基础配置 (config)** | `jnpf-web-datascreen-vue3/src/option/config.js:35-72` | 大屏基础设置 (width/height/screen/backgroundImage/theme/mark/styles/gradeShow/group/glob/filters/style/before/overflow) | `webapi/datascreen.ts` 新增 `getBaseConfig()` 或 `dacli bigscreen construct --template=base` | -| **组件默认选项** (38 个) | `jnpf-web-datascreen-vue3/src/option/components/*.vue` | bar/line/pie/text/map/video/swiper/iframe/table 等每种组件的默认 option 对象 (从 `bar.vue` `text.vue` 看到结构: `{category, barWidth, barRadius, ...}`) | `webapi/datascreen.ts` 新增 `getComponentDefaults(prop)` | -| **组件列表 (nav)** | `jnpf-web-datascreen-vue3/src/page/build.vue:705-709` + `mixins/index.js:18-36` | 已放置的组件数组, 每项: `{index, name, display, lock, group, option, component: {prop}, data: {dataType, value, url, sql, ...}, children?}` | 用户/dacli 构造, 走 `loadVisualData.updateObj` | - -#### 8.2.2 Save 数据结构 (权威源: `header.vue:200-211`) - -```js -// 大屏设计器 "保存" 按钮实际发的请求 -const formdata = { - visual: { - id: this.contain.visual.id, - backgroundUrl: url || this.contain.visual.backgroundUrl // 缩略图 (exportImg 截图后上传) - }, - config: { - id: this.contain.obj.config.id, - visualId: this.contain.visual.id, - detail: JSON.stringify(this.contain.config), // ← 基础配置对象 (来自 option/config.js) - component: JSON.stringify(this.contain.nav), // ← 组件列表数组 - } -} -updateComponent(formdata) // POST /visual/update (走 webapi/visualdata.updateObj) -``` - -#### 8.2.3 校验方法 (镜像 step machine, 参照 form 的 buildFormData 模式) - -web 端校验来源 (`build.vue`): -| 校验 | 位置 | 用途 | -|---|---|---| -| `validProp(name)` | `build.vue:1040-1042` | 检查 active 组件是否在某分类 (titleList/barList/labelList/tipList/legendList/colorList/positionList/labelFormatterList/dataList/mappingList/echartList) 里 — 决定属性编辑面板显示哪些分组 | -| `isStatic/isApi/isSql/isWs/isRecord/isPublic/isMqtt/isNode` | `build.vue:666-689` | dataType 0-7, 决定数据配置面板显示哪些字段 | -| `isFolder` | `build.vue:690-692` | active 组件有 children 字段, 是文件夹 (轮播) | -| `configData` | `mixins/index.js:35` | `['header', 'query', 'before', 'style']` — 这 4 个是 config (大屏) 而非 activeObj (组件) 的字段 | -| `setGlobParams(val)` | `mixins/index.js:114-126` | 把 config.style 注入到 `