# 通道模板模型设计

## 1. 设计结论

通道配置分成三层：

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

`temp_model` 只使用两个值：

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

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

## 2. Mermaid 架构图

```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. 模板示例

```text
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 直接执行。