# 第三方服务结构化设计

## 背景

当前后台已经将配置相关能力拆分为两层：

- `场景配置`：定义一个最终要运行的业务场景
- `基础配置`：承载场景配置引用的公共配置

在现有项目中，第三方服务相关配置仍然散落在模板参数中，没有独立的结构和复用关系。当前已确认存在的第三方服务参数包括：

- 对象存储：`minio_endpoint`、`minio_bucket`、`minio_access_key`、`minio_secret_key`
- 认证服务：`external_get_token_url`
- 告警服务：`external_put_message_url`
- 租户字段：`tenant_code`

这些配置本质上不是某个单独场景私有的内容，而是会被多个场景反复引用的基础服务配置。继续把它们直接放在模板或场景参数里，会带来几个问题：

- 相同服务地址和密钥在多个场景中重复填写
- 修改服务地址或凭据时，需要逐个场景同步修改
- 难以判断某个第三方服务被哪些场景使用
- 服务配置与识别模板逻辑混在一起，页面职责不清楚

因此，这一轮设计的目标是把“第三方服务”独立为一类可复用的基础配置。

## 目标

本次设计只解决下面这些问题：

1. 为第三方服务建立统一、结构化的数据模型
2. 在 `基础配置` 中提供独立的 `第三方服务` 管理入口
3. 让 `场景配置` 通过引用第三方服务完成配置，而不是直接填写服务参数
4. 在生成最终 agent 配置时，将服务引用展开为现有模板参数

## 非目标

本次不包含以下内容：

- 不引入多环境字段，如 `prod / test`
- 不引入适用范围字段，如客户 / 项目 / 站点
- 不做复杂权限模型
- 不做服务连通性探测
- 不做密码加密存储方案升级
- 不支持自定义服务类型

第一版只覆盖项目中已经真实存在的三类第三方服务。

## 服务类型

第一版支持以下三种服务类型：

1. `object_storage`：对象存储
2. `token_service`：认证服务
3. `alarm_service`：告警服务

页面文案使用中文：

- 对象存储
- 认证服务
- 告警服务

## 数据模型

### 顶层公共字段

所有第三方服务共享以下字段：

- `name`：服务名称，唯一标识
- `type`：服务类型
- `description`：描述
- `enabled`：是否启用
- `config`：按服务类型存储的结构化字段

推荐的数据结构如下：

```json
{
  "name": "minio_prod_main",
  "type": "object_storage",
  "description": "主对象存储",
  "enabled": true,
  "config": {
    "endpoint": "http://10.0.0.49:9000",
    "bucket": "myminio",
    "access_key": "admin",
    "secret_key": "password"
  }
}
```

这种设计的关键点是：

- 顶层字段保持简单，便于列表展示和统一管理
- 类型差异收纳在 `config` 中，避免一张平表容纳所有服务字段
- 后续增加新服务类型时，不需要推翻已有结构

### 类型字段

#### 对象存储

字段：

- `endpoint`
- `bucket`
- `access_key`
- `secret_key`

#### 认证服务

字段：

- `get_token_url`
- `username`
- `password`
- `tenant_code`

#### 告警服务

字段：

- `put_message_url`
- `username`
- `password`
- `tenant_code`

## 与现有模板参数的映射

为了兼容当前 agent 模板，第三方服务字段需要在预览和下发阶段映射回模板参数。

映射关系如下：

### 对象存储

- `config.endpoint` -> `minio_endpoint`
- `config.bucket` -> `minio_bucket`
- `config.access_key` -> `minio_access_key`
- `config.secret_key` -> `minio_secret_key`

### 认证服务

- `config.get_token_url` -> `external_get_token_url`
- `config.tenant_code` -> `tenant_code`

### 告警服务

- `config.put_message_url` -> `external_put_message_url`
- `config.tenant_code` -> `tenant_code`

说明：

- `username` 和 `password` 在第一版中先作为结构化存储字段保留
- 是否映射到模板参数，取决于具体模板是否已经定义对应参数
- 如果当前模板没有用到用户名和密码，这两个字段暂时只在后台维护，不强制写入模板参数

## 场景配置中的引用方式

场景配置不再直接保存第三方服务的 URL、密钥和租户字段，而是保存服务引用。

建议增加以下引用字段：

- `object_storage_ref`
- `token_service_ref`
- `alarm_service_ref`

示例：

```json
{
  "object_storage_ref": "minio_prod_main",
  "token_service_ref": "token_service_prod",
  "alarm_service_ref": "alarm_center_prod"
}
```

