work-secretfile-selfcheck/docs/plans/2026-06-08-secret-file-selfcheck.md

# 涉密文件自检工具 实施计划

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 在 Windows 上做一个单文件 GUI 程序，对磁盘中文档（doc/docx/pdf）按可配置数量随机抽检，借助本地 Umi-OCR HTTP 服务识别是否含有"机密"等敏感关键词，并产出截图+结论报告。

**Architecture:**
- `eframe + egui` Material 风格单窗口 GUI（暗/亮/跟随系统三主题），左侧设置、右侧主面板、底部状态栏；按钮 "开始检测" 启动任务。
- 抽检分三层：
  - `docx`：`docx-rs` 解析段落 → 关键词匹配
  - `pdf`：调用 Windows 默认 PDF 关联程序 → 等待 → 模拟 `Win+Shift+S` 触发系统截图 → 用户在屏幕上手动框选 → 程序轮询剪贴板读取位图 → 调 Umi-OCR HTTP → 关键词匹配
  - `doc`：调用 `<exe 同目录>/doclite.exe` 打开 → 同上截图链路
- OCR 客户端：`reqwest` 把 base64 图像 POST 到 `http://127.0.0.1:1224/api/ocr`，解析返回 `data[].text` 与 `box`。
- 默认全盘扫描；UI 中加"白名单目录"列表（不扫的目录）；启动时单次申请 UAC，整会话复用。
- 配置 `serde + toml` 持久化到 `%APPDATA%\secret-file-selfcheck\config.toml`。
- 资源（中文字体、图标）通过 `include_bytes!` 嵌入二进制；`doclite.exe` / `Umi-OCR.exe` 由程序在 exe 同目录自动发现并按需启动。
- `#![windows_subsystem = "windows"]` 隐藏控制台，单 exe 交付。

**Tech Stack:**
- 语言/工具链：Rust `stable-x86_64-pc-windows-gnu`（MSYS2 + MinGW）
- GUI：`eframe = "0.27"`、`egui = "0.27"`、`egui_extras`，手写 Material token
- 文本：`docx-rs`、`encoding_rs`、`chardetng`
- OCR 客户端：`reqwest`（阻塞 + JSON）→ Umi-OCR
- 截屏链路：`windows` crate（`keybd_event` 触发 `Win+Shift+S`、`OpenClipboard` / `GetClipboardData` 读位图）
- 进程/窗口：`sysinfo`、`windows` crate（`CreateProcessW`、`EnumWindows`、`WM_CLOSE`、`taskkill`）
- 异步：`tokio`（轻量使用）
- 权限：`windows` crate（`ShellExecuteExW` + `runas` 提升 UAC）
- 配置/日志：`serde`、`toml`、`tracing` + `tracing-appender`
- 打包：`embed-resource` 嵌入图标 + `#![windows_subsystem = "windows"]` 隐藏控制台
- 构建：`cargo build --release --target x86_64-pc-windows-gnu`

> 用户规则 2 规定 Python 才用 loguru；本项目是 Rust，统一使用 `tracing`。

---

## 一、需求与决策记录

### 1.1 用户已确认的设计决策

| # | 项 | 决策 |
|---|----|------|
| 1 | 扫描范围 | **默认全盘扫描**；UI 维护"白名单目录"列表（不扫的目录） |
| 2 | 排除目录语义 | "白名单" = 不扫描的目录；模板按钮：系统目录、Program Files、回收站、临时目录 |
| 3 | 文件大小 | **不设上限**（可加最小 KB 过滤以跳过空文件） |
| 4 | .doc 打开 | **`<exe 同目录>/doclite.exe`** 自动探测，配置中可改 |
| 5 | .pdf 打开 | Windows 默认 PDF 关联程序（SumatraPDF / Edge / Adobe），可设置覆盖 |
| 6 | 启动后等待 | 设置项"截图前等待时间"毫秒（默认 1500ms） |
| 7 | 截图方式 | **模拟 `Win+Shift+S`** 触发系统截图工具；UI 提示用户在屏幕上手动框选；轮询剪贴板读位图 |
| 8 | OCR | **Umi-OCR HTTP**（`http://127.0.0.1:1224/api/ocr`），`Umi-OCR.exe` 放 exe 同目录自动启动 |
| 9 | 管理员权限 | **启动时单次申请 UAC**（未以管理员运行时 `ShellExecuteExW` + `runas` 重启一次） |
| 10 | 报告 | **本地留存**（HTML/JSON/PNG 组图） |
| 11 | 关键词来源 | **不从网络拉取** |
| 12 | UI 风格 | **Material**（圆角、阴影、规范化间距、Material 配色） |
| 13 | 触发方式 | **"开始检测"按钮**，无全局热键 |
| 14 | 关键词网络拉取 | 不做 |

