# 云超服 OPC 培训站 · FastAPI 后端

> 📍 工作区位置：`code/opc-training/server/`（培训系统代码）。课程内容见 `materials/培训计划/`；三端总览见 `materials/培训计划/课程体系0.1/三端架构设计.md`；关联前端 `../website/`、`../miniprogram/`。

原 mock 后端（`website/server/mock-api.mjs`）的完整迁移，FastAPI + SQLite。

## 启动（uv）

```bash
cd server
uv run uvicorn app.main:app --port 8091 --reload
```

> 端口默认 **8091**。文档/健康检查：
> - Swagger: `http://127.0.0.1:8091/docs`
> - 健康: `http://127.0.0.1:8091/api/health`

## 数据

- 落盘 `server/opc.db`（SQLite，WAL 模式）。
- 首次启动自动建表并种子：内置账号 `pine/123456`、8 场活动。
- OPC 测评题库由 `website/server/opcTest.js` 生成到 `app/opc_data.py`（勿手改；改题需重跑生成脚本）。

## 覆盖的接口（与原 mock 完全一致）

- 认证：`/api/auth/register|login|send-code|phone-login|logout|verify|wx-login|me|bind-phone`
- 活动：`/api/events`（`?current=1` / `?bookable=1`）、`/api/events/:id`、管理端 POST/PUT/DELETE
- 报名：`/api/bookings`、`/api/bookings/mine`、`/api/checkins`、管理端 GET/PATCH/DELETE
- 测评：`/api/tests/opc/questions`、`/api/tests/opc/calculate`、`/api/tests`
- 日志：`/api/policy-logs`、`/api/plan-logs`、`/api/survey-logs`
- 统计：`/api/ops/stats`

## 前端接入

- **web** `website/src/services/*.js` 的 `API_BASE` → 改为 `http://127.0.0.1:8091`（或部署域）。
- **小程序** `miniprogram/src/utils/api.js` 的 `API_BASE` → 改为 `http://127.0.0.1:8091`（真机需 HTTPS + 配置合法域名）。

## 真实微信登录（配置步骤）

小程序 `wx.login` / `getPhoneNumber` 真实登录，需配置微信 `AppID/AppSecret`：

1. 微信公众平台 mp.weixin.qq.com → 开发 → 开发设置 → 复制 **AppID / AppSecret**。
2. 复制 `server/.env.example` 为 `server/.env`，填入两个值（或部署时设置环境变量 `WX_APPID` / `WX_SECRET`）。
3. 后端启动时自动读取 `.env`。配置后：
   - `POST /api/auth/wx-login`：用 `code` 调微信 `jscode2session` 换真实 `openid` 建号/登录。
   - `POST /api/auth/wx-phone`：一键绑定手机号（`getPhoneNumber` 的 code → 真实手机号）。
   - 未配置时自动降级为"演示伪 openid"（开发可用，`configured:false`），不影响开发。

> ⚠️ 仅在本机/开发者工具调试；小程序**真机必须**配置业务域名（request 合法域名 = 后端 HTTPS 地址）与 AppID，微信手机号授权也需在真机 + 已认证小程序下才可用。