docs: 重新生成 OpenAPI 文档,补全 Phase 03.1 新增字段

This commit is contained in:
2026-03-28 13:32:48 +08:00
parent a8becf55ff
commit f0f21e52f1

View File

@@ -581,27 +581,111 @@ components:
type: object
DtoAssetInfoResponse:
properties:
activated_at:
description: 激活时间
format: date-time
nullable: true
type: string
activation_status:
description: 激活状态0:未激活, 1:已激活)
type: integer
asset_id:
description: 资产ID
minimum: 0
type: integer
asset_type:
description: 资产类型 (card:卡, device:设备)
description: 资产类型card:卡, device:设备
type: string
bound_card_count:
description: 绑定卡数量
type: integer
bound_device_id:
description: 绑定的设备ID
minimum: 0
nullable: true
type: integer
bound_device_name:
description: 绑定的设备名称
type: string
bound_device_no:
description: 绑定的设备虚拟号
type: string
card_category:
description: 卡业务类型normal:普通卡, industry:行业卡)
type: string
cards:
description: 绑定卡列表含每张卡的ICCID/MSISDN/网络状态/实名状态/插槽位置)
items:
$ref: '#/components/schemas/DtoBoundCardInfo'
type: array
carrier_id:
description: 运营商ID
minimum: 0
type: integer
carrier_name:
description: 运营商名称
type: string
carrier_type:
description: 运营商类型CMCC/CUCC/CTCC/CBN
type: string
current_package:
description: 当前套餐名称(无套餐时为空)
type: string
device_model:
description: 设备型号
type: string
device_name:
description: 设备名称
type: string
device_protect_status:
description: 设备保护期状态none:无, stop:停机保护, start:开机保护)
type: string
device_realtime:
$ref: '#/components/schemas/DtoDeviceRealtimeInfo'
device_type:
description: 设备类型
type: string
generation:
description: 制式
description: 世代
type: string
iccid:
description: 卡ICCID
type: string
identifier:
description: 资产标识符
type: string
real_name_status:
description: 实名状态 (0:未实名, 1:已实名)
imei:
description: 设备IMEI
type: string
manufacturer:
description: 制造商
type: string
max_sim_slots:
description: 最大插槽数
type: integer
msisdn:
description: 手机号
type: string
network_status:
description: 网络状态0:停机, 1:开机)
type: integer
package_remain_mb:
description: 当前剩余虚流量(MB),已按虚流量比例换算
type: number
package_total_mb:
description: 当前套餐总虚流量(MB),已按虚流量比例换算
type: integer
package_used_mb:
description: 当前已用虚流量(MB),已按虚流量比例换算
type: number
real_name_status:
description: 实名状态0:未实名, 1:已实名)
type: integer
sn:
description: 设备序列号
type: string
status:
description: 状态 (0:禁用, 1:启用)
description: 状态1:在库, 2:已分销, 3:已激活, 4:已停用)
type: integer
virtual_no:
description: 虚拟号
@@ -703,6 +787,24 @@ components:
description: 已用虚流量(MB)按virtual_ratio换算
type: number
type: object
DtoAssetPackagesResult:
properties:
items:
description: 套餐列表
items:
$ref: '#/components/schemas/DtoAssetPackageResponse'
nullable: true
type: array
page:
description: 当前页码
type: integer
page_size:
description: 每页条数
type: integer
total:
description: 总条数
type: integer
type: object
DtoAssetRealtimeStatusResponse:
properties:
asset_id:
@@ -723,6 +825,8 @@ components:
device_protect_status:
description: 保护期状态asset_type=device时有效none/stop/start
type: string
device_realtime:
$ref: '#/components/schemas/DtoDeviceGatewayInfo'
last_sync_time:
description: 最后同步时间asset_type=card时有效
format: date-time
@@ -732,7 +836,7 @@ components:
description: 网络状态asset_type=card时有效0停机 1开机
type: integer
real_name_status:
description: 实名状态asset_type=card时有效
description: 实名状态asset_type=card时有效0未实名 1已实名
type: integer
type: object
DtoAssetRefreshRequest:
@@ -846,6 +950,16 @@ components:
imsi:
description: IMSI
type: string
last_gateway_sync_at:
description: 最后 sync-info 同步时间(设备类型时有效)
format: date-time
nullable: true
type: string
last_online_time:
description: 最后在线时间(设备类型时有效)
format: date-time
nullable: true
type: string
manufacturer:
description: 制造商
type: string
@@ -858,6 +972,9 @@ components:
network_status:
description: 网络状态0停机 1开机asset_type=card时有效
type: integer
online_status:
description: 在线状态0未知 1在线 2离线设备类型时有效
type: integer
package_remain_mb:
description: 当前套餐剩余虚流量(MB)已按virtual_ratio换算
type: number
@@ -868,7 +985,7 @@ components:
description: 当前已用虚流量(MB)已按virtual_ratio换算
type: number
real_name_status:
description: 实名状态0未实名 1实名中 2已实名
description: 实名状态0未实名 1已实名
type: integer
series_id:
description: 套餐系列ID
@@ -889,12 +1006,18 @@ components:
sn:
description: 设备序列号
type: string
software_version:
description: 固件版本号(设备类型时有效)
type: string
status:
description: 资产状态
type: integer
supplier:
description: 供应商
type: string
switch_mode:
description: 切卡模式0=自动1=手动(设备类型时有效)
type: string
updated_at:
description: 更新时间
format: date-time
@@ -1229,9 +1352,6 @@ components:
type: string
price_adjustment:
$ref: '#/components/schemas/DtoPriceAdjustment'
pricing_target:
description: 调价目标 cost_price-成本价(默认) retail_price-零售价
type: string
series_id:
description: 套餐系列ID可选不填则调整所有
minimum: 0
@@ -1322,6 +1442,9 @@ components:
iccid:
description: ICCID
type: string
is_current:
description: 是否为当前使用的卡
type: boolean
msisdn:
description: 手机号
type: string
@@ -1329,7 +1452,7 @@ components:
description: 网络状态0停机 1开机
type: integer
real_name_status:
description: 实名状态
description: 实名状态0未实名 1已实名
type: integer
slot_position:
description: 插槽位置
@@ -2241,13 +2364,13 @@ components:
maximum: 120
minimum: 1
type: integer
enable_realname_activation:
description: 是否启用实名激活 (true:需实名后激活, false:立即激活)
nullable: true
type: boolean
enable_virtual_data:
description: 是否启用虚流量
type: boolean
expiry_base:
description: 到期时间基准 (from_activation:实名激活时起算, from_purchase:购买时起算)
example: from_activation
type: string
package_code:
description: 套餐编码
maxLength: 100
@@ -2855,6 +2978,9 @@ components:
description: IoT卡ID
minimum: 0
type: integer
is_current:
description: 是否为当前使用的卡
type: boolean
msisdn:
description: 接入号
type: string
@@ -2912,6 +3038,137 @@ components:
required:
- identifier
type: object
DtoDeviceGatewayInfo:
properties:
battery_level:
description: 电池电量百分比无电池时为null
nullable: true
type: integer
connect_time:
description: 本次联网时间(秒)
nullable: true
type: string
current_iccid:
description: 当前使用的ICCID
nullable: true
type: string
daily_usage:
description: 日使用流量(字节)
nullable: true
type: string
device_id:
description: Gateway设备ID(IMEI/SN)
nullable: true
type: string
device_name:
description: Gateway返回的设备名称
nullable: true
type: string
device_type:
description: Gateway返回的设备类型
nullable: true
type: string
dl_stats:
description: 本次开机下载流量(字节)
nullable: true
type: string
imei:
description: IMEI号
nullable: true
type: string
imsi:
description: IMSI用户标识码
nullable: true
type: string
ip_address:
description: IP地址
nullable: true
type: string
lan_ip:
description: 局域网网关IP地址
nullable: true
type: string
last_online_time:
description: 设备最后在线时间
nullable: true
type: string
last_update_time:
description: 设备信息最后更新时间
nullable: true
type: string
limit_speed:
description: 限速速率(KB/s)
nullable: true
type: integer
mac_address:
description: MAC地址
nullable: true
type: string
max_clients:
description: 最大连接客户端数
nullable: true
type: integer
online_status:
description: 在线状态1=在线2=离线
nullable: true
type: integer
rsrp:
description: 参考信号接收功率(dBm)
nullable: true
type: integer
rsrq:
description: 参考信号接收质量(dB)
nullable: true
type: integer
rssi:
description: 接收信号强度
nullable: true
type: string
run_time:
description: 本次开机运行时间(秒)
nullable: true
type: string
sinr:
description: 信噪比(dB)
nullable: true
type: integer
software_version:
description: 软件版本号
nullable: true
type: string
ssid:
description: WiFi热点名称
nullable: true
type: string
status:
description: 设备状态1=正常0=禁用
nullable: true
type: integer
switch_mode:
description: 切卡模式0=自动1=手动
nullable: true
type: string
sync_interval:
description: 信息上报周期(秒)
nullable: true
type: integer
ul_stats:
description: 本次开机上传流量(字节)
nullable: true
type: string
wan_ip:
description: 基站分配IPv4地址
nullable: true
type: string
wifi_enabled:
description: WiFi开关状态
nullable: true
type: boolean
wifi_password:
description: WiFi密码
nullable: true
type: string
type: object
DtoDeviceImportResultItemDTO:
properties:
line:
@@ -3059,6 +3316,145 @@ components:
description: 请求ID
type: string
type: object
DtoDeviceRealtimeInfo:
properties:
battery_level:
description: 电池电量百分比
nullable: true
type: integer
connect_time:
description: 设备本次联网时间(秒)
nullable: true
type: string
created_at:
description: Gateway创建时间(Unix时间戳)
nullable: true
type: integer
current_iccid:
description: 当前使用的ICCID
nullable: true
type: string
daily_usage:
description: 日使用流量(字节)
nullable: true
type: string
device_id:
description: Gateway设备ID(IMEI/SN)
nullable: true
type: string
device_name:
description: Gateway返回的设备名称
nullable: true
type: string
device_type:
description: Gateway返回的设备型号
nullable: true
type: string
dl_stats:
description: 本次开机下载流量(字节)
nullable: true
type: string
imei:
description: Gateway返回的IMEI号
nullable: true
type: string
imsi:
description: Gateway返回的IMSI
nullable: true
type: string
ip_address:
description: IP地址
nullable: true
type: string
lan_ip:
description: 局域网网关IP地址
nullable: true
type: string
last_online_time:
description: 设备最后在线时间
nullable: true
type: string
last_update_time:
description: 设备信息最后更新时间
nullable: true
type: string
limit_speed:
description: 限速速率(KB/s)
nullable: true
type: integer
mac_address:
description: MAC地址
nullable: true
type: string
max_clients:
description: 最大连接客户端数
nullable: true
type: integer
online_status:
description: 在线状态1:在线, 2:离线)
nullable: true
type: integer
rsrp:
description: 参考信号接收功率(dBm)
nullable: true
type: integer
rsrq:
description: 参考信号接收质量(dB)
nullable: true
type: integer
rssi:
description: 接收信号强度
nullable: true
type: string
run_time:
description: 设备本次开机运行时间(秒)
nullable: true
type: string
sinr:
description: 信噪比(dB)
nullable: true
type: integer
software_version:
description: 软件版本号
nullable: true
type: string
ssid:
description: WiFi热点名称
nullable: true
type: string
status:
description: 设备状态1:正常, 0:禁用)
nullable: true
type: integer
switch_mode:
description: 切卡模式0:自动, 1:手动)
nullable: true
type: integer
sync_interval:
description: 信息上报周期(秒)
nullable: true
type: integer
ul_stats:
description: 本次开机上传流量(字节)
nullable: true
type: string
updated_at:
description: Gateway更新时间(Unix时间戳)
nullable: true
type: integer
wan_ip:
description: 基站分配IPv4地址
nullable: true
type: string
wifi_enabled:
description: WiFi开关状态
nullable: true
type: boolean
wifi_password:
description: WiFi密码
nullable: true
type: string
type: object
DtoDeviceRebootRequest:
properties:
identifier:
@@ -3108,12 +3504,25 @@ components:
imei:
description: 设备IMEI
type: string
last_gateway_sync_at:
description: 最后 sync-info 同步时间
format: date-time
nullable: true
type: string
last_online_time:
description: 最后在线时间
format: date-time
nullable: true
type: string
manufacturer:
description: 制造商
type: string
max_sim_slots:
description: 最大插槽数
type: integer
online_status:
description: 在线状态0未知 1在线 2离线
type: integer
series_id:
description: 套餐系列ID
minimum: 0
@@ -3133,12 +3542,18 @@ components:
sn:
description: 设备序列号
type: string
software_version:
description: 固件版本号
type: string
status:
description: 状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)
type: integer
status_name:
description: 状态名称
type: string
switch_mode:
description: 切卡模式0=自动1=手动
type: string
updated_at:
description: 更新时间
format: date-time
@@ -4458,12 +4873,12 @@ components:
duration_months:
description: 套餐时长(月数)
type: integer
enable_realname_activation:
description: 是否启用实名激活 (true:需实名后激活, false:立即激活)
type: boolean
enable_virtual_data:
description: 是否启用虚流量
type: boolean
expiry_base:
description: 到期时间基准 (from_activation:实名激活时起算, from_purchase:购买时起算)
type: string
id:
description: 套餐ID
minimum: 0
@@ -6275,14 +6690,14 @@ components:
minimum: 1
nullable: true
type: integer
enable_realname_activation:
description: 是否启用实名激活 (true:需实名后激活, false:立即激活)
nullable: true
type: boolean
enable_virtual_data:
description: 是否启用虚流量
nullable: true
type: boolean
expiry_base:
description: 到期时间基准 (from_activation:实名激活时起算, from_purchase:购买时起算)
nullable: true
type: string
package_name:
description: 套餐名称
maxLength: 255
@@ -6497,6 +6912,15 @@ components:
required:
- status
type: object
DtoUpdateRetailPriceParams:
properties:
retail_price:
description: 零售价(单位:分)
minimum: 0
type: integer
required:
- retail_price
type: object
DtoUpdateRoleParams:
properties:
role_desc:
@@ -8467,8 +8891,23 @@ paths:
- 资产管理
/api/admin/assets/{asset_type}/{id}/packages:
get:
description: 查询该资产所有套餐记录,含虚流量换算结果。
description: 查询该资产所有套餐记录,含虚流量换算结果。支持分页(默认 page=1, page_size=50, 最大100
parameters:
- description: 页码默认1
in: query
name: page
schema:
description: 页码默认1
minimum: 1
type: integer
- description: 每页条数默认50最大100
in: query
name: page_size
schema:
description: 每页条数默认50最大100
maximum: 100
minimum: 1
type: integer
- description: 资产类型card 或 device
in: path
name: asset_type
@@ -8495,9 +8934,7 @@ paths:
example: 0
type: integer
data:
items:
$ref: '#/components/schemas/DtoAssetPackageResponse'
type: array
$ref: '#/components/schemas/DtoAssetPackagesResult'
msg:
description: 响应消息
example: success
@@ -15680,6 +16117,52 @@ paths:
summary: 更新套餐
tags:
- 套餐管理
/api/admin/packages/{id}/retail-price:
patch:
parameters:
- description: ID
in: path
name: id
required: true
schema:
description: ID
minimum: 0
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DtoUpdateRetailPriceParams'
responses:
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 请求参数错误
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 未认证或认证已过期
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 无权访问
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 服务器内部错误
security:
- BearerAuth: []
summary: 修改零售价(代理)
tags:
- 套餐管理
/api/admin/packages/{id}/shelf:
patch:
parameters:
@@ -20574,6 +21057,22 @@ paths:
maxLength: 50
minLength: 1
type: string
- description: 套餐类型 (formal:正式套餐, addon:加油包)
in: query
name: package_type
schema:
description: 套餐类型 (formal:正式套餐, addon:加油包)
nullable: true
type: string
- description: 套餐状态 (0:待生效, 1:生效中, 2:已用完, 3:已过期, 4:已失效)
in: query
name: status
schema:
description: 套餐状态 (0:待生效, 1:生效中, 2:已用完, 3:已过期, 4:已失效)
maximum: 4
minimum: 0
nullable: true
type: integer
- description: 页码
in: query
name: page