# 管理后台开发文档

**版本**: v1.0  
**日期**: 2026-03-07  
**作者**: AI Assistant

---

## 目录

1. [功能概述](#一功能概述)
2. [架构设计](#二架构设计)
3. [核心模块](#三核心模块)
4. [API接口文档](#四api接口文档)
5. [前端实现](#五前端实现)
6. [使用指南](#六使用指南)
7. [待完善事项](#七待完善事项)

---

## 一、功能概述

管理后台为行情数据服务提供统一的可视化管理界面，支持配置热加载、数据源适配器管理、接口测试等功能。

### 1.1 功能模块

| 模块 | 功能描述 | 状态 |
|------|----------|------|
| 系统概览 | 实时监控系统状态、内存使用、运行时长 | ✅ 已完成 |
| 配置管理 | 在线修改配置、热加载、配置持久化 | ✅ 已完成 |
| 数据源适配 | 适配器管理、启用/禁用、配置更新 | ✅ 已完成 |
| 接口测试 | API测试、WebSocket测试、历史记录 | ✅ 已完成 |

### 1.2 技术特性

- **热加载**: 配置修改后无需重启服务即可生效
- **实时状态**: 系统运行状态定时刷新（5秒间隔）
- **单页应用**: 纯前端实现，无页面刷新
- **响应式设计**: 适配桌面端浏览器

---

## 二、架构设计

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                         前端层                                │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐            │
│  │  系统概览    │ │  配置管理    │ │  数据源适配  │  接口测试   │
│  └─────────────┘ └─────────────┘ └─────────────┘            │
│                         │                                   │
│                    内嵌HTML/JS                               │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP API
┌─────────────────────────┼───────────────────────────────────┐
│                         ▼                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                   AdminRouter                         │  │
│  │  (api/admin_router.go)                               │  │
│  └──────────────────────────────────────────────────────┘  │
│                         │                                   │
│                         ▼                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │                AdminHandlerImpl                       │  │
│  │  (internal/handler/admin.go)                         │  │
│  └──────────────────────────────────────────────────────┘  │
│                         │                                   │
│       ┌─────────────────┼─────────────────┐                 │
│       ▼                 ▼                 ▼                 │
│  ┌─────────┐      ┌─────────┐      ┌─────────┐             │
│  │Config   │      │Adapter  │      │Test     │             │
│  │Service  │      │Service  │      │Service  │             │
│  └─────────┘      └─────────┘      └─────────┘             │
│                                                         服务层│
└─────────────────────────────────────────────────────────────┘
```

### 2.2 目录结构

```
market-data-service/
├── api/
│   ├── admin_types.go          # 管理后台类型定义 (270行)
│   └── admin_router.go         # 管理后台路由 + HTML页面 (680行)
├── internal/
│   ├── handler/
│   │   └── admin.go            # 管理后台Handler (180行)
│   └── service/
│       ├── config.go           # 配置管理服务 (330行)
│       ├── adapter.go          # 适配器管理服务 (220行)
│       └── test.go             # 测试服务 (350行)
├── pkg/
│   └── config/
│       └── config.go           # 配置结构定义
├── cmd/server/
│   └── main.go                 # 服务入口（集成管理后台）
└── docs/
    └── admin-dashboard-development.md  # 本文档
```

---

## 三、核心模块

### 3.1 配置管理服务 (ConfigService)

**文件**: `internal/service/config.go`

#### 功能
- 配置加载与保存（JSON格式）
- 热加载配置（支持按类型选择性加载）
- 配置变更回调机制
- 系统状态监控

#### 核心接口

```go
type ConfigService interface {
    GetConfigList(ctx context.Context, req *api.ConfigListRequest) (*api.ConfigListData, error)
    UpdateConfig(ctx context.Context, req *api.ConfigUpdateRequest) (*api.ConfigUpdateData, error)
    ReloadConfig(ctx context.Context, req *api.ReloadRequest) (*api.ConfigUpdateData, error)
    GetSystemStatus(ctx context.Context) (*api.SystemStatusData, error)
    GetCurrentConfig() *config.Config
}
```

#### 配置类型

| 配置类型 | 说明 | 热加载支持 |
|----------|------|-----------|
| server | 服务器端口、运行模式、API Key | 部分需重启 |
| database | 数据库连接配置 | 需重启 |
| redis | Redis连接配置 | 需重启 |
| source | 数据源适配器配置 | ✅ 支持 |

#### 使用示例

```go
// 创建配置服务
configService, err := service.NewConfigService("./config.json")

// 获取配置列表
data, err := configService.GetConfigList(ctx, &api.ConfigListRequest{Type: "server"})

// 更新配置
result, err := configService.UpdateConfig(ctx, &api.ConfigUpdateRequest{
    Type: "server",
    Items: map[string]interface{}{
        "port": 8080,
        "mode": "release",
    },
})

// 热加载配置
result, err := configService.ReloadConfig(ctx, &api.ReloadRequest{ConfigType: "source"})
```

---

### 3.2 适配器管理服务 (AdapterService)

**文件**: `internal/service/adapter.go`

#### 功能
- 适配器工厂注册
- 适配器启用/禁用
- 适配器配置管理
- 适配器实例管理

#### 适配器状态

| 状态 | 说明 |
|------|------|
| active | 已激活，正在使用 |
| standby | 待命，可用但未激活 |
| disabled | 已禁用 |
| error | 发生错误 |

#### 核心接口

```go
type AdapterService interface {
    GetAdapterList(ctx context.Context) (*api.AdapterListData, error)
    ToggleAdapter(ctx context.Context, req *api.AdapterToggleRequest) error
    UpdateAdapterConfig(ctx context.Context, req *api.AdapterConfigUpdateRequest) error
    GetActiveAdapter(assetClass string) (adapter.DataSourceAdapter, error)
    RegisterAdapter(name string, factory AdapterFactory)
}
```

#### 内置适配器

| 适配器 | 类型 | 状态 | 说明 |
|--------|------|------|------|
| tushare | HTTP | 已实现 | Tushare Pro 数据接口 |
| wind | WebSocket | 预留 | Wind 金融终端（待实现） |

---

### 3.3 测试服务 (TestService)

**文件**: `internal/service/test.go`

#### 功能
- API接口测试用例管理
- WebSocket连接测试
- 测试历史记录
- 实时测试执行

#### 测试分类

**API测试**:
- 股票接口：K线查询、标的列表、批量查询、交易日历
- 期货接口：K线查询、标的列表、批量查询、合约查询
- 管理接口：健康检查、数据源状态

**WebSocket测试**:
- 订阅股票行情
- 订阅期货行情
- 批量订阅
- 取消订阅

#### 核心接口

```go
type TestService interface {
    GetAPITestList(ctx context.Context) (*api.APITestListData, error)
    RunAPITest(ctx context.Context, baseURL string, req *api.APITestRequest) (*api.APITestResult, error)
    GetWSTestList(ctx context.Context) (*api.WSTestListData, error)
    RunWSTest(ctx context.Context, wsURL string, req *api.WSTestRequest) (*api.WSTestResult, error)
    GetTestHistory(ctx context.Context, req *api.TestHistoryRequest) (*api.TestHistoryData, error)
}
```

---

## 四、API接口文档

### 4.1 系统管理接口

#### 获取系统状态
```
GET /v1/admin/system/status
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "status": "running",
    "version": "1.0.0",
    "start_time": "2026-03-07T13:00:00Z",
    "uptime": "1小时30分钟",
    "go_version": "go1.21.0",
    "memory": {
      "alloc": 10485760,
      "total_alloc": 52428800,
      "sys": 33554432,
      "num_gc": 5
    },
    "goroutines": 15
  }
}
```

#### 热加载配置
```
POST /v1/admin/system/reload
Content-Type: application/json

{
  "config_type": "source"  // 可选：server/database/redis/source
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "success": true,
    "message": "配置热加载成功"
  }
}
```

#### 重启服务
```
POST /v1/admin/system/restart
Content-Type: application/json

{
  "force": false
}
```

---

### 4.2 配置管理接口

#### 获取配置列表
```
GET /v1/admin/config?type=server
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "sections": [
      {
        "name": "服务器配置",
        "type": "server",
        "description": "HTTP服务器相关配置",
        "items": [
          {
            "key": "port",
            "value": 8080,
            "type": "int",
            "description": "服务端口",
            "editable": true,
            "required": true
          }
        ]
      }
    ],
    "version": "1.0.0",
    "updated": "2026-03-07T13:00:00Z"
  }
}
```

#### 更新配置
```
PUT /v1/admin/config
Content-Type: application/json

{
  "type": "server",
  "items": {
    "port": 8080,
    "mode": "release",
    "api_key": "new-key"
  }
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "success": true,
    "need_restart": false,
    "message": "配置更新成功"
  }
}
```

---

### 4.3 适配器管理接口

#### 获取适配器列表
```
GET /v1/admin/adapters
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "adapters": [
      {
        "name": "tushare",
        "type": "http",
        "version": "1.0.0",
        "description": "Tushare Pro 金融数据接口",
        "status": "active",
        "config": {
          "token": "***",
          "base_url": "https://api.tushare.pro"
        },
        "updated_at": "2026-03-07T13:00:00Z"
      }
    ]
  }
}
```

#### 启用/禁用适配器
```
POST /v1/admin/adapters/toggle
Content-Type: application/json

