# 电信 V3 APN 状态与开停适配

## 接口依据

查询依据《中国电信天翼物联5GCMP能力调用参考文档-V3 (1).pdf》159–164 页；
开停依据 CTIOT_5GCMP_BA004（添加或取消单独断网，PDF p217-219）。

### 查询：GET /api/v3/getApnInfo

- msisdn/iccid/imsi 至少一项；读取 result.apnInfoList。
- 查询表格使用 status，示例使用 apnStatus，网关兼容两者；0 表示停用，1 表示正常。
- 两字段冲突、缺失或不在 0/1 范围时，状态保留为空，不推断为正常。

### 开停：GET /5gcmp/openapi/v1/common/singleCutNet

- 参数 access_number（物联网接入号，必传）+ action（ADD/DEL）。
- **整卡数据开停语义**，电信侧没有「按 APN 定向」这一维度。
- action 语义与平台相反，必须转换、禁止透传（见 `convertDxApnOperType`）：
  - 平台 0(开通数据) → `DEL`（取消单独断网，恢复联网）
  - 平台 1(停用数据) → `ADD`（单独断网）
- 忽略调用方携带的 ApnName：预警自动断网、批量数据开停都会固定带 `apnName="CMIOT"`，
  电信卡不含该 APN，若据此拒绝会直接打断主流程。
- 响应为 XML：`SvcCont > Response > RspCode`，`0000` 表示成功接收；
  `GROUP_TRANSACTIONID` 为流水号，透传为 orderNum。
- 缺返回码、非 `0000`、缺流水号、HTTP 失败均不视为成功，不自动重试以免重复操作。

> 注意：`/api/v3/updateApnFunctionStatus` 是另一个接口（单卡 APN 开停，按 APN 定向），
> 与「数据服务开停」业务语义不匹配，v1 不再使用。
> 历史：2026-10-10 `b3f00a0` 曾把 v1 改成该接口，导致电信数据开停因 APN 名不匹配而全部失败，已回退。

## 读取链路

智能诊断展示与 APN 开关查询分离：

- 电信：小程序/Web 后端复用卡状态查询 → 请求代理 → 网关 sim_dx_v1 → /openapi/v1/prodinst/queryCardMainStatus。
- 网关透传独立 netBlockStatus（0 未断网、1 已断网）和 netBlockTypes，诊断返回 dataServiceSource=network_block、netBlockStatus、netBlockReason。
- 电信 dataStatus 保持空值，不将断网状态转换成 APN 开关，也不以此驱动 APN 开停按钮；电信卡片排查不展示 APN 开停操作。
- 未返回有效断网状态时显示 -；已断网时展示全部有效断网原因并去重，不推测原因。
- 卡主状态查询失败时数据服务模块同步标记失败，不能展示本地旧状态。
- 电信在线状态继续独立查询 /api/v1/onlineSessionOpen/qryOnlineSataus；APN、IP、IMEI、时间等会话字段不能推断 APN 开启。
- 电信会话 netModel=1/2 统一为 4G/5G，不再透传数字让前端按移动编码误解释。
- 移动数据服务仍使用 ec/query/apn-info 的 CMIOT 状态；移动和电信的会话状态都从会话接口获取。
- 独立 APN 查询 /sim/query/sim-apn-info 仍使用 CM001 /api/v3/getApnInfo，但不再作为电信智能诊断数据服务断网展示的来源。

两端对非移动 APN 列表采用保守一致性判定：单个 APN 或所有 APN 的有效状态一致时才给出开/停；空列表、缺名称、缺状态、混合状态均不选第一项代替整体状态，界面无值显示 -。
这不是多 APN 的业务目标选择规则；若要显示某个专用业务 APN，需进一步明确目标并让查询和操作使用同一配置。

## 开停保护与剩余事项

- 开停走整卡语义的 singleCutNet，只要求物联网接入号（MSISDN）；缺接入号时明确失败。
- 不将 CMIOT 自动改成 ctnet 或 CTIOT，也不猜选唯一 APN：
  指定 APN 开停需要另接 `/api/v3/updateApnFunctionStatus`，属独立业务契约，未接入。
- 当前小程序/Web 批次入口仍默认写入 CMIOT；singleCutNet 忽略该字段，不影响执行。
- 小程序操作预检仍读取本地 data_service_status，可能与实时状态不同；后续应与上游校验统一。
- Worker 目前依据网关 code=0 判成功并更新本地状态。电信返回流水号表示订单受理，最终生效状态需要后续查单或实时 APN 查询核实，尚未做真实业务验收。
- 若启停请求发送后网络中断或成功响应缺流水号，结果未确认，不应盲目重试以免重复操作；先核对上游状态。
- singleCutNet 的 GET/POST 以网关实测为准：文档写 POST/GET，现网 v1 走 GET；
  v3 适配器走 POST（`sim_dx_v3.go`），尚未实卡验收。

## 验证边界

回归测试采用 httptest 本地模拟上游，覆盖：查询字段兼容/缺字段/错误码；
开停的 ADD/DEL 方向、参数编码、XML 解析、缺结果码、缺流水号、非 0000、HTTP 失败保护，
并断言不携带 APN 定向参数。
测试不对真实卡发起启停，不替代生产通道权限、配置及 Worker 全链路验收。