### 1.2 进入设置页的可配置项

| # | 项 | 默认 |
|---|----|------|
| 15 | 关键词列表 / 导入导出 / 大小写 / 正则 / 整词 / 按文件类型覆盖 | 默认"机密/秘密/绝密/内部/Confidential/Secret" |
| 16 | 抽检数量 | 10 |
| 17 | 抽样策略（随机 / 分层 / 类型配额） | 完全随机 |
| 18 | 并发度 | 1（人工参与截图，串行更稳） |
| 19 | 单文件超时 | 120s |
| 20 | 报告格式（HTML/JSON/PNG 组图） | HTML + JSON |
| 21 | 首次启动向导 | 引导 Umi-OCR/doclite 路径、关键词、等待时间 |
| 22 | 中文字体（嵌入或自选） | 嵌入 SourceHanSansSC |
| 23 | 主题（Light / Dark / Follow） | Follow |
| 24 | 国际化（中/英） | 中文 |
| 25 | 日志（级别、保留天数、UI 实时） | Info，14 天 |
| 26 | 静默/托盘/开机自启 | 默认关闭 |
| 27 | 历史去重（同文件 N 天不重复） | 7 |

---

## 二、目录结构

```
secret-file-selfcheck/
├── Cargo.toml
├── build.rs                       # embed-resource / winres
├── app.ico                        # 图标
├── app.rc                         # 资源脚本
├── README.md                      # 部署说明：与 doclite.exe / Umi-OCR.exe 同目录
├── assets/
│   ├── fonts/SourceHanSansSC-Regular.otf
│   └── templates/report.html
├── src/
│   ├── main.rs                    # eframe 入口 + UAC 提升 + 启动 Umi-OCR
│   ├── app.rs                     # 顶层 App struct + 页面路由
│   ├── privilege.rs               # 单次 UAC 提升（ShellExecuteExW runas）
│   ├── config/
│   │   ├── mod.rs
│   │   ├── model.rs               # AppConfig 强类型
│   │   └── persist.rs             # 读写 %APPDATA%/.../config.toml
│   ├── ui/
│   │   ├── settings.rs            # 设置页（多分组）
│   │   ├── home.rs                # 主面板（开始/进度/日志/截图引导）
│   │   ├── report.rs              # 报告查看
│   │   ├── material.rs            # Material 风格 token & 主题
│   │   └── widgets.rs             # 字体加载、托盘
│   ├── scan/
│   │   ├── walker.rs              # 全盘遍历 + 白名单（不扫的目录）
│   │   ├── sampler.rs             # 抽检算法
│   │   └── filter.rs              # 扩展名/隐藏/最小大小过滤
│   ├── inspect/
│   │   ├── mod.rs                 # Inspector trait + Finding
│   │   ├── docx_inspector.rs      # 文本解析（docx-rs）
│   │   ├── pdf_inspector.rs       # 外部查看器 + 截图 + OCR
│   │   ├── doc_inspector.rs       # doclite.exe + 截图 + OCR
│   │   ├── external.rs            # 启进程 / 关闭窗口 / 强杀
│   │   ├── screenshot.rs          # 触发 Win+Shift+S + 读剪贴板
│   │   └── umi_ocr.rs             # Umi-OCR HTTP 客户端
│   ├── matcher/
│   │   ├── keywords.rs            # 关键词匹配（正则、大小写、整词、按文件类型）
│   │   └── hash.rs                # 文件指纹 + 去重
│   ├── report/
│   │   ├── model.rs               # Report / Finding 结构
│   │   ├── html.rs                # 渲染 HTML
│   │   └── png.rs                 # 合并截图
│   └── utils/
│       ├── paths.rs               # APPDATA / exe 同目录 / 临时目录
│       └── logger.rs              # tracing 初始化
└── tests/
    ├── matcher_test.rs
    ├── sampler_test.rs
    └── fixtures/
        ├── sample.docx
        └── sample.pdf
```

