Agent Performance Mini Program · Five Major Business Function Interface Integration Documentation

Target Audience: Front-end developers (Miada) implementing features on the mini program side. No local backend code is required; simply call the pre-deployed HTTP interfaces as per this document.

Backend Address: Uniformly injected by the mini program's src/api/request.js (baseURL for dev/prod environments is pre-configured). Front-end only needs to write relative paths like /api/....

Authentication: All interfaces require the request header `Authorization: Bearer `, except for login interfaces explicitly marked with skipAuth. src/api/request.js automatically handles login/token exchange and token expiration retries. You can directly call the encapsulated API without managing authentication yourself.

Uniform Response Structure: `{ success: true/false, status: 200, data: {...}, message: null, timestamp: "..." }`. On error, `success: false` and `message` contains descriptive text.

Overview: Five Functions → Corresponding Interfaces

① PLM Product → SKU → Listing (Product Source Management)

Prefix: All interfaces start with /api/miniapp/gst (mini-program exclusive gateway, directly connected to the local backend, no external forwarding).

1.1 Synchronize PLM Products

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

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

Description: Pull Parts from 114's SCSAI(PLM) and write them into the local product table. Demo data already exists; you can see the list without calling this.

1.2 Product List (Products synchronized from 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 Convert Product to Merchandise (Listing Guide)

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

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

Description: Generate PLM products into the mall merchandise table gst_product, ready for listing directly.

1.4 Merchandise List / List / Delist / Price Change

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-Generated Merchandise Images / Posters / Carousel Images (Optional, for enhanced display)

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' 调用即可。

Demo Flow: Each product on the list page has 'Convert to Merchandise' → Fill in merchandise name and listing status → Generate merchandise → On the merchandise page, you can list/delist/change price/AI generate images.

② BOM Change Impact Analysis (ECharts Force-Directed Graph)

Core Interfaces:

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): Convert the above res.data into { nodes: [{id,name,category,value}], links: [{source,target}] }
• toEChartsOption(graph): Generate a standard ECharts option with series: [{ type:'graph', layout:'force', force:{ repulsion, edgeLength, gravity } }], which can be directly setOption (reusing the same logic for web and mini-program).

Frontend encapsulation: changeApi.analyze(params) in src/api/change.js.

Demo flow: Input a change description (e.g., the document example "P-1001 precision shaft material upgrade") → call analyze → forceGraph renders the impact graph + statistics cards (affected parts/BOM count, severity) + affected object list.

Note:

• Real impact is only returned if SCSAI(PLM) is reachable (114 is connected); if unreachable, success:true but affected* fields are empty, with a message indicating "SCSAI unreachable". The frontend should display this prompt, not an error.
• An empty impactChain array is normal (pre-analysis when no target_id is provided).

③ Procurement price comparison + real boss confirmation

Prefix: /api/purchase-order/*. State machine: pending_approval → approved → confirmed → completed (or any non-terminal state → cancelled).

3.1 Purchase Order List (Kanban)

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

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

Response: { 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 Purchase Order Details

GET /api/purchase-order/{po_id}

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

3.3 Boss Approval (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 Complete / Cancel

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：待审批/进行中/已完成/历史）。

Real Workflow Explanation: In the real environment, the process "send RFQ → receive supplier quotation emails (IMAP) → manual confirmation" is automatically executed by the backend procurement-workflow; the mini-program is responsible for display + the boss clicking "Approve/Confirm" in the UI, which actually drives the state machine.

Known Issue (Fixed): The demo PO data belongs to enterprise_id='default'. When a real enterprise tenant logs in, the list query is already compatible (automatically includes default demo data). The mini-program can directly call getPOs() to see demo orders without special handling.

④ Poster Factory (Real AI-generated graphic copy + QR code)

4.1 Generate Poster Copy (Real 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 Generate QR Code

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

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

Frontend encapsulation: generatePoster / generatePosterQrcode in src/api/content.js.

Demo flow: Fill in product name + selling points → call generate → get copy + color scheme → render into a poster image using canvas or image component, then call the QR code interface to generate a purchase/landing page QR code and overlay it.

⑤ Open Platform (External API access, requires API Key)

This part is typically not a mini-program frontend feature, but rather an authentication system for external developers calling our backend. If the mini-program needs a "My Open Key Management" page, call the following interfaces (all require x-api-key: ba_xxx or Authorization: Bearer ba_xxx).

5.1 Create 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 鉴权。

Documentation page: GET /api/open/docs returns API documentation (currently this route exists but the documentation content is not generated, returning a 404 page; if it needs to be opened to external developers, the backend needs to supplement the documentation page).

Suggestion for Miaoda: ⑤ is generally not included in the mini-program demo. If the boss wants to see the "Open Platform Dashboard", use /api/open/usage to fetch call volume for a leaderboard; use an administrator Key for authentication (backend colleagues will provide it to you).

General Notes (for Frontend Implementation)

1. Ignore baseURL: Write all paths relative to /api/..., as src/api/request.js is already configured with environment address + auto-login + token refresh.
2. Timeout: Default request timeout is 15s; BOM analysis and poster generation may be slow (calling LLM/PLM), so add loading on the page.
3. SCSAI Dependencies: Both ① sync and ② impact analysis rely on the PLM at 114. If unreachable, the API returns success:true but with empty data + a message prompt. The frontend must display the message and not treat it as an error.
4. ECharts Component: ② Use toEChartsOption from forceGraph.js for chart configuration; do not write chart config manually. If the mini-program environment does not import echarts, use buildGraph to get {nodes, links} and render with any force-directed graph component.
5. State Machine Sequence: ③ Confirmation/approval has a strict sequential order. Frontend buttons should be enabled based on PO_STATUS_MAP and the current status.
6. Tenant: ①② Use the miniapp-exclusive routes, which are not subject to tenant restrictions; ③ Already compatible with default demo data, call directly.

Backend implemented list (for verification, no backend changes needed)

• ✅ /api/miniapp/gst/productSource/{list,syncFromPlm,convert,goods/list,goods/upsert} —— ①
• ✅ POST /api/change/analyze (includes where-used / propagate sub-capabilities) —— ②
• ✅ /api/purchase-order/{list,create,{id}, {id}/approve|confirm|complete|cancel} —— ③
• ✅ POST /api/content/generate-poster + generate-poster-qrcode —— ④
• ✅ /api/open/* (requires Key) —— ⑤
• ✅ src/utils/forceGraph.js (ECharts force-directed graph), src/api/{gst/url,change,purchase,content}.js (frontend encapsulation)