626 lines
27 KiB
Markdown
626 lines
27 KiB
Markdown
# 新增需求 01：数据同步触发与轮询优化
|
||
|
||
> 状态：已合并至标准评审稿，本文保留为实施明细。
|
||
> 评审主文档：`../../7月迭代技术方案-标准评审稿.md`
|
||
> 范围：IoT 卡实名、流量、网络状态和设备实时数据同步。
|
||
|
||
## 一、已确认决策
|
||
|
||
1. 轮询、运营商回调、业务事件触发是三条相互隔离的自动同步通道。
|
||
2. 轮询始终保留，负责回调失效、事件漏网和上游偶发失败时的最终兜底。
|
||
3. 资产是否轮询只保留现有全局开关 `enable_polling`；不再设计“实名资格、流量资格、状态资格”等业务资格开关。
|
||
4. 轮询优化只区分活跃卡和不活跃卡，通过不同轮询间隔降低无效请求，不因业务类型直接永久排除某类卡。
|
||
5. 行业卡是否需要实名不能由 `card_category=industry` 推断，统一以运营商 `realname_link_type` 判断。
|
||
6. 业务事件触发不是新增一个显式同步接口，而是埋点到关键查询、停复机、支付、实名和设备操作用例中。
|
||
7. 每次事件默认形成三个独立尝试：立即、事件发生后 3 分钟、事件发生后 5 分钟；三次结束后由常规轮询继续兜底。
|
||
8. 不设置统一五分钟冷却。重复请求控制拆成同场景触发合并、单卡请求互斥和运营商最小请求间隔；Gateway 超频只记录当前失败，不建立退避状态。
|
||
9. 运营商实名回调百分百信任，不做来源真实性校验；但必须经过防腐层完成报文解析、标识转换和状态语义转换。
|
||
10. 解除实名第一版不修改业务状态，只保留回调入口、写入统一集成审计并返回运营商要求的成功报文。
|
||
11. 三条自动通道和现有手动刷新接口共享同一套“获取上游观测并应用到业务”的 DDD 用例，禁止各入口直接更新卡字段。
|
||
12. 同步执行记录属于全局审计的 Integration Log，不在本方案新建 `tb_card_sync_execution` 或独立同步监控系统。
|
||
13. 本次迁移触碰到的旧实名、流量和状态写逻辑必须删除或改为调用新用例，不保留长期双实现。
|
||
|
||
## 二、现状问题
|
||
|
||
当前代码存在以下明确问题：
|
||
|
||
- `internal/task/polling_realname_handler.go` 直接跳过所有行业卡，与“是否实名由运营商特性决定”冲突。
|
||
- `PollingRealnameHandler`、`PollingCarddataHandler` 和 `PollingCardStatusHandler` 同时承担 Gateway 查询、字段更新和业务联动。
|
||
- `internal/service/iot_card/service.go:RefreshCardDataFromGateway` 又实现一套实名、流量和网络状态同步。
|
||
- `ManualUpdateRealnameStatus` 单独实现实名状态变更联动，无法保证与轮询、回调行为一致。
|
||
- `ClientRealnameHandler`、部分设备 Handler 直接调用 Gateway，业务事件无法在统一用例边界埋点。
|
||
- 现有获取实名链接后的自动检查借用了 `ManualTriggerService`，把系统事件伪装成平台用户手工操作。
|
||
- 调度任务载荷只有 `card_id`，缺少触发场景、来源、序列和关联链路。
|
||
- `last_sync_time` 被实名、流量和状态共同覆盖，无法说明最后同步了什么。
|
||
- 现有显式刷新接口已经存在，再增加 `/card-sync/requests` 只会形成重复入口。
|
||
|
||
因此，本次不是增加更多同步 Service，而是先收口写侧用例，再把轮询、回调和事件触发接入同一边界。
|
||
|
||
## 三、目标架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Polling[轮询调度] --> Activity[按活跃度计算下次间隔]
|
||
Activity --> Request[RequestCardObservation]
|
||
|
||
Business[关键业务用例] --> Trigger[CreateSyncTriggerSeries]
|
||
Query[关键查询用例] --> Trigger
|
||
Trigger --> A1[立即尝试]
|
||
Trigger --> A2[3分钟后尝试]
|
||
Trigger --> A3[5分钟后尝试]
|
||
A1 --> Gate[请求协调器]
|
||
A2 --> Gate
|
||
A3 --> Gate
|
||
Gate --> Request
|
||
|
||
Manual[现有手动刷新接口] --> Request
|
||
|
||
Callback[运营商实名回调] --> ACL[运营商防腐层]
|
||
ACL --> RealObs[标准实名观测]
|
||
|
||
Request --> Gateway[Gateway Adapter]
|
||
Gateway --> Observation[标准化观测值]
|
||
RealObs --> Apply[ApplyCardObservation]
|
||
Observation --> Apply
|
||
|
||
Apply --> Card[保存卡状态]
|
||
Apply --> Events[记录领域事件和 Outbox]
|
||
Events --> Package[套餐激活与流量扣减]
|
||
Events --> StopResume[停复机评估]
|
||
Events --> ActivityMark[更新活跃标记]
|
||
Request --> Integration[统一 Integration Log]
|
||
ACL --> Integration
|
||
Events --> Audit[关键业务 Audit Event]
|
||
```
|
||
|
||
各入口边界：
|
||
|
||
| 入口 | 是否调用 Gateway | 执行方式 | 作用 |
|
||
|---|---:|---|---|
|
||
| 轮询 | 是 | 异步、持续重排 | 最终一致性兜底 |
|
||
| 运营商回调 | 否 | 同步应用状态，联动异步可靠投递 | 实名成功急速通道 |
|
||
| 业务事件触发 | 是 | 异步 `0/3/5` 三次 Best Effort | 提高正在操作资产的命中概率 |
|
||
| 现有手动刷新 | 是 | 保持现有响应契约 | 用户明确要求立即刷新 |
|
||
|
||
手动刷新不是第四种自动策略，也不能被业务埋点调用。
|
||
|
||
## 四、DDD 设计
|
||
|
||
### 4.1 目录
|
||
|
||
```text
|
||
internal/
|
||
├── domain/cardstate/
|
||
│ ├── card.go 卡状态聚合及状态转换
|
||
│ ├── observation.go 实名、流量、网络状态观测值
|
||
│ ├── events.go 状态变化领域事件
|
||
│ └── repository.go 聚合仓储接口
|
||
├── application/cardsync/
|
||
│ ├── request_observation.go 查询 Gateway 并获取标准观测
|
||
│ ├── apply_observation.go 在事务内应用观测和领域事件
|
||
│ ├── create_trigger_series.go 创建事件触发序列
|
||
│ ├── execute_trigger_attempt.go 执行单次阶梯尝试
|
||
│ ├── mark_activity.go 更新活跃标记
|
||
│ └── refresh_asset.go 承接现有显式刷新接口
|
||
├── infrastructure/adapter/gateway/
|
||
│ └── card_observation_adapter.go 复用现有 Gateway Client
|
||
├── infrastructure/adapter/carrier_callback/
|
||
│ ├── translator.go 防腐层统一接口
|
||
│ ├── cmcc.go
|
||
│ ├── cucc.go
|
||
│ └── ctcc.go
|
||
├── infrastructure/messaging/cardsync/
|
||
│ ├── trigger_publisher.go Outbox/Asynq 任务发布
|
||
│ └── trigger_handler.go 阶梯任务处理器
|
||
└── query/cardsync/
|
||
└── activity_query.go 活跃状态和下次轮询查询
|
||
```
|
||
|
||
### 4.2 实名要求判断
|
||
|
||
不得继续使用以下判断：
|
||
|
||
```go
|
||
if card.CardCategory == constants.CardCategoryIndustry {
|
||
// 跳过实名
|
||
}
|
||
```
|
||
|
||
现有 `tb_carrier.realname_link_type` 可以直接决定该运营商接入是否需要实名，不新增重复能力字段：
|
||
|
||
| `realname_link_type` | 实名要求 | 实名入口 |
|
||
|---|---|---|
|
||
| `none` | 不需要实名 | 不提供实名链接，不创建实名查询任务 |
|
||
| `template` | 需要实名 | 使用模板生成实名链接 |
|
||
| `gateway` | 需要实名 | 调用 Gateway 获取实名链接 |
|
||
|
||
- 资产 `realname_policy` 只决定“先实名后购买”或“先购买后实名”的业务顺序。
|
||
- `realname_link_type=none` 时，资产有效实名策略统一视为 `none`。
|
||
- `realname_link_type!=none` 时，资产 `realname_policy=none` 属于冲突数据，发布前列出并修正，禁止运行时静默选择其中一方。
|
||
- `card_category` 只保留业务分类和展示用途，不参与实名轮询、复机或套餐激活判断。
|
||
|
||
运营商是否配置回调 Adapter 只影响有没有回调急速通道，不改变 `realname_link_type` 对实名要求的判断。
|
||
|
||
### 4.3 标准化观测值
|
||
|
||
```go
|
||
type SyncSource string
|
||
|
||
const (
|
||
SyncSourcePolling SyncSource = "polling"
|
||
SyncSourceBusinessEvent SyncSource = "business_event"
|
||
SyncSourceOpenAPI SyncSource = "open_api"
|
||
SyncSourceManualRefresh SyncSource = "manual_refresh"
|
||
SyncSourceCarrierCallback SyncSource = "carrier_callback"
|
||
)
|
||
|
||
type ObservationMeta struct {
|
||
Source SyncSource
|
||
TriggerScene string
|
||
TriggerSeries string
|
||
Attempt int
|
||
Provider string
|
||
ObservedAt time.Time
|
||
RequestID string
|
||
CorrelationID string
|
||
}
|
||
|
||
type RealnameObservation struct {
|
||
CardID uint
|
||
ICCID string
|
||
Verified bool
|
||
Meta ObservationMeta
|
||
}
|
||
|
||
type TrafficObservation struct {
|
||
CardID uint
|
||
GatewayReadingMB float64
|
||
Meta ObservationMeta
|
||
}
|
||
|
||
type NetworkObservation struct {
|
||
CardID uint
|
||
CardStatus string
|
||
Extend string
|
||
GatewayIMEI string
|
||
Meta ObservationMeta
|
||
}
|
||
```
|
||
|
||
领域层不使用 `map[string]any` 传递核心状态，防止不同入口遗漏字段或混淆单位。
|
||
|
||
### 4.4 观测应用规则
|
||
|
||
`ApplyCardObservation` 是唯一允许把上游数据写入卡领域状态的入口：
|
||
|
||
1. 加载并锁定卡聚合。
|
||
2. 根据观测类型执行实名、流量或网络状态规则。
|
||
3. 状态未变化时只更新时间和观测来源，不重复产生业务事件。
|
||
4. 状态变化时保存聚合，并在同一事务写 Outbox 和关键 Audit Event。
|
||
5. 实名 `0 -> 1` 产生 `CardRealnamed`，触发卡级/设备级套餐激活和停复机评估。
|
||
6. 流量正增量产生 `CardTrafficIncreased`，由套餐应用服务扣减套餐流量。
|
||
7. 网络状态变化产生 `CardNetworkStatusChanged`，由停复机策略重新评估。
|
||
8. 状态变化或流量增加时更新卡活跃标记。
|
||
|
||
解除实名回调不构造 `Verified=false` 观测，不修改卡状态。
|
||
|
||
## 五、轮询优化：只做活跃度调频
|
||
|
||
### 5.1 全局开关
|
||
|
||
`enable_polling` 是资产是否参与自动轮询的唯一业务开关：
|
||
|
||
- `false`：从所有轮询队列移除，事件触发也不因此失效；用户主动操作仍可触发 Best Effort 同步。
|
||
- `true`：按照活跃度和运营商能力进入对应 Gateway 查询队列。
|
||
- 设备关闭轮询时，继续沿用现有设备与绑定卡级联规则。
|
||
|
||
不再提供“实名轮询开关、流量轮询开关、状态轮询开关”给业务人员配置。
|
||
|
||
### 5.2 活跃标记
|
||
|
||
卡增加或维护以下轮询调度字段：
|
||
|
||
```text
|
||
polling_activity_level active / inactive
|
||
last_polling_activity_at 最后活跃时间
|
||
last_polling_activity_scene 最后活跃场景
|
||
last_upstream_change_at 上游观测最后发生变化时间
|
||
```
|
||
|
||
以下情况标记为活跃：
|
||
|
||
| 场景 | 说明 |
|
||
|---|---|
|
||
| C 端、后台或开放接口查询资产实时信息 | 表明当前有人关心该资产 |
|
||
| 获取实名链接 | 表明即将发生实名操作 |
|
||
| 停机、复机、切卡、重启、恢复出厂设置 | 表明上游状态正在变化 |
|
||
| 套餐支付、激活、失效或流量重置 | 可能影响流量和停复机 |
|
||
| 运营商回调 | 上游已发生变化 |
|
||
| 轮询发现实名、流量或网络状态变化 | 卡当前确实活跃 |
|
||
|
||
卡在配置时间内没有业务活动，且连续轮询未发现上游变化时转为 `inactive`。该判断在每次重排队时完成，不新增全表扫描任务。
|
||
|
||
第一版建议配置而非写死：
|
||
|
||
```text
|
||
inactive_after = 30m
|
||
active_realname_interval = 现有实名默认间隔
|
||
active_traffic_interval = 现有流量默认间隔
|
||
active_network_interval = 现有状态默认间隔
|
||
inactive_realname_interval = 15m
|
||
inactive_traffic_interval = 15m
|
||
inactive_network_interval = 15m
|
||
```
|
||
|
||
现有 `tb_polling_config` 的有效间隔迁移为活跃卡默认值，但不再按 `card_condition/card_category` 匹配多套业务资格。第一版调整为一套全局活跃/不活跃间隔；运营商配置只描述接口能力和上游限频，不再决定某张卡是否“有资格”轮询。上线前使用生产数据做只读测算，确认 Gateway QPS 和最长兜底延迟后再调整数值。
|
||
|
||
### 5.3 调度规则
|
||
|
||
```text
|
||
enable_polling=false
|
||
-> 不入自动轮询队列
|
||
|
||
enable_polling=true + active
|
||
-> 使用全局活跃间隔
|
||
|
||
enable_polling=true + inactive
|
||
-> 使用全局不活跃间隔
|
||
|
||
realname_link_type=none
|
||
-> 不创建实名查询任务
|
||
```
|
||
|
||
已实名卡仍可低频查询实名状态，以发现上游实名逆转；未实名行业卡也不能因卡类别被排除。
|
||
|
||
## 六、业务事件触发
|
||
|
||
### 6.1 不是新增接口
|
||
|
||
本需求不新增 `POST /api/admin/card-sync/requests`，也不新增独立“事件同步”按钮。
|
||
|
||
现有接口保持：
|
||
|
||
```http
|
||
POST /api/admin/assets/:identifier/refresh
|
||
POST /api/c/v1/asset/refresh
|
||
```
|
||
|
||
现有批量轮询运维接口可以保留，但必须改为调用新的 Application 用例，不再自行维护另一套同步逻辑。
|
||
|
||
业务事件触发由 Application UseCase 或 Query 完成后调用内部端口：
|
||
|
||
```go
|
||
type SyncTriggerCommand struct {
|
||
Scene string
|
||
ResourceType string
|
||
ResourceID uint
|
||
CardIDs []uint
|
||
SyncTypes []string
|
||
ExpectedState map[string]any
|
||
Source SyncSource
|
||
RequestID string
|
||
CorrelationID string
|
||
}
|
||
```
|
||
|
||
写操作在业务成功后触发；有数据库事务的关键写操作通过 Outbox 发布触发事件，避免提交成功后进程退出造成埋点丢失。读操作只查询本地快照，不等待 Gateway；在返回前 Best Effort 写入 Asynq，入队失败不得改变原接口响应。
|
||
|
||
### 6.2 阶梯式尝试
|
||
|
||
每个触发序列默认创建三个 Asynq 任务：
|
||
|
||
| 尝试 | 计划时间 | Asynq 自动重试 |
|
||
|---:|---:|---:|
|
||
| 1 | 立即 | 0 |
|
||
| 2 | 事件发生后 3 分钟 | 0 |
|
||
| 3 | 事件发生后 5 分钟 | 0 |
|
||
|
||
每次任务都有确定性的 `series_id + attempt` 幂等键。单次失败不会额外重试，也不会取消后续两次；三次结束后由常规轮询兜底。
|
||
|
||
存在明确预期状态时允许提前完成序列：
|
||
|
||
- 复机后已观测为开机。
|
||
- 停机后已观测为停机。
|
||
- 获取实名链接后已通过回调或查询确认实名。
|
||
- 切卡后设备当前卡已经是目标 ICCID。
|
||
|
||
序列提前完成后，剩余任务启动时检查状态并直接记为 `completed`，不再请求 Gateway。
|
||
|
||
### 6.3 关键埋点
|
||
|
||
埋点放在应用用例成功边界，不散落在 Handler 的 `response.Success` 前后。现有 Handler 直接调用 Gateway 的路径在迁移时收口到 Application。
|
||
|
||
| 现有入口/用例 | 触发内容 | 预期状态 |
|
||
|---|---|---|
|
||
| `GET /api/c/v1/asset/info` | 资产绑定卡的实名、流量、网络状态 | 无 |
|
||
| `GET /api/admin/assets/:identifier/realtime-status` | 对应卡或设备绑定卡的实时数据 | 无 |
|
||
| `GET /api/open/v1/cards/traffic` | 流量 | 无 |
|
||
| `GET /api/open/v1/cards/status` | 网络状态 | 无 |
|
||
| `GET /api/open/v1/cards/realname-status` | 实名 | 无 |
|
||
| `GET /api/open/v1/devices/traffic` | 设备信息、绑定卡流量 | 无 |
|
||
| C 端和后台获取实名链接 | 实名 | 已实名 |
|
||
| 后台、C 端、开放接口停机/复机成功 | 网络状态 | 停机或开机 |
|
||
| 自动停复机 Gateway 调用成功 | 网络状态 | 停机或开机 |
|
||
| 订单支付、钱包购买套餐、套餐激活成功 | 实名、流量、网络状态 | 无 |
|
||
| 设备切卡或切换模式成功 | 设备信息、源卡和目标卡网络状态、目标卡流量 | 目标 ICCID |
|
||
| 设备重启、恢复出厂设置、WiFi 设置成功 | 设备信息、绑定卡网络状态 | 无 |
|
||
| 卡绑定/解绑、设备或卡分配/回收 | 只标记活跃；确有上游操作时再创建同步序列 | 无 |
|
||
|
||
补充规则：
|
||
|
||
- `POST /api/admin/assets/:identifier/refresh` 和 `POST /api/c/v1/asset/refresh` 已经直接同步，不再额外创建 `0/3/5` 序列。
|
||
- 运营商实名回调直接应用观测，不再反查 Gateway；回调成功后终止相同卡的待执行实名序列。
|
||
- 轮询发现状态变化只更新活跃标记，不反向创建新的事件序列。
|
||
- 同一次设备操作涉及多张绑定卡时使用同一 `correlation_id`，但每张卡独立限流和记录结果。
|
||
|
||
### 6.4 冷却、合并与限流
|
||
|
||
不使用一个固定五分钟 `SET NX` 键拦截所有事件。请求协调器只处理同场景合并、单卡互斥和最小请求间隔；Gateway 返回超频后不建立额外退避状态。
|
||
|
||
#### 同场景触发合并
|
||
|
||
```text
|
||
cardsync:series:{scene}:{resource_type}:{resource_id}:{sync_type}
|
||
```
|
||
|
||
- 同一场景、同一资源、同一同步类型已有未结束序列时，新触发合并到原序列。
|
||
- 合并只防止页面轮询、开放接口重试等重复创建大量 `0/3/5` 任务。
|
||
- 停复机、支付、切卡等不同业务场景不会被一个查询场景长期压制。
|
||
- 序列键只覆盖最后一次计划任务和短暂缓冲，不作为全局五分钟冷却。
|
||
|
||
#### 单卡请求互斥
|
||
|
||
```text
|
||
cardsync:inflight:{provider}:{sync_type}:{card_id}
|
||
```
|
||
|
||
- 只覆盖一次 Gateway 请求的执行时间，TTL 为请求超时加安全余量。
|
||
- 防止轮询、手动刷新和事件任务同时请求并重复应用同一观测。
|
||
- 轮询命中互斥时延迟短时间重排；事件尝试命中互斥时只跳过当前尝试，后续阶梯任务仍存在。
|
||
|
||
#### 运营商最小请求间隔
|
||
|
||
最小间隔按运营商接入和接口类型配置，例如实名、流量、状态可以不同，不能统一写死为五分钟。
|
||
|
||
- 默认兜底值建议为 10 秒，仅用于阻止近乎同时的重复调用。
|
||
- 如果上游明确给出更严格限制，以运营商配置为准。
|
||
- 高价值状态变更事件命中最小间隔时，延迟到最近允许时间，不直接丢弃整个序列。
|
||
|
||
#### 超频结果处理
|
||
|
||
- Gateway 返回超频时，当前尝试记录为 `rate_limited` 后直接结束。
|
||
- 不记录 `blocked_until`，不读取 `Retry-After`，也不执行 `30s/60s/120s` 退避。
|
||
- 不为当前尝试额外补发任务，原定 3 分钟、5 分钟尝试保持不变。
|
||
- 后续轮询仍按正常调度时间继续，是否再次超频由当时上游实际情况决定。
|
||
- 轮询、事件和手动刷新仍共享本系统的并发控制，避免本系统自身在同一时刻并发打满 Gateway。
|
||
|
||
因此，“5 分钟”是第三次尝试的计划时间，不是禁止新业务事件同步的冷却时间。
|
||
|
||
### 6.5 开放接口行为
|
||
|
||
开放接口继续返回本地快照，不等待 Gateway：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Agent as 代理系统
|
||
participant API as Open API
|
||
participant DB as PostgreSQL
|
||
participant Trigger as CreateSyncTriggerSeries
|
||
participant Worker as Sync Attempt Worker
|
||
|
||
Agent->>API: 查询实名/状态/流量
|
||
API->>DB: 查询当前本地快照
|
||
DB-->>API: 当前数据
|
||
API-->>Agent: 按现有结构立即返回
|
||
API->>Trigger: Best Effort 创建 0/3/5 序列
|
||
Trigger-->>Worker: 同场景重复请求自动合并
|
||
```
|
||
|
||
## 七、运营商实名回调防腐层
|
||
|
||
### 7.1 防腐层职责
|
||
|
||
“百分百信任回调”表示信任其业务结论，不表示让运营商报文直接进入领域模型。
|
||
|
||
```go
|
||
type CarrierRealnameCallbackTranslator interface {
|
||
TranslateSuccess(body []byte) (CarrierRealnameNotice, error)
|
||
TranslateRemoval(body []byte) (CarrierRealnameRemovalNotice, error)
|
||
SuccessResponse() CallbackResponse
|
||
FailureResponse(err error) CallbackResponse
|
||
}
|
||
```
|
||
|
||
各运营商 Adapter 负责：
|
||
|
||
- 解析 JSON、XML 或表单字段。
|
||
- 提取并校验 19/20 位 ICCID、MSISDN 等标识。
|
||
- 把运营商状态码翻译为“实名成功”或“解除实名通知”。
|
||
- 屏蔽运营商字段名、状态码和成功响应格式。
|
||
- 生成脱敏 Integration Log 摘要。
|
||
|
||
领域层只接收标准 `RealnameObservation`，不依赖移动、联通、电信的报文结构。
|
||
|
||
#### ICCID 19/20 位解析
|
||
|
||
回调必须复用现有双列存储和按长度路由规则：
|
||
|
||
```text
|
||
收到 19 位 ICCID
|
||
-> 原值查询 tb_iot_card.iccid_19
|
||
|
||
收到 20 位 ICCID
|
||
-> 原值查询 tb_iot_card.iccid_20
|
||
|
||
收到其他长度
|
||
-> invalid_payload，不进入实名用例
|
||
```
|
||
|
||
- 先去除首尾空白，再调用现有 ICCID Validator，只接受 19 位或 20 位字母数字值。
|
||
- 禁止把 20 位回调值截成 19 位后降级查询。
|
||
- 禁止为 19 位值自行补第 20 位校验位。
|
||
- 查询 Miss 时不切换另一列重试，记录原始长度、运营商和脱敏 ICCID 摘要。
|
||
- 复用 `IotCardStore.GetByICCID` 的长度路由语义；防腐层只负责提取和校验，不自己拼接模糊 SQL。
|
||
- `iccid_19` 必须在未删除卡中保持唯一。发布前检查重复前缀并建立 Partial Unique Index，避免 19 位回调错误命中任意一张卡。
|
||
- Repository 查询若发现多条匹配必须返回冲突，不允许使用 `First` 静默选择。
|
||
- Integration Log 的 `resource_key` 保存回调原始 19/20 位值，展示时按审计权限脱敏。
|
||
|
||
### 7.2 路由
|
||
|
||
```http
|
||
POST /api/callback/carriers/cmcc/realname
|
||
POST /api/callback/carriers/cucc/realname
|
||
POST /api/callback/carriers/ctcc/realname
|
||
|
||
POST /api/callback/carriers/cmcc/realname/remove
|
||
POST /api/callback/carriers/cucc/realname/remove
|
||
POST /api/callback/carriers/ctcc/realname/remove
|
||
```
|
||
|
||
- 成功回调：防腐层转换后直接调用 `ApplyCardObservation(Verified=true)`。
|
||
- 解除回调：只写统一 Integration Log，状态记为 `ignored`，不修改卡状态。
|
||
- 广电或其他没有回调能力的接入继续依赖事件和轮询。
|
||
- 不验证回调是否真的来自运营商，不执行 Gateway 二次查询。
|
||
- 不调用旧平台 `inner_callback`、第三方推送或删除实名接口。
|
||
|
||
### 7.3 响应原则
|
||
|
||
- 找到卡并应用成功：返回运营商要求的成功报文。
|
||
- 重复成功回调：幂等返回成功，不重复激活套餐。
|
||
- 找不到卡：Integration Log 记 `not_found`，仍返回成功，避免无意义高频重推。
|
||
- 报文无法解析：记录 `invalid_payload`；若运营商有固定成功应答要求，仍按接入约定返回，避免不可控重试风暴。
|
||
- 状态已落库但异步联动失败：返回成功，联动通过 Outbox 重试。
|
||
|
||
## 八、统一审计契约
|
||
|
||
同步运行数据不在本方案定义独立表和独立页面，统一由 `04-全局多视角审计方案.md` 管理。
|
||
|
||
本模块需要向审计系统提供：
|
||
|
||
| 记录 | 进入位置 |
|
||
|---|---|
|
||
| 每次 Gateway 实际请求或被限流、合并的尝试 | Integration Log |
|
||
| 每次运营商实名/解除实名回调 | Integration Log |
|
||
| 实名、流量、网络状态发生业务变化 | Audit Event + Integration Log |
|
||
| 手动刷新、手动实名修改 | Audit Event + Integration Log |
|
||
| 连续失败达到阈值、超频持续异常 | 风险 Audit Event |
|
||
| 普通高频轮询成功且数据未变化 | 仅 Integration Log |
|
||
|
||
必须携带：
|
||
|
||
```text
|
||
provider / operation / resource / trigger_scene / trigger_series
|
||
attempt / result / duration / request_id / correlation_id
|
||
state_changed / provider_code / error_summary
|
||
```
|
||
|
||
资产详情的“查看同步轨迹”跳转审计中心外部集成视角，不再建设 `/operations/card-sync` 独立监控页。
|
||
|
||
## 九、接口和前端调整
|
||
|
||
### 9.1 后端接口
|
||
|
||
本需求不新增显式同步接口。
|
||
|
||
现有手动刷新接口内部改为调用 `RefreshAssetUseCase`，响应结构和权限保持不变。现有轮询监控接口增加：
|
||
|
||
- 活跃卡数量、不活跃卡数量。
|
||
- 各活跃级别的实际轮询 QPS。
|
||
- 因互斥或运营商最小间隔而延迟的任务数，以及 Gateway 超频失败次数。
|
||
|
||
资产实时状态或详情 Query 增加可选调度信息：
|
||
|
||
```json
|
||
{
|
||
"polling": {
|
||
"enabled": true,
|
||
"activity_level": "active",
|
||
"last_activity_at": "2026-07-15T10:00:00+08:00",
|
||
"last_activity_scene": "client_asset_info",
|
||
"next_poll_at": "2026-07-15T10:01:00+08:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
同步明细查询复用全局审计接口：
|
||
|
||
```http
|
||
GET /api/admin/audit/integrations
|
||
?provider=gateway
|
||
&resource_type=iot_card
|
||
&resource_key=89860...
|
||
&trigger_scene=
|
||
&trigger_series=
|
||
```
|
||
|
||
### 9.2 前端
|
||
|
||
保留现有资产刷新按钮，不新增第二个同步按钮。
|
||
|
||
资产详情增加紧凑的轮询状态展示：
|
||
|
||
```text
|
||
自动轮询：已开启
|
||
活跃状态：活跃
|
||
最后活跃：2分钟前，C端资产详情
|
||
下次兜底：约1分钟后
|
||
同步轨迹：查看
|
||
```
|
||
|
||
“查看”跳转：
|
||
|
||
```text
|
||
/operations/audit?tab=integrations&resource_type=iot_card&resource_key={identifier}
|
||
```
|
||
|
||
轮询监控页只增加活跃/不活跃分布和限流状态，不重复实现 Integration Log 表格、详情抽屉和导出。
|
||
|
||
## 十、代码迁移范围
|
||
|
||
### 10.1 必须删除或收口
|
||
|
||
- 删除 `PollingRealnameHandler` 按 `CardCategoryIndustry` 跳过实名的判断。
|
||
- 修正 `pkg/constants/iot.go` 中“普通卡必需实名、行业卡无需实名”的绝对化注释和依赖逻辑。
|
||
- `PollingRealnameHandler`、`PollingCarddataHandler`、`PollingCardStatusHandler` 只调用 Application 用例，不再直接更新卡或执行业务联动。
|
||
- 删除重复流量增量算法，只保留领域实现。
|
||
- `RefreshCardDataFromGateway` 改为调用 `RequestCardObservation + ApplyCardObservation`。
|
||
- `ManualUpdateRealnameStatus` 改为调用领域用例。
|
||
- 获取实名链接后的 `ManualTriggerService.TriggerSingle` 改为 `CreateSyncTriggerSeries`。
|
||
- C 端和后台设备操作中直接调用 Gateway 的路径迁入 Application，再在用例成功边界创建触发序列。
|
||
|
||
### 10.2 保留并复用
|
||
|
||
- Gateway Client 的加密、签名和 HTTP 封装。
|
||
- Redis 分片 Sorted Set 调度基础设施。
|
||
- Asynq Worker。
|
||
- 卡流量同步锁，迁移为通用请求互斥实现。
|
||
- 现有资产手动刷新接口和权限契约。
|
||
- 现有批量轮询运维能力；其执行逻辑和记录迁入新用例与统一审计后，再下线旧专用日志表。
|
||
|
||
### 10.3 数据变更
|
||
|
||
- 不新增实名要求字段，继续以 `tb_carrier.realname_link_type` 判断是否需要实名及链接生成方式。
|
||
- 发布前检查 `iccid_19` 重复数据并建立未删除数据范围内的唯一索引，保证 19 位回调精确命中。
|
||
- 卡增加轮询活跃标记字段，或由独立调度状态表保存；实现阶段根据写入频率决定，不能把高频调度心跳写入核心卡表。
|
||
- 现有 `tb_polling_config` 条件匹配迁移为单一全局活跃/不活跃策略，不再使用 `card_condition/card_category` 形成隐式轮询资格。
|
||
- 事件任务载荷增加 `scene/series_id/attempt/source/request_id/correlation_id/expected_state`。
|
||
- 不创建 `tb_card_sync_execution`。
|
||
|
||
## 十一、发布与人工验证
|
||
|
||
停机发布，API 与 Worker 同时切换：
|
||
|
||
1. 验证 `realname_link_type=none/template/gateway` 分别对应无需实名、模板实名和 Gateway 实名，不再按行业卡统一跳过。
|
||
2. 验证 `enable_polling=false` 会移除自动轮询，但业务事件和手动刷新仍能按各自规则工作。
|
||
3. 验证活跃卡使用活跃间隔，不活跃卡使用低频间隔，重新活跃后立即恢复。
|
||
4. 验证一次业务事件形成立即、3 分钟、5 分钟三个任务。
|
||
5. 验证停复机、实名和切卡达到预期状态后，剩余任务不再请求 Gateway。
|
||
6. 验证同场景高频查询只合并重复序列，不压制新的停复机或支付事件。
|
||
7. 验证单卡互斥只覆盖请求执行时间，不形成五分钟全局冷却。
|
||
8. 验证 Gateway 超频时当前尝试直接记为 `rate_limited`，不创建退避状态，后续阶梯任务仍保留。
|
||
9. 验证现有后台和 C 端刷新接口契约不变，且不额外创建阶梯序列。
|
||
10. 验证移动、联通、电信回调均先经过防腐层，19 位和 20 位 ICCID 分别按双列精确路由，重复成功回调不重复激活套餐。
|
||
11. 验证解除实名回调只写 Integration Log，不修改卡实名状态。
|
||
12. 验证开放接口仍立即返回本地数据，事件触发失败不改变响应。
|
||
13. 验证普通同步、状态变化、手动刷新和连续失败能够在审计中心按资源和触发序列查询。
|