一、环境与 Apifox 准备

项 说明

服务地址

http://localhost:8089（以 application.yml 中 server.port 为准）

数据库

MySQL + Flyway 迁移；种子账号见 V2__seed.sql

默认账号

管理员：admin@platform.com / admin123；商家：owner@test.com / merchant123

种子商家 ID

merchantId = 1（TEST001）

Apifox 导入（推荐）

  1. 启动 platform：mvn spring-boot:run
  2. Apifox → 导入 → OpenAPI：http://localhost:8089/v3/api-docs
  3. 或浏览器打开 Swagger：http://localhost:8089/swagger-ui/index.html

环境变量（Apifox 环境里配置）

变量 示例 用途

baseUrl

http://localhost:8089

所有请求前缀

adminToken

登录后写入

Authorization: Bearer {{adminToken}}

merchantToken

登录后写入

商家端接口

deviceToken

handshake 后写入

设备拉活动/模板

merchantId

1

商家查询参数

deviceId

handshake 返回

设备路径参数

activityId

创建活动后

后续绑定

templateId

管理端创建后

版本/绑定

统一响应格式

{ "success": true|false, "message": "...", "data": { ... } }

鉴权规则（SecurityConfig）

  • 公开：/api/v1/auth/**、Swagger、/api/v1/device/**、/api/v1/ai/**
  • 管理端：/api/v1/admin/** → 需 ADMIN + Bearer JWT
  • 商家端：/api/v1/merchant/** → 需 ADMIN / MERCHANT_OWNER / MERCHANT_STAFF

Apifox 可在「登录」接口的后置脚本里写：pm.environment.set("adminToken", json.data.token)。

二、按模块测试的接口

第 0 层：连通与文档（必做）

方法 路径 鉴权 说明

GET

/v3/api-docs

无

验证服务、导入 Apifox

GET

/swagger-ui/index.html

无

浏览器对照参数

第 1 层：认证（必做，Apifox 前置）

方法 路径 鉴权

POST

/api/v1/auth/login

无

用例

  • 正确账号 → success=true，data.token 非空
  • 错误密码 → success=false
  • 分别测 admin / merchant，保存两个 token

第 2 层：设备端（无需用户 JWT，适合入门）

方法 路径 鉴权 说明

POST

/api/v1/device/handshake

无（deviceCode+secret）

换 deviceToken

POST

/api/v1/device/heartbeat

无

需先有设备；3s 限流

GET

/api/v1/device/{deviceId}/activities

Header: Authorization: Bearer {{deviceToken}}

活动列表

GET

/api/v1/device/{deviceId}/activities/{activityId}/templates

同上

活动下模板

前置数据：库中需有 devices 记录（可用商家端创建设备，或 SQL 插入，见 DEVICE_HANDSHAKE_TEST.md）。

推荐链路：handshake → heartbeat → activities → templates

第 3 层：商家端（需 merchantToken）

方法 路径 说明

GET

/api/v1/merchant/activities?merchantId=1

分页列表

GET

/api/v1/merchant/activities/{activityId}

详情

POST

/api/v1/merchant/activities

创建活动

POST

/api/v1/merchant/activities/{id}/template-versions

绑定模板版本（推荐）

POST

/api/v1/merchant/activities/{id}/templates

旧接口：按 templateId 绑定

GET

/api/v1/merchant/activities/{id}/template-versions

查询已绑版本

POST

/api/v1/merchant/activities/{id}/devices

活动绑设备

GET

/api/v1/merchant/activities/{id}/devices

活动设备列表

GET

/api/v1/merchant/devices?merchantId=1

商户设备列表

POST

/api/v1/merchant/devices

创建设备（供 handshake 用）

GET

/api/v1/merchant/template-versions

可选模板版本

GET

/api/v1/merchant/payments

当前可能返回禁用提示（迁移期）

课堂主流程（E2E 简版）

  1. 商家登录
  2. 创建设备 → 记下 deviceCode / secret
  3. 创建活动
  4. （需管理端先有模板版本）绑定 template-versions + devices
  5. 设备 handshake → 拉 activities/templates

第 4 层：管理端核心（需 adminToken）

4.1 模板与版本（业务核心，建议重点练）
方法 路径

GET

/api/v1/admin/templates

GET

/api/v1/admin/templates/{id}

POST

/api/v1/admin/templates

GET

/api/v1/admin/templates/{templateId}/versions

POST

/api/v1/admin/templates/{templateId}/versions

PUT

/api/v1/admin/templates/{templateId}/versions/{versionId}

DELETE

/api/v1/admin/templates/{templateId}/versions/{versionId}

POST

/api/v1/admin/templates/{templateId}/versions/{versionId}/activate

POST

/api/v1/admin/templates/{id}/delete

POST

/api/v1/admin/templates/{id}/restore

课堂建议：先测 GET 列表/详情 和 POST 创建模板+版本（body 用 JSON，package 可先填 URL 字符串）；ZIP 上传（package-upload、package-zip）放选做（multipart，Apifox 要配 form-data）。

4.2 商户与设备
方法 路径

GET/POST/PUT

/api/v1/admin/merchants

POST

/api/v1/admin/merchants/{id}/enable、/disable

GET

/api/v1/admin/merchants/{merchantId}/devices

POST

/api/v1/admin/merchants/{merchantId}/devices

GET

/api/v1/admin/merchants/{merchantId}/activities 及子路径

GET/PUT

/api/v1/admin/devices、/bind-merchant、/unbind-merchant
4.3 AI 路由（与 Resolve 配套，适合「接口编排」作业）
方法 路径

GET/POST/PUT

/api/v1/admin/providers

GET/POST/PUT

/api/v1/admin/providers/{id}/capabilities

GET/POST

/api/v1/admin/providers/{id}/keys

PUT

/api/v1/admin/providers/{id}/keys/{keyId}/disable

GET/POST/PUT

/api/v1/admin/routing-policies

文档与示例见仓库：ADMIN_CRUD_API_DOC.md、RESOLVE_API_TEST_GUIDE.md。

4.4 模板类型 / 设计器（选做）
前缀 说明

/api/v1/admin/template-types

类型 CRUD

/api/v1/admin/designer/drafts

草稿、资产、预览、发布（含文件上传）

第 5 层：AI Resolve（公开，无需登录）

方法 路径

POST

/api/v1/ai/resolve

典型 body：{ "capability": "segmentation" } 或带 prefer、merchantId。
前置：库里有 model_providers、provider_capabilities（可跟 RESOLVE_API_TEST_GUIDE.md 插测试数据）。

推荐作业：先 Admin 建 Provider/Capability/Policy → 再调 Resolve 验证路由结果。

第 6 层：系统 RBAC / 财务（进阶，可选）

模块 路径前缀

用户/角色/菜单/权限

/api/v1/admin/system/users、roles、menus、permissions

会员套餐/计价规则

/api/v1/admin/system/membership-plans、pricing-rules

财务

/api/v1/admin/finance/orders、withdrawals；/api/v1/finance/tieredPrice

订阅/点数/支付

merchants/{id}/subscriptions、points；payments

定制需求

/api/v1/admin/request/customReq

部分接口带 @PreAuthorize 细粒度权限；纯 ADMIN 角色一般仍可测，适合讲 403 / RBAC 的对比实验。

三、Apifox 测试方案（建议 4 个实验）

实验 1：认证与环境（1 课时）

目标：掌握 Apifox 环境变量、Bearer、断言。

步骤 接口 断言

1

POST /auth/login（admin）

success、data.token 存在

2

GET /admin/templates 无 token

401

3

带 Authorization: Bearer {{adminToken}}

200 + success

4

merchant 登录重复 1–3

角色对比

实验 2：设备握手与拉取（1 课时）

目标：两种凭证（用户 JWT vs 设备 token）、路径参数。

步骤 接口

1

商家 POST /merchant/devices 创建设备

2

POST /device/handshake

3

POST /device/heartbeat

4

GET .../activities（Bearer deviceToken）

5

错误 secret / 无 token

扩展：连续 handshake 触发限流（文档：30s 窗口最多 10 次）。

实验 3：商家 + 管理端业务链（2 课时）

目标：跨角色、变量传递、CRUD 顺序。

登录创建模板+版本登录创建活动绑定 template-versions + devicehandshakeGET activities/templatesAdminMerchantDevice

Apifox 测试套件 按顺序跑，上一步响应脚本提取 templateVersionId、activityId、deviceId。

实验 4：AI 路由与 Resolve（1–2 课时）

步骤 角色 接口

1

Admin

创建 Provider → Capability →（可选）API Key

2

Admin

创建 Routing Policy

3

无鉴权

POST /ai/resolve 多种 capability/prefer

4

断言

data.providerCode、endpoint、timeoutMs

四、Apifox 配置要点（课堂常踩坑）

  1. 端口：文档里偶有 8080，当前仓库默认 8089。
  2. Header 名称：Authorization: Bearer <token>（不是 token 自定义头，除非你们自己改过滤器）。
  3. 商家接口：多数要带 merchantId=1 查询参数。
  4. 设备 activities/templates：需要 deviceToken，不是 adminToken。
  5. 文件上传：multipart/form-data，选做；未配 OSS 时上传可能失败，不影响 JSON CRUD 实验。
  6. 不要测生产库：application.yml 里若是远程 DB，学校应改为本地 MySQL + 独立库名。
  7. payments：商家/管理端支付相关接口可能返回「迁移期禁用」，可当作 业务开关 案例，不必判为 Apifox 配错。

五、接口优先级速查（给老师勾选）

优先级 接口群 适合

P0

auth/login、admin/templates(GET)、merchant/activities(GET)

第一节课

P1

device 全链路、merchant 活动/设备 CRUD

核心业务

P2

admin providers/routing + ai/resolve

编排与断言

P3

admin merchants/devices、template-versions

联调作业

P4

designer 上传、finance、system RBAC

进阶选修

六、与课堂交付物对应

交付物 内容

Apifox 项目

从 /v3/api-docs 导入 + 环境 baseUrl/token

测试集合

实验 1–4 四个 Folder + 前置/后置脚本

测试报告

每个用例：请求、预期状态码、success、关键字段

扩展题

403 无权限、handshake 限流、resolve 无 provider 数据

# postman
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

AI写小说用什么模型最好？DeepSeek、Claude、豆包实测对比，别只盯着一个用

avatar AI编程社区
cover

[论文学习]ToolEmu:用语言模型模拟沙盒识别语言模型智能体的风险

avatar AI编程社区
cover

【生产力】Claude Opus 5 新特性与行为变化：完整更新与迁移指南

avatar AI编程社区