wecom_it_smart_desk/docs/01-产品文档/08-集成生态/PRD-REQ-集成-001-OpenClaw合规检查-v1.0.md

# PRD: OpenClaw 安全合规检查与通知系统

> **版本**: v1.0
> **日期**: 2026-07-20
> **状态**: [草稿]
> **作者**: Simon
> **需求编号**: REQ-集成-001
> **关联文档**:
>   - 原型: `01-产品文档/08-集成生态/原型-REQ-集成-001-OpenClaw合规检查-v1.0.html`
>   - 技术: `02-技术文档/实现配置/技术方案-REQ-集成-001-OpenClaw合规检查-v1.0.md`
>   - 测试: `03-测试文档/03-功能测试用例/TC-REQ-集成-001-OpenClaw合规检查.md`

---

## 1. 问题陈述 (Problem Statement)

### 背景
在重大安全活动期间（如国家网络安全周、重大会议保障期），公司需要对终端进行合规审计。

> 💡 **本期目标**：以 OpenClaw 检测为 **一期试点**，验证安全策略检查与通知框架的可行性。
>
> **扩展性设计**：本系统设计为 **通用安全策略检查平台**，未来可低成本扩展其他策略和推送渠道。

### 问题描述
- **现状**：目前依赖手工导出联软数据或通过火绒终端管理查看，缺乏自动化的定期检查和通知机制
- **痛点**：
  - 无法及时发现违规软件安装
  - 依赖人工通知，效率低、易遗漏
  - 无法形成定期的合规审计报告

### 影响
- **安全风险**：未经授权的远程软件可能成为攻击入口
- **合规风险**：无法满足重大活动期间的安全审计要求
- **业务影响**：IT 运维人员需要投入大量人工排查

---

## 2. 目标 (Goals)

| # | 目标 | 成功衡量标准 |
|---|------|-------------|
| G1 | **一期试点**：自动检测 OpenClaw 安装 | 系统可自动发现所有已安装 OpenClaw 的终端，覆盖率 ≥ 95% |
| G2 | 及时通知当事人 | 检测到违规软件后，24 小时内通过企微发送通知给终端用户 |
| G3 | 支持定时+手动执行 | 支持每日定时执行 + 管理员手动触发两种方式 |
| G4 | 合规审计留痕 | 支持导出 Excel 审计报告，保留检测记录至少 6 个月 |
| G5 | 活动期间管控 | 支持设置活动期间，自动开启检查 |
| G6 | **框架可扩展** | 新增其他安全策略和推送渠道的成本 ≤ 1人天 |

---

## 3. 非目标 (Non-Goals)

| # | 非目标 | 原因 |
|---|--------|------|
| N1 | **自动封禁/断网** | 仅做通知提醒，不做自动阻断，避免影响业务连续性 |
| N2 | ~~**支持其他软件检查**~~ | ⚠️ 已调整为扩展性设计，详见下方框架说明 |
| N3 | **实时监控** | 采用定时检查（非实时推送），5 分钟级延迟可接受 |
| N4 | **移动端管理** | 本期仅支持 PC Web 端管理 |
| N5 | **火绒+联软自动同步** | 联软数据本期采用手动导入 Excel，不做自动 API 对接 |

---

## 3.1 扩展性框架设计（重要）

> 📐 **架构理念**：将"检测策略"与"推送渠道"解耦，实现可扩展的安全合规平台

### 3.1.1 策略类型（Strategy）

| 策略ID | 策略名称 | 检测规则 | 数据源 | 状态 |
|--------|----------|----------|--------|------|
| openclaw_remote | OpenClaw/向日葵远程软件 | 软件名包含 OpenClaw/向日葵/sunflower | 火绒API | 🔵 一期 |
| unknown_usb | 未知USB设备 | 未登记的USB设备接入 | 联软/火绒 | ⚪ 二期 |
| illegal_proxy | 非法代理软件 | 软件名包含 proxy/vpn | 火绒API | ⚪ 二期 |
| unverified_software | 未授权软件 | 不在白名单内的软件 | 火绒API | ⚪ 二期 |

### 3.1.2 推送渠道（Channel）

| 渠道ID | 渠道名称 | 适用场景 | 状态 |
|--------|----------|----------|------|
| wecom_app | 企微应用消息 | 终端用户通知 | 🔵 一期 |
| wecom_group | 企微群通知 | 部门汇总、管理员 | 🔵 一期 |
| email | 邮件通知 | 正式留痕、邮件通知 | ⚪ 二期 |
| sms | 短信通知 | 紧急告警、无企微用户 | ⚪ 二期 |
| dingtalk | 钉钉通知 | 跨平台通知 | ⚪ 二期 |

