字段与数据约定
字段与数据约定
转发类接口的字段沿用服务端数据模型，以下约定对所有列表与详情响应通用。
| 约定 | 取值 | 说明 |
|---|---|---|
| 时间 | yyyy-MM-dd HH:mm:ss | 字符串而非时间戳；自动化会话的 createdAt 例外，是毫秒数字 |
| 开关 | ON · OFF | actived、opened、audioSwitch 等字段 |
| 分页入参 | page · size | 默认 1 与 20，size 服务端上限 1000；/sms/records 上限 100，/mail/pull 固定每页 10 条 |
| 关键词 | keyword | 账号匹配 username/remark；代理匹配 host/username/activeIp/remark |
| 数组查询参数 | state=1&state=0 | 重复传参构造数组，state[]= 写法不生效 |
| 批量写入集合 | items | 后端命令只读取 items；批量创建需自行传 items（或 accounts / proxyList 别名），删除接口由客户端把各种 ID 别名归一化为 items |
| 团队归属 | teamId | 账号与代理保存时由服务端按当前登录团队覆盖，请求里传入无效 |
| 代理状态 | 0 · 1 · -1 · -2 | 待检测、可用、不可用、已过期 |
| 代理枚举 | IPv4/IPv6 · SOCKS5/HTTP/HTTPS · CUSTOM/BUY | 对应 ipVersion、protocol、source |
| 窗口 ID | windowId | 取窗口的数字主键 id，不是 uuid |
| 窗口运行状态 | local_running · occupied_by_other · closed | /browser/list 的 runtimeState；opened 只是服务端记录，可能残留旧状态 |
| 窗口绑定字段 | platformId · pluginId | 是 ID 数组的 JSON 文本，如 "[5001,5002]"，不是数组 |
| 金额 | USDT | 价格可能是数字或十进制字符串；计算总价请用定点十进制，不要用浮点乘法 |
| JSON 文本字段 | product · resources · message · solution | 业务服务记录中的这些字段是 JSON 字符串，需要再解析一次 |
业务服务 ID
业务服务的各类 ID 不能互相代替：
| ID | 含义 | 用在哪里 |
|---|---|---|
/ip/products 的 productId | 一般代理商品 ID | /ip/buy |
/proxy/list 的 id | 本地代理 ID | /ip/renew 的 items |
/ip/orders 的 id | 本地订单 ID | 短效提取 /ip/snap/pull 的 nexIpId |
/sms/records 的 tel | 完整手机号字符串 | /sms/pull、/sms/recover |
/mail/records 的 id | 本地邮箱记录 ID | /mail/pull、/mail/detail 的 id |
/mail/pull 的 data[].id | 邮件数字 ID，不是 Message-ID | /mail/detail 的 mailId |
/captcha/records 的 id | 本地识别任务 ID，不是 taskId | /captcha/query |
凭据外发范围
/account/list 与 /browser/list 会返回平台账号的明文 password 与 key2fa；/browser/accounts 只返回脱敏用户名与 hasPassword / has2fa 标记。需要登录时优先用 account_fill，密码与验证码只在客户端内部流转。/ip/orders 的 resources 与 /ip/snap/pull 的响应含明文代理凭据。