yl-frontend/api-docs/security-api.txt

安全中心模块接口文档
================

基础信息
-------
- 基础路径: /api/v1/security
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

SecurityStatus 安全状态对象:
{
  id: number,          // 状态ID
  name: string,        // 状态名称
  description: string, // 状态描述
  status: string,      // 状态(safe/risk/danger)
  lastCheck: string,   // 最后检查时间
  details?: string     // 详细信息
}

SecurityAlert 安全告警对象:
{
  id: number,          // 告警ID
  title: string,       // 告警标题
  description: string, // 告警描述
  level: string,       // 告警级别(info/warning/danger)
  time: string,        // 告警时间
  handled: boolean,    // 是否已处理
  location?: string,   // 告警位置
  deviceId?: number    // 相关设备ID
}

SecurityDevice 安全设备对象:
{
  id: number,          // 设备ID
  name: string,        // 设备名称
  type: string,        // 设备类型
  status: string,      // 设备状态(online/offline)
  battery?: number,    // 电量
  lastUpdate: string   // 最后更新时间
}

BackupRecord 备份记录对象:
{
  id: number,          // 备份ID
  type: string,        // 备份类型
  size: string,        // 备份大小
  time: string,        // 备份时间
  status: string,      // 备份状态(success/failed)
  path: string         // 备份路径
}

API 接口
-------

1. 获取安全状态
GET /api/v1/security/status

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "账号安全",
      "description": "密码强度良好，双因素认证已开启",
      "status": "safe",
      "lastCheck": "2024-03-20 10:00:00"
    }
  ]
}

2. 获取告警信息
GET /api/v1/security/alerts

请求参数：
| 参数名   | 类型    | 必填 | 说明 |
| handled | boolean | 否   | 是否已处理 |

3. 处理告警
POST /api/v1/security/alerts/{id}/handle

4. 获取安全设备列表
GET /api/v1/security/devices

5. 更新设备状态
PUT /api/v1/security/devices/{id}/status

请求参数：
{
  "status": "online"  // online/offline
}

6. 获取备份记录
GET /api/v1/security/backups

7. 创建备份
POST /api/v1/security/backups

请求参数：
{
  "type": "manual"  // auto/manual
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "type": "手动备份",
    "size": "2.1GB",
    "time": "2024-03-20 10:00:00",
    "status": "success",
    "path": "/backups/manual/20240320"
  }
}

8. 恢复备份
POST /api/v1/security/backups/{id}/restore

9. 执行安全检查
POST /api/v1/security/check

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "score": 85,
    "issues": [
      {
        "level": "medium",
        "description": "部分设备密码强度较弱",
        "suggestion": "建议修改为更复杂的密码"
      }
    ]
  }
}

10. 发送紧急求助
POST /api/v1/security/emergency

请求参数：
{
  "type": "medical",
  "description": "需要医疗救助"
}

11. 生成安全报告
GET /api/v1/security/report

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://example.com/security_report.pdf"
  }
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 资源不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 安全检查建议：
   - 定期执行安全检查
   - 及时处理安全隐患
   - 保持设备固件更新

2. 备份策略：
   - 自动备份：每日凌晨执行
   - 手动备份：重要数据变更时
   - 定期清理过期备份

3. 告警处理：
   - 高危告警需在1小时内处理
   - 记录所有处理过程
   - 定期分析告警趋势

4. 设备管理：
   - 定期检查设备状态
   - 及时更换低电量设备
   - 保持固件版本最新

5. 访问控制：
   - 重要操作需二次认证
   - 记录所有操作日志
   - 异常访问自动告警

6. 数据安全：
   - 敏感数据加密存储
   - 定期更新加密密钥
   - 严格控制访问权限