---

## 三、关键 Cargo.toml 节选

```toml
[package]
name = "secret-file-selfcheck"
version = "0.1.0"
edition = "2021"

[dependencies]
eframe = { version = "0.27", default-features = false, features = ["default_fonts", "glow"] }
egui = "0.27"
egui_extras = { version = "0.27", features = ["all_loaders"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "fs"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
tracing-appender = "0.2"
docx-rs = "0.4"
encoding_rs = "0.8"
chardetng = "0.1"
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
base64 = "0.22"
sysinfo = "0.31"
windows = { version = "0.58", features = [
    "Win32_UI_WindowsAndMessaging",
    "Win32_System_Threading",
    "Win32_Graphics_Gdi",
    "Win32_System_Console",
    "Win32_Foundation",
] }
sys-locale = "0.3"
dirs = "5"
walkdir = "2"
regex = "1"
aho-corasick = "1"
sha2 = "0.10"
anyhow = "1"
thiserror = "1"
chrono = { version = "0.4", features = ["serde"] }
once_cell = "1"
log = "0.4"
url = "2"
image = { version = "0.25", default-features = false, features = ["png"] }

[build-dependencies]
embed-resource = "2"

[profile.release]
opt-level = 3
lto = "thin"
codegen-units = 1
strip = true
panic = "abort"
```

---

## 四、设置页设计（6 个分组，60+ 控件）

设置页用 `egui::ScrollArea` + `CollapsingHeader` 分组，所有变更即时写入 `config.toml`。

### A. 常规
- 启动时自动检测（开关）
- 启动时最小化到托盘（开关）
- 开机自启（开关 + 写入 `HKCU\...\Run`）
- 主题：Light / Dark / Follow
- 语言：中文 / English
- 日志级别：Error / Warn / Info / Debug / Trace
- 日志保留天数（数字框）
- 日志文件路径（只读 + 打开按钮）
- 单实例锁（开关，避免多开）
- 检查前清空临时目录（开关）
- 检查完自动退出（开关 + 倒计时秒数）

### B. 扫描范围
- 扫描根目录：默认空（=全盘）
- **白名单目录**（不扫的目录，多行列表 + 增删 + 拖拽）
- 模板按钮：系统目录、Windows、Program Files、回收站、临时目录
- 包含隐藏文件（开关）
- 包含系统文件（开关）
- 跟随符号链接（开关）
- 文件最小大小 KB（数字框，默认 1；0 = 不限）
- 最大遍历深度（数字框，0=无限）
- 扩展名白名单（多选 + 自定义：默认 doc/docx/pdf）
- 修改时间范围（起始/结束日期）
- 单次扫描超时（分钟，0=无限）

### C. 抽检
- 抽检数量（数字框）
- 抽样策略（单选：完全随机 / 分层 / 类型配额）
- 类型配额：DOC / DOCX / PDF 各自数量
- **抽检执行方式：串行**（一个接一个打开，前一份处理完再开下一份，**无并发选项**）
- 单文件总超时（秒，默认 120）
- 同文件多少天内不重复（数字框，默认 7）
- 跳过锁定/无权限文件（开关）
- 命中后是否继续后续文件（开关，默认继续；关闭则一旦命中就停）

### D. 查看器与截图
- .doc 查看器路径（默认 `<exe 同目录>/doclite.exe`，文件选择 + 探测）
- .doc 启动参数模板（默认 `{path}` 占位）
- .pdf 查看器路径（默认 = Windows 关联程序，文件选择 + "用默认"按钮）
- .pdf 启动参数模板（默认 `{path}`）
- 截图前等待时间 ms（默认 1500）
- 用户截图超时秒（默认 60，超时跳过当前文件）
- 截图后是否自动关闭查看器（开关 + 关闭等待 ms + 强杀超时 ms）
- Umi-OCR HTTP 地址（默认 `http://127.0.0.1:1224/api/ocr`）
- Umi-OCR 启动路径（默认 `<exe 同目录>/Umi-OCR.exe`）
- Umi-OCR 启动后等待秒（默认 3）
- Umi-OCR 调用超时秒（默认 30）
- OCR 选项语言配置（默认 `models/config_chinese.txt`）
- OCR 启用文本方向校正（开关）
- OCR 限制边长（960/2880/4320/不压缩）

