Refactor code structure and optimize performance across multiple modules

code/opc-training/server/README.md

@@ -0,0 +1,49 @@
+# 云超服 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，微信手机号授权也需在真机 + 已认证小程序下才可用。