# 域名信息远程列表功能实施计划

## 概述
在 DNS 服务器的屏蔽管理系统中增加三类域名信息的远程异步加载功能，用于增强日志详情 API 和威胁告警 API 的域名信息查询能力。

## 需要添加的远程域名信息

### 1. 域名信息列表
- **URL**: `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/domains/domain-info.json`
- **用途**: 用于查询日志详情 API 中的域名信息
- **格式**: JSON

### 2. 威胁告警域名列表
- **URL**: `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/src/branch/main/threats/threats-database.csv`
- **用途**: 用于威胁告警 API 的威胁域名信息
- **格式**: CSV

### 3. 跟踪器域名列表
- **URLs**: 
  - `https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/tracker/trackers.json`
- **用途**: 用于查询日志详情 API 中的跟踪器信息
- **格式**: JSON

## 实施步骤

### 步骤 1: 扩展配置文件结构
1.1 在 `config/config.go` 中添加新的配置结构：
   - `DomainInfoConfig` - 域名信息配置
   - 包含三个远程列表的配置条目（类似 `BlacklistEntry`）
   - 添加更新间隔、启用状态等配置项

1.2 在 `Config` 结构体中添加 `DomainInfo DomainInfoConfig` 字段

1.3 实现配置解析函数：
   - `parseDomainInfoLists()` - 解析域名信息列表配置
   - 支持 INI 格式配置

### 步骤 2: 创建域名信息管理器
2.1 创建新文件 `shield/domain_info_manager.go`

2.2 实现 `DomainInfoManager` 结构体：
   - 存储域名信息数据（JSON 格式）
   - 存储威胁域名数据（CSV 格式）
   - 存储跟踪器数据（JSON 格式）
   - 缓存管理和过期检查机制
   - 异步加载和更新逻辑

2.3 实现核心方法：
   - `LoadDomainInfo()` - 加载所有域名信息
   - `fetchRemoteDomainInfo()` - 获取远程域名信息
   - `fetchThreatDatabase()` - 获取威胁数据库
   - `fetchTrackerInfo()` - 获取跟踪器信息
   - `shouldUpdateCache()` - 检查缓存是否需要更新
   - `GetDomainInfo(domain)` - 查询域名信息
   - `GetThreatInfo(domain)` - 查询威胁信息
   - `GetTrackerInfo(domain)` - 查询跟踪器信息
   - `GetAllDomainInfo()` - 获取所有域名信息（用于 API）

2.4 实现缓存机制：
   - 使用内存缓存存储加载的数据
   - 定期后台刷新（根据配置的更新间隔）
   - 支持手动刷新

### 步骤 3: 实现后端 API
3.1 在 `http/server.go` 中添加新的 API 路由：
   - `/api/shield/domain-info` - 获取域名信息列表（GET）
   - `/api/shield/domain-info/update` - 手动更新所有域名信息（POST）
   - `/api/shield/domain-info/{type}/update` - 更新指定类型的域名信息（POST）
   - `/api/domain/info` - 查询单个域名的详细信息（GET）

3.2 实现 API 处理函数：
   - `handleDomainInfo()` - 处理域名信息列表的获取
   - `handleUpdateDomainInfo()` - 处理手动更新请求
   - `handleDomainInfoQuery()` - 处理域名信息查询

3.3 在服务器初始化时：
   - 创建 `DomainInfoManager` 实例
   - 启动后台定期更新任务

### 步骤 4: 实现前端界面
4.1 创建 `static/js/modules/domain-info.js` 模块：
   - `loadDomainInfoLists()` - 加载域名信息列表
   - `updateDomainInfo(type)` - 更新域名信息
   - `renderDomainInfoLists()` - 渲染域名信息列表表格
   - `showDomainInfoDetails()` - 显示域名信息详情

4.2 在 `static/js/shield.js` 中添加：
   - `loadRemoteDomainInfoLists()` - 异步加载远程域名信息列表
   - `updateDomainInfoListsTable()` - 更新域名信息列表 UI
   - 添加状态指示器和通知逻辑

4.3 创建前端管理界面 `static/domain-info.html`（或集成到现有 shield.html）：
   - 域名信息列表管理表格
   - 显示各列表的状态、规则数量、最后更新时间
   - 手动更新按钮
   - 启用/禁用切换

### 步骤 5: 集成到日志详情 API
5.1 修改日志详情查询接口：
   - 在返回的日志详情中添加域名信息字段
   - 添加跟踪器信息字段
   - 如果域名在威胁数据库中，添加威胁告警信息

5.2 优化查询性能：
   - 使用缓存避免重复查询
   - 批量查询优化

### 步骤 6: 集成到威胁告警 API
6.1 修改威胁告警查询接口：
   - 使用远程威胁数据库进行匹配
   - 返回威胁类型、风险等级等详细信息

### 步骤 7: 测试和文档
7.1 功能测试：
   - 测试远程列表加载
   - 测试缓存机制
   - 测试 API 接口
   - 测试前端界面

7.2 更新文档：
   - 更新 README.md
   - 添加配置示例
   - 更新 API 文档

## 技术要点

### 异步加载机制
- 使用 goroutine 进行后台异步加载
- 使用 channel 或 context 控制加载流程
- 支持并发加载多个远程列表

### 缓存策略
- 内存缓存 + 文件缓存双重机制
- 基于时间的过期策略
- 支持手动刷新和自动刷新

### 错误处理
- 网络错误的重试机制
- 加载失败时的降级处理（使用缓存）
- 详细的错误日志记录

### 性能优化
- 批量处理减少锁竞争
- 使用 RWMutex 优化读写性能
- 延迟加载和按需加载

## 文件清单

### 新增文件
- `shield/domain_info_manager.go` - 域名信息管理器
- `static/js/modules/domain-info.js` - 前端域名信息管理模块
- `static/domain-info.html` - 域名信息管理界面（可选，如集成到现有页面则不需要）

### 修改文件
- `config/config.go` - 添加域名信息配置
- `http/server.go` - 添加 API 路由和处理函数
- `shield/manager.go` - 集成域名信息管理（可选）
- `static/js/shield.js` - 添加前端加载逻辑
- `README.md` - 更新文档

## 配置示例

```ini
[domainInfo]
; 域名信息列表配置
; 格式：name = url,enabled
domainInfoList = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/domains/domain-info.json,true
threatDatabase = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/src/branch/main/threats/threats-database.csv,true
trackerList = https://gitea.amazehome.xyz/AMAZEHOME/domain-info/raw/branch/main/tracker/trackers.json,true

; 更新间隔（秒）
updateInterval = 3600

; 是否启用自动更新
enableAutoUpdate = true
```

## 时间估算
- 步骤 1: 配置文件扩展 - 30 分钟
- 步骤 2: 域名信息管理器 - 2 小时
- 步骤 3: 后端 API 实现 - 1 小时
- 步骤 4: 前端界面实现 - 1.5 小时
- 步骤 5-6: API 集成 - 1 小时
- 步骤 7: 测试和文档 - 1 小时

**总计**: 约 7-8 小时