这样做的好处是：

- 多个场景可以复用同一组基础服务
- 修改服务地址或凭据时，无需逐个调整场景
- 后台可以反查“某个服务被哪些场景引用”
- 场景配置页面更聚焦于业务场景本身，而不是堆满连接参数

## 预览与下发的数据流

生成最终 agent 配置时，数据流按以下顺序处理：

1. 读取场景配置
2. 解析场景中引用的第三方服务名称
3. 加载对应第三方服务配置
4. 按服务类型展开为模板参数
5. 合并模板默认参数、场景参数、调试参数和第三方服务参数
6. 生成最终配置预览或下发内容

参数优先级建议保持清晰：

1. 模板默认参数
2. 场景配置显式参数
3. 第三方服务展开参数
4. 调试参数覆盖

如果同名字段冲突，后面的层级覆盖前面的层级。

## 存储设计

后台当前 `assets_repo` 已经持久化模板、场景配置和调试参数。第一版建议延续这个模式，为第三方服务新增独立存储。

建议新增一类持久化对象：

- 表名可使用 `integration_services`

每条记录至少包含：

- `name`
- `type`
- `description`
- `enabled`
- `config_json`
- `created_at`
- `updated_at`

其中 `config_json` 保存类型字段。

这样可以避免在数据库层为三类服务各建一张表，保持实现简单，同时保留后续扩展空间。

## 后端结构建议

建议在服务层新增一个明确模型，例如：

```go
type ThirdPartyServiceAsset struct {
    Name        string
    Type        string
    Description string
    Enabled     bool
    Config      map[string]any
}
```

如果后续需要更强约束，可以进一步拆出按类型的辅助结构，但第一版不必过度设计。

建议新增以下能力：

- 列表读取
- 单项读取
- 新建 / 编辑 / 删除
- 引用计数查询
- 按场景展开为模板参数

## UI 设计

### 入口位置

主入口保持在：

- `基础配置 -> 第三方服务`

### 列表页

列表页先展示最重要的信息，字段建议如下：

- 服务名称
- 服务类型
- 描述
- 地址摘要
- 启用状态
- 引用数量

地址摘要按类型生成：

- 对象存储：显示 `endpoint / bucket`
- 认证服务：显示 `get_token_url`
- 告警服务：显示 `put_message_url`

这样用户可以快速判断服务是做什么的，以及是否大致配置正确。

### 详情 / 编辑页

详情和编辑页分为两块：

1. 基本信息
   - 名称
   - 类型
   - 描述
   - 启用状态

2. 服务配置
   - 根据服务类型显示不同字段

字段展示规则：

- 密码和 `secret_key` 默认掩码显示
- 列表页不展示敏感字段
- 类型切换时动态切换表单字段

## 校验规则

### 通用校验

- 名称不能为空
- 名称必须唯一
- 类型不能为空

### 对象存储校验

- `endpoint` 必填
- `bucket` 必填
- `access_key` 必填
- `secret_key` 必填

### 认证服务校验

- `get_token_url` 必填
- `tenant_code` 可选
- `username`、`password` 可选

### 告警服务校验

- `put_message_url` 必填
- `tenant_code` 可选
- `username`、`password` 可选

## 删除与引用约束

第三方服务被场景配置引用时，不应允许直接删除。

删除前需要检查：

- 是否有场景配置正在引用该服务

如果存在引用，应提示：

- 当前服务已被某些场景配置使用，不能删除

这与模板删除前检查引用的现有交互保持一致。

## 第一阶段实施范围

第一阶段只实现以下能力：

1. 第三方服务的数据结构和存储
2. `基础配置 -> 第三方服务` 列表与详情编辑
3. 场景配置对第三方服务的引用
4. 配置预览与下发时的参数展开
5. 删除前引用检查

## 后续扩展方向

本设计为后续扩展保留空间，但不在第一阶段实现：

- 新增更多服务类型，如 MQTT、Kafka、Webhook
- 服务连通性测试按钮
- 敏感字段加密存储
- 按客户或项目进行服务分组
- 服务变更审计

## 结论

第三方服务应当被视为一类可复用的基础配置，而不是模板参数的零散集合。

通过引入独立的第三方服务结构：

- 可以降低场景配置的重复录入
- 可以集中管理 URL、租户和凭据
- 可以让模板、场景和服务的职责分离
- 可以为后续更完整的配置治理打下基础

第一版只支持对象存储、认证服务、告警服务三类，已经足够覆盖当前项目里的真实需求，并且能与现有 agent 模板参数平滑兼容。