pk-lab-server/README.md

PK Lab Server

pk-lab-xhs 与 rice-pk-xhs 共用的 FastAPI + PostgreSQL 后端。它保存首批七套题库、PK 决策轨迹、最终排名和用户历史，并负责把两个小红书小程序各自的 open_id 安全映射到内部用户。

核心设计

• xhs.login() 的一次性 code 只发给 /api/v1/auth/xhs；服务端换取 open_id，绝不把 session_key 下发。
• 小红书 open_id 只在单个小程序内唯一。综合版与饭类独立版通过 6 位、10 分钟有效、单次使用的绑定码合并内部用户。
• 完整 PK 决策轨迹和 Top 排名写入 PostgreSQL，可复现结果并支持后续统计。
• 固定 Compose project pk-lab-production 和具名卷 pk-lab-postgres-data。CI 只执行 up -d 更新，不执行 down -v，发布后服务与数据持续存在。

CI 所需配置

部署前只需由仓库所有者配置 Secret POSTGRES_PASSWORD。用户登录采用 PostgreSQL 持久化 session，服务端只保存随机 token 的 SHA-256 哈希，不需要全局 token 签名密钥。上线真实登录前再配置两套 XHS_*_APP_ID/SECRET。拉取源码默认使用 Gitea 工作流自带令牌，也可用 GITEA_TOKEN 覆盖。后端只在 pk-lab-public Docker 网络内以别名 pk-lab-api:8000 提供服务，不映射宿主机端口；两个预览站通过同源 /api 反向代理访问。可选 Variables：PUBLIC_BASE_URL、CORS_ORIGINS、TEST_AUTH_ENABLED。

当前流水线默认 TEST_AUTH_ENABLED=true，让两个公网预览可以创建明确隔离的测试身份。接入真实小红书 App ID/Secret 后，必须把该变量改成 false，关闭 dev: 登录路径。

生产 API 必须使用 HTTPS，并在两个小程序后台加入 request 合法域名。首次配置 App ID/Secret 后重新运行流水线即可启用真实登录。

本地命令（可选）

python -m venv .venv
. .venv/bin/activate
pip install . pytest ruff
TEST_AUTH_ENABLED=true pytest -q

接口文档部署后位于 /docs，健康检查为 /health。