用户数据管理 API 服务 - 开发文档

一套为小程序、APP、Web 应用提供用户管理、数据存储、团队协作等能力的完整 API 服务。

1. 项目概述

• 用户认证：账号密码注册登录、微信小程序一键登录、游客模式
• 数据存储：自定义用户数据字段，支持分组、加密、按需返回
• 团队协作：创建团队、成员管理、自定义字段、权限控制
• 数据分享：生成分享码，安全分享用户数据
• 访问控制：IP 限制、频率限制、登录限制、邮箱验证

2. 快速开始

1. 获取 API Key：登录管理后台 → "项目管理" → 创建/编辑项目 → 复制 API Key
2. 测试连通性：

GET /api/ping HTTP/1.1
Host: your-domain.com

{
    "code": 200,
    "message": "pong",
    "timestamp": 1773842113,
    "trace_id": "abc123...",
    "data": {
        "time": 1773842113
    }
}

1. 接入流程：后台"项目字段管理"配置字段 → /api/auth/register 或 /api/auth/login 注册登录 → GET/PUT /api/user/field-values 读写用户数据 → /api/auth/heartbeat 心跳保活

---

3. 核心概念

3.1 认证

所有业务接口需在 Header 携带 API Key（识别项目），需用户身份的接口额外携带 User Token（通过登录接口获取，guest_ 前缀为游客）：

X-API-Key: your_project_api_key
X-User-Token: user_token_here   // 可选

• 游客模式：通过 /api/auth/login（不带账号密码）或 /api/guest/token 领取临时 Token，仅可访问 require_auth = 0 的公开字段；显式请求需登录字段返回 403，按分组请求静默过滤
• Token 有效期：-1 永不过期，否则为过期时间戳；微信 Token 登录始终刷新，账号密码/微信 Code 是否刷新取决于项目配置
• 用户类型：普通用户（账号密码注册登录，支持忘记密码、邮箱验证）；微信用户（须用 /api/auth/wechat 授权，无密码、不支持忘记密码、account 返回 wechat_user）

3.2 字段与分组

字段可归入分组，通过 group 参数批量获取，结合 require_auth 控制组内字段的访问权限。

3.3 统一响应格式

所有接口遵循统一响应结构：

{
    "code": 200,
    "message": "Success",
    "timestamp": 1743681193,
    "trace_id": "abc123def456...",
    "data": { ... }
}

下文部分接口示例仅展示 data 字段，省略与之一致的外层字段。

---

4. API 参考

4.1 通用说明

各部分接口按资源分组，完整列表：

---

4.2 认证接口

4.2.1 用户注册

POST /api/auth/register

创建新用户账号。

请求 Header：

X-API-Key: your_api_key
Content-Type: application/json

请求参数：

请求示例：

{
    "account": "user123",
    "password": "password123",
    "email": "user@example.com"
}

响应示例：

{
    "code": 200,
    "message": "Registration successful",
    "data": {
        "user_id": 6,
        "account": "user123",
        "email": "user@example.com",
        "token": "18985018a96bc95dc195a07e5bf494bb",
        "expires_at": 1773849313,
        "has_password": true,
        "token_type": "standard"
    }
}

响应字段说明：

4.2.2 用户登录 / 游客 Token 领取

POST /api/auth/login

账号密码登录，或不提供任何参数领取游客 Token。

注意：微信用户无法使用此接口，必须使用 微信小程序登录。不提供 account 参数时自动走游客 Token 领取流程（需项目开启游客模式）。

请求 Header：

X-API-Key: your_api_key
Content-Type: application/json

请求参数：

重要说明：user_data 通过 user_data_fields / user_data_group 指定返回字段；传 user_data_fields=all 返回全部字段。不指定这两个参数时不返回 user_data。

请求示例（用户登录）：

{
    "account": "user123",
    "password": "password123",
    "include_user_info": true,
    "user_data_fields": "all"
}

请求示例（用户登录 + JSON字段范围查询）：

// 场景1：只对 schedule 字段过滤
{
    "user_data_group": "user,site",
    "field_key_field": "schedule",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31"
}

// 场景2：对所有 JSON 字段都过滤（不传 field_key_field）
{
    "user_data_fields": "schedule,tags",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31"
}

// 场景3：使用字符串键范围
{
    "user_data_fields": "tags",
    "field_key_field": "tags",
    "field_key_start": "b",
    "field_key_end": "d"
}

// 场景4：JSON字段分页查询（获取5月份排班数据，每页10条）
{
    "user_data_fields": "schedule",
    "field_key_field": "schedule",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31",
    "field_key_page": 1,
    "field_key_page_size": 10
}

// 场景5：多个JSON字段进行范围查询
{
    "user_data_fields": "schedule,tags",
    "field_key_field": "schedule,tags",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31"
}

请求示例（游客 Token 领取）：

{}

响应示例（用户登录）：

