--- name: wechat-viewer-dev description: WeChat Viewer 开发模式参考——认证系统、简历状态列、Flask 重启、DOM 下拉菜单、Cloudflare 隧道。触发词:wechat viewer 开发、viewer 登录、viewer 认证、简历状态、cloudflared。 version: 1.0 category: wechat --- # WeChat Viewer 开发参考 非官方 skill——沉淀 wechat-viewer 项目的开发模式、常见坑和架构决策。wechat-viewer 和 wechat-web-viewer 是受保护的 bundled skill,此文件作为补充参考。 ## 登录认证系统 ### 架构 ``` before_request → 检查 session['user_id'] → 无 → redirect /login?next=<原路径> → 有 → 正常渲染 /login POST → 查 users 表 → SHA-256 验证密码 → 通过 → session['user_id'] = id → redirect next → 失败 → 返回错误 /logout → session.clear() → redirect /login ``` ### 关键文件 | 文件 | 改动 | |------|------| | `local_db.py` init_db() | `CREATE TABLE users (id, username UNIQUE, password_hash, created_at)` + 默认 admin | | `app.py` | `from flask import session` + `app.secret_key = os.urandom(24)` + `@app.before_request` + `/login` `/logout` 路由 | | `templates/login.html` | 登录表单 | ### 白名单 `/login`, `/logout`, `/static` 不检查登录。 ### 默认账号 `admin` / `wechat2026`(SHA-256 存储) ### 注意事项 - Flask 使用 client-side session(signed cookie),`session.clear()` 后旧 cookie 仍可解密出旧数据。真实浏览器会接受 logout 返回的新空 Set-Cookie。curl 测试需注意此行为。 - `secret_key = os.urandom(24)` 每次重启随机生成 → 重启后所有已登录 session 失效。生产环境应设固定 key。 ## 简历状态列 ### 数据模型 `resumes` 表加 `status TEXT DEFAULT NULL` 列(`/sdcard/bosszhipin/data/resumes.db`)。 ```sql ALTER TABLE resumes ADD COLUMN status TEXT DEFAULT NULL; ``` `import_resumes.py` 的 CREATE TABLE 也需同步加上此列。 ### API ``` PATCH /api/resumes//status Body: {"status": "待面试|已面试|已淘汰|已入职"} → 200 {"ok": true, "data": {"id": N, "status": "..."}} → 400 无效状态 ``` `/api/resumes` 的 SELECT 需包含 `r.status`。 ### 前端 列表页 `getStatusBadge(r)` 渲染状态 badge + 下拉菜单。`updateStatus(id, status)` 调 PATCH API 后更新 `allResumes[]` + `render()`。 ## DOM 下拉菜单定位坑 **症状**:点击状态 badge 无反应,下拉菜单不出现。 **根因**:`.status-menu`(`position: absolute; top: 100%`)是 `.status-badge` span 的**兄弟元素**,不是子元素。`position: absolute` 相对于最近的 `position: relative` 祖先定位——兄弟元素的 relative 对 absolute sibling 无效。 **修复**:用 `` 包裹 badge + menu 两者: ```html 状态 ▾
...
``` **通用原则**:任何 `position: absolute` 的元素必须从 DOM 树上是其 `position: relative` 容器的**后代**,兄弟关系不构成定位上下文。 ## Flask 重启:root 属主进程 **症状**:`fuser -k 5001/tcp` 或 `pkill -f 'python3 app.py'` 杀不掉,重启报 `Address already in use`。 **根因**:Flask 可能被 nohup 或 su 启动,进程属主是 root。Termux 用户的 kill 对 root 进程无效。 **正确做法**: ```bash # 找到 PID su -c "netstat -tlnp 2>/dev/null | grep 5001" # 示例输出: ... LISTEN 21905/python3 # 用 root 杀 su -c "kill -9 21905" ``` **重启命令**(必须用 `-B` 跳过 pycache): ```bash su -c "kill -9 $(su -c 'netstat -tlnp 2>/dev/null | grep 5001' | awk '{print $NF}' | cut -d/ -f1)" 2>/dev/null sleep 1 cd ~/wechat-viewer && python3 -B app.py ``` ## Cloudflare Tunnel ### 安装 Termux 仓库有现成的(不要从 GitHub 下载,网络不稳): ```bash apt update && apt install -y cloudflared ``` ### Quick Tunnel(免账号免域名) ```bash cloudflared tunnel --url http://localhost:5001 # → https://xxxx.trycloudflare.com ``` **注意**:`api.trycloudflare.com` 在中国大陆网络可能被墙,导致无法创建 Quick Tunnel。此时需切网络或走正式 Tunnel。 ### 正式 Tunnel(需 Cloudflare 账号 + 域名) ```bash cloudflared tunnel login # → 浏览器授权 → cert.pem cloudflared tunnel create wechat-viewer cloudflared tunnel route dns wechat-viewer viewer.your-domain.com cloudflared tunnel run wechat-viewer --url http://localhost:5001 ``` 回调 URL `login.cloudflareaccess.org` 也可能被墙,需手动把浏览器下载的 `cert.pem` 放到 `~/.cloudflared/cert.pem`。 ## 注册与权限分层(2026-08-08) **背景**:task.hexdo.com 公网暴露后要开放互联网访问日报,但 viewer 里还有简历/岗位/微信等敏感数据。 - users 表加 `role` 列(admin/user),local_db.py 建表已带,老库 init_db() 幂等 ALTER - `/register` 自助注册 → role=user;登录时 session['role'] - `check_auth` 分层:admin 全放行;user 只放行 `USER_ROUTES`(/reports /report/ /report-images /report-image/ /digest/)+ `USER_API_GET`(/api/reports /api/report/ /api/report-images GET);**boss 只放行 `BOSS_ROUTES`(/boss-jobs /boss-job/ /resumes /resume/)+ `BOSS_API`(/api/boss-jobs /api/resumes /api/resume/,含 POST 打分/导入)**(2026-08-13);其余返回 403 - base.html 导航按角色渲染:`{% if session.get('role') != 'boss' %}` 包裹 admin-only 菜单,BOSS 岗位/简历筛选对所有登录用户可见(boss 只见这两个) - boss 默认账号:boss/boss2026(role=boss,2026-08-13 创建) - 静态日报 HTML:`/digest/` 路由(正则校验 `\d{4}-\d{2}-\d{2}` 防路径穿越)→ `send_file` viewer 目录下 digests/digest_.html(**不能放 /static/**,static 在登录白名单里会绕过权限) - **日报 HTML 公开免登录(2026-08-13)**:`/digest/` 加入 `PUBLIC_ROUTES`(check_auth 在 whitelist 之后、隧道豁免之前放行),公网链接无需登录可直接访问(发链接给别人分享用)。验证脚本已加「未登录 /digest 200」「未登录(带CF) /digest 200」「未登录 /reports 302」「未登录(带CF) /api/reports 302」断言。其余路由(/reports 列表、API)权限不变。 - **日报二维码(2026-08-13)**:`GET /digest//qr`(公开)返回独立二维码 PNG(`gen_daily_qr.py` 生成,内容=https://task.hexdo.com/digest/,输出 `~/daily_digest_qr_.png`,文件缺失时路由内 subprocess 现场生成)。日期用 `_valid_date()` 严格校验(真实日历日,防 2026-13-99)。列表页按钮 + 详情页链接加入口。手动生成:`python3 ~/.hermes/skills/gpt-image-gen/scripts/gen_daily_qr.py --date YYYY-MM-DD`。 - ⚠️ **隧道 header 漏洞(已修复)**:cloudflared 转发到 localhost → Flask 看到 remote_addr=127.0.0.1 → 原本「127.0.0.1 + /api/ 免登录」的 cron 豁免被公网请求触发,所有 API 裸奔。修复:`_is_tunnel_request()` 检测 CF-Connecting-IP / X-Forwarded-For / X-Real-IP header,带这些 header 的请求不豁免。**改认证逻辑后必须用带假 CF-Connecting-IP 的 curl 复测公网路径。** - 测试账号 testuser/test123456(role=user)可复用于验证 - **验证脚本**:`scripts/verify-auth-permissions.py`(本 skill)——Flask test_client 覆盖注册/登录/日报可见/敏感 403/隧道 header/本地豁免/admin 全通,幂等自动清理测试账号。改认证逻辑后跑它(`python3 ~/.hermes/skills/wechat/wechat-viewer-dev/scripts/verify-auth-permissions.py`),全 PASS 才能收工。 ## 简历详情页 原始 JSON(`raw_json` 列)默认展示在经历上方,不使用 `
` 折叠。顺序:基本信息 → 打分 → **原始数据** → 经历。 ## BOSS 岗位 4 层页面(2026-08-06) 用户纠正了旧设计:**每个岗位必须有自己的 benchmark/筛选标准**,禁止全岗位共用一套 rubric。wechat-viewer 新增: - 页面路由:`/boss-jobs`(岗位列表页,模板 `boss_jobs.html`)、`/boss-job/`(岗位详情页,模板 `boss_job_detail.html`) - API:`GET /api/boss-jobs`(岗位聚合列表)、`GET /api/boss-jobs//resumes`、`POST /api/boss-jobs//score`、`POST /api/boss-jobs//import` - 数据源:`/sdcard/bosszhipin/data/jobs_registry.json`(岗位→rubric→提取关键词 注册表)+ `rubrics/{jobId}.json`(每岗位独立 rubric) - 打分脚本必须传 `--job-id` + 该岗位自己的 rubric;未配置 rubric 的岗位打分返回 400 - 导航:base.html 加「BOSS 岗位」入口(active 匹配 `/boss-job*` 或 `/boss-jobs`) 完整设计(API 参数、rubric 迁移方法、验证要点)见 `resume-screener/references/boss-4layer-architecture.md`。 ### 打分脚本维度名硬编码(2026-08-06 实战) `score_resumes.py` 的 criteria 维度分支是**硬编码**的(专业匹配度/学校层次/写作创作经验/到岗状态/AI相关经验),其他名字一律得 1 分"未知维度"。新增维度必须先加脚本分支再启用。已支持的自定义维度:`作品与市场验证`、`美术功底`(读 chat_text+经历)、`毕业年限`(数值逻辑:compute_grad_year ≥2年5分/1-2年3分/应届1分,rules 留空 `{}`)。同一维度既可做淘汰(elimination within_years)也可做加分,按岗位定——AI短剧制作岗最终 v3 从淘汰改加分(0 淘汰)。 ### 简历作品信息在聊天文本里(2026-08-06) BOSS 简历 BLOB(ChatResumeBean)只有 29 个字段,**没有作品链接/经历描述**。候选人作品集链接(网盘/新片场/抖音)、独立制作自述、AI 工具名(可灵/即梦/Seedance)全在 `MessageTable type=1` 聊天文本。resumes 表加 `chat_text` 列回填后打分可用;**必须 clean_chat_text 清洗岗位复述词**("看到贵司招聘AI短剧制作岗位"会被当经验证据假命中)。详见 resume-screener skill「聊天文本扩展」章节。