diff --git a/docs/README.md b/docs/README.md index c0718de..8913c4e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,22 @@ -# 微信小程序登录服务 +# 文档目录 -记录小程序端 `wx.login` 换取 `openid` 并写入数据库的后端服务说明。 +本仓库支持多个小程序共用一套后端。文档按“公共约定 + 每个小程序一个目录”的方式组织。 + +## 公共文档（所有小程序通用） + +- `docs/common/README.md` +- `docs/common/auth.md` +- `docs/common/response.md` + +## 去水印小程序 + +- `docs/remove_watermark/README.md` +- `docs/remove_watermark/API.md` + +## 戒烟/抽烟记录小程序 + +- `docs/smoke/README.md` +- `docs/smoke/API.md` ## 配置 @@ -20,7 +36,7 @@ go run ./cmd/api 启动流程： 1. 加载 `.env`。 2. 初始化数据库连接（参见 `internal/database/database.go`）。 -3. 自动迁移 `internal/model/user.go` 中的 `users` 表。 +3. 自动迁移相关数据表（用户表、去水印日志表、戒烟记录表等）。 4. 注册路由并启动 Gin HTTP 服务。 ## 数据表 @@ -51,55 +67,9 @@ go run ./cmd/api | `session_key` | varchar(100) | 微信会话密钥 | | `created_at/updated_at/deleted_at` | timestamp | GORM 默认时间戳 | -## 接口 +## 登录接口 -### `POST /api/v1/auth/login` - -- **说明**：接收小程序端 `wx.login` 返回的 `code`，向微信 `jscode2session` 请求 `openid` / `session_key`。若 `open_id` 不存在则创建用户，存在则更新资料并返回用户信息。 -- **请求体** - -```json -{ - "mini_program_id": 1, - "code": "wx.login返回的code", - "nickname": "可选", - "avatar_url": "可选", - "gender": 1, - "phone": "110" -} -``` - -- **响应体** - -```json -{ - "code": 200, - "message": "success", - "data": { - "user": { - "id": 1, - "mini_program_id": 1, - "open_id": "oXXX", - "union_id": "可选", - "nickname": "昵称", - "avatar_url": "链接", - "gender": 1, - "phone": "110" - }, - "session_key": "wx-session-key", - "mini_program": { - "id": 1, - "name": "商城小程序", - "app_id": "wx67444119b166caa0" - } - } -} -``` - -- **错误** - - `400`：`code` 或 `mini_program_id` 缺失、请求体非法、小程序不存在。 - - `502`：微信 API 返回错误。 - - `500`：数据库或其他内部异常。 +登录接口属于公共能力，请查看：`docs/common/auth.md`。 ## 健康检查 diff --git a/docs/common/README.md b/docs/common/README.md new file mode 100644 index 0000000..86f31a3 --- /dev/null +++ b/docs/common/README.md @@ -0,0 +1,25 @@ +# 公共说明 + +本目录存放所有小程序共用的接口约定与调用方式，避免每个子系统重复描述。 + +## 基础信息 + +- 接口前缀：`/api/v1` +- 健康检查：`GET /healthz` → `{"status":"ok"}` + +## 通用响应结构 + +本项目所有接口使用统一 JSON 结构（见：`docs/common/response.md`）： + +```json +{ + "code": 200, + "message": "success", + "data": {} +} +``` + +## 认证方式 + +除登录接口外，其他接口都需要携带登录后返回的 `session_key`（见：`docs/common/auth.md`）。 + diff --git a/docs/common/auth.md b/docs/common/auth.md new file mode 100644 index 0000000..9429f23 --- /dev/null +++ b/docs/common/auth.md @@ -0,0 +1,64 @@ +# 认证与登录 + +## 1) 登录 + +`POST /api/v1/auth/login` + +说明：小程序端调用 `wx.login()` 获取 `code`，后端用该 `code` 向微信 `jscode2session` 换取 `openid/session_key`，并在数据库中创建/更新用户记录。 + +请求示例： + +```bash +curl -X POST 'http://127.0.0.1:8080/api/v1/auth/login' \ + -H 'Content-Type: application/json' \ + -d '{ + "mini_program_id": 1, + "code": "wx.login 返回的 code", + "nickname": "可选：昵称", + "avatar_url": "可选：头像", + "gender": 1, + "phone": "可选：手机号" + }' +``` + +成功响应示例（节选）： + +```json +{ + "code": 200, + "message": "success", + "data": { + "user": { + "id": 1, + "mini_program_id": 1, + "open_id": "oXXX", + "nickname": "昵称", + "avatar_url": "https://...", + "gender": 1, + "phone": "110" + }, + "session_key": "wx-session-key", + "mini_program": { + "id": 1, + "name": "某小程序", + "app_id": "wx..." + } + } +} +``` + +## 2) 受保护接口如何带 Token + +后端把 `session_key` 当做 Token 使用，调用受保护接口时在 Header 中带： + +``` +Authorization: Bearer +``` + +请求示例： + +```bash +curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs?page=1&page_size=20' \ + -H 'Authorization: Bearer wx-session-key' +``` + diff --git a/docs/common/response.md b/docs/common/response.md new file mode 100644 index 0000000..e0140af --- /dev/null +++ b/docs/common/response.md @@ -0,0 +1,29 @@ +# 通用响应与错误 + +## 通用响应结构 + +所有接口响应结构： + +```json +{ + "code": 200, + "message": "success", + "data": {} +} +``` + +- `code`：业务码（本项目中与 HTTP 状态码保持一致） +- `message`：提示信息（部分接口为中文提示） +- `data`：成功时返回的数据，失败时通常省略 + +## 常见 HTTP 状态码 + +- `200`：成功 +- `400`：请求参数错误 +- `401`：未登录或登录已过期（缺少/无效 Token） +- `403`：无权限或触发业务限制（例如今日额度用尽） +- `404`：资源不存在 +- `500`：服务端内部错误 +- `502`：第三方服务错误 +- `503`：服务暂不可用（缺少关键配置等） + diff --git a/docs/remove_watermark/API.md b/docs/remove_watermark/API.md index fa7058d..e264095 100644 --- a/docs/remove_watermark/API.md +++ b/docs/remove_watermark/API.md @@ -6,6 +6,8 @@ `POST /api/v1/auth/login` +登录与认证的公共说明见：`docs/common/auth.md`。 + ## 接口 ### `POST /api/v1/auth/login` @@ -35,6 +37,15 @@ | 必填校验 | `content` 必须包含一个合法的 http/https 链接 | | 响应 | `provider` 固定为 `23bt`，`raw` 为第三方原始 JSON，`free_quota_used` 表示是否占用免费额度 | +curl 示例： + +```bash +curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer wx-session-key' \ + -d '{"content":"帮我解析 https://v.douyin.com/xxxx/"}' +``` + **成功示例** ```json @@ -57,12 +68,12 @@ | HTTP 码 | code | message | 说明 | | --- | --- | --- | --- | -| 400 | 400 | `content must contain a valid url` | 未找到链接 | -| 401 | 401 | `unauthorized` | Token 缺失/失效 | -| 403 | 403 | `daily free quota exceeded, please watch an ad to continue` | 超过每日免费额度，需要走广告解锁 | -| 502 | 502 | `third-party api error: ...` | 第三方返回异常 | -| 503 | 503 | `short video api key missing` | 未配置 `SHORT_VIDEO_API_KEY` | -| 500 | 500 | `remove watermark failed` | 其他内部错误 | +| 400 | 400 | `请求参数错误` / `请检查分享链接是否正确` | 请求体非法或内容未包含有效链接 | +| 401 | 401 | `未登录或登录已过期` | Token 缺失/失效 | +| 403 | 403 | `今日免费次数已用完，观看广告后今天可无限制使用` | 超过每日免费额度，需要走广告解锁 | +| 502 | 502 | `解析服务异常，请稍后重试` | 第三方返回异常 | +| 503 | 503 | `服务暂不可用，请联系管理员` | 未配置 `SHORT_VIDEO_API_KEY` 等关键配置 | +| 500 | 500 | `去水印失败，请稍后重试` | 其他内部错误 | ## 3. 完成广告解锁 @@ -74,6 +85,13 @@ | 请求体 | 空 | | 响应 | `{"code":200,"message":"success","data":{"unlocked":true}}` | +curl 示例： + +```bash +curl -X POST 'http://127.0.0.1:8080/api/v1/video/remove_watermark/unlock' \ + -H 'Authorization: Bearer wx-session-key' +``` + 说明：调用该接口表示用户当天已经观看完广告，服务端会写入 `video_parse_unlocks`，当天余下时间不再校验免费额度。 ## 4. 数据落地 diff --git a/docs/remove_watermark/README.md b/docs/remove_watermark/README.md index 3944ece..a2b0910 100644 --- a/docs/remove_watermark/README.md +++ b/docs/remove_watermark/README.md @@ -4,6 +4,8 @@ 小程序需要提供“短视频去水印”功能。用户提交的文本中包含短视频分享链接，后台需调用第三方接口 `https://api.23bt.cn/api/d1w/index?key=<你的key>&url=<分享链接>` 获取解析结果并返回。该接口仅向已登录用户开放。 +公共登录与认证说明见：`docs/common/auth.md`。 + ## 功能需求 1. **访问控制** diff --git a/docs/smoke/API.md b/docs/smoke/API.md new file mode 100644 index 0000000..c798ee1 --- /dev/null +++ b/docs/smoke/API.md @@ -0,0 +1,122 @@ +# 戒烟/抽烟记录 API + +所有接口前缀：`/api/v1/smoke` +除登录外都需要：`Authorization: Bearer `（见：`docs/common/auth.md`） + +## 1) 新增记录 + +`POST /api/v1/smoke/logs` + +请求体： + +```json +{ + "smoke_time": "2025-12-31", + "remark": "压力大", + "level": 2, + "num": 3 +} +``` + +说明： +- `smoke_time` 可选；不传则默认“当天”。 +- `level/num` 可选；不传或传 `<=0` 时会按 `1` 处理。 + +curl 示例： + +```bash +curl -X POST 'http://127.0.0.1:8080/api/v1/smoke/logs' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer wx-session-key' \ + -d '{"smoke_time":"2025-12-31","remark":"压力大","level":2,"num":3}' +``` + +成功响应示例（字段以实际为准）： + +```json +{ + "code": 200, + "message": "success", + "data": { + "id": 5202, + "smoke_time": "2025-12-31T00:00:00+08:00", + "remark": "压力大", + "createtime": 1735600000, + "updatetime": 1735600000, + "deletetime": null, + "level": 2, + "num": 3 + } +} +``` + +## 2) 获取单条记录 + +`GET /api/v1/smoke/logs/:id` + +curl 示例： + +```bash +curl -X GET 'http://127.0.0.1:8080/api/v1/smoke/logs/5202' \ + -H 'Authorization: Bearer wx-session-key' +``` + +## 3) 列表查询（分页） + +`GET /api/v1/smoke/logs?page=1&page_size=20&start=2025-12-01&end=2025-12-31` + +参数： +- `page`：页码，默认 `1` +- `page_size`：每页数量，默认 `20`，最大 `200` +- `start/end`：可选，按 `smoke_time` 过滤（格式 `YYYY-MM-DD`） + +成功响应示例： + +```json +{ + "code": 200, + "message": "success", + "data": { + "items": [], + "total": 0, + "page": 1, + "page_size": 20 + } +} +``` + +## 4) 更新记录 + +`PUT /api/v1/smoke/logs/:id` + +请求体（字段可选，按需传）： + +```json +{ + "smoke_time": "2026-01-01", + "remark": "聚会", + "level": 3, + "num": 1 +} +``` + +注意： +- 如果你想“清空 smoke_time”，请传空字符串：`{"smoke_time":""}`。 +- 如果传 `null` 或者不传 `smoke_time`，后端会认为你没有修改该字段。 + +## 5) 删除记录（软删除） + +`DELETE /api/v1/smoke/logs/:id` + +成功响应： + +```json +{ + "code": 200, + "message": "success", + "data": { + "deleted": true + } +} +``` + diff --git a/docs/smoke/README.md b/docs/smoke/README.md new file mode 100644 index 0000000..50b7a84 --- /dev/null +++ b/docs/smoke/README.md @@ -0,0 +1,17 @@ +# 戒烟/抽烟记录小程序 + +本小程序用于记录抽烟情况（日期、原因、烟瘾程度、数量等）。 + +## 依赖 + +- 公共登录与认证：`docs/common/auth.md` +- 通用响应结构：`docs/common/response.md` + +## 数据表 + +主表：`fa_smoke_log`（DDL 见：`docs/sql/smoke.sql`）。 + +说明： +- 该表使用旧系统字段：`createtime/updatetime/deletetime`（秒级时间戳），并非 GORM 默认的 `created_at/updated_at/deleted_at`。 +- 接口层通过 Token 识别用户，`uid` 由后端从登录用户推导，不允许前端传入。 + diff --git a/docs/sql/smoke.sql b/docs/sql/smoke.sql new file mode 100644 index 0000000..06c1996 --- /dev/null +++ b/docs/sql/smoke.sql @@ -0,0 +1,16 @@ +-- 戒烟/抽烟记录主表 +-- 注意：该表字段来自旧系统（createtime/updatetime/deletetime 为秒级时间戳） + +CREATE TABLE `fa_smoke_log` ( + `id` int(11) NOT NULL AUTO_INCREMENT, + `uid` int(11) NOT NULL COMMENT '用户ID', + `smoke_time` date DEFAULT NULL COMMENT '抽烟时间', + `remark` text COMMENT '抽烟原因', + `createtime` int(11) DEFAULT NULL COMMENT '创建时间', + `updatetime` int(11) DEFAULT NULL COMMENT '修改时间', + `deletetime` int(11) DEFAULT NULL COMMENT '删除时间', + `level` bigint(2) DEFAULT '1' COMMENT '烟瘾程度', + `num` int(2) DEFAULT '1' COMMENT '抽烟数量', + PRIMARY KEY (`id`,`uid`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='抽烟记录'; +