Files
jianli-boss/docs/优化方案.md
2026-08-25 19:46:38 +08:00

193 lines
9.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Boss直聘 AI 投递系统 — 优化方案
> 本文档汇总系统搭建后,通过评审讨论确定的优化项。
> 每个优化项包含:问题来源、现状缺陷、改造方案、涉及文件、验收标准与当前状态。
---
## 一、架构现状(优化前)
- **服务端**:FastAPI + MySQL + JWT,按 `client_code`(机器硬件指纹)识别用户
- **客户端**:本地 Web 控制面板 + AdsPower 指纹浏览器 + Playwright + AI 评分
- **身份模型**:以机器硬件指纹作为唯一编码注册,数据按用户隔离
本轮优化主要围绕**身份体系**与**登录健壮性**展开。
---
## 二、优化项清单
### ⭐ 优化项 1:系统登录改为「账号密码」体系(核心)
**问题来源**
- 「RPA 是不是要有一个登录步骤?要不然怎么知道这个 RPA 要登录到系统的哪一个账号?」
- 「RPA 的编码是不是应该以指纹浏览器为唯一?要不然用户切换了机器也会被认为是新的。」
**现状缺陷**
- 身份绑定在**机器硬件指纹**上:换机器 = 新用户,数据无法延续。
- 无真正的"账号"概念:无用户名、无密码、无法管理、无法找回。
- RPA 与账号无显式关系,无法明确"控制哪个 RPA 启停"。
**改造方案**(已确认:**账号密码登录**)
- 身份从"机器指纹 / Profile 编码"改为**服务端账号(用户名 + 密码)**。
- 账号存于服务端,与机器、与指纹浏览器 Profile 完全解耦。
- 指纹浏览器回归本职:仅作为访问 Boss直聘 的防检测浏览器工具(本地配置)。
- 数据(简历 / 投递记录)全部挂在账号下。
> 说明:此前讨论的"Profile localStorage 编码"方案已被账号密码体系取代,不再实施。
**涉及改动**
| 端 | 文件 | 改动内容 |
|----|------|---------|
| 服务端 | `server/auth.py` | 新增 `hash_password` / `verify_password`(PBKDF2);token payload 用 username |
| 服务端 | `server/models.py` | User 增加 `username`(唯一)、`password_hash`;`client_code` 降为可选设备标记 |
| 服务端 | `server/schemas.py` | 改造注册模型;新增登录请求/响应模型 |
| 服务端 | `server/routers/register.py` | 拆分 `/register`(注册)与 `/login`(登录)接口 |
| 客户端 | `client/server_api.py` | `register/login` 改为账密;保留 token 持久化 |
| 客户端 | `client/web/app.py` | 新增 `/api/register`、`/api/login`;替换指纹连接逻辑 |
| 客户端 | `client/web/templates/index.html` + `static/app.js` | Step1 改为登录/注册表单 |
**验收标准**
- [x] 可通过用户名密码注册新账号,密码以加盐哈希存储(不存明文)
- [x] 可通过用户名密码登录,返回 JWT token
- [x] 客户端保存 token,二次启动免登录;token 失效时引导重新登录
- [x] 换机器登录同一账号,可见原有简历与投递记录
**状态**:✅ 已完成
---
### 优化项 2:Boss直聘登录「活体检测」(重连健壮性)
**问题来源**
- 「如果 RPA 离线后再次登录,但指纹浏览器已经登录了 Boss 该怎么办?是不是应该做一个检查处理?」
**现状缺陷**
- 登录状态只存在服务端字段里(`login_status`),从不与真实浏览器做活体校验。
- 场景 A:Profile 里 Cookie 仍有效(已登录),却仍强制用户手动扫码。
- 场景 B:Cookie 已过期,但服务端仍记 `logged_in`,后续抓简历/投递会失败。
**改造方案**(已确认:**进入登录步骤自动检测**)
- 进入登录步骤时,自动调用 `BrowserManager.check_boss_login()` 做活体校验。
- 已登录 → 自动标记 `logged_in`,跳过手动登录,直接进入简历步骤。
- 未登录 → 展示手动登录引导(扫码/账密)。
- 新增 `/api/detect-login` 接口供前端触发。
**涉及改动**
| 端 | 文件 | 改动内容 |
|----|------|---------|
| 客户端 | `client/web/app.py` | 新增 `/api/detect-login`,内部调用 `check_boss_login` 并回写服务端状态 |
| 客户端 | `client/web/static/app.js` | 进入 Step2 自动触发检测,按结果决定跳过或引导登录 |
**验收标准**
- [x] Profile 已登录时,进入登录步骤自动识别并跳过手动登录
- [x] Cookie 失效时,能正确识别为未登录并引导重新登录
**状态**:✅ 已完成
---
### 优化项 3:单账号模式(范围决策,非编码项)
**问题来源**
- 「RPA 是不是需要与账号有一个关系?要不然怎么控制哪个 RPA 开始、哪个结束?」
**决策**(已确认:**单账号**)
- 一个客户端一次只服务一个账号,投递任务为该账号的全局单例。
- "启停控制"即"启停当前登录账号的投递任务",无需多账号实体。
- 多账号 / 多 Profile 独立启停为后续可扩展方向(届时引入 `RpaProfile` 实体)。
**状态**:已确认范围,本轮不做多账号改造
---
### 优化项 4:RPA 在线判定(心跳机制)
**问题来源**
- 「我们现在是怎么确认 RPA 在线的?」
**现状缺陷**(优化前)
- 无真正的在线判定:`last_seen_at` 只在登录/写操作时被动更新,客户端静默挂着不刷新。
- 前端 8 秒轮询只调只读接口 `/me`,服务端不记录为存活。
- 客户端崩溃/断网后服务端永远不知道离线,`logging_in` 状态会永久卡死。
**改造方案**
- 服务端新增 `/api/auth/heartbeat`,客户端登录后每 30s 上报一次,刷新 `last_seen_at`。
- 在线判定:`last_seen_at` 距今 ≤ 90s(= 3 个心跳周期)为在线。
- `/api/auth/me` 返回 `is_online` 字段;前端顶部展示“RPA在线/离线”徽章。
- 懒清理:客户端已离线却仍停留在 `logging_in` 时,自动重置为 `not_login`。
**涉及改动**
| 端 | 文件 | 改动内容 |
|----|------|---------|
| 服务端 | `server/schemas.py` | `UserInfo` 增加 `is_online` |
| 服务端 | `server/routers/register.py` | 新增 `/heartbeat`、`is_user_online` 判定、`/me` 懒清理 |
| 客户端 | `client/config.py` | 新增 `HEARTBEAT_INTERVAL=30` |
| 客户端 | `client/server_api.py` | 新增 `heartbeat()`(失败不抛异常) |
| 客户端 | `client/web/app.py` | 后台心跳线程(登录启动、退出停止);`/api/status` 返回 `rpa_online` |
| 客户端 | `client/web/static/app.js` | 顶部展示 RPA 在线徽章 |
**验收标准**
- [x] 登录后心跳线程自动启动,每 30s 上报;退出登录自动停止
- [x] 客户端关闭/断网 90s 后,服务端判定离线,前端徽章变为“RPA离线”
- [x] 离线时 `logging_in` 状态自动重置为 `not_login`
**业务底层收敛(重要设计约束)**
在线判定不允许在各路由里各自实现,统一收敛到 `server/online.py`:
| 服务 | 职责 | 使用方 |
|------|------|--------|
| `is_online(user)` | 纯判定,无副作用 | `/me` 返回在线状态 |
| `touch(user, db)` | 刷新活跃时间 | `/heartbeat` |
| `require_online_user` | 前置校验依赖:认证→先验在线→再刷新 | 所有需 RPA 存活的写操作 |
前置校验接入清单:
- ✅ `/api/sessions/start`(开始投递)、`/stats`(上报统计)
- ✅ `/api/auth/login-status`(Boss 登录状态变更)
- ✅ `/api/resumes/batch`(简历上传)、`/api/jobs/report`(投递上报)
- ⚠️ 特例:`/api/sessions/{id}/stop` 故意豁免在线拦截——stop 是安全清理操作,
否则离线前遗留的 running 僵尸会话永远无法关闭
- 只读查询接口(history/stats/list)不强制在线
客户端同步收敛:`client/web/app.py` 的 `_require_auth()` 统一未登录拦截,
`_require_rpa_online()` 在开始投递前先发心跳再确认服务端判定在线。
后续新增任何写操作接口,必须走 `require_online_user`,不得另起炉灶。
**状态**:✅ 已完成
---
## 三、已通过设计决策解决(无需单独实现)
| 讨论点 | 结论 |
|--------|------|
| RPA 编码唯一性(跨机器) | 由服务端账号体系解决:账号与机器/Profile 解耦 |
| RPA 与账号绑定、启停控制 | 单账号下,账号即身份,投递会话已有单实例约束 |
| 账号找回 | 使用服务端账号密码,账号常驻服务端,无需找回机制 |
---
## 四、实施顺序
1. **服务端账号密码体系**(优化项 1)
- auth.py 密码哈希 → models.py → schemas.py → register.py 路由
2. **客户端登录/注册**(优化项 1 客户端部分)
- server_api.py → web/app.py → 前端表单
3. **Boss登录活体检测**(优化项 2)
- web/app.py detect-login → 前端自动检测
4. **RPA 在线判定**(优化项 4)
- 服务端 heartbeat 接口 → 客户端心跳线程 → 前端徽章
---
## 五、决策记录
| 议题 | 选项 | 最终决定 |
|------|------|---------|
| 账号规模 | 单账号 / 多账号多开 | **单账号** |
| Boss登录检测时机 | 自动检测 / 手动按钮 / 两者 | **进入登录步骤自动检测** |
| 系统登录模式 | 纯编码自动 / 账号密码 / 混合 | **账号密码登录** |
| 账号找回 | 需要 / 不需要 | **不需要**(服务端账号密码天然解决) |