opc-backup/code/opc-training/server/README.md

云超服 OPC 培训站 · FastAPI 后端

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

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

启动（uv）

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，微信手机号授权也需在真机 + 已认证小程序下才可用。