{
  "name": "tushare",
  "enable": true
}
```

#### 更新适配器配置
```
PUT /v1/admin/adapters/config
Content-Type: application/json

{
  "name": "tushare",
  "config": {
    "token": "new-token",
    "base_url": "https://api.tushare.pro"
  }
}
```

---

### 4.4 接口测试管理

#### 获取API测试列表
```
GET /v1/admin/tests/api
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "categories": [
      {
        "name": "股票接口",
        "items": [
          {
            "id": "stock_klines",
            "name": "查询股票K线",
            "method": "GET",
            "path": "/v1/stock/klines/{symbol}",
            "description": "查询指定股票的K线数据",
            "params": {
              "symbol": "000001.SZ",
              "start": "20260201",
              "end": "20260307",
              "freq": "1d"
            }
          }
        ]
      }
    ],
    "base_url": "http://localhost:8080"
  }
}
```

#### 执行API测试
```
POST /v1/admin/tests/api/run
Content-Type: application/json

{
  "id": "stock_klines",
  "params": {
    "symbol": "000001.SZ"
  }
}
```

**响应示例**:
```json
{
  "code": 0,
  "data": {
    "id": 1234567890,
    "case_id": "stock_klines",
    "name": "查询股票K线",
    "success": true,
    "status_code": 200,
    "latency": 45,
    "request": {
      "method": "GET",
      "url": "http://localhost:8080/v1/stock/klines/000001.SZ?start=20260201&end=20260307&freq=1d"
    },
    "response": {
      "code": 0,
      "data": {...}
    },
    "timestamp": "2026-03-07T13:00:00Z"
  }
}
```

#### 获取WebSocket测试列表
```
GET /v1/admin/tests/ws
```

#### 执行WebSocket测试
```
POST /v1/admin/tests/ws/run
Content-Type: application/json