{
    "code": 200,
    "message": "Login successful",
    "data": {
        "user_id": 4,
        "account": "user123",
        "email": "user@example.com",
        "token": "2e371f414860a99a601bb3321557267f",
        "expires_at": -1,
        "has_password": true,
        "token_type": "standard",
        "is_new_user": false,
        "user_info": {
            "email_verified": 0,
            "status": 1,
            "last_login_at": "2026-03-18 21:53:12",
            "last_heartbeat_at": "2026-03-18 21:53:12",
            "created_at": "2026-03-18 21:53:12"
        }
    }
}

响应示例（游客 Token 领取）：

{
    "code": 200,
    "message": "Guest token created successfully",
    "data": {
        "guest": true,
        "token": "guest_xxxxxx...",
        "expires_at": "2026-05-02 19:10:41",
        "max_requests": 100
    }
}

4.2.3 微信小程序登录

POST /api/auth/wechat

微信小程序登录，支持 Code 登录和 Token 续期两种模式。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token   // 可选，Token 登录模式使用
Content-Type: application/json

请求参数：

重要说明：user_data 通过 user_data_fields / user_data_group 指定返回字段；传 user_data_fields=all 返回全部字段。不指定这两个参数时不返回 user_data。

登录模式：

请求示例（用户登录 + JSON字段范围查询）：

// 场景1：只对 schedule 字段过滤
{
    "user_data_group": "user,site",
    "field_key_field": "schedule",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31"
}

// 场景2：对所有 JSON 字段都过滤（不传 field_key_field）
{
    "user_data_fields": "schedule,tags",
    "field_key_start": "2025-05-01",
    "field_key_end": "2025-05-31"
}

// 场景3：使用字符串键范围
{
    "user_data_fields": "tags",
    "field_key_field": "tags",
    "field_key_start": "b",
    "field_key_end": "d"
}

响应示例：

{
    "code": 200,
    "message": "WeChat authentication successful",
    "data": {
        "user_id": 1,
        "account": "wechat_xxx",
        "email": "user@example.com",
        "token": "token_here...",
        "expires_at": -1,
        "has_password": false,
        "token_type": "standard",
        "is_new_user": false,
        "user_info": {
            "email_verified": 0,
            "status": 1,
            "last_login_at": "2026-04-17 20:30:00",
            "last_heartbeat_at": "2026-04-17 20:30:00",
            "created_at": "2026-04-17 10:00:00"
        },
        "user_data": {
            "nickname": "用户昵称",
            "avatar": "https://example.com/avatar.png"
        }
    }
}

4.2.4 用户退出

POST /api/auth/logout

用户主动退出登录，清理 Token、IP 等登录信息。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Logout successful",
    "data": null
}

4.2.5 心跳检测

GET /api/auth/heartbeat

更新用户活跃时间，保持在线状态。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Heartbeat successful",
    "data": {
        "status": "online",
        "last_heartbeat": "2026-04-11 10:47:22",
        "expires_at": -1,
        "is_online": true
    }
}

4.2.6 忘记密码

POST /api/auth/forgot-password

发送密码重置邮件。微信用户无法使用此功能。

请求 Header：

X-API-Key: your_api_key
Content-Type: application/json

请求参数：

响应示例：

{
    "code": 200,
    "message": "Password reset link generated",
    "data": {
        "message": "密码重置邮件已发送，请查收"
    }
}

4.2.7 重置密码

POST /api/auth/reset-password   （也支持 GET）

使用重置令牌设置新密码。GET 请求返回 HTML 表单页面，POST 请求处理密码重置。

请求参数：

响应示例：

{
    "code": 200,
    "message": "密码重置成功",
    "data": {
        "message": "密码重置成功，请使用新密码登录"
    }
}

4.2.8 修改密码（auth 路径）

POST /api/auth/change-password

已登录用户修改密码。微信用户无法使用。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

响应示例：

{
    "code": 200,
    "message": "Password changed successful",
    "data": {
        "message": "密码修改成功"
    }
}

4.2.9 发送验证邮件

POST /api/auth/send-verify-email

向已登录用户发送邮箱验证邮件。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Verification email sent",
    "data": {
        "message": "验证邮件已发送"
    }
}

4.2.10 验证邮箱

GET /api/auth/verify-email

通过邮件中的验证链接完成邮箱验证。此接口不需要 API Key，Token 可通过 URL 参数或 X-User-Token 请求头传递。

请求参数：

请求示例：

GET /api/auth/verify-email?token=xxx&project_id=1

或

GET /api/auth/verify-email?project_id=1
X-User-Token: xxx

响应示例：

{
    "code": 200,
    "message": "Email verified successfully",
    "data": {
        "message": "邮箱验证成功"
    }
}

---

4.3 用户信息接口

4.3.1 获取用户信息

GET /api/user/info

