# 部署说明（试点期）

## 结论：试点不需要容器编排

单台机器即可跑起完整服务：一个后端进程 + 一个 PostgreSQL + 前端静态文件。
后续接入 officeπ 主站时再按公司标准容器化（Dockerfile 可在那时补）。

## 组成

| 组件 | 形式 | 说明 |
|---|---|---|
| 后端 | `python -m uvicorn app.asgi:application --port 8000` | 单进程；试点量级无需多 worker |
| 数据库 | PostgreSQL（5435 或公司实例） | `alembic upgrade head` 建表；存量 SQLite 用 `scripts/migrate_sqlite_to_postgres.py` 迁移 |
| 前端 | `npm run build` → `frontend/dist` | Nginx/静态托管；通过 `VITE_API_BASE_URL` 指向后端 |

## 环境变量（backend/.env）

| 变量 | 必填 | 说明 |
|---|---|---|
| `OPENAI_API_KEY` | 是（AI 功能） | 兼容网关密钥；留空则全部走规则兜底（仅演示流程） |
| `OPENAI_BASE_URL` / `OPENAI_MODEL` | 是 | 网关地址与模型 |
| `DATABASE_URL` | 生产必填 | `postgresql+psycopg://user:pass@host:5435/resume_agent` |
| `RESUME_AGENT_TEST_DATABASE_URL` | 仅测试 | 测试库 |
| `RESUME_AGENT_CORS_ORIGINS` | 生产必填 | 逗号分隔的前端来源，接入 officeπ 时加其域名 |
| `RESUME_AGENT_INTENT_ROUTER_MODE` | 建议 `on` | 对话意图路由（off/shadow/on） |
| `OFFERPAI_AUTH_REQUIRED` | 必须为 `true` | 强制每个 session 请求携带 OfferPai Token 并校验会话归属 |
| `OFFERPAI_AUTH_BASE_URL` | 必填 | OfferPai 登录鉴权与用户信息服务 Origin |
| `OFFERPAI_AUTH_TIMEOUT_SECONDS` | 建议 `8` | 登录鉴权与用户信息请求超时 |
| `OFFERPAI_RESUME_API_BASE_URL` | 必填 | C 端简历 API 根地址，例如 `https://test.offerpai.com.cn/api` |
| `OFFERPAI_RESUME_TIMEOUT_SECONDS` | 建议 `8` | C 端简历读写请求超时 |

## 安全红线（试点必须遵守）

1. **保持 OfferPai 鉴权开启**：`OFFERPAI_AUTH_REQUIRED=true`。前端 Token 只保存在页面内存，所有 session、SSE、上传和简历编辑请求都必须携带 `Authorization: Bearer`；后端会校验 Token 用户与 session 绑定用户一致。
2. **不要设置** `RESUME_AGENT_DEFAULT_TIER=vip`：该开关会把所有会话默认提权（后门告警会打日志）。
3. **不要设置** `RESUME_AGENT_API_DOCS=1`：生产暴露 `/docs` 等于公开 API 结构。
4. 密钥只放 `.env`（已被 gitignore）；仓库内不得出现明文令牌。
5. 简历文件含用户 PII：`backend/data/`（上传件、SQLite）不得外传、不得提交。
6. `/?token=` 会被前端立即从地址栏移除，但首次请求仍可能进入 Nginx/CDN 访问日志；生产网关必须关闭 query string 日志或对 `token` 参数脱敏。

## C 端简历同步语义

- 初步资料完成后自动创建本地工作文档与 C 端简历，后续同步主表及教育、工作、实习、项目、竞赛五类经历。
- local DB 继续保存 FSM、revision、稳定子项 ID、候选稿、撤销和优化状态；C 端接口目前不能完全替代它。
- 双写不是分布式事务：本地修改先提交，远端失败时会记录同步失败并由后续请求补偿。调用方重试前应先刷新 timeline，不能假设 HTTP 同步错误代表本地未修改。
- 删除 session（前端“重新开始”）会同步删除已绑定的 C 端镜像；远端返回不存在按幂等成功处理。

## 健康检查

`GET /health` 恒返回 `{"status": "ok"}`，供探活。