{
  "id": "ws_subscribe_stock",
  "symbols": ["000001.SZ", "000002.SZ"]
}
```

#### 获取测试历史
```
GET /v1/admin/tests/history?type=api&limit=20
```

---

## 五、前端实现

### 5.1 技术方案

- **纯HTML/CSS/JS**: 无前端框架依赖
- **单页应用**: 前端路由切换，无页面刷新
- **嵌入式部署**: HTML代码内嵌在Go文件中

### 5.2 页面结构

```
/admin
├── 系统概览 (dashboard)
│   ├── 状态卡片（运行状态、运行时长、版本、Goroutines）
│   ├── 内存使用详情
│   └── 操作按钮（热加载、重启）
│
├── 配置管理 (config)
│   ├── 服务器配置
│   ├── 数据库配置
│   ├── Redis配置
│   └── 数据源配置
│
├── 数据源适配 (adapters)
│   └── 适配器列表表格
│
└── 接口测试 (tests)
    ├── API测试页签
    ├── WebSocket测试页签
    └── 测试历史页签
```

### 5.3 前端API封装

```javascript
// API请求封装
async function apiRequest(method, path, data = null) {
    const options = {
        method,
        headers: {
            'Content-Type': 'application/json',
            'X-Admin-Token': localStorage.getItem('adminToken') || ''
        }
    };
    
    if (data) {
        options.body = JSON.stringify(data);
    }
    
    const response = await fetch(state.baseURL + path, options);
    return response.json();
}
```

---

## 六、使用指南

### 6.1 启动服务

```bash
# 设置配置文件路径
export CONFIG_PATH="./config.json"

