API REFERENCE · 接口文档

横影·映航 HengYing·CinePilot API 接口

RESTful JSON · JWT 鉴权 · 统一响应 Result 包装 · 开放平台独立 AK/SK 网关
版本 V2.0编号 CP-API-11Base URL http://localhost:8080/api

通用约定

除登录与开放网关外，所有接口需携带 Authorization: Bearer {token}；统一响应结构：

{ "code": 0, "message": "ok", "data": { ... } }   // code=0 成功；4xx 业务/鉴权错误；429 限流

开发环境在线文档：http://localhost:8080/swagger-ui.html（SpringDoc）。

1. 认证 Auth

方法路径说明
POST/api/auth/login登录，body：{"username","password"}；返回 token + 用户信息
POST/api/auth/logout退出登录
GET/api/auth/me当前登录用户信息（角色/数据范围）

演示账号：admin/admin123（集团管理员）、analyst/analyst123（分析师）、store_hz/store123（杭州店长）。

2. 核心管理中心 Home

方法路径说明
GET/api/home/kpis六大经营 KPI（票房/场次/上座率/预警/AI 建议/会员）
GET/api/home/box-trend近 7 日集团票房趋势
GET/api/home/warnings实时预警事件流
GET/api/home/system-status系统与权限运行状态

3. 票房监控 BoxOffice

方法路径说明
GET/api/boxoffice/overview三级大盘 KPI+趋势；参数 level(nation/region/store)、regionId、storeId、startDate、endDate
GET/api/boxoffice/region-summary区域票房大盘表
GET/api/boxoffice/store-detail门店影片明细（storeId）
GET/api/boxoffice/film-rank影片票房 Top 榜（startDate/endDate）
GET/api/boxoffice/competitors竞对列表（storeId）
GET/api/boxoffice/warnings实时预警流
POST/api/boxoffice/daily-report/generate生成经营日报（storeId 可选）
GET/api/boxoffice/daily-reports日报列表
GETPOST/api/boxoffice/daily-report/subscriptions日报订阅查询 / 新增（P0）
POST/api/boxoffice/daily-report/push一键推送日报
GET/api/boxoffice/attributionAI 归因分布
GET/api/boxoffice/bigscreen经营大屏聚合数据

4. AI 智能排片 Scheduling

方法路径说明
GET/api/scheduling/plans排片计划列表
POST/api/scheduling/plans/{id}/confirm · /dispatch计划确认 / 下发
GET/api/scheduling/ratio-suggestion排片占比建议
GET/api/scheduling/predictions票房预测（filmId 可选）
GET/api/scheduling/backtests预测回测
GET/api/scheduling/suggestions动态调排建议（storeId）
GET/api/scheduling/preference-model本地化偏好模型
GET/api/scheduling/efficiency时段效率
GET/api/scheduling/consistency-checks排片一致性检查

5. CDP / RFM Cdp

方法路径说明
GET/api/cdp/overview会员全景
GET/api/cdp/oneid-channelsOneID 渠道分布
GET/api/cdp/rfm-distributionRFM 分层
GETPOST/api/cdp/campaigns活动列表 / 创建
GET/api/cdp/coupon-templates券模板
POST/api/cdp/coupons/issue发券
GET/api/cdp/touch-logs触达日志
GET/api/cdp/wakeup-summary沉睡唤醒汇总
GET/api/cdp/tags · /data-sources标签体系 / 数据源

6. 智能动态定价 Pricing

方法路径说明
GETPOST/api/pricing/zone-rules分区规则
GET/api/pricing/zone-distribution · /session-curve · /session-rules · /user-matrix · /clearance · /channels · /compliance-checks · /adjust-logs · /attribution各维度定价与审计数据
POST/api/pricing/adjust执行调价（合规校验+审计）
GETPOSTDELETE/api/pricing/ticket-source-constraints[/{id}]票源约束规则（P0）
POST/api/pricing/ticket-source/check票源合规实时检查

7. 预警中心 Warning

方法路径说明
GETPOST/api/warning/rules预警规则列表 / 新增
PUTDELETE/api/warning/rules/{id}更新 / 删除规则
GETPOSTDELETE/api/warning/target-ratios[/{id}]目标占比规则管理
GET/api/warning/inbox预警收件箱
PUT/api/warning/{id}/status处理状态流转
GET/api/warning/stats预警统计
POST/api/warning/scan手动触发检测扫描

8. AI 中台 Ai

