Files
dacli/docs/cmd-review/integration.md
T
sswandClaude b9c9e318af feat(v0.11+): Phase 1 - 23 个 dacli 父命令审计完成
派 25 个 Explore 子代理 (5 批 × 5) 审计 23 个父命令.
产出 cmd-review/{cmd}.md (24 文件) + _summary.md.

关键发现:
- webapi 镜像使用率 < 30% (12+ 父命令 100% 绕 webapi)
- 30+ P0 必补新命令 (form update, log exception, di CRUD, role authorize 等)
- 3 处 P0 端点错误 (假 PASS):
  * integration emailTest/smsTest
  * msg templateCreate
- 用户关键修正: bigscreen → jnpf-web-datascreen-vue3 (独立子项目)
- 用户关键修正: report → jnpf-web-datareport (独立子项目)

下一步: Phase 2 按 P0 优先级执行 (修端点 + 新命令 + webapi 化)

Co-Authored-By: Claude <[email protected]>
2026-06-25 14:58:32 +08:00

7.2 KiB
Raw Blame History

Integration 父命令审计报告 (v0.11+)

1. 命令清单

dacli integration emailTest --configId=<id> [--email=<e>]          — 邮件测试发送 (走 SendMessageConfig/testSendConfig)
dacli integration smsTest --templateId=<id> [--phone=<n>]            — 短信测试发送 (走 SmsTemplate/testSent, 决策 8)
dacli integration webhookTest --url=<u> [--payload=<json>]           — Webhook 测试发送 (走 SendMessageConfig/testSendConfig, channel=webhook)

当前实现:

  • index.ts (P2 收尾) 仅作为父命令注册容器
  • 3 个 test 子命令均通过硬编码端点调用 JNPF API
  • 未走 webapi 镜像架构 (dataModel/dataSource/dict/menu/visualDev/workflow 已有)

2. Web 端对应

集成中心目录结构

  • /web/apps/jnpf-web-apps-main/src/views/integrationCenter/
    • email/ (Form.vue + Test.vue + index.vue) — 邮件账号配置
    • sms/ (Form.vue + index.vue) — 短信配置
    • webhook/ (Form.vue + index.vue) — Webhook 配置
    • dingTalk/ weChatMp/ weCom/ aiModelConfig/ (其他集成,dacli 未覆盖)