### E. 关键词
- 全局关键词列表（多行编辑 + 增删 + 一键清空）
- 导入 / 导出 txt
- 区分大小写（开关）
- 使用正则（开关）
- 整词匹配（开关）
- 按文件类型追加（DOC / DOCX / PDF 各自多行列表）
- 误报白名单（列表：指纹 → 关键词，可清除）
- 命中最低置信度（数字框 0-100）
- 高亮颜色（颜色选择器）

### F. 报告
- 输出目录（路径选择）
- 输出格式（多选：HTML / JSON / PNG 组图）
- 报告文件名前缀（默认 `selfcheck-{date}`）
- 包含截图（开关）
- 敏感词高亮（开关）
- 截图最大边长 px（数字框，默认 1600）
- 历史保留条数（数字框，默认 30）
- 检查完自动打开报告（开关）
- 同时复制报告到剪贴板摘要（开关）

底部按钮：**恢复默认** / **另存为模板** / **立即保存** / **打开配置文件**。

---

## 五、工作流程

```
[启动]
   ├─ IsUserAnAdmin? 否 → ShellExecuteExW "runas" 重启 → 退出当前进程
   ├─ 加载 config.toml（不存在则首次启动向导）
   ├─ 嵌入字体 set_fonts
   ├─ 启动 Umi-OCR.exe（同目录 / 配置路径）→ 轮询 HTTP /api/ocr 是否可达
   └─ 启动单实例锁

[主面板] 用户点击 "开始检测"
   │
   ▼
[扫描阶段] walker 遍历全盘 → 白名单剔除 → 扩展名/大小/隐藏过滤 → 候选列表 Vec<PathBuf>
   │
   ▼
[抽样阶段] sampler 按策略（随机 / 分层 / 类型配额）选 N 个
   │
   ▼
[抽检阶段] 串行（默认 1 并发；并发时 buffer_unordered）
   ├─ DOCX：docx-rs 读段落 → keywords 匹配
   ├─ DOC：  spawn(doclite.exe "{path}") → 等待 wait_ms
   │           → keybd_event LWIN+LSHIFT+'S' 模拟 Win+Shift+S
   │           → UI 弹层 "请框选 doclite 窗口区域" + 倒计时
   │           → 轮询剪贴板（OpenClipboard/GetClipboardData CF_BITMAP）拿位图
   │           → base64 编码 → POST /api/ocr
   │           → 匹配关键词 → WM_CLOSE 关闭窗口 → 等 close_wait_ms → 强杀
   └─ PDF：  spawn(pdf_viewer "{path}") → 等待 → 同上截图 → OCR → 匹配 → 关闭

[汇总] Finding 列表 → 写 HTML/JSON/PNG → 通知系统 → 弹窗（命中/未命中）
```

并发：用 `tokio::sync::watch` 通道发取消信号；进度用 `Arc<AtomicUsize>` 推进；UI 在 `update()` 里非阻塞地拉取状态。

---

## 六、报告格式

**HTML 报告（默认）**：
- 顶部：检查时间、机器名、用户、抽检数量、命中数量、关键词列表
- 表格：文件名、路径、类型、命中关键词、置信度、截图缩略图、状态
- 截图：原图 + 敏感词高亮（红框）
- 底部：原始 JSON 数据链接

**JSON 报告**：
```json
{
  "scan_id": "2026-06-08-153012-1234",
  "machine": "DESKTOP-XXX", "user": "alice",
  "started_at": "...", "finished_at": "...",
  "total": 20, "hit": 1,
  "findings": [
    { "path": "...", "type": "doc", "matched": ["机密"], "score": 0.92,
      "screenshot": "screenshots/001.png", "boxes": [[x1,y1,x2,y2]] }
  ]
}
```

**PNG 组图**：把每张截图拼成 A4 大图，便于一键分享。

---

## 七、关键技术点

