BossAgents BossAgents

智能体表演小程序 · 五大业务功能接口对接文档

👤 BossAgents 团队 📅 2026-08-30 👁️ 阅读 22 👍 点赞 0 ☕ 58 分钟阅读

智能体表演小程序 · 五大业务功能接口对接文档

读者对象：在小程序端实现功能的前端同学（秒哒），本地无后端代码，只需按本文档调用后端已部署好的 HTTP 接口。

后端地址：由小程序 src/api/request.js 统一注入（开发/生产环境 baseURL 已配好），前端只需写相对路径 /api/...。

鉴权：除明确标注 skipAuth 的登录接口外，所有接口都需要在请求头带 Authorization: Bearer 。src/api/request.js 已自动处理登录换 token、token 失效重试，你直接调封装好的 api 即可，不用自己管鉴权。

统一响应结构：{ success: true/false, status: 200, data: {...}, message: null, timestamp: "..." }。错误时 success:false 且 message 有文案。

总览：五个功能 → 对应接口

#业务功能核心接口前端入口页面
①PLM 产品 → 商品 → 上架/api/miniapp/gst/productSource/*pkg/gst/mall/productSource.vue
②BOM 变更影响分析（ECharts 力导向图）POST /api/change/analyzepkg/misc/bom-impact/index.vue
③采购比价 + 老板真实确认/api/purchase-order/subpackages/procurement/ + subpackages/approval/*
④海报工厂（真实出图）POST /api/content/generate-posterpkg/asset/poster-generate.vue
⑤开放平台（对外 API 接入）/api/open/*（需 API Key）通常为外部开发者使用，小程序端一般只做"我的 Key 管理"

① PLM 产品 → 商品 → 上架（商品来源管理）

前缀：所有接口都以 /api/miniapp/gst 开头（小程序专属网关，已直连本地后端，不转发外部）。

1.1 同步 PLM 产品

POST /api/miniapp/gst/productSource/syncFromPlm
Body: {}（可选 { clear: false }）

返回：{ success, data: { synced, updated, created, items: [...] } }

说明：从 114 的 SCSAI(PLM) 拉取 Part 写入本地产品表。演示数据已存在，可不调也能看到列表。

1.2 产品列表（PLM 同步来的"产品"）

GET /api/miniapp/gst/productSource/list?limit=20&offset=0

返回：{ success, data: { list: [{ id, name, plmItemNumber, classifyName, description, images, status, locked }], total } }

1.3 产品转商品（上架引导）

POST /api/miniapp/gst/productSource/convert
Body: { id: "<产品id>", goodsName: "上架后的商品名", status: "on_sale" | "off_shelf", price, stock, ... }

返回：{ success, data: { goodsId, ... } }

说明：把 PLM 产品生成到商城商品表 gst_product，直接可上架。

1.4 商品列表 / 上架 / 下架 / 改价

GET  /api/miniapp/gst/productSource/goods/list?limit=20
POST /api/miniapp/gst/productSource/goods/upsert      Body: { id?, name, price, stock, status, coverImage, ... }
DEL  /api/miniapp/gst/productSource/goods/{id}

status 取值：on_sale（上架）/ off_shelf（下架）。

1.5 AI 生成商品图 / 海报 / 轮播图（可选，增强展示）

POST /api/miniapp/gst/productSource/aiGenerate   Body: { id, prompt, type: "cover"|"poster"|"carousel" }
POST /api/miniapp/gst/productSource/saveImages   Body: { id, images: [...] }

前端封装：src/api/gst/url.js 的 gstApi.productSourceList / productSourceSync / productSourceConvert / productSourceGoodsList / productSourceGoodsUpsert。直接 import { gstApi } from '@/api/gst/url' 调用即可。

演示串法：列表页每个产品有「转商品」→ 填商品名+上架状态 → 生成商品 → 商品页可上架/下架/改价/AI 出图。

② BOM 变更影响分析（ECharts 力导向图）

核心接口：

POST /api/change/analyze
Content-Type: application/json
Body: {
  "description": "P-1001精密转轴材料从42CrMo4升级为18CrNiMo7-6",  // 必填，变更描述（自然语言）
  "change_type": "part" | "product" | "model" | "bom" | "process" | "auto",  // 可选，默认 auto 自动识别
  "target_id": "P-1001"   // 可选，PLM 上的 Part id；不填则尝试从描述里抽编号反查
}

返回（真实数据）：

{
  "success": true,
  "data": {
    "change_type": "part",
    "description": "...",
    "affectedProducts":  [ { "id": "...", "name": "..." } ],
    "affectedModels":    [ { "id": "...", "name": "..." } ],
    "affectedParts":     [ { "id": "...", "name": "...", "item_number": "..." } ],
    "affectedBoms":      [ { "id": "...", "name": "..." } ],
    "affectedProcesses": [ { "id": "...", "name": "..." } ],
    "impactChain": [               // 影响链路，用于画层级
      { "level": 0, "type": "part",  "name": "...", "id": "..." },
      { "level": 1, "type": "BOM",   "name": "...", "id": "..." },
      { "level": 2, "type": "model", "name": "...", "id": "..." }
    ],
    "severity": "High" | "Medium" | "Low",
    "totalAffected": 7,
    "message": "..."     // SCSAI 不可达时会有明确提示文案
  }
}

前端怎么渲染成 ECharts 图

小程序已内置 src/utils/forceGraph.js，提供两个函数：

  • buildGraph(res)：把上面的 res.data 转成 { nodes: [{id,name,category,value}], links: [{source,target}] }
  • toEChartsOption(graph)：生成标准 ECharts series: [{ type:'graph', layout:'force', force:{ repulsion, edgeLength, gravity } }] 的 option，直接 setOption 即可（网页端和小程序复用同一份逻辑）。

前端封装：src/api/change.js 的 changeApi.analyze(params)。

演示串法：输入变更描述（如文档例子"P-1001 精密转轴材料升级"）→ 调 analyze → forceGraph 渲染影响图 + 统计卡片（受影响零件/ BOM 数、严重度）+ 受影响对象清单。

注意：

  • 必须 SCSAI(PLM) 可达（114 已连通）才返回真实影响；不可达时 success:true 但 affected* 全空、message 提示"SCSAI 不可达"。前端应展示该提示而非报错。
  • impactChain 为空数组也属正常（未提供 target_id 时走预分析）。

③ 采购比价 + 老板真实确认

前缀：/api/purchase-order/*。状态机：pending_approval → approved → confirmed → completed（或任意非终态 → cancelled）。

3.1 采购订单列表（看板）

GET /api/purchase-order/list?status=pending_approval&limit=20&offset=0

可选 status：pending_approval | approved | confirmed | completed | cancelled（不传返回全部，按 created_at 倒序）。

返回：{ success, data: { total, items: [{ po_id, title, supplier_name, items:[{name,quantity,unit_price}], total_amount, status, priority, requested_by, approved_by, created_at }] } }

3.2 采购订单详情

GET /api/purchase-order/{po_id}

返回完整 PO 对象（含 items、各状态时间戳）。

3.3 老板审批（pending_approval → approved）

POST /api/purchase-order/{po_id}/approve
Body: { "approved_by": "boss" }    // 审批人，可空

3.4 老板确认（approved → confirmed）★ 这是"真确认"

POST /api/purchase-order/{po_id}/confirm
Body: {}

真实写库：后端 UPDATE purchase_orders SET status='confirmed'。状态不对会报错（如已是 confirmed 再 confirm 会 500 提示"当前状态 confirmed 不可确认"）。

3.5 完成 / 取消

POST /api/purchase-order/{po_id}/complete   Body: {}
POST /api/purchase-order/{po_id}/cancel     Body: { "reason": "..." }

3.6 创建采购单（可选）

POST /api/purchase-order/create
Body: { title, supplier_id, supplier_name, items:[{name,quantity,unit_price}], currency, priority, requested_by, notes }

前端封装：src/api/purchase.js：getPOs / getPO / approvePO / confirmPO / completePO / cancelPO / createPO，外加 PO_STATUS_MAP（状态中文）、PO_BOARD_TABS（看板四个 tab：待审批/进行中/已完成/历史）。

真实链路说明：真实环境里"发询价→收供应商报价邮件(IMAP)→人工确认"由后端 procurement-workflow 自动跑；小程序端负责展示 + 老板在 UI 上点"审批/确认"，点确认即真实驱动状态机。

已知坑（已修复）：PO 演示数据归属 enterprise_id='default'，真实企业租户登录时列表查询已做兼容（自动包含 default 演示数据），小程序端直接调 getPOs() 即可看到演示单，无需特殊处理。

④ 海报工厂（真实 AI 出图文案 + 二维码）

4.1 生成海报文案（真实 LLM）

POST /api/content/generate-poster
Content-Type: application/json
Body: {
  "productName": "必填，产品名",
  "keywords":   ["卖点1","卖点2"],     // 或 features
  "features":   ["卖点1","卖点2"],
  "style":      "promotional" | "professional" | "minimal",  // 默认 promotional
  "targetAudience": "潜在客户",
  "language":   "zh-CN"
}

返回：

{
  "success": true,
  "data": {
    "title": "主标题(8-15字)",
    "subtitle": "副标题",
    "taglines": ["标语1","标语2","标语3"],
    "features": ["卖点1","卖点2","卖点3","卖点4"],
    "callToAction": "行动号召",
    "colorScheme": { "primary":"#xxxxxx", "secondary":"#xxxxxx", "background":"#xxxxxx", "text":"#xxxxxx" },
    "layoutHint": "center-headline | left-image | card-grid",
    "style": "promotional",
    "generatedAt": "2026-..."
  }
}

若 LLM 不可用，generatePosterData 会回退到模板文案（title 用 产品名+新品发布，固定配色），前端不会崩。

4.2 生成二维码

POST /api/content/generate-poster-qrcode
Body: { "content": "https://..." }    // 二维码内容，必填

返回：{ success, data: { qrDataUrl: "data:image/png;base64,..." } } —— 注意这是 base64 dataURL，小程序 直接能显示。

前端封装：src/api/content.js 的 generatePoster / generatePosterQrcode。

演示串法：填产品名+卖点 → 调生成 → 拿到文案+配色 → 用 canvas 或 image 组件渲染成海报图，再用二维码接口生成购买/落地页二维码贴上去。

⑤ 开放平台（对外 API 接入，需 API Key）

这部分通常不是小程序前端功能，而是给外部开发者调我们后端的鉴权体系。若小程序要做"我的开放 Key 管理"页，调以下接口（均需 x-api-key: ba_xxx 或 Authorization: Bearer ba_xxx）。

5.1 创建 Key

POST /api/open/keys
Header: x-api-key: ba_admin_xxx   （管理员 Key）
Body: { name, scopes: ["content:generate","plm:read"], expireDays }

5.2 查看 Key / 用量

GET /api/open/keys
GET /api/open/usage?key_id=xxx

5.3 用 Key 调业务（示例）

POST /api/goai-demo/...   或   /api/agents/...
Header: x-api-key: ba_xxx

后端 open-platform 中间件会校验 Key 有效性、记录用量、按 scope 鉴权。

文档页：GET /api/open/docs 返回 API 文档（目前该路由存在但文档内容未生成，返回 404 页面；如需对外部开发者开放，需后端补文档页）。

给秒哒的建议：⑤ 一般不进小程序演示。若老板要看"开放平台大屏"，用 /api/open/usage 拉调用量做排行榜即可，鉴权用管理员 Key（后端同学给你）。

通用注意事项（给前端实现）

  1. baseURL 不用管：所有路径写相对 /api/...，src/api/request.js 已配环境地址 + 自动登录 + token 刷新。
  2. 超时：默认请求超时 15s；BOM 分析、海报生成可能慢（调 LLM/PLM），页面要加 loading。
  3. SCSAI 依赖：① 同步、② 影响分析都依赖 114 的 PLM。不可达时接口返回 success:true 但数据空+message 提示，前端务必展示 message，不要当报错。
  4. ECharts 组件：② 用 forceGraph.js 的 toEChartsOption，不要自己写图配置；若小程序环境没引 echarts，用 buildGraph 拿 {nodes,links} 后用任意力导向图组件渲染。
  5. 状态机顺序：③ 确认/审批有严格先后顺序，前端按钮按 PO_STATUS_MAP 和当前 status 决定可点哪些。
  6. 租户：①② 走 miniapp 专属路由，不受租户限制；③ 已做 default 演示数据兼容，直接调即可。

后端已实现清单（供核对，秒哒无需改后端）

  • ✅ /api/miniapp/gst/productSource/{list,syncFromPlm,convert,goods/list,goods/upsert} —— ①
  • ✅ POST /api/change/analyze（含 where-used / propagate 子能力）—— ②
  • ✅ /api/purchase-order/{list,create,{id}, {id}/approve|confirm|complete|cancel} —— ③
  • ✅ POST /api/content/generate-poster + generate-poster-qrcode —— ④
  • ✅ /api/open/*（需 Key）—— ⑤
  • ✅ src/utils/forceGraph.js（ECharts 力导向图）、src/api/{gst/url,change,purchase,content}.js（前端封装）
← 返回案例列表
分享：
🤖 Try Now →
🤖
🎁