方法路径说明
GETPOSTDELETE/api/ai/models[/{id}]垂类模型注册表 CRUD
POST/api/ai/models/{id}/train · /evaluate · /gate · /deploy · /rollback模型生命周期动作
GETPOSTDELETE/api/ai/channels[/{id}]大模型通道管理
POST/api/ai/channels/{id}/test通道连通测试
GET/api/ai/channels/route · /call-logs · /call-stats场景路由 / 调用日志 / 统计
POST/api/ai/ask智能问答（body：question）→ RAG / NL2SQL
GETPOSTDELETE/api/ai/kb[/{id}]知识库文档管理
GET/api/ai/qa-records问答记录

应用工坊 App Studio

方法路径说明
POST/api/ai/apps/generateNL 生成应用（body：prompt）→ 组件布局 JSON
GETPOST/api/ai/apps应用列表 / 保存
POST/api/ai/apps/{id}/publish发布应用
DELETE/api/ai/apps/{id}删除应用
GET/api/ai/apps/{id}/preview预览（渲染组件+取数，访问数+1）
POST/api/ai/apps/render?layout=布局即时渲染取数
// NL 生成示例请求
POST /api/ai/apps/generate
{ "prompt": "生成一个近7日全国票房趋势和影片Top榜的看板，指标用上座率" }

// 返回（layout 组件数组）
{ "code":0, "data": { "appName":"近7日全国票房趋势和影片To","sourceType":"nl_gen",
  "layout":[ {"type":"kpi","title":"核心指标","config":{"metric":"occupancy","dimension":"nation"}} ],
  "confidence":96, "source":"llm" } }

9. 营销 Agent Marketing

方法路径说明
POST/api/marketing/strategy/generate目标驱动策略生成（body：goalType/goalDesc）
GETPOSTDELETE/api/marketing/campaigns[/{id}]营销活动 CRUD
POST/api/marketing/campaigns/{id}/contents/generate文案+券规则生成
GET/api/marketing/campaigns/{id}/contents内容列表
POST/api/marketing/contents/{id}/review?pass=内容审核通过/驳回
POST/api/marketing/campaigns/{id}/schedule渠道排期一键下发（channel/planTime）
GET/api/marketing/campaigns/{id}/deliveries下发记录
POST/api/marketing/campaigns/{id}/effects录入转化（metricType/target/actual）
GET/api/marketing/effects · /effect-lib效果列表 / 策略效果库
POST/api/marketing/optimize生成权重自优化

10. 开放平台 OpenPlatform + 数据网关

管理端（JWT）

方法路径说明
GETPOSTDELETE/api/open-platform/apps[/{id}]伙伴应用 CRUD
POST/api/open-platform/apps/{id}/review?pass= · /toggle · /rotate-secret审核 / 启停 / 密钥轮换
GET/api/open-platform/catalog · /logs · /dashboardAPI 目录 / 调用日志 / 计量看板

数据网关（AK/SK，免 JWT）

方法路径说明
GET/api/open/v1/boxoffice/overview票房大盘（level/startDate/endDate）
GET/api/open/v1/boxoffice/film-rank影片票房榜
GET/api/open/v1/boxoffice/region-summary区域票房大盘
GET/api/open/v1/warnings实时预警流
GET/api/open/v1/scheduling/suggestions排片建议
GET/api/open/v1/sandbox/boxoffice/overview · /sandbox/warnings免密钥沙箱
// 网关调用示例（密钥直连）
GET /api/open/v1/boxoffice/overview?startDate=2026-08-19&endDate=2026-08-25
Header: X-App-Key: ak_hd_2026_demo_001
        X-App-Secret: sk_demo_secret_2026_8f2a
// 或签名：X-App-Sign: sig:{HMAC-SHA256(appSecret, path)}

11. 系统与租户 System / Tenant

方法路径说明
GET/api/system/regions · /stores · /store-tree区域 / 门店 / 门店树（级联筛选）
GET/api/tenant/list · /packages · /{id}/quota · /bills · /expiring · /summary租户/套餐/配额/账单/临期/总览
PUT/api/tenant/{id}更新租户
POST/api/tenant/{id}/renew续费

错误码约定

code含义场景
0成功—
400业务参数错误参数缺失/校验失败/业务规则拦截
401未认证未登录或 token 过期；开放网关密钥错误
403无权限数据范围不足；开放应用未启用/scope 越权
404资源不存在ID 无效
429限流开放网关 QPS / 日调用超限