# 明缘进阶场 API（单 FastAPI 服务）

单服务承载 auth / pages / checkin / plan / profile / course-vote / survey / feedback，统一挂载在 `/api/v1` 下。

## 部署

1. 安装依赖：

   ```bash
   pip install -r server/requirements.txt
   ```

2. 配置环境变量（复制 `server/.env.example` 后填写）：

   - `WECHAT_APPID` / `WECHAT_SECRET`：微信小程序凭证
   - `JWT_SECRET`：JWT 签名密钥（>=32 字节随机串）
   - `ADMIN_KEY`：反馈解决接口的管理密钥
   - `MYSQL_*`：`mys_info_test` 数据库连接
   - `SURVEY_DB`：问卷库 `myxhxc`
   - `PHONE_HMAC_KEY`：手机号 HMAC 密钥，必须与既有 `phone_encrypted` 生成一致（默认 `MingYuan2026AuthKey`）
   - `H5_BASE_URL`：H5 模块基础地址（默认 `https://muguaclub.cn`）
   - `FEEDBACK_DIR` / `COURSE_VOTES_FILE`：文件存储路径
   - `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` / `OSS_ENDPOINT` / `OSS_BUCKET` /
     `OSS_PUBLIC_ENDPOINT` / `OSS_URL_EXPIRE` / `OSS_POST_EXPIRE`：对象存储（打卡附件 / 头像）
     —— 2026-09-22 起**图片只存 OSS，没有磁盘兜底**，这四项缺任意一项上传会直接 503
   - 注：原 `PLAN_ATTACH_DIR` / `AVATAR_DIR` / `STATIC_ROOT` 已随磁盘读路径删除

3. 执行 wechat_openid 迁移（一次性）：

   ```bash
   mysql mys_info_test < server/migrations/001_add_wechat_openid_column.sql
   ```

4. 启动：

   ```bash
   uvicorn server.main:app --host 0.0.0.0 --port 8000
   ```

5. 健康检查：`GET /api/v1/health` 返回 `{"ok": true}`。

## 认证

- `POST /api/v1/auth/wechat-login`：`{code}`，`wechat_openid` 命中自动登录；未命中返回 `need_phone=true`。
- `POST /api/v1/auth/bind-phone`：`{code, phone_code}`，手机号匹配后回填 `wechat_openid` 并登录。
- 受保护接口使用 `Authorization: Bearer <JWT>`，不使用 cookie。

## 小程序

- 目录：`miniprogram/`，四 tab（首页/打卡/计划/我的）。
- 首页调用 `GET /api/v1/pages/home` 按返回顺序渲染，模块通过 web-view 打开并附带 `?token=`。
- H5 引入 `h5/shared/auth.js` 后，`fetch` 自动附带 Bearer token。

## 测试

```bash
python -m pytest tests -q
```