# ProcessDock 实现蓝图

## 需求证据

| 条目 | 分类 | 依据 | 实现决定 |
|---|---|---|---|
| 进程、端口、CPU、内存列表 | requested | 用户给出的表格字段 | 使用 `psutil` 读取本机实时数据 |
| 搜索、刷新、自动刷新 | requested | 用户给出的页头控件 | 本地代理筛选；3 秒后台刷新 |
| 点击行显示完整详情 | requested | 用户给出的详情字段 | 使用主窗口右侧详情面板 |
| 打开位置、复制命令、两种结束方式 | requested | 用户给出的详情操作 | 真实调用资源管理器、剪贴板和系统进程 API |
| 原生 GUI | requested | 用户补充“用 GUI 实现” | PySide6 Qt Widgets，不启动 Web 服务 |
| TCP 只显示监听连接 | inferred | “监听端口”及端口管理工具的核心用途 | 排除临时出站 TCP 端口，UDP 保留绑定端口 |
| 当前应用自保护与 PID 复用校验 | inferred | 降低危险操作误用风险 | 禁止结束自身；操作前核对创建时间 |

未提供外部截图、源码或演示站点，因此不存在无法访问的外部材料，也不声明对第三方产品的像素级复刻。

## 页面与操作矩阵

| 区域 | 读取 | 可见操作 | 空/错状态 |
|---|---|---|---|
| 顶部工具栏 | 当前筛选与刷新状态 | 搜索、手动刷新、自动刷新开关 | 刷新错误显示警告条 |
| 统计卡片 | 进程数、端口数、系统 CPU/内存 | 无 | 首次加载显示占位符 |
| 进程表格 | 真实进程和监听端口快照 | 排序、选中、正常结束 | 无匹配结果页、权限警告 |
| 右侧详情 | 选中进程完整信息 | 打开位置、复制命令、正常/强制结束 | 未选择、进程已结束、权限受限 |

## 领域对象与状态

应用没有数据库。核心对象是只读的 `ProcessSnapshot`，以 `(PID, create_time)` 标识一个进程实例。结束操作的状态转换为：

```text
运行中 --正常结束请求--> 已结束
   \--请求后仍运行--> 运行中 --强制结束--> 已结束
```

操作前重新读取 `create_time`。如果 PID 已被复用，则拒绝操作并要求刷新。

## 验收场景

1. 启动应用后，后台读取本机进程，窗口保持可交互。
2. 输入进程名、PID 或已知监听端口，列表立即缩小到匹配项。
3. 点击任意一行，右侧显示与该 PID 对应的路径、命令和资源数据。
4. 点击复制命令后，系统剪贴板获得完整启动命令。
5. 点击正常结束或强制结束，先显示确认框；确认后执行真实系统操作并刷新列表。
6. 对 ProcessDock 自身，结束按钮禁用；对已结束或 PID 已复用的进程，操作被拒绝并显示明确错误。

## 交付范围

- 目标系统：Windows 10/11
- 运行时：Python 3.10+
- 依赖：PySide6、psutil
- 存储：无
- 网络服务：无
- 已知限制：受当前 Windows 用户权限约束；非 Windows 兼容模式的 CPU 首帧是采样基线；正常结束的温和程度取决于目标进程与 Windows 行为。