# popadmin 音乐 / 小说 & sparkapi `/docs` 部署要点

## 1. spark-server（音乐 API + OpenAPI）

```bash
# 本机（Windows/WSL）：构建并部署到新加坡机
make deploy
# 会：linux 交叉编译 → docker image → 上传 ECS → spark-migrate（含 0020_music / 0021_music_background）→ 重启容器 → nginx reload
```

新加坡机手工补跑迁移（仅 image 已更新但 migrate 未跑时）：

```bash
docker exec spark-server spark-migrate -config /app/configs/config.yaml
# 或 compose 目录下：docker compose run --rm spark-server spark-migrate -config /app/configs/config.yaml
sudo nginx -t && sudo nginx -s reload
# 确认 include 了 popadmin-spark-admin-locations.conf（含 music，client_max_body_size 55m）
```

验证：

- `GET https://sparkapi.wyrs365.com/v1/music/playlist` → `code=0`，曲目含 `coverUrl` / `backgroundUrl`（可空）/ `audioUrl`
- `GET https://sparkapi.wyrs365.com/docs` → 可见 music / admin-music
- popadmin「音乐列表」：封面 / **背景** / mp3 上传；`POST /api/admin/spark/music/{id}/background`

## 2. Aliyun wyrs-admin（popadmin 静态）

热更音乐背景图 UI（与现网一致）：

```bash
# 源：spark-server/deploy/popadmin/popadmin.js（已含背景列与上传）
scp -i ~/.ssh/wyrs_shanghai_deploy.pem deploy/popadmin/popadmin.js \
  root@47.236.66.9:/opt/wyrs-admin/static-override/popadmin.js
# 若 index 带 ?v= 缓存戳，同步 bump popadmin.index.html
```

新加坡若用 static-override，覆盖后强刷浏览器即可。

## 3. FullStoryNovel CMS（小说 iframe）

- 部署 `static/admin/admin.js`（`embed=1&from=popadmin` + postMessage SSO）
- 部署 nginx：去掉 `X-Frame-Options SAMEORIGIN`，改为  
  `Content-Security-Policy: frame-ancestors 'self' https://popadmin.wyrs365.com`
- 确认 `fullstorynovel.service` :8095 与 `adopt-ops-session` 可用

验证：popadmin →「小说内容管理」iframe 加载 novels；或新窗口打开 `https://admin.fullstorynovel.com/admin/`。

## 4. 设备登录文档（devices-client）

OpenAPI 已按 `Spark资源文档/devices-client.md` 更新契约。  
**当前 Go 实现仍为旧登录**（Body 必填客户端 `device_id`、字符串 `device_type`，JWT 无 `aid`）。上线新契约前需改 auth/login、JWT、meta 枚举。

## 5. Demo 曲目（可选）

仓库旁 `_demo_music/`：`tracks.json` + `01..10.mp3/png` + `upload_demo.py`。  
背景图**可空**，demo **不强制**补背景；脚本勿删已有曲目（仅 POST 新建）。

```bash
# 在新加坡机（或可访问 popadmin 登录与 spark admin API 的环境）
export SPARK_ADMIN_BASE=http://127.0.0.1:18080
export POPADMIN_LOGIN=http://127.0.0.1:8090/api/admin/auth/login
python3 upload_demo.py
curl -sS https://sparkapi.wyrs365.com/v1/music/playlist | jq '.data.items|length,.data.items[0]|{title,coverUrl,backgroundUrl,audioUrl}'
```