消息 API 端点

  • /api/message/Notice/* — 系统公告 CRUD (web/.../api/system/message.ts:4)
  • /api/message/{id} — 消息读取/删除/标记已读
  • /api/message/AccountConfig — 账号配置核心 (web/.../api/msgCenter/accountConfig.ts:4)
    • GET / 分页列表
    • POST / 创建
    • PUT /:id 更新
    • GET /:id 详情
    • DELETE /:id 删除
    • POST /:id/Actions/Copy 复制
    • POST /:testType 测试 (testType = testSendMail / testSendSms / testSendWebhook)
  • /api/message/SendMessageConfig — 发送配置 (web/.../api/msgCenter/sendConfig.ts:4)
    • 8 个端点,含 testSendConfig 和 getSendConfigList (下拉)

Web 测试逻辑 (integrationCenter/email/Test.vue)

  • 接收 dataForm (含 smtp 服务器、端口、用户、密码等)
  • UI 采集: testSendEmail (收件人), testEmailTitle, testEmailContent
  • 真实端点: POST /api/message/AccountConfig/testSendMail
  • 当前 dacli 错误地用了 /message/SendMessageConfig/testSendConfig

3. 改/删/留 建议

[DEPRECATE] integration emailTest

  • 理由:API 端点错误。当前 dacli 调用 /message/SendMessageConfig/testSendConfig 但 web 端用 /message/AccountConfig/testSendMail。
  • 影响:调用成功但实际功能不匹配 (SendMessageConfig 是发送配置,不是账号配置)。
  • 建议:标记 @deprecated,下版本删除或重写。

[DEPRECATE] integration smsTest

  • 理由:API 端点模糊。web 端 sms 测试应在 /message/AccountConfig/testSendSms,dacli 当前用 /system/SmsTemplate/testSent。
  • 影响:与 web 端逻辑不一致,AI 难以判断真实流程。
  • 建议:标记 @deprecated,统一改用 AccountConfig 测试端点。

[KEEP-REFACTOR] integration webhookTest

  • 理由:通道对应清晰 (channel=webhook),但应改用 AccountConfig 路径。
  • 建议:保留但重写,下版本走 /message/AccountConfig/testSendWebhook。

[REFACTOR-WEBAPI] 新增 src/webapi/integration.ts

  • 理由:v0.11+ webapi 镜像架构要求。dacli 应直接 import web/.../api/msgCenter/accountConfig.ts 复用 web 端真实 API。
  • 目标:
    • 镜像 accountConfig.ts 的 8 个函数 (list/create/update/info/del/copy/testConfig)
    • 镜像 sendConfig.ts 的 8 个函数
  • 收益:零参数错误、零端点错误、与 web 100% 一致。

[NEW-CMD] integration configList

  • 理由:当前 test 命令硬编码 configId,AI 无法选择可用配置。
  • 建议:dacli integration configList [--type=email|sms|webhook] 列已有配置。
  • 价值:AI 在测试前可先 list 获取真实 ID。

[NEW-CMD] integration configCreate

  • 理由:web 端有完整的 CRUD,但 dacli 只暴露测试,AI 无法创建新配置。
  • 建议:dacli integration configCreate --type=email --fullName=... --enCode=... --smtpServer=...。
  • 关键参数 (email 举例):fullName, enCode, smtpServer, smtpPort, smtpUser, smtpPassword, addressorName, enabledMark。
  • 价值:补齐 CRUD 闭环。

[NEW-CMD] integration configGet

  • 理由:当前 configId 来源不明确。
  • 建议:dacli integration configGet --id=<id> 获取详情 JSON,便于 AI 验证参数。

[NEW-CMD] integration configUpdate

  • 理由:CRUD 闭环必需。
  • 建议:dacli integration configUpdate --id=<id> --field=value 支持部分更新。

[NEW-CMD] integration configDelete

  • 理由:CRUD 闭环必需。
  • 建议:dacli integration configDelete --id=<id>。

[NEW-CMD] integration log

  • 理由:web 端有 msgMonitor.ts (发送日志),AI 调试时需查询发送历史。
  • 建议:dacli integration log [--configId=<id>] [--startTime=...] [--endTime=...]。
  • API 对应:/api/message/MessageMonitor/* (JNPF 后端已有)。

[NEW-CMD] integration selector

  • 理由:表单设计器中需选择消息配置 (如触发邮件)。
  • 建议:dacli integration selector --type=email 返回下拉列表 (复用 SendMessageConfig/getSendConfigList)。

4. AI 痛点评估

痛点 A:API 端点错误

  • 现状:3 个 test 命令调用了错误的端点 (SendMessageConfig vs AccountConfig)。
  • 根因:手动拼接 URL 而非走 webapi 镜像。
  • 影响:AI 调用成功但实际数据未生效,调试时困惑。
  • 修复:v0.11+ 强制 webapi 镜像。

痛点 B:CRUD 残缺

  • 现状:仅 3 个 test 命令,无 list/create/get/update/delete。
  • 根因:v0.8 草草上线 "P2 收尾",未与 web 端 CRUD 对齐。
  • 影响:AI 无法独立管理消息配置,只能依赖 web UI。
  • 修复:新增 5 个 config* 命令。

痛点 C:业务闭环断裂

  • 现状:表单提交 → 触发邮件?流程未连通。
  • 根因:form 模块无 message 配置关联,integration 模块无 form 联动。
  • 影响:AI 无法搭建 "表单提交 → 发送邮件" 的完整业务闭环。
  • 建议:
    • dacli form bindMessage --formId=X --trigger=submit --configId=Y
    • 或在 dacli integration log 中按 form 字段过滤。

痛点 D:日志查询困难

  • 现状:无 log 命令,AI 无法验证邮件是否发送成功。
  • 根因:未集成 msgMonitor API。
  • 修复:新增 integration log。

痛点 E:决策 8 标注混乱

  • 现状:仅 smstest.ts 有 decision 8 标注,email/webhook 无。
  • 影响:AI 难以理解为何短信用 SmsTemplate,邮件用 SendMessageConfig。
  • 修复:统一走 AccountConfig 路径,删除决策 8 备注。

总结

类型 数量 优先级
DEPRECATE 2 (emailTest, smsTest) P0 (端点错误)
REFACTOR-WEBAPI 1 (webapi/integration.ts) P0 (架构升级)
NEW-CMD 5 (configList, configCreate, configGet, configUpdate, configDelete, log, selector) P1 (功能补齐)
KEEP 1 (webhookTest, 需重写) P1 (API 统一)

核心建议:

  1. 立即:emailTest/smsTest 标记 @deprecated (端点错误误导 AI)
  2. v0.11+:新增 src/webapi/integration.ts 镜像 accountConfig + sendConfig
  3. v0.12+:补齐 config CRUD + log + selector 命令,形成完整业务闭环