获取当前登录用户的详细信息。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": {
        "user": {
            "id": 1,
            "account": "user123",
            "email": "user@example.com",
            "email_verified": 0,
            "status": 1,
            "last_login_at": "2024-01-01 12:00:00",
            "last_heartbeat_at": "2024-01-01 12:30:00",
            "created_at": "2024-01-01 00:00:00"
        }
    }
}

---

4.4 用户数据接口

用户数据接口实现自定义字段的完整 CRUD 操作。字段定义由后台管理员配置，客户端通过以下接口读写数据。

游客亦可调用这些接口，通过 X-User-Token 携带游客 Token，系统仅返回 require_auth = 0 的公开字段。

4.4.1 获取用户数据

GET /api/user/field-values

获取当前用户的自定义字段数据。游客模式下仅返回公开字段。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

请求参数：

重要说明：

- 本接口只支持 fields / group 参数筛选字段，不支持 user_data_fields / user_data_group 等参数（这些参数用于 POST /api/auth/login、POST /api/auth/wechat 登录接口）。

- 不传 fields / group 时不返回任何用户数据（data 为空对象），防止全量数据泄露。需要全量数据必须显式传 fields=all。

请求示例（返回全部字段）：

GET /api/user/field-values?fields=all

响应示例（用户）：

{
    "code": 200,
    "message": "Success",
    "data": {
        "user_id": 1,
        "account": "user123",
        "email": "user@example.com",
        "data": {
            "nickname": "张三",
            "avatar": "https://example.com/avatar.jpg",
            "phone": "13800138000"
        }
    }
}

未指定字段时返回空数据：

GET /api/user/field-values

{
    "code": 200,
    "message": "ok",
    "data": {
        "user_id": 1,
        "account": "user123",
        "email": "user@example.com",
        "data": {}
    }
}

请求示例（游客，返回全部公开字段）：

GET /api/user/field-values?fields=all

响应示例（游客）：

{
    "code": 200,
    "message": "Success",
    "data": {
        "guest": true,
        "data": {
            "site_title": "我的项目",
            "announcement": "欢迎访问！"
        },
        "request_count": 2,
        "max_requests": 100
    }
}

JSON字段键范围查询示例：

假设用户有一个 schedule 字段，存储了如下JSON数据：

{
    "2025-05-01": "1",
    "2025-05-02": "1",
    "2025-05-03": "5",
    "2025-05-04": "5",
    "2025-05-05": "3"
}

查询指定日期范围的数据：

GET /api/user/field-values?fields=schedule&field_key_start=2025-05-02&field_key_end=2025-05-04

响应结果：

{
    "code": 200,
    "data": {
        "schedule": {
            "2025-05-02": "1",
            "2025-05-03": "5",
            "2025-05-04": "5"
        }
    }
}

查询字符串键范围：

GET /api/user/field-values?fields=tags&field_key_start=b&field_key_end=d

指定字段进行范围查询（当获取多个字段时，仅对指定字段过滤）：

GET /api/user/field-values?fields=schedule,user_setting&field_key_field=schedule&field_key_start=2025-05-01&field_key_end=2025-05-31

此请求会返回：

• schedule 字段：仅包含5月份的数据（范围过滤后）
• user_setting 字段：完整数据（不受范围过滤影响）

JSON字段分页查询：

GET /api/user/field-values?fields=schedule&field_key_field=schedule&field_key_start=2025-05-01&field_key_end=2025-05-31&field_key_page=1&field_key_page_size=10

分页响应示例：

{
    "code": 200,
    "data": {
        "schedule": {
            "data": {
                "2025-05-01": {"shift": "morning"},
                "2025-05-02": {"shift": "afternoon"},
                "2025-05-03": {"shift": "morning"}
            },
            "pagination": {
                "page": 1,
                "page_size": 10,
                "total": 31,
                "total_pages": 4
            }
        }
    }
}

场景说明：

游客访问控制规则：

游客显式请求需登录字段时的错误响应：

{
    "code": 403,
    "message": "The following fields require authentication: phone, email. Please login to access these fields."
}

4.4.2 更新用户数据（全量）

PUT /api/user/field-values

全量更新用户字段数据。需提供所有必填字段，未提供的字段将被清空。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求示例：

{
    "nickname": "新昵称",
    "avatar": "https://new-avatar.jpg"
}

响应示例：

{
    "code": 200,
    "message": "Data updated successfully",
    "data": null
}

4.4.3 更新用户数据（部分）

PATCH /api/user/field-values

部分更新用户字段数据。仅更新提供的字段，未提供的字段保持不变。

对于 json 类型字段，PATCH 会合并 JSON 对象，而不是覆盖。例如字段 user_remark_data 已有 {"2026-07-15":"15"}，再 PATCH {"user_remark_data":{"2026-07-16":"16"}}，最终值为 {"2026-07-15":"15","2026-07-16":"16"}。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求示例：

{
    "nickname": "新昵称"
}

响应示例：

{
    "code": 200,
    "message": "Data updated successfully",
    "data": null
}

