4.5 KiB
新项目 API 规格（/t/:tenant_code/v1）
0. 通用约定
0.1 Base URL 与租户
- Base：
/t/:tenant_code/v1 tenant_code校验：服务端对路径段做lower()后校验^[a-z0-9_-]+$，并查表确认租户存在且启用
0.2 认证
- WeChat H5：Cookie 会话（例如
token），请求需携带withCredentials - Admin：
Authorization: Bearer <token>
0.3 响应
- 成功：
200（或 201/204），JSON - 业务错误：
400（含错误信息） - 未登录：
401 - 无权限：
403 - 不存在：
404
1. WeChat OAuth
1.1 发起授权
GET /auth/wechat?redirect=<url>
- 行为：302 跳转到微信授权 URL；回调为
/t/:tenant_code/v1/auth/login
1.2 授权回调
GET /auth/login?code=<code>&state=<state>&redirect=<url>
- 行为：
- 获取 openid 与用户资料
(tenant_id, open_id)获取或创建users- 写入 Cookie 会话
- 302 回跳
redirect
2. WeChat H5 内容与用户
2.1 曲谱列表（仅已发布）
GET /posts
Query：
page（默认 1）limit（默认 10）keyword（可选）
Response（示例结构）：
{
"items": [
{
"id": 1,
"title": "标题",
"description": "简介",
"price": 19900,
"discount": 80,
"views": 10,
"likes": 0,
"tags": ["tag"],
"head_images": ["https://signed-url..."],
"bought": false,
"recharge_wechat": "联系微信（可选）"
}
],
"total": 123,
"page": 1,
"limit": 10
}
2.2 曲谱详情（仅已发布）
GET /posts/:id/show
Response：同 PostItem，额外含 content
2.3 获取播放 URL
GET /posts/:id/play
Response：
{ "url": "https://signed-url..." }
规则：未购买返回 metas.short=true 的视频 URL；已购买返回 metas.short=false 的视频 URL。
2.4 我的已购
GET /posts/mine
Query：page、limit、keyword（可选）
Response：同分页结构
2.5 余额购买
POST /posts/:id/buy
Response（余额支付成功）：
- 可直接返回
{ "ok": true }或返回订单信息（由你最终 UI/交互决定）
错误：
- 余额不足：
400，message 建议为“余额不足，请联系管理员充值” - 已购买：
400
2.6 用户资料
GET /users/profile
Response：
{ "id": 1001, "created_at": "2025-01-01T00:00:00Z", "username": "xx", "avatar": "url", "balance": 10000 }
2.7 修改用户名
PUT /users/username
Body：
{ "username": "新昵称" }
约束：trim 后不能为空；最大 12 个字符（按 rune 计）。
2.8 JS-SDK 配置
GET /wechats/js-sdk?url=<current_page_url_without_hash>
Response：JS-SDK 签名数据（结构按前端 weixin-js-sdk 需要输出）
3. Admin（租户后台）
3.1 登录
POST /admin/auth
Body：
{ "username": "admin", "password": "******" }
Response：
{ "token": "..." }
3.2 仪表盘统计
GET /admin/statistics
Response：
{
"post_draft": 0,
"post_published": 0,
"media": 0,
"order": 0,
"user": 0,
"amount": 0
}
3.3 媒体库
GET /admin/medias?page=&limit=&keyword=
GET /admin/medias/:id：302 跳转到 OSS 签名 URL
DELETE /admin/medias/:id：删除 OSS 对象并软删/删 DB 记录（最终由你决定）
3.4 上传（预签名）
GET /admin/uploads/pre-uploaded-check/:md5.:ext?mime=<mime>
Response：
{ "exists": false, "pre_sign": { "...": "..." } }
说明：
md5在租户内去重- OSS Key：
quyun/<tenant_uuid>/<md5>.<ext>
POST /admin/uploads/post-uploaded-action
Body：
{ "originalName": "a.mp4", "md5": "...", "mimeType": "video/mp4", "size": 123 }
3.5 曲谱管理
GET /admin/posts?page=&limit=&keyword=
POST /admin/posts、PUT /admin/posts/:id Body（示例）：
{
"title": "标题",
"head_images": [1,2,3],
"price": 19900,
"discount": 80,
"introduction": "简介",
"content": "正文",
"status": 1,
"medias": [10,11,12]
}
GET /admin/posts/:id：返回曲谱 + medias 列表
DELETE /admin/posts/:id
POST /admin/posts/:id/send-to/:userId：赠送曲谱（写入授权记录）
3.6 用户管理
GET /admin/users?page=&limit=&keyword=
GET /admin/users/:id
GET /admin/users/:id/articles?page=&limit=
POST /admin/users/:id/balance
Body：
{ "balance": 10000 }
3.7 订单管理
GET /admin/orders?page=&limit=&order_number=&user_id=
POST /admin/orders/:id/refund：仅余额订单可退款