iotlcm/docs/plans/channel-template-model-design.md

通道模板模型设计

1. 设计结论

通道配置分成三层：

temp_model  接入方式大类
temp_key    具体上游协议模板
chan_config 具体通道的账号凭证和运行时状态

temp_model 只使用两个值：

direct        直接调用上游 API
shared_token  先获取共享 Token，再调用业务 API

direct 是分类值，不是通用实现。普通模板必须通过 temp_key 找到精确注册的协议实现；不能仅凭 direct 推断运营商或请求协议。 shared_token 是共享 Token 模型的路由值，可以由共享实现工厂创建具体通道。

2. Mermaid 架构图

flowchart TB
    DB["模板数据"] --> TEMPLATE["通道模板"]
    TEMPLATE --> KEY["temp_key\n具体协议模板"]
    TEMPLATE --> MODEL["temp_model\n接入方式"]

    MODEL --> DIRECT["direct\n直接调用上游 API"]
    MODEL --> SHARED["shared_token\n先获取共享 Token"]

    KEY --> TY["sim_recharge_sdtywl_v1\n腾宇直连"]
    KEY --> YD["sim_yd_v5\n中国移动官方"]
    KEY --> DX["sim_dx_v1\n中国电信官方"]
    KEY --> TY_SHARED["sim_onelink_tengyu_v1\n腾宇获取 Token + OneLink"]
    KEY --> XZ_SHARED["sim_onelink_xuzhou_mobile_v1\n徐州移动获取 Token + OneLink"]

    TY --> DIRECT_IMPL["精确 temp_key 注册的 direct 实现"]
    YD --> DIRECT_IMPL
    DX --> DIRECT_IMPL

    TY_SHARED --> SHARED_IMPL["shared_token 模型工厂\n复用 OneLink 业务能力"]
    XZ_SHARED --> SHARED_IMPL
    SHARED_IMPL --> PROVIDER["Token Provider"]
    PROVIDER --> TOKEN["共享 Token"]
    TOKEN --> ONELINK["OneLink 业务 API"]

    CREATE["新建通道"] --> SELECT["选择已有 temp_key"]
    SELECT --> CREDENTIALS["填写通道凭证"]
    CREDENTIALS --> CHANNEL["t_sim_channels"]

    RULES["规则"] --> R1["temp_model 只有 direct / shared_token"]
    RULES --> R2["temp_key 决定具体协议"]
    RULES --> R3["direct 必须有精确注册"]
    RULES --> R4["shared_token 使用共享工厂"]

3. 模板示例

sim_yd_v5
    temp_model = direct
    中国移动官方 OneLink

sim_yd_mock_v5
    temp_model = direct
    中国移动 Mock OneLink

sim_dx_v1
    temp_model = direct
    中国电信 CMP

sim_recharge_sdtywl_v1
    temp_model = direct
    腾宇直连 API

sim_onelink_tengyu_v1
    temp_model = shared_token
    腾宇获取 Token + OneLink

sim_onelink_xuzhou_mobile_v1
    temp_model = shared_token
    徐州移动获取 Token + OneLink

4. 路由规则

运行时始终先按 temp_key 查找精确实现。精确注册优先于模型工厂，因此现有直连通道的协议行为不会因为模型分类改变。

当没有精确 temp_key 注册时：

• temp_model=shared_token 使用共享 Token 模型工厂。
• temp_model=direct 返回明确错误，因为 direct 本身不描述具体协议。
• 空值、未知值或旧的具体实现名称返回明确配置错误。

5. 新增三方协议流程

1. 实现三方协议的请求、签名、响应映射、错误处理和业务能力。
2. 增加新的 temp_key 并注册精确实现。
3. 为模板设置 temp_model=direct；如果需要共享 Token，则设置 temp_model=shared_token。
4. 在模板数据中保存公共配置，通道数据中保存账号凭证。
5. 业务人员创建通道时选择已有 temp_key，只填写该通道自己的凭证。

6. 配置边界

模板配置适合保存公共 API 地址、固定路径、超时时间和其他非账号协议参数。 通道配置适合保存 appKey、appSecret、pwdKey、channelNo、appId、账号密码及该通道独立的 Token 状态。

配置不能试图描述完整协议；新增协议通常仍需要修改代码。

7. 迁移约束

• 新代码只接受 direct 和 shared_token 两个模型值。
• 部署前通过 DBX 将现有普通模板修正为 direct，共享 Token 模板修正为 shared_token。
• 旧的 onelink、onelink_mock、telecom、shared_token_onelink 不作为新配置值保留。
• 发现无法根据 temp_key 判断类型的模板时，停止自动迁移并人工确认。
• 本仓库不提交数据库修复 SQL；数据库变更由 DBX 直接执行。