4.4.4 删除用户数据字段

DELETE /api/user/field-values

删除用户指定的某个字段数据。支持以下两种传参方式：

1. 请求体中传 field_name
2. 路径参数：DELETE /api/user/field-values/{field_name}

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

请求示例：

{
    "field_name": "custom_field1"
}

或

DELETE /api/user/field-values/custom_field1

响应示例：

成功删除数据（字段存在且有数据）：

{
    "code": 200,
    "message": "Data deleted successfully",
    "data": null
}

删除不存在的数据（字段不存在或已被删除）：

{
    "code": 200,
    "message": "Field does not exist or has been deleted",
    "data": null
}

---

4.5 项目元数据接口

4.5.1 获取项目信息

GET /api/project

获取当前项目基本信息。

请求 Header：

X-API-Key: your_api_key

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": {
        "project": {
            "id": 1,
            "name": "我的项目",
            "status": 1,
            "created_at": "2026-04-01 09:00:00"
        }
    }
}

4.5.2 获取字段定义

GET /api/project/fields

获取项目的字段结构定义（schema），不含用户实际数据。

请求 Header：

X-API-Key: your_api_key

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": [
        {
            "field_name": "nickname",
            "field_type": "varchar",
            "field_length": 255,
            "is_required": 0,
            "description": "用户昵称"
        }
    ]
}

此接口返回字段元信息，用于客户端了解数据模型结构。如需获取字段的当前值，请使用 获取用户数据。

---

4.6 分享接口

4.6.1 生成分享码

POST /api/share/generate

生成分享码用于分享用户数据。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

响应示例：

{
    "code": 200,
    "message": "Share code generated",
    "data": {
        "share_code": "ABC123",
        "max_uses": 1,
        "used_count": 0,
        "expires_at": "2026-04-12 12:00:00",
        "fields": "nickname,avatar",
        "field_groups": ""
    }
}

4.6.2 使用分享码

GET /api/share/use

使用分享码获取分享的数据。

请求 Header：

X-API-Key: your_api_key

请求参数：

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": {
        "nickname": "张三",
        "avatar": "https://example.com/avatar.jpg"
    }
}

4.6.3 获取分享列表

GET /api/share/list

获取当前用户创建的所有分享码列表。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": [
        {
            "id": 1,
            "share_code": "ABC123",
            "fields": "nickname,avatar",
            "field_groups": "",
            "max_uses": 5,
            "used_count": 2,
            "expires_at": "2026-04-12 12:00:00",
            "status": "active",
            "created_at": "2026-04-11 12:00:00"
        }
    ]
}

4.6.4 撤销分享

DELETE /api/share/:id

删除指定的分享码（不可恢复）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "Share revoked",
    "data": null
}

---

4.7 游客接口

游客可通过以下独立端点管理临时 Token。大部分场景下，建议使用 登录接口统一领取，无需单独调用这些端点。

4.7.1 获取游客 Token

POST /api/guest/token

独立获取游客临时 Token，与通过 /api/auth/login 空请求体领取等效。

请求 Header：

X-API-Key: your_api_key
Content-Type: application/json

响应示例：

{
    "code": 200,
    "message": "Guest token created successfully",
    "data": {
        "token": "guest_xxxxxx...",
        "expires_at": "2026-05-02 19:10:41",
        "max_requests": 100
    }
}

与 /api/auth/login 空请求领取的游客 Token 格式一致。

4.7.2 验证游客 Token

GET /api/guest/token/verify

验证游客 Token 是否有效。

请求 Header：

X-API-Key: your_api_key
X-User-Token: guest_xxxxxx...

响应示例：

{
    "code": 200,
    "message": "ok",
    "data": {
        "token": "guest_xxxxxx...",
        "project_id": 1,
        "expires_at": "2026-05-02 19:10:41",
        "request_count": 5,
        "max_requests": 100
    }
}

4.7.3 清理过期游客 Token

GET /api/guest/token/cleanup

清理项目中所有已过期的游客 Token。

请求 Header：

X-API-Key: your_api_key

响应示例：

{
    "code": 200,
    "message": "ok",
    "data": {
        "deleted_count": 5
    }
}

---

4.8 团队接口

团队接口提供完整的团队协作功能，包括创建、成员管理、自定义字段配置和数据存储。

4.8.0 团队接口说明

认证要求

所有团队接口均需携带 X-API-Key 和 X-User-Token。

角色与权限

系统使用等级制管理角色，等级数字越小权限越大。成员只能管理等级严格低于自己的成员，不能管理同级或上级。

昵称规则

• 允许 2-6 个中文或 2-12 个英文字符
• 禁止数字、符号、空格、保留词（如"我"）
• API 返回时当前登录用户的昵称会显示为"我"，但数据库中不得存储"我"

---

4.8.1 创建团队

POST /api/team

