# 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` 覆盖。Variables：`DEPLOY_PORT`（默认 `18082`）、`PUBLIC_BASE_URL`、`CORS_ORIGINS`、`TEST_AUTH_ENABLED`。默认允许 `3000`（综合版）和 `3002`（饭类独立版）访问。

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

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

## 本地命令（可选）

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

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