### 1. MSYS2 + MinGW 编译要点
```bash
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake
rustup target add x86_64-pc-windows-gnu
```
`.cargo/config.toml`：
```toml
[target.x86_64-pc-windows-gnu]
linker = "x86_64-w64-mingw32-gcc"
ar = "x86_64-w64-mingw32-ar"
```

### 2. 隐藏控制台 + UAC 单次提升
- `src/main.rs` 顶部：`#![windows_subsystem = "windows"]`
- `privilege.rs`：
  - `IsUserAnAdmin()` → `false` 时构造 `ShellExecuteExW { lpVerb: "runas", lpFile: current_exe, nShow: SW_SHOWNORMAL }`
  - 当前进程 `ExitProcess(0)`；新进程以管理员启动
  - 第二次进入已经管理员，跳过
- 入口处保证 `IsUserAnAdmin() == true` 后再 `run()`

### 3. 中文字体
- `assets/fonts/SourceHanSansSC-Regular.otf`（~16MB）通过 `include_bytes!` 嵌入
- `eframe::NativeOptions` 启动后 `egui::Context::set_fonts`：
  ```rust
  let mut fonts = FontDefinitions::default();
  fonts.font_data.insert("cn".into(), FontData::from_static(include_bytes!("../assets/fonts/SourceHanSansSC-Regular.otf")));
  fonts.families.get_mut(&FontFamily::Proportional).unwrap().insert(0, "cn".into());
  ctx.set_fonts(fonts);
  ```

### 4. .doc / .pdf 截图流程（最复杂）
1. `CreateProcessW` 启动 `doclite.exe "{path}"`（或 PDF 关联程序）
2. 轮询 `EnumWindows` + `GetWindowThreadProcessId` 匹配 PID 获取 HWND
3. `SetForegroundWindow` + `ShowWindow(SW_RESTORE)` 强制前台
4. `Sleep(wait_ms)`
5. `keybd_event(VK_LWIN, 0, 0, 0); keybd_event(VK_LSHIFT, 0, 0, 0); keybd_event(0x53, 0, 0, 0)` 等
   - 释放：`keybd_event(..., KEYEVENTF_KEYUP, 0)`
6. UI 弹层 "请用系统截图工具框选窗口区域"（带倒计时）
7. 启动 `tokio::time::interval(200ms)` 轮询剪贴板：`OpenClipboard` → `GetClipboardData(CF_BITMAP)` → 转 `DynamicImage`
8. 拿到位图 → `base64::encode` → `reqwest::Client::new().post(URL).json(...)`
9. 解析 `{"code":100, "data":[{"text":"...","box":[[x1,y1],...]}]}`
10. `keywords` 匹配 → 写 `Finding`
11. 关闭：先 `PostMessage(hwnd, WM_CLOSE, 0, 0)` → `Sleep(close_wait_ms)` → `taskkill /F /PID xxx /T`

### 5. Umi-OCR HTTP 客户端（关键代码片段）
```rust
// src/inspect/umi_ocr.rs
pub struct UmiOcrClient { base_url: String, client: reqwest::blocking::Client }

#[derive(Serialize)]
struct OcrRequest<'a> { base64: &'a str, options: OcrOptions }

#[derive(Serialize)]
struct OcrOptions { #[serde(rename = "ocr.language")] language: String,
                    #[serde(rename = "ocr.cls")] cls: bool,
                    #[serde(rename = "ocr.limit_side_len")] limit_side_len: u32,
                    #[serde(rename = "tbpu.parser")] parser: String }

#[derive(Deserialize)]
pub struct OcrResponse { pub code: u32, pub data: Vec<OcrItem>, pub time: f64 }
pub struct OcrItem { pub text: String, pub score: f32, pub box: Vec<[f64;2]> }

impl UmiOcrClient {
    pub fn recognize_png(&self, png: &[u8], lang: &str) -> anyhow::Result<OcrResponse> {
        let b64 = base64::engine::general_purpose::STANDARD.encode(png);
        let req = OcrRequest { base64: &b64, options: OcrOptions { language: lang.into(), cls: false, limit_side_len: 2880, parser: "multi_para".into() } };
        let resp = self.client.post(&self.base_url).json(&req).send()?.json::<OcrResponse>()?;
        if resp.code != 100 { anyhow::bail!("Umi-OCR 返回 code={}", resp.code); }
        Ok(resp)
    }
}
```