通过 API 接口 创建新团队，创建者自动成为 creator 角色成员。系统同时自动创建默认角色：admin（管理员）和 member（普通成员）。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

请求示例：

{
    "name": "开发团队",
    "description": "项目开发协作团队",
    "invite_mode": "both",
    "is_public": 0,
    "max_members": 20,
    "default_role": "member",
    "nickname": "张三"
}

响应示例：

{
    "code": 200,
    "message": "团队创建成功",
    "data": {
        "team_id": 1,
        "name": "开发团队",
        "creator_id": 6,
        "role": "creator"
    }
}

后台管理接口说明：

后台管理接口（/admin/team/createTeam）创建团队时，除了上述参数外，还需要额外传入 creator_account 参数来指定创建者账号（支持用户账号或手机号）。同时需要传入 creator_nickname 作为创建者在团队内的昵称。

后台接口额外参数：

| 参数 | 必填 | 说明 |

| ----------------- | --------------------------------------- |

| creator_account | 是 | 创建者的用户账号或手机号 |

| creator_nickname | 是 | 创建者在团队内的昵称（见昵称规则） |

4.8.2 获取团队列表

GET /api/team

获取当前用户所属的所有团队。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "teams": [
            {
                "id": 1,
                "name": "开发团队",
                "description": "项目开发协作团队",
                "role": "creator",
                "invite_mode": "both",
                "is_public": 0,
                "member_count": 5,
                "created_at": "2026-04-19 10:00:00"
            }
        ]
    }
}

响应字段：

4.8.3 获取团队详情

GET /api/team/:id

获取指定团队的详细信息（需为团队成员）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "team": {
            "id": 1,
            "name": "开发团队",
            "description": "项目开发协作团队",
            "creator_id": 6,
            "my_role": "creator",
            "invite_mode": "both",
            "is_public": 0,
            "max_members": 20,
            "default_role": "member"
        },
        "members": [
            {
                "user_id": 6,
                "account": "wechat_user",
                "nickname": "我",
                "role": "creator",
                "joined_at": "2026-04-19 10:00:00"
            },
            {
                "user_id": 7,
                "account": "user1",
                "nickname": "小明",
                "role": "member",
                "joined_at": "2026-04-19 11:00:00"
            }
        ],
        "member_count": 2
    }
}

字段说明：

- account：微信用户显示 wechat_user（脱敏），普通用户显示真实账号

- nickname：当前登录用户显示"我"，其他成员显示在团队内的昵称

- 移除了 permissions 字段（未使用）

4.8.4 更新团队信息

PUT /api/team/:id

更新团队基本信息（仅 admin 及以上角色可操作）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数（全部可选）：

请求示例：

{
    "name": "产品研发团队",
    "description": "负责产品研发工作",
    "max_members": 30
}

响应示例：

{
    "code": 200,
    "message": "团队配置已更新"
}

4.8.5 解散团队

DELETE /api/team/:id

解散团队（仅 creator 可操作，软解散后不可恢复）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "团队已解散"
}

---

团队成员管理

4.8.6 生成邀请码

POST /api/team/:id/invite-code

生成或重置团队邀请码（仅 admin 以上可操作，有效期 7 天）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "invite_code": "XYZ789",
        "expires_at": "2026-04-26 12:00:00"
    }
}

4.8.7 加入团队

POST /api/team/join

通过邀请码加入团队（系统自动校验用户所属项目）。必须提供昵称。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

请求示例：

{
    "invite_code": "XYZ789",
    "nickname": "小明"
}

响应示例：

{
    "code": 200,
    "message": "加入成功"
}

可能的错误：邀请码无效或已过期、团队已解散、已是成员（自动重新激活）、成员已达上限、昵称格式不正确、昵称为保留词。

4.8.8 获取成员列表

GET /api/team/:id/members

获取团队所有正常状态成员。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "members": [
            {
                "user_id": 6,
                "account": "wechat_user",
                "nickname": "我",
                "role": "creator",
                "joined_at": "2026-04-19 10:00:00"
            },
            {
                "user_id": 7,
                "account": "user1",
                "nickname": "小明",
                "role": "member",
                "joined_at": "2026-04-19 11:00:00"
            }
        ],
        "member_count": 2
    }
}

字段说明：

- account：微信用户显示 wechat_user（脱敏），普通用户显示真实账号

- nickname：当前登录用户显示"我"，其他成员显示在团队内的昵称

4.8.9 移除成员

DELETE /api/team/:id/member/:user_id  或  DELETE /api/team/:id/members/:user_id

从团队中软移除成员（仅 admin 以上可操作，creator 不可被移除）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "成员已移除"
}

4.8.10 离开团队

POST /api/team/:id/leave

当前用户主动离开团队（creator 无法离开，需先解散团队）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "已离开团队"
}

4.8.11 更新成员角色

PUT /api/team/:id/member/:user_id/role  或  PUT /api/team/:id/members/:user_id/role