### 3.1.3 策略-渠道映射

```
策略配置:
{
  "strategy_id": "openclaw_remote",
  "name": "OpenClaw远程软件检测",
  "channels": [
    {"id": "wecom_app", "template": "终端用户通知"},
    {"id": "wecom_group", "template": "部门汇总"}
  ],
  "schedule": "0 8 * * *",  # 每天8点
  "enabled": true
}
```

### 3.1.4 扩展成本

| 扩展项 | 工作量预估 | 说明 |
|--------|------------|------|
| 新增检测策略 | 0.5人天 | 仅需配置检测规则和数据源 |
| 新增推送渠道 | 1人天 | 需开发渠道适配器 |
| 新策略+新渠道 | 1人天 | 配置映射关系即可 |

---

## 4. 用户故事 (User Stories)

### 角色定义
- **IT 管理员**：负责配置检查策略、查看检测结果、触发手动检查
- **终端用户**：收到通知的被检查对象
- **部门负责人**：（可选）收到本部门汇总通知

### 用户故事列表

| # | 角色 | 用户故事 | 优先级 |
|---|------|----------|--------|
| US1 | IT 管理员 | 我希望系统能自动从火绒 API 获取终端软件列表，以便及时发现 OpenClaw 安装 | P0 |
| US2 | IT 管理员 | 我希望能够导入联软导出的用户-终端关联 Excel，以便知道哪台设备属于哪个用户 | P0 |
| US3 | IT 管理员 | 我希望系统能自动匹配"终端→用户"，输出"谁在哪台设备安装了 OpenClaw"，以便精准确认责任人 | P0 |
| US4 | IT 管理员 | 我希望能够设置定时任务（如每天 8:00 自动检查），以便在活动期间自动执行 | P0 |
| US5 | IT 管理员 | 我希望能够手动点击"立即检查"按钮，以便随时执行检查 | P0 |
| US6 | IT 管理员 | 我希望能够编辑通知模板（包含变量），以便自定义通知内容 | P1 |
| US7 | IT 管理员 | 我希望能够设置"是否通知部门负责人"开关，以便灵活配置通知范围 | P1 |
| US8 | IT 管理员 | 我希望能够导出 Excel 报告，以便留存审计记录 | P0 |
| US9 | 终端用户 | 我希望收到企微应用消息通知，告诉我哪台设备安装了违规软件，以便及时卸载 | P0 |
| US10 | 部门负责人 | 我希望收到本部门的汇总通知（可选），以便了解本部门合规情况 | P1 |
| US11 | IT 管理员 | 我希望能够新增其他安全策略（如未知USB、非法代理），以便扩展检测范围 | P0 |
| US12 | IT 管理员 | 我希望能够配置不同策略使用不同推送渠道（如邮件、短信），以便灵活通知 | P1 |

---

## 5. 需求规格 (Requirements)

### 5.1 功能需求

> 📌 **需求说明**：一期以 OpenClaw 为试点，但架构设计需支持策略和渠道的扩展。

#### T0: 策略与渠道管理（框架层）

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-00 | 策略配置：支持创建/编辑/启停安全策略 | P0 | 可配置策略名称、检测规则、数据源、推送渠道 |
| REQ-001-00a | 预置策略：一期预置"OpenClaw远程软件"检测策略 | P0 | 内置关键词规则（OpenClaw/向日葵/sunflower） |
| REQ-001-00b | 渠道配置：支持配置推送渠道参数 | P0 | 企微渠道：应用ID/Secret；邮件渠道：SMTP配置 |
| REQ-001-00c | 渠道适配器：企微应用消息发送 | P0 | 复用现有企微消息能力 |
| REQ-001-00d | 渠道适配器：（扩展）邮件发送 | P2 | 可延后至二期 |
| REQ-001-00e | 渠道适配器：（扩展）短信发送 | P2 | 可延后至二期 |

#### T1: 数据采集层

> ⚠️ **注意**：火绒 API 集成功能已存在于系统中（`app/integrations/huorong`），无需重复开发。
> - 现有 API：`GET /api/admin/integrations/huorong/terminals` - 获取终端列表
> - 现有 API：`GET /api/admin/integrations/huorong/terminals/{client_id}` - 获取终端详情（含软件列表）
> - 本期仅需确认现有 API 满足 OpenClaw 检测需求（获取终端软件列表）。

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-01 | ✅ 已存在：火绒 API 集成（`/api/clnts/_list` 获取终端列表） | - | 复用现有功能 |
| REQ-001-02 | ✅ 已存在：火绒 API 集成（`/api/clnts/_info2` 获取软件列表） | - | 复用现有功能，确认支持 OpenClaw 检测 |
| REQ-001-03 | 联软 Excel 导入：支持上传 .xlsx/.xls 文件 | P0 | 能解析联软导出的 Excel，提取用户-终端关联字段 |
| REQ-001-04 | 联软字段映射：自动识别 `用户名`、`设备名称`、`MAC地址`、`设备IP`、`部门名称` | P0 | 上传文件后自动匹配字段，无需手动配置 |
| REQ-001-05 | 联软数据存储：将导入的关联数据存入数据库 | P0 | 导入后数据持久化，支持后续匹配查询 |

