第64章　Adapter

1. Adapter 定义

Adapter 是 SATE 中负责将 Renderer 产生的表现结果连接到实际输出环境 的组件。

上一章已经确定：

Expression
    ↓
Template
    ↓
Renderer
    ↓
Rendered Result
    ↓
Adapter
    ↓
Output

其中：

Renderer
= 表现成什么

Adapter
= 输出到哪里、如何连接目标环境

例如：

ApiRenderer
    ↓
JSON
    ↓
ApiAdapter
    ↓
External API

WebRenderer
    ↓
HTML
    ↓
WebAdapter
    ↓
Browser

DeviceRenderer
    ↓
Device Data
    ↓
DeviceAdapter
    ↓
Device

Adapter 不负责：

感知
认知
理解
推理
决策
学习
记忆
表现格式设计

它主要负责连接与输出。

因此：

Adapter ≠ Renderer
Adapter ≠ Action
Adapter ≠ Device
Adapter ≠ External System

核心定义：

Adapter 是系统与外部表现环境之间的连接与输出组件，用于将 Renderer 产生的结果传递到指定目标。

2. Adapter Interface

为了让不同 Adapter 能够被统一管理，可以定义 Adapter Interface。

基本接口：

interface AdapterInterface
{
    public function send($data, $target = null);

    public function supports($target);

    public function getName();
}

例如 WebAdapter：

class WebAdapter implements AdapterInterface
{
    public function send($data, $target = null)
    {
        return $data;
    }

    public function supports($target)
    {
        return $target === 'WEB';
    }

    public function getName()
    {
        return 'WebAdapter';
    }
}

ApiAdapter：

class ApiAdapter implements AdapterInterface
{
    public function send($data, $target = null)
    {
        return $data;
    }

    public function supports($target)
    {
        return $target === 'API';
    }

    public function getName()
    {
        return 'ApiAdapter';
    }
}

DeviceAdapter：

class DeviceAdapter implements AdapterInterface
{
    public function send($data, $target = null)
    {
        return $data;
    }

    public function supports($target)
    {
        return $target === 'DEVICE';
    }

    public function getName()
    {
        return 'DeviceAdapter';
    }
}

统一接口的意义是：

AdapterInterface
       │
       ├── WebAdapter
       ├── ApiAdapter
       ├── DeviceAdapter
       ├── FileAdapter
       └── ConsoleAdapter

不同 Adapter 可以使用不同的连接方式，但保持统一调用结构。

3. Adapter Manager

当系统存在多个 Adapter 时，需要 Adapter Manager 负责管理。

基本结构：

AdapterManager
{
    adapters

    register()
    remove()
    get()
    find()
    send()
}

PHP 示例：

class AdapterManager
{
    protected $adapters = array();

    public function register(AdapterInterface $adapter)
    {
        $this->adapters[$adapter->getName()] = $adapter;
    }

    public function get($name)
    {
        if (!isset($this->adapters[$name])) {
            return null;
        }

        return $this->adapters[$name];
    }

    public function send($name, $data, $target = null)
    {
        $adapter = $this->get($name);

        if (!$adapter) {
            return null;
        }

        return $adapter->send($data, $target);
    }
}

$manager = new AdapterManager();

$manager->register(new WebAdapter());
$manager->register(new ApiAdapter());
$manager->register(new DeviceAdapter());

调用：

$result = $manager->send(
    'ApiAdapter',
    $json,
    'API'
);

Adapter Manager 的核心职责：

Adapter 注册
    ↓
Adapter 查找
    ↓
Adapter 选择
    ↓
Adapter 调用
    ↓
Adapter Result

它本身也不执行认知和推理。

4. Adapter 注册

Adapter 必须先注册，系统才能使用。

基本流程：

Create Adapter
    ↓
Validate
    ↓
Register
    ↓
Available

例如：

$manager->register(
    new ApiAdapter()
);

注册以后：

AdapterManager
    │
    ├── WebAdapter
    ├── ApiAdapter
    └── DeviceAdapter

也可以保存 Adapter 的基本信息：

Adapter
{
    id
    name
    type
    target
    configuration
    state
}

例如：

Adapter
{
    id: 1001,
    name: "ApiAdapter",
    type: "API",
    target: "ExternalSystem",
    state: "ACTIVE"
}

Adapter 状态可以包括：

NEW
ACTIVE
INACTIVE
ERROR
DISABLED
INVALID

只有 ACTIVE 的 Adapter 才应该被正常调用。

5. Adapter 调用

Adapter 调用发生在 Renderer 完成表现转换之后。

例如 API：

Expression
    ↓
ApiRenderer
    ↓
JSON
    ↓
ApiAdapter

JSON：

{
    "success": true,
    "data": {
        "id": 1001,
        "state": "created"
    }
}

调用：

$result = $apiAdapter->send(
    $json,
    'API'
);

或者通过 Manager：

$result = $adapterManager->send(
    'ApiAdapter',
    $json,
    'API'
);

完整调用：

Rendered Result
      ↓
AdapterManager
      ↓
ApiAdapter
      ↓
Target

调用之前可以进行：

Adapter 是否存在
Adapter 是否 ACTIVE
Target 是否有效
Data 是否完整
Connection 是否可用
执行发送

如果条件不满足，不应该假设发送成功。

6. Adapter 返回

Adapter 不只是“发送”，还应该返回明确的执行结果。

可以定义：

AdapterResult
{
    adapter_id
    target
    state
    success
    output
    error
    started_at
    completed_at
}

成功：

AdapterResult
{
    adapter_id: 1001,
    target: "API",
    state: "SUCCESS",
    success: true,
    output: {
        status: 200
    },
    error: null
}