更新团队成员的角色（仅 creator 可操作，admin 仅可修改非管理员角色）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

限制：操作者只能将目标成员的角色修改为 level ≥ 自己角色 level 的角色（即权限 ≤ 自己）。且不能将任何成员设置为 creator。

请求示例：

{
    "role": "admin"
}

响应示例：

{
    "code": 200,
    "message": "角色已更新"
}

---

团队角色管理

角色管理接口用于定义团队中的角色及其权限，仅限 creator 操作。

自定义角色通过 default_permissions 配置权限，常见权限包括：

role_manage 仅限 creator 拥有。

请求示例（创建带完整权限的自定义角色）：

POST /api/team/:id/roles
{
  "role_key": "dev_lead",
  "display_name": "开发组长",
  "level": 6,
  "default_permissions": {
    "field_create": false,
    "field_edit": false,
    "field_delete": false,
    "group_create": true,
    "group_edit": true,
    "group_delete": true,
    "data_view_all": true,
    "data_edit_own": true,
    "data_edit_all": true,
    "data_delete_own": true,
    "data_delete_all": false,
    "data_export": true,
    "member_invite": true,
    "member_remove": true,
    "member_role_change": false,
    "member_manage": true,
    "role_manage": false
  }
}

4.8.12 获取角色列表

GET /api/team/:id/roles

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
  "code": 200,
  "message": "Success",
  "data": {
    "roles": [
      {
        "role_key": "creator",
        "display_name": "创建者",
        "color": "#F56C6C",
        "level": 1,
        "is_system": 1,
        "editable": false
      },
      {
        "id": 1,
        "role_key": "admin",
        "display_name": "管理员",
        "level": 2,
        "is_system": 1,
        "editable": true
      },
      {
        "id": 2,
        "role_key": "member",
        "display_name": "成员",
        "level": 0,
        "is_system": 1,
        "editable": true
      },
      {
        "id": 5,
        "role_key": "dev_lead",
        "display_name": "开发组长",
        "level": 6,
        "is_system": 0,
        "editable": true
      }
    ]
  }
}

字段说明：

- creator 角色：default_permissions 为 null，editable 为 false（不可编辑）

- 其他角色：editable 为 true，可编辑配置

- 角色按 level 从小到大排序

4.8.13 创建角色

POST /api/team/:id/roles

创建自定义角色。仅限 creator 操作，自定义角色等级必须 ≥ 5。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

注意：角色按 level 从小到大排序，不再支持手动排序（sort_order 已移除）。

请求示例：

{
  "role_key": "dev_lead",
  "display_name": "开发组长",
  "level": 6,
  "description": "负责管理开发团队",
  "color": "#67C23A",
  "default_permissions": {
    "data_view_all": true,
    "data_edit_own": true,
    "data_edit_all": true,
    "data_export": true
  }
}

响应示例：

{
  "code": 200,
  "message": "Role created",
  "data": {
    "role_id": 5,
    "role_key": "dev_lead"
  }
}

4.8.14 更新角色

PUT /api/team/:id/roles/:role_id

更新角色配置。仅限 creator 操作。 role_id 可使用角色数字 ID 或 role_key。

• creator 角色的所有配置不可修改（返回错误）
• 系统角色（is_system=1，如 admin、member）的 level 可以修改
• 自定义角色的 level 必须 ≥ 5
• 角色的 level 必须唯一，不能与已有角色重复

请求参数（全部可选，传什么改什么）：

注意：sort_order 已移除，角色按 level 自动排序。

请求示例：

{
  "display_name": "开发负责人",
  "level": 7
}

响应示例：

{
  "code": 200,
  "message": "Role updated",
  "data": {
    "role_id": 5
  }
}

4.8.15 删除角色

DELETE /api/team/:id/roles/:role_id

删除自定义角色。仅限 creator 操作。

• 系统角色（creator 等）不可删除
• 如果有成员正在使用该角色，无法删除

响应示例：

{
  "code": 200,
  "message": "Role deleted"
}

---

团队字段管理

4.8.16 获取字段列表

GET /api/team/:id/fields

获取团队所有自定义字段定义。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "fields": [
            {
                "id": 1,
                "team_id": 1,
                "group_id": null,
                "field_name": "team_name",
                "field_type": "varchar",
                "field_length": 100,
                "description": "团队名称",
                "sort_order": 1,
                "require_auth": 0,
                "is_required": 0,
                "default_value": null,
                "merge_with_default": 0,
                "is_readonly": 0,
                "is_encrypted": 0,
                "is_decrypt": 1,
                "placeholder": "请输入团队名称",
                "options": null,
                "created_at": "2026-04-19 10:00:00"
            }
        ]
    }
}

4.8.17 创建字段

POST /api/team/:id/fields

创建新的团队自定义字段（仅 admin 以上可操作）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

请求示例：

