Update documentation structure and enhance API descriptions
- Revised README.md to provide a clearer documentation structure for multiple mini programs, including a new table of contents. - Added references to common authentication documentation in both the remove watermark API and README files. - Improved clarity of the login interface description and error handling messages in the remove watermark API documentation.
This commit is contained in:
nepiedg
+21
-51
@@ -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`。
|
||||
|
||||
## 健康检查
|
||||
|
||||
|
||||
@@ -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`）。
|
||||
|
||||
@@ -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 <session_key>
|
||||
```
|
||||
|
||||
请求示例：
|
||||
|
||||
```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'
|
||||
```
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 通用响应与错误
|
||||
|
||||
## 通用响应结构
|
||||
|
||||
所有接口响应结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
- `code`：业务码（本项目中与 HTTP 状态码保持一致）
|
||||
- `message`：提示信息（部分接口为中文提示）
|
||||
- `data`：成功时返回的数据，失败时通常省略
|
||||
|
||||
## 常见 HTTP 状态码
|
||||
|
||||
- `200`：成功
|
||||
- `400`：请求参数错误
|
||||
- `401`：未登录或登录已过期（缺少/无效 Token）
|
||||
- `403`：无权限或触发业务限制（例如今日额度用尽）
|
||||
- `404`：资源不存在
|
||||
- `500`：服务端内部错误
|
||||
- `502`：第三方服务错误
|
||||
- `503`：服务暂不可用（缺少关键配置等）
|
||||
|
||||
@@ -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. 数据落地
|
||||
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
小程序需要提供“短视频去水印”功能。用户提交的文本中包含短视频分享链接，后台需调用第三方接口 `https://api.23bt.cn/api/d1w/index?key=<你的key>&url=<分享链接>` 获取解析结果并返回。该接口仅向已登录用户开放。
|
||||
|
||||
公共登录与认证说明见：`docs/common/auth.md`。
|
||||
|
||||
## 功能需求
|
||||
|
||||
1. **访问控制**
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
# 戒烟/抽烟记录 API
|
||||
|
||||
所有接口前缀：`/api/v1/smoke`
|
||||
除登录外都需要：`Authorization: Bearer <session_key>`（见：`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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -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` 由后端从登录用户推导，不允许前端传入。
|
||||
|
||||
@@ -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='抽烟记录';
|
||||
|
||||
Reference in New Issue
Block a user