#### T2: 数据融合引擎

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-06 | IP 地址匹配：优先通过 IP 完全匹配关联终端和用户 | P0 | 火绒终端 IP 与联软数据完全一致时，成功匹配 |
| REQ-001-07 | 主机名匹配：IP 未匹配时，通过主机名包含匹配 | P0 | 火绒主机名包含联软设备名称时，成功匹配 |
| REQ-001-08 | MAC 地址匹配：前两者未匹配时，通过 MAC 地址匹配 | P0 | 火绒 MAC 与联软 MAC 一致时，成功匹配 |
| REQ-001-09 | 未匹配记录标记：无法关联到用户的终端需标记为"未匹配" | P0 | 输出结果中明确标注哪些终端无法确定责任人 |
| REQ-001-10 | OpenClaw 命中过滤：仅输出安装了 OpenClaw 的终端 | P0 | 匹配关键词：`OpenClaw`, `向日葵`, `sunflower`（不区分大小写） |

#### T3: 策略规则与命中管理

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-11 | 白名单规则：支持配置排除的用户/终端 | P1 | 配置白名单后，命中用户不在通知范围内 |
| REQ-001-12 | 部门汇总：支持按部门聚合命中结果 | P1 | 统计每个部门的违规终端数量 |
| REQ-001-12a | 命中状态管理：支持手动修改命中记录状态 | P0 | 状态：待处理→已通知→已解决/误报 |
| REQ-001-12b | 自动状态更新：再次检测时自动判断状态变化 | P0 | 历史命中用户再次检测未命中，自动标记"已解决" |
| REQ-001-12c | 状态变更记录：记录状态变更时间和操作人 | P1 | 可查看每条记录的状态变更历史 |

#### T4: 通知模板管理

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-13 | 模板变量：支持变量替换（{username}, {device}, {dept}, {software}, {detect_time}） | P0 | 通知内容中变量被正确替换 |
| REQ-001-14 | 默认模板：内置默认通知模板 | P0 | 未配置模板时使用默认模板发送 |
| REQ-001-15 | 模板编辑：支持富文本编辑通知模板 | P1 | 可编辑标题和正文内容 |
| REQ-001-16 | 企微消息发送：通过企微应用消息接口发送通知 | P0 | 成功发送至终端用户企微 |

#### T5: 调度与执行

| 需求ID | 描述 | 优先级 | 验收标准 |
|--------|------|--------|----------|
| REQ-001-17 | 定时任务：支持配置 cron 表达式执行检查 | P0 | 每天 8:00 自动执行检查任务 |
| REQ-001-18 | 手动触发：提供"立即检查"按钮 | P0 | 点击后立即执行检查流程 |
| REQ-001-19 | 活动期间开关：支持设置活动起止时间 | P0 | 活动期间自动开启检查，非活动期间可手动开启 |
| REQ-001-20 | 执行日志：记录每次执行的起止时间、命中数量、发送结果 | P0 | 可查看历史执行记录 |
| REQ-001-21 | Excel 导出：支持导出检测结果为 Excel | P0 | 导出字段：用户名、用户全名、部门、设备名称、IP、MAC、软件名称、安装日期 |

### 5.2 边缘情况处理

| 场景 | 处理方式 |
|------|----------|
| 火绒 API 调用失败 | 记录错误日志，发送告警给 IT 管理员，继续使用上次导入的联软数据 |
| 联软 Excel 未导入 | 仅使用火绒数据，未匹配用户的终端标记为"用户未知" |
| 用户无企微账户 | 跳过发送，标记为"发送失败"，记录日志 |
| 重复检测 | 同一用户同一天多次检测，仅发送首次通知（去重） |
| 空结果（无违规） | 发送"本次检查无违规"的汇总通知给管理员 |

---

## 6. 成功指标 (Success Metrics)

### 6.1 领先指标（Leading Indicators）

| 指标 | 定义 | 目标 | 测量方式 |
|------|------|------|----------|
| 检测覆盖率 | 成功关联到用户的终端数 / 火绒总终端数 | ≥ 85% | 数据库统计 |
| 通知成功率 | 成功发送通知数 / 需通知总数 | ≥ 95% | 企微 API 返回 |
| 执行完成率 | 定时任务成功执行次数 / 计划执行次数 | ≥ 99% | 调度日志 |