{
    "field_name": "team_name",
    "field_type": "varchar",
    "field_length": 100,
    "description": "团队名称",
    "sort_order": 1,
    "require_auth": 0,
    "is_required": 1,
    "placeholder": "请输入团队名称"
}

响应示例：

{
    "code": 200,
    "message": "字段创建成功",
    "data": {
        "field_id": 1
    }
}

4.8.18 更新字段

PUT /api/team/:id/fields/:field_id

更新字段定义（仅 admin 以上可操作，field_name 不可修改）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：同创建字段，除 field_name 外均可更新。

响应示例：

{
    "code": 200,
    "message": "字段已更新"
}

4.8.19 删除字段

DELETE /api/team/:id/fields/:field_id

删除字段定义，同时删除该字段的所有数据。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "字段已删除"
}

---

团队字段分组

4.8.20 获取分组列表

GET /api/team/:id/groups

获取团队所有字段分组。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "groups": [
            {
                "id": 1,
                "team_id": 1,
                "name": "基础信息",
                "key": "basic_info",
                "description": "团队基础信息",
                "sort_order": 1,
                "created_at": "2026-04-19 10:00:00"
            }
        ]
    }
}

4.8.21 创建分组

POST /api/team/:id/groups

创建字段分组（仅 admin 以上可操作）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

响应示例：

{
    "code": 200,
    "message": "分组创建成功",
    "data": {
        "group_id": 1
    }
}

4.8.22 更新分组

PUT /api/team/:id/groups/:group_id

更新分组信息（仅 admin 以上可操作）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：同创建分组，全部可选。

响应示例：

{
    "code": 200,
    "message": "分组已更新"
}

4.8.23 删除分组

DELETE /api/team/:id/groups/:group_id

删除分组（字段不会被删除，group_id 置为 null）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "message": "分组已删除"
}

---

团队字段数据

4.8.24 获取字段数据

GET /api/team/:id/field-values

获取团队所有自定义字段的值。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token

响应示例：

{
    "code": 200,
    "data": {
        "values": {
            "team_name": "我的开发团队",
            "team_description": "这是一个示例团队"
        }
    }
}

4.8.25 更新字段数据

PUT /api/team/:id/field-values

批量更新团队字段数据（仅 admin 以上可操作）。

路径参数：

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token
Content-Type: application/json

请求参数：

请求示例：

{
    "fields": {
        "team_name": "新的团队名称",
        "team_description": "更新后的描述"
    }
}

响应示例：

{
    "code": 200,
    "message": "字段值更新成功",
    "data": {
        "updated_count": 2
    }
}

---

4.9 系统接口

4.9.1 连通性测试

GET /api/ping

测试 API 服务是否正常运行。不需要 API Key，可在任何阶段调用。

响应示例：

{
    "code": 200,
    "message": "pong",
    "timestamp": 1773592665,
    "trace_id": "c87f8ab97f17598ba58c023168a10105",
    "data": {
        "time": 1773592665
    }
}

---

4.10 定时任务接口

定时任务 CRUD，由开发者通过 API 管理定时推送任务。鉴权方式与其它用户接口一致（X-API-Key + X-User-Token）。

任务 ID（task_id）由开发者自定义，非后端自动生成。

4.10.1 创建定时任务

POST /api/scheduled-task

请求 Header：

X-API-Key: your_api_key
X-User-Token: your_user_token
Content-Type: application/json

请求参数：

type=wechat_subscribe 时的 config 结构：

{
  "template_id": "微信模板ID",
  "user_ids": ["用户openid1", "用户openid2"],
  "template_data": {
    "thing5": {"value": "内容1"},
    "thing2": {"value": "内容2"}
  }
}

注意：

- user_ids 为必填，指定接收消息的用户ID列表。为空时任务将直接失败，不会推送给所有用户。

- thing 类型字段（如 thing5、thing2）的值最多 20 个字符（中文算 1 个），超出部分将被自动截断。其他类型（如 date4、number2）无此限制。

- template_data 中的字段名（如 thing5、date4）必须与微信小程序订阅消息模板中的字段名完全一致。

请求示例：

{
  "task_id": "birthday_reminder_001",
  "name": "生日提醒推送",
  "type": "wechat_subscribe",
  "config": {
    "template_id": "r933m2iL4NB7IU8tydTI1FWTNE7gDo6vADrG1F2MQ7s",
    "user_ids": ["oXz8w5J..."],
    "template_data": {
      "thing5": {"value": "张三的生日"},
      "thing2": {"value": "今天是张三的生日！"}
    }
  },
  "execute_time": "2026-07-10 09:00:00"
}

响应示例：

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "task_id": "birthday_reminder_001"
  }
}

4.10.2 获取任务列表

GET /api/scheduled-task

请求 Header：

X-API-Key: your_api_key
X-User-Token: your_user_token

