MiFaZhan
96b1edff45
iotlcm-upstream-chan：运营商上游通道适配服务（统一 /sim/* 协议）。 - 内联原私有依赖：yunze-public → internal/pub/（10 包 18 文件）， yunze-pb/pb → internal/pb/（9 文件）；Consul 注册改用官方 gogf/gf/contrib/registry/consul/v2（API 兼容） - Go module：yz-svr → git.5iot.com/iotlcm-public/iotlcm-upstream-chan - 修复 mingqian 包测试：实现重构后 `adapter.operations` 字段已移除， 测试断言按当前实现语义重写（不改产品行为） - 凭据与内部标识脱敏：MySQL/Redis/Consul 凭据、私网与生产 IP、 内网域名、真实手机号、注释里的真实 token/transid - 移除内部资产：CI 触发器、生产通道种子 SQL、真实凭据测试资源文档 - Dockerfile 改用公共基础镜像，移除写死的 registry 凭据 - 补 Apache-2.0 LICENSE，重写 README，LF 行尾 + .gitattributes
66 lines
4.8 KiB
Markdown
66 lines
4.8 KiB
Markdown
# 电信 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 全链路验收。
|