# 启动服务
go run ./cmd/server

# 或使用Makefile
make run
```

### 6.2 访问管理后台

浏览器访问：`http://localhost:8080/admin`

### 6.3 配置热加载示例

```bash
# 1. 修改 config.json 文件

# 2. 调用热加载API
curl -X POST "http://localhost:8080/v1/admin/system/reload" \
  -H "Content-Type: application/json" \
  -d '{"config_type": "source"}'

# 3. 或在管理后台点击"热加载配置"按钮
```

### 6.4 适配器管理流程

```
1. 进入"数据源适配"页面
2. 查看已注册的适配器列表
3. 点击"启用"/"禁用"按钮切换状态
4. 点击适配器名称可编辑配置
```

---

## 七、待完善事项

### 7.1 功能增强

| 优先级 | 功能 | 说明 |
|--------|------|------|
| P1 | 用户认证 | 实现基于Token的管理员认证机制 |
| P1 | 操作日志 | 记录所有配置变更和管理操作 |
| P2 | 配置版本 | 支持配置历史版本回滚 |
| P2 | 批量操作 | 支持批量启用/禁用适配器 |
| P3 | 数据可视化 | 添加数据源调用统计图表 |
| P3 | 告警管理 | 集成钉钉/邮件告警配置 |

### 7.2 安全加固

| 优先级 | 功能 | 说明 |
|--------|------|------|
| P1 | 访问控制 | 基于IP白名单的访问限制 |
| P1 | HTTPS支持 | 管理后台强制HTTPS访问 |
| P2 | 密码加密 | 配置文件中的敏感信息加密存储 |
| P2 | 审计日志 | 详细的操作审计日志 |

### 7.3 性能优化

| 优先级 | 功能 | 说明 |
|--------|------|------|
| P2 | 配置缓存 | 热点配置缓存，减少磁盘IO |
| P3 | 前端优化 | 静态资源CDN、代码分割 |
| P3 | WebSocket推送 | 系统状态通过WebSocket实时推送 |

### 7.4 已知问题

1. **重启服务**: 当前仅返回成功响应，实际重启需外部脚本配合
2. **并发安全**: 配置热加载时可能存在短暂的数据竞争
3. **测试隔离**: API测试直接调用生产接口，需增加测试模式

### 7.5 扩展建议

1. **插件系统**: 支持第三方适配器动态加载
2. **多租户**: 支持多用户、多权限级别的管理
3. **移动端**: 开发响应式移动端管理界面
4. **国际化**: 支持中英文切换

---

## 附录

### A. 配置文件示例

```json
{
  "server": {
    "port": 8080,
    "mode": "debug",
    "api_key": "your-api-key"
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "password",
    "database": "marketdata"
  },
  "redis": {
    "host": "localhost",
    "port": 6379,
    "password": "",
    "db": 0
  },
  "sources": {
    "stock": {
      "active": "tushare"
    },
    "futures": {
      "active": "tushare"
    }
  }
}
```

### B. 相关文件清单

| 文件 | 说明 | 行数 |
|------|------|------|
| `api/admin_types.go` | 类型定义 | ~270 |
| `api/admin_router.go` | 路由 + HTML | ~680 |
| `internal/handler/admin.go` | Handler实现 | ~180 |
| `internal/service/config.go` | 配置服务 | ~330 |
| `internal/service/adapter.go` | 适配器服务 | ~220 |
| `internal/service/test.go` | 测试服务 | ~350 |
| `pkg/config/config.go` | 配置结构 | ~60 |

---

**文档结束**