失败：

AdapterResult
{
    adapter_id: 1001,
    target: "API",
    state: "FAILED",
    success: false,
    output: null,
    error: {
        code: "CONNECTION_ERROR",
        message: "Target unavailable"
    }
}

因此：

Renderer Result
    ↓
Adapter
    ↓
AdapterResult

这里需要严格区分：

ActionResult
= Action 执行结果

ExpressionResult
= 表现结果

AdapterResult
= 输出连接结果

三者不是同一个结果。

例如：

ActionResult
SUCCESS
    ↓
ExpressionResult
SUCCESS
    ↓
AdapterResult
FAILED

完全可能发生。

原因可能是：

Action 本身执行成功
→ 表现数据形成成功
→ 外部系统连接失败

因此系统不能因为 Action 成功，就直接认为 External Output 成功。

7. Adapter 与 Device

DeviceAdapter 是连接系统与设备的 Adapter。

基本关系：

Expression
    ↓
DeviceRenderer
    ↓
Device Data
    ↓
DeviceAdapter
    ↓
Device

例如：

Expression
{
    type: "STATE",
    target: "Device_A",

    data: {
        power: "ON",
        mode: "NORMAL"
    }
}

DeviceRenderer：

DEVICE_STATE
POWER=ON
MODE=NORMAL

然后：

DeviceAdapter
    ↓
Device_A

DeviceAdapter 负责：

找到目标设备
检查设备连接状态
转换连接协议需要的数据
发送数据
接收返回
形成 AdapterResult

但必须明确：

DeviceAdapter
≠ Device

DeviceAdapter
= 系统与 Device 的连接层

例如：

System
   ↓
DeviceRenderer
   ↓
Device Representation
   ↓
DeviceAdapter
   ↓
Device

如果设备返回：

POWER=ON
MODE=NORMAL

Adapter 可以形成：

AdapterResult
{
    success: true,
    state: "SUCCESS",
    output: {
        power: "ON",
        mode: "NORMAL"
    }
}

之后这个结果是否进入：

Perception
Cognition
Memory
Experience

则由系统后续流程决定，而不是由 Adapter 自己完成。

8. Adapter 与 External System

Adapter 同样可以连接外部系统。

例如：

ICAI
 ↓
Expression
 ↓
ApiRenderer
 ↓
JSON
 ↓
ApiAdapter
 ↓
External System

External System 可以是：

Website
API
ERP
CRM
Database Interface
Business System
Remote Service

例如：

JSON
{
    "order_id": 5001,
    "state": "created"
}

ApiAdapter：

ApiAdapter
    ↓
External API

外部系统返回：

{
    "success": true,
    "received": true
}

Adapter 接收以后形成：

AdapterResult
{
    state: "SUCCESS",
    success: true,

    output: {
        received: true
    }
}

完整链路：

ICAI
 ↓
Decision
 ↓
Behavior
 ↓
Action
 ↓
ActionResult
 ↓
Expression
 ↓
Template
 ↓
Renderer
 ↓
Rendered Result
 ↓
Adapter
 ↓
External System
 ↓
External Result
 ↓
AdapterResult

这时候 Adapter 是系统边界上的重要连接层。

Adapter 完整架构

第64章最终可以形成：

                         ICAI
                           ↓
                       Expression
                           ↓
                         SATE
                           ↓
                        Template
                           ↓
                        Renderer
                           ↓
                    Rendered Result
                           ↓
                    Adapter Manager
                           ↓
             ┌─────────────┼─────────────┐
             ↓             ↓             ↓
        WebAdapter     ApiAdapter   DeviceAdapter
             ↓             ↓             ↓
          Browser     External API    Device

如果继续扩展：

AdapterManager
     │
     ├── WebAdapter
     ├── ApiAdapter
     ├── DeviceAdapter
     ├── FileAdapter
     ├── ConsoleAdapter
     └── SystemAdapter

Renderer 与 Adapter 的最终边界

这一章最重要的是把两者彻底区分：

Expression
    ↓
Renderer
    ↓
表现成什么
    ↓
Adapter
    ↓
连接到哪里
    ↓
External Environment

例如：

Expression
    ↓
ApiRenderer
    ↓
JSON
    ↓
ApiAdapter
    ↓
External API

或者：

Expression
    ↓
WebRenderer
    ↓
HTML
    ↓
WebAdapter
    ↓
Browser

或者：

Expression
    ↓
DeviceRenderer
    ↓
Device Data
    ↓
DeviceAdapter
    ↓
Device

核心定义

Adapter 是 SATE 与外部环境之间的连接与输出组件，负责接收 Renderer 产生的表现结果，按照目标环境的连接方式进行传递，并返回明确的 AdapterResult。

最终模型：

Expression
    ↓
Template
    ↓
Renderer
    ↓
Rendered Result
    ↓
Adapter Manager
    ↓
Adapter
    ↓
External Environment
    ↓
AdapterResult

因此 SATE 到外部环境的完整表现链已经形成：

Expression
    ↓
Template
    ↓
Renderer
    ↓
Adapter
    ↓
Output

其中：

Expression = 表现什么
Template   = 如何组织表现
Renderer   = 表现成什么格式
Adapter    = 连接到什么环境
Output     = 外部实际结果

Adapter 是 SATE 从“表现系统”进入“外部环境”的边界层。

第64章 Adapter

第64章 Adapter

1. Adapter 定义

2. Adapter Interface

3. Adapter Manager

4. Adapter 注册

5. Adapter 调用

6. Adapter 返回

7. Adapter 与 Device

8. Adapter 与 External System

Adapter 完整架构

Renderer 与 Adapter 的最终边界

核心定义