地域购物车前台接口
地域购物车插件为智简魔方业务系统 V10 提供统一的前台购买接口,支持魔方云和 DCIM 商品。前端按计费方式、部署区域、可用区、网络线路和商品完成选择,动态获取配置、实时报价并加入站点现有购物车。
| 项目 | 内容 |
|---|---|
| 文档类型 | 前台接口 |
| 所属业务 | 地域购物车 |
| 插件标识 | location_cart |
| 接口版本 | v2 |
| 接口前缀 | /console/v1/location_cart |
| 接口数量 | 6 |
接口目录
| 请求方式 | 接口 | 接口地址 |
|---|---|---|
GET | 获取部署区域和可用区 | /console/v1/location_cart/locations |
POST | 获取网络线路 | /console/v1/location_cart/availability |
POST | 获取当前条件下的可购商品 | /console/v1/location_cart/products |
POST | 获取商品配置项 | /console/v1/location_cart/product/{id}/options |
POST | 获取商品实时报价 | /console/v1/location_cart/quote |
POST | 将报价配置加入购物车 | /console/v1/location_cart/cart |
调用流程
- 选择产品类型与计费方式。
- 获取部署区域和可用区,选择
region_key与zone_key。 - 获取网络线路,选择
line_key。 - 获取可购商品,选择
product_id与source_key。 - 获取商品配置项,填写完整的
config_options;选项变化时刷新配置协议。 - 获取实时报价,展示购买总价并保留完整请求与报价令牌。
- 将报价配置加入购物车,然后进入站点原有购物车结算流程。
产品类型、计费方式、地域、线路或商品变化时,重新获取下游目录和配置。购买配置或数量变化后,重新报价再加购。
公共约定
| 项目 | 约定 |
|---|---|
| 请求地址 | 请求域名使用实际 V10 站点域名。示例中的 https://your-v10.example 为占位域名。 |
| 请求格式 | GET 使用 query 参数;POST 使用 Content-Type: application/json 提交 JSON 请求体。 |
| 登录凭证 | 登录用户使用站点前台 JWT,格式为 Authorization: Bearer <前台登录 JWT>。不要使用后台登录凭证。 |
| 游客会话 | 支持游客 Cookie 购物车。报价与加购保留同一 Cookie 及 User-Agent,切换登录状态后重新报价。 |
| 购买权限 | 报价与加购沿用核心购物车操作权限;子账户须具有对应权限。 |
| 敏感配置 | 提交密码或私钥等登录配置前需要登录。报价响应不会回显密码和私钥。 |
| 部署方式 | 前台页面与 V10 同源部署,或通过受控网关接入;跨域策略由实际部署环境配置。 |
| 响应结构 | status 为业务状态码,msg 为提示信息,data 为业务数据;失败响应不保证含有 data。 |
| 标识传递 | region_key、zone_key、line_key、source_key 均从上一步响应取得并原样传递。 |
| 报价有效期 | quote_token 有效期为 5 分钟;过期、配置变动或切换身份后重新报价。 |
| 示例数据 | 商品 ID、地域名称、来源标识、配置、金额、时间戳和令牌均为示意,不代表站点真实数据。 |
产品类型与计费方式
| 参数 | 值 | 说明 |
|---|---|---|
category | cloud | 魔方云,对应 mf_cloud 模块。 |
category | dcim | DCIM,对应 mf_dcim 模块。 |
billing_mode | recurring_prepayment | 包年包月,魔方云和 DCIM 均可使用。 |
billing_mode | on_demand | 按需计费,仅魔方云支持;具体以当前可售条件为准。 |
配置字段协议
商品配置项接口通过 data.groups[].fields[] 返回动态字段。使用字段的 key 作为 config_options 的属性名;根据 required、visible_when、config_modes、options 和数值约束生成表单。
| 控件类型 | 说明 |
|---|---|
radio | 单选,显示 options[].label,提交 options[].value。 |
select | 下拉选择,遵守返回的选项值和禁用状态。 |
number | 数值输入,遵守 min、max、step、unit 和 constraints。 |
text | 文本输入,遵守当前字段必填条件。 |
password | 密码输入;不使用脱敏后的报价响应替代原始请求配置。 |
repeatable | 可重复子项,按 item_schema 填写子项列表。 |
配置分组:compute 为计算,storage 为存储,network 为网络,system 为系统与周期。
配置方式从商品来源的 configuration_modes 取得:custom 为自定义配置,recommend 为推荐套餐,model 为 DCIM 机型。
defaults 仅为当前活动公开字段的默认值,不代表必填项已完整或已经通过购买校验。不要提交 disabled = true 的选项。
报价与加购处理
| 情况 | 处理方式 |
|---|---|
| 报价成功 | 展示 data.quote.price_total,保存报价令牌、过期时间和完整的原请求配置。 |
| 配置或数量变化 | 重新报价,不继续使用旧令牌。 |
| 登录或切换用户 | 重新报价,保持加购与报价身份一致。 |
| 令牌过期或无效 | 重新获取报价和令牌后加购。 |
| 价格发生变化 | 检查 data.reason = "quote_changed",展示 data.quote,确认后使用 data.quote.quote_token 重试。 |
| 库存不足 | 展示 msg,修改配置或数量后重新报价。 |
库存状态为 null | 表示模块无法确认余量,不等同于明确缺货。后续仍由报价和加购执行购买校验。 |
| 加购成功 | 进入站点现有购物车流程,也可继续加入其他商品。 |
报价令牌不锁定库存,也不保证后续价格不变。加购时会再次校验,最终结算继续使用站点原有购物车流程。