### 6. Umi-OCR 启动 + 健康检查
- 启动时检查 `<exe 同目录>/Umi-OCR.exe` 存在 → 不存在则提示"请将 Umi-OCR.exe 放在 exe 同目录"
- `CreateProcessW` 启动后，循环 `GET http://127.0.0.1:1224/` 直到成功或超时（默认 3s）
- 失败时给出修复指引（端口被占、Umi-OCR 未运行）

### 7. 关键词匹配
- 关键词少：用 `regex::RegexSet`
- 关键词多：用 `aho_corasick::AhoCorasick`（多模式 AC 自动机）
- 命中位置记录 `(text_index, char_offset, length)` → 写回 `box` 坐标做红框高亮

### 8. 取消与超时
- 全局 `tokio::sync::watch::Sender<bool>` 发取消信号
- 每个 Inspector 用 `tokio::time::timeout(总超时, ...)` 包裹
- UI 顶栏 "取消" 按钮 → 发送 `true`

### 9. 性能与稳定
- 截图位图大于 `screenshot_max_side` 时先 `image::imageops::resize`
- 临时文件清理：每次启动清 `temp/secret-scan-*`
- 关闭查看器失败 → 二次 `taskkill /F /T`
- doclite 进程残留 → 主程序退出前强制清

---

## 八、构建与发布

```bash
# 一次性
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake
rustup target add x86_64-pc-windows-gnu

# 编译
cargo build --release --target x86_64-pc-windows-gnu

# 产物
ls target/x86_64-pc-windows-gnu/release/secret-file-selfcheck.exe
```

发布物（同级目录）：
```
secret-file-selfcheck.exe
Umi-OCR.exe
Umi-OCR-data/        # Umi-OCR 自带数据目录
doclite.exe
README.md
```

README 章节：构建步骤、运行方式、首次配置（放 Umi-OCR 与 doclite）、常见问题（OCR 不返回、doclite 启动失败、UAC 弹窗被禁用、AV 误报）。

---

## 九、测试策略

- **单元测试**：
  - `matcher::keywords`：大小写、正则、整词、误报白名单
  - `sampler`：随机 / 分层 / 配额
  - `filter`：隐藏文件、扩展名白名单、最小大小
  - `walker`：白名单目录剔除、最大深度
- **集成测试**：
  - `inspect::umi_ocr` 用一个 mock HTTP server（`httpmock` / `wiremock`）验证请求体/响应解析
  - fixture：`sample.docx`（含"机密"）和"普通"两份 → 走完 Inspector
- **手动测试**：
  - 在 doclite / SumatraPDF / Edge 下验证窗口截图与 OCR 准确度
  - 验证 Umi-OCR 中文识别率
  - 验证 UAC 弹窗仅出现一次
- **不**做 GUI 自动化测试（egui 暂无稳定 e2e 方案）

---

## 十、MVP 任务拆分

### 任务 1：脚手架 + 隐藏控制台 + UAC
1. `Cargo.toml` + 最小 `main.rs`，`cargo build` 通过
2. `build.rs` + `#![windows_subsystem = "windows"]` 隐藏控制台
3. `privilege.rs` 实现 `ensure_admin()`，未提权时 `runas` 重启
4. 提交

### 任务 2：egui 入口 + Material 主题 + 中文字体
1. `app.rs` 骨架：左侧设置、右侧主面板、底部状态栏
2. `ui/material.rs`：颜色 token + 圆角控件
3. `ui/widgets.rs`：嵌入 `SourceHanSansSC-Regular.otf`
4. UI 显示"涉密文件自检工具"中文正常
5. 提交

### 任务 3：配置模型与持久化
1. `config/model.rs` 强类型 `AppConfig`（serde + toml）
2. 启动加载、退出保存到 `%APPDATA%\secret-file-selfcheck\config.toml`
3. 首次启动向导：检测 Umi-OCR/doclite 路径、关键词、等待时间
4. 单元测试：序列化往返
5. 提交

### 任务 4：目录遍历 walker
1. `walkdir` + 白名单剔除 + 扩展名白名单 + 隐藏/系统过滤 + 最小大小
2. 单元测试：白名单、扩展名、深度
3. 提交