### 6.2 滞后指标（Lagging Indicators）

| 指标 | 定义 | 目标 | 测量方式 |
|------|------|------|----------|
| 闭环率 | 当事人确认处理（卸载）的比例 | ≥ 80% | 用户反馈或二次检测 |
| 投诉率 | 通知后用户投诉误报的比例 | < 5% | 反馈记录 |
| 合规达标率 | 活动期间最后一天违规终端清理比例 | 100% | 最终检测报告 |

---

## 7. 开放问题 (Open Questions)

| # | 问题 | 负责人 | 状态 |
|---|------|--------|------|
| Q1 | 联软 Excel 导入频率？建议每日导入一次还是每次检查前导入？ | 产品 | 待确认 |
| Q2 | 部门负责人通知是否需要汇总（多条合并为1条）？ | 产品 | 待确认 |
| Q3 | 活动期间结束后，是否需要自动关闭定时任务？ | 产品 | 待确认 |

---

## 7.1 任务拆分说明（重要）

> ⚠️ **系统现有火绒 API 集成，无需重复开发**

| 任务 | 说明 | 状态 |
|------|------|------|
| **T0: 策略与渠道管理** | 需开发：策略配置、渠道适配器框架 | 🔲 待开发 |
| **T1a: 火绒API集成** | 现有功能已支持（`/api/admin/integrations/huorong/terminals`） | ✅ 已存在 |
| **T1b: 联软Excel导入** | 需开发：从联软导出Excel导入用户-终端关联 | 🔲 待开发 |
| T2: 数据融合引擎 | 需开发：IP/主机名/MAC三级匹配 | 🔲 待开发 |
| T3: 策略规则引擎 | 需开发：白名单、命中过滤 | 🔲 待开发 |
| T4: 通知模板管理 | 需开发：模板编辑、企微消息发送 | 🔲 待开发 |
| T5: 调度与执行 | 需开发：定时任务、手动触发、活动开关 | 🔲 待开发 |

**实际开发任务**：T0 + T1b + T2 + T3 + T4 + T5（共6个任务）

---

## 8. 时间计划 (Timeline)

### 阶段划分

> ⚠️ **注**：T1a（火绒API）已存在，无需开发。

| 阶段 | 内容 | 预估工期 |
|------|------|----------|
| Phase 0 | T0（策略与渠道框架）+ T1b（联软导入） | 2 天 |
| Phase 1 | T2（融合引擎）+ T3（策略规则） | 2 天 |
| Phase 2 | T4（通知模板）+ T5（调度执行+导出） | 2 天 |
| Phase 3 | 联调测试 + 验收 | 2 天 |
| **合计** | 实际开发 | **8 天** |

### 里程碑

| 日期 | 里程碑 |
|------|--------|
| 2026-07-25 | Phase 1-2 完成，进入联调 |
| 2026-07-28 | Phase 3-4 完成，进入测试 |
| 2026-07-30 | UAT 通过，具备上线条件 |

---

## 9. 风险与依赖 (Risks & Dependencies)

| 风险/依赖 | 影响 | 缓解措施 |
|-----------|------|----------|
| 火绒 API 性能 | 终端数量多时可能超时 | 分页获取，增加重试机制 |
| 联软数据更新 | 用户-终端关联可能变更 | 建议每次检查前重新导入最新 Excel |
| 企微消息频率限制 | 大批量发送可能触发限制 | 增加发送间隔，批量改单发 |

---

## 10. 附录

### 数据字段映射

#### 火绒终端字段（API 返回）
- `client_id`: 终端唯一标识
- `hostname`: 主机名
- `ip`: IP 地址
- `mac`: MAC 地址
- `software`: 已安装软件列表

#### 联软 Excel 字段
- `用户名`: 企微/AD 用户名
- `用户全名`: 真实姓名
- `部门名称`: 组织架构
- `设备名称`: 终端名称
- `设备IP`: IP 地址
- `MAC地址`: MAC 地址
- `软件名称`: 已安装软件
- `安装日期`: 软件安装时间

### 匹配优先级
1. IP 地址完全匹配
2. 主机名包含匹配（联软设备名称 in 火绒主机名）
3. MAC 地址匹配

---

## 变更记录

| 日期 | 版本 | 变更内容 | 变更人 | 变更原因 |
|------|------|----------|--------|----------|
| 2026-07-20 | v1.0 | 初始版本 | Simon | 新建需求 |

---

**审批记录**

| 角色 | 姓名 | 日期 | 签字 |
|------|------|------|------|
| 产品负责人 | | | |
| 技术负责人 | | | |
| 业务负责人 | | | |