响应示例：

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "task_id": "birthday_reminder_001",
      "type": "wechat_subscribe",
      "name": "生日提醒推送",
      "config": {
        "template_id": "r933m2iL4NB7IU8tydTI1FWTNE7gDo6vADrG1F2MQ7s",
        "template_data": {}
      },
      "execute_time": "2026-07-10 09:00:00",
      "status": 0,
      "result": null,
      "executed_at": null,
      "created_at": "2026-07-03 12:00:00",
      "updated_at": "2026-07-03 12:00:00"
    }
  ]
}

状态说明：

4.10.3 获取单个任务

GET /api/scheduled-task/:task_id

请求 Header：

X-API-Key: your_api_key
X-User-Token: your_user_token

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "birthday_reminder_001",
    "type": "wechat_subscribe",
    "name": "生日提醒推送",
    "config": {},
    "execute_time": "2026-07-10 09:00:00",
    "status": 0,
    "result": null,
    "executed_at": null,
    "created_at": "2026-07-03 12:00:00",
    "updated_at": "2026-07-03 12:00:00"
  }
}

4.10.4 修改定时任务

PUT /api/scheduled-task/:task_id

仅 status=0（待执行）的任务可以修改。

请求 Header：

X-API-Key: your_api_key
X-User-Token: your_user_token
Content-Type: application/json

请求示例：

{
  "name": "生日提醒推送（已更新）",
  "execute_time": "2026-07-11 09:00:00"
}

响应示例：

{
  "code": 200,
  "message": "修改成功",
  "data": null
}

4.10.5 删除定时任务

DELETE /api/scheduled-task/:task_id

请求 Header：

X-API-Key: your_api_key
X-User-Token: your_user_token

响应示例：

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

---

5. 错误码参考

5.1 HTTP 状态码

5.2 通用错误响应格式

{
    "code": 401,
    "message": "Invalid API Key or project not found"
}

5.3 常见业务错误

实际错误信息以服务端返回为准，上表为典型示例。

---

6. 使用场景示例

6.1 微信小程序登录

async function login() {
    const token = wx.getStorageSync('token');

    // 1. 尝试 Token 登录（即使过期也能续期）
    if (token) {
        try {
            const res = await tokenLogin(token);
            if (res.code === 200) {
                wx.setStorageSync('token', res.data.token);
                return res.data;
            }
        } catch (e) {
            console.log('Token 登录失败，回退到微信授权');
        }
    }

    // 2. Token 不可用，执行微信授权登录
    return wechatAuthLogin();
}

async function tokenLogin(token) {
    return request('POST', '/api/auth/wechat', {}, {
        'X-User-Token': token
    });
}

async function wechatAuthLogin() {
    return new Promise((resolve, reject) => {
        wx.login({
            success: async (loginRes) => {
                const res = await request('POST', '/api/auth/wechat', {
                    code: loginRes.code
                });
                if (res.code === 200) {
                    wx.setStorageSync('token', res.data.token);
                }
                resolve(res);
            },
            fail: reject
        });
    });
}

// 通用请求封装
function request(method, path, data = {}, extraHeaders = {}) {
    return new Promise((resolve, reject) => {
        wx.request({
            url: 'https://api.example.com' + path,
            method: method,
            header: {
                'X-API-Key': 'your_api_key',
                'Content-Type': 'application/json',
                ...extraHeaders
            },
            data: data,
            success: (res) => resolve(res.data),
            fail: reject
        });
    });
}

6.2 完整注册登录流程

// 1. 注册
const regRes = await request('POST', '/api/auth/register', {
    account: 'newuser',
    password: 'MyPass123',
    email: 'user@example.com'
});
// regRes.data.token → 保存 Token

// 2. 后续登录
const loginRes = await request('POST', '/api/auth/login', {
    account: 'newuser',
    password: 'MyPass123',
    include_user_info: true
});

// 3. 读写用户数据（需显式指定字段，fields=all 返回全部字段）
const userData = await request('GET', '/api/user/field-values?fields=all', {}, {
    'X-User-Token': loginRes.data.token
});

await request('PUT', '/api/user/field-values', {
    nickname: '小明',
    age: 25
}, {
    'X-User-Token': loginRes.data.token
});

// 4. 心跳保活（建议每 3 分钟调用一次）
setInterval(async () => {
    await request('GET', '/api/auth/heartbeat', {}, {
        'X-User-Token': loginRes.data.token
    });
}, 180000);

6.3 游客模式使用

// 1. 领取游客 Token
const guestRes = await request('POST', '/api/auth/login', {});
const guestToken = guestRes.data.token; // guest_xxxx...

// 2. 获取公开字段数据
const data = await request('GET', '/api/user/field-values', {
    group: 'public_info'
}, {
    'X-User-Token': guestToken
});

// 3. 游客尝试访问需登录字段 → 403
const restricted = await request('GET', '/api/user/field-values', {
    fields: 'phone,email'
}, {
    'X-User-Token': guestToken
});
// → { code: 403, message: "The following fields require authentication..." }

---

附录：接口速查表