### 任务 5：抽检 sampler
1. 完全随机 / 分层 / 类型配额 三种策略
2. 单元测试
3. 提交

### 任务 6：关键词匹配
1. `keywords` 模块：大小写、正则、整词、白名单
2. `aho-corasick` 多模式
3. 单元测试
4. 提交

### 任务 7：DOCX 文本抽检
1. `docx-rs` 读段落
2. 命中检测
3. fixture 测试
4. 提交

### 任务 8：Umi-OCR HTTP 客户端
1. `umi_ocr.rs` 阻塞 POST /api/ocr，解析返回
2. Umi-OCR 启动 + 健康检查
3. 集成测试（mock server）
4. 提交

### 任务 9：截图链路
1. `external.rs` 启进程 / 关闭窗口 / 强杀
2. `screenshot.rs`：`keybd_event` 模拟 `Win+Shift+S` + 剪贴板轮询读位图
3. 单元测试 + 手动测试
4. 提交

### 任务 10：DOC 抽检
1. `doc_inspector.rs` 拼装流程：doclite.exe + 等待 + 截图 + OCR + 匹配 + 关闭
2. 提交

### 任务 11：PDF 抽检
1. `pdf_inspector.rs` 拼装流程：关联程序 + 等待 + 截图 + OCR + 匹配 + 关闭
2. 提交

### 任务 12：并发调度
1. `tokio` + `buffer_unordered` 调度；进度、取消、日志
2. 提交

### 任务 13：报告输出
1. `report::html` + `report::png` + `report::json`
2. 提交

### 任务 14：设置页 UI（A-F 六分组）
1. 所有控件
2. 即时写 config
3. 提交

### 任务 15：主面板 UI
1. "开始检测" 按钮、进度条、实时日志
2. 截图引导弹层
3. 提交

### 任务 16：打包
1. release 构建
2. 验证无控制台、UI 中文、抽检 10 份报告正确、UAC 仅一次
3. README（构建/部署/FAQ）
4. 提交

---

## 十一、风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| Umi-OCR 启动失败/端口占用 | OCR 全失败 | 启动时健康检查 + 清晰错误提示；允许用户在设置中改端口 |
| Win+Shift+S 触发失败（被其它程序抢占） | 截不到图 | 增加"手动粘贴"兜底：UI 提供"从剪贴板读取"按钮；再不行就跳过 |
| doclite 启动后窗口未出现 | 截图空白 | wait_ms 可调；增加"窗口标题探测"再截图 |
| OCR 识别率低（中文/复杂排版） | 漏报 | 提供 hi-res（limit_side_len=4320）；截图后预处理（二值化）作为后续 |
| 截图位图被 Word 起始页覆盖 | 漏报 | OCR 后再次截图（用户配合二次框选），或启用 `PrintWindow` 抓窗口（兜底） |
| 单 exe 体积 | 20-40MB | LTO + strip + release 优化；提供"瘦身版"不内嵌字体 |
| Anti-Virus 误报 | 启动被拦 | README 提示加白名单；可选代码签名 |
| 全盘扫描耗时 | 几分钟到几十分钟 | UI 实时进度 + 可取消；默认全盘但允许"白名单"缩小范围 |
| UAC 弹窗被用户禁用 | 后续权限不足 | 首次启动检测 UAC 状态；告知用户 |
| 剪贴板被其它程序占用 | 读不到图 | `OpenClipboard` 重试 + 退避；超过 N 次失败则放弃当前文件 |

---

## 十二、可后续追加（不在 MVP 范围）

- 哈希去重在 SQLite 中持久化
- 关键词 + 文件指纹的"已确认误报"列表
- 隔离区（命中后复制到独立目录）
- 开机自启 + 托盘
- 报告 PDF 格式
- 关键词网络下发
- 抽检历史对比 / 趋势图

---

## 十三、最终确认（已通过）

1. ✅ 截图三模式（manual / auto_printwindow / auto_with_manual_fallback）已纳入设计与实现。
2. ✅ 抽检固定串行，无并发选项。
3. ✅ 所有核心设计决策（1.1 节 15 项）已锁定。

可进入实现阶段，按任务 1-16 顺序执行。