SKILL.md 9.99 KB

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)。

ALTER TABLE resumes ADD COLUMN status TEXT DEFAULT NULL;

import_resumes.py 的 CREATE TABLE 也需同步加上此列。

API

PATCH /api/resumes/<id>/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 无效。

修复:用 <span style="position:relative;display:inline-block"> 包裹 badge + menu 两者:

<span style="position:relative;display:inline-block">
  <span class="status-badge" onclick="toggleMenu(event,id)">状态 ▾</span>
  <div class="status-menu" id="stmenu-N">...</div>
</span>

通用原则:任何 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 进程无效。

正确做法:

# 找到 PID
su -c "netstat -tlnp 2>/dev/null | grep 5001"
# 示例输出: ... LISTEN  21905/python3
# 用 root 杀
su -c "kill -9 21905"

重启命令(必须用 -B 跳过 pycache):

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 下载,网络不稳):

apt update && apt install -y cloudflared

Quick Tunnel(免账号免域名)

cloudflared tunnel --url http://localhost:5001
# → https://xxxx.trycloudflare.com

注意:api.trycloudflare.com 在中国大陆网络可能被墙,导致无法创建 Quick Tunnel。此时需切网络或走正式 Tunnel。

正式 Tunnel(需 Cloudflare 账号 + 域名)

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/<date> 路由(正则校验 \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/<date>/qr(公开)返回独立二维码 PNG(gen_daily_qr.py 生成,内容=https://task.hexdo.com/digest/,输出 ~/daily_digest_qr_<date>.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 列)默认展示在经历上方,不使用 <details> 折叠。顺序:基本信息 → 打分 → 原始数据 → 经历。

BOSS 岗位 4 层页面(2026-08-06)

用户纠正了旧设计:每个岗位必须有自己的 benchmark/筛选标准,禁止全岗位共用一套 rubric。wechat-viewer 新增:

  • 页面路由:/boss-jobs(岗位列表页,模板 boss_jobs.html)、/boss-job/<job_id>(岗位详情页,模板 boss_job_detail.html)
  • API:GET /api/boss-jobs(岗位聚合列表)、GET /api/boss-jobs/<id>/resumes、POST /api/boss-jobs/<id>/score、POST /api/boss-jobs/<id>/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「聊天文本扩展」章节。