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

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

---

1. 项目概述

1.1 简介

本系统是一套完整的用户数据管理 API 服务，为你的应用提供开箱即用的后端能力。你无需从零搭建用户系统，只需调用 API 即可实现：

• 用户认证：账号密码注册登录、微信小程序一键登录
• 数据存储：自定义用户数据字段，灵活存储各类业务数据
• 团队协作：创建团队、成员管理、自定义字段、权限控制
• 数据分享：生成分享码，安全分享用户数据
• 游客模式：未登录用户也可访问公开数据

1.2 适用场景

1.3 功能特性

1.4 系统架构

┌─────────────────────────────────────────────────────┐
│                      客户端应用                       │
│             (小程序 / APP / Web 应用)                  │
└───────────────────┬─────────────────────────────────┘
                    │ HTTP API
                    ▼
┌─────────────────────────────────────────────────────┐
│                    API 服务端                         │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ 认证接口   │  │ 用户接口   │  │ 项目接口   │      │
│  └───────────┘  └───────────┘  └───────────┘      │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ 分享接口   │  │ 团队接口   │  │ 游客接口   │      │
│  └───────────┘  └───────────┘  └───────────┘      │
│  ┌───────────────────────────────────────────┐     │
│  │              字段配置系统                    │     │
│  │   用户字段  │  项目字段  │  团队字段         │     │
│  └───────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────┘

1.5 文档导航

---

2. 快速开始

2.1 环境准备

在开始之前，确保你拥有：

1. 有效的 API Key（联系管理员获取）
2. 了解你的应用需要的用户数据字段
3. 开发环境支持 HTTP 请求

2.2 获取 API Key

1. 登录管理后台
2. 进入"项目管理"
3. 创建或编辑项目配置
4. 复制 API Key

2.3 第一个 API 调用

以下是一个简单的连通性测试：

请求：

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

响应：

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

2.4 快速开始流程

1. 获取 API Key          → 联系管理员
2. 测试连通性             → GET /api/ping
3. 配置数据字段           → 后台"项目字段管理"
4. 用户注册/登录          → POST /api/auth/register 或 /api/auth/login
5. 获取/更新用户数据       → GET / PUT /api/user/field-values
6. 实现心跳保活           → GET /api/auth/heartbeat

---

3. 核心概念

3.1 认证体系

系统提供三层认证机制，从宽松到严格逐级叠加：

┌──────────────┐
│  API Key     │  ← 所有业务接口必须携带，用于识别项目
├──────────────┤
│  User Token  │  ← 需要用户身份的接口额外携带
├──────────────┤
│  IP 校验     │  ← 可选开启，绑定 Token 与请求 IP
└──────────────┘

3.1.1 API Key 认证

所有业务 API 请求都需要在 Header 中携带 API Key，系统据此识别所属项目：

X-API-Key: your_project_api_key

不含 API Key 的请求将返回 401 错误。

3.1.2 Token 认证

需要用户身份的接口（如读写用户数据）额外携带 User Token：

X-API-Key: your_project_api_key
X-User-Token: user_token_here

Token 通过登录接口获取，可以是用户 Token 或游客 Token，系统通过 Token 前缀自动区分身份。

3.1.3 游客模式

未登录用户可以通过领取临时游客 Token 访问标记为 require_auth = 0 的公开字段：

3.2 Token 机制

3.2.1 Token 格式

3.2.2 Token 过期与刷新

3.3 用户类型

3.3.1 普通用户

• 通过账号密码注册和登录
• 支持修改密码、忘记密码
• 支持邮箱验证

3.3.2 微信用户

• 通过微信小程序授权登录（必须使用 /api/auth/wechat）
• 无密码，无法使用账号密码登录
• 无法使用忘记密码功能
• account 字段返回 wechat_user（不暴露真实 openid）

3.4 字段与分组

3.4.1 字段类型

3.4.2 分组功能

3.5 统一响应格式

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

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

为精简篇幅，下文部分接口示例仅展示 data 字段内容，省略了与外层一致的时间戳和追踪 ID 字段。

---

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

请求参数：

请求示例（用户登录）：

{
    "account": "user123",
    "password": "password123",
    "include_user_info": true,
    "include_user_data": true
}

请求示例（游客 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": {
            "id": 4,
            "account": "user123",
            "email": "user@example.com",
            "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"
        },
        "user_data": [],
        "project_data": {}
    }
}

响应示例（游客 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

请求参数：

登录模式：

响应示例：

{
    "code": 200,
    "message": "WeChat authentication successful",
    "data": {
        "user_id": 1,
        "account": "wechat_xxx",
        "email": "user@example.com",
        "token": "token_here...",
        "token_expires_at": -1,
        "has_password": false,
        "token_type": "standard",
        "is_new_user": false,
        "user_info": {
            "id": 1,
            "account": "wechat_xxx",
            "email": "user@example.com",
            "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"
        },
        "project_data": {
            "default_setting": {"key": "value"}
        }
    }
}

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

通过邮件中的验证链接完成邮箱验证。

请求参数：

响应示例：

{
    "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

请求参数：

响应示例（用户）：

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

响应示例（游客）：

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

游客访问控制规则：

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

{
    "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

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

请求 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

删除用户指定的某个字段数据。

请求 Header：

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

请求参数：

请求示例：

{
    "field_name": "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/data

⚠️ 重要：请勿与用户信息接口混淆

| 接口 | 用途 | 返回内容示例 |

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

| GET /api/project/data ✅ 本接口 | 获取项目级公共配置（全局共享的字段默认值） | 网站标题、Logo、公告等项目级别的配置项 |

| GET /api/user/info | 获取当前登录用户的账号资料 | 用户 ID、账号、邮箱、注册时间等个人信息 |

| GET /api/user/field-values | 获取当前登录用户的自定义字段值 | 昵称、头像、手机号等用户填写的个人数据 |

简单记忆：路径含 /project/ → 项目配置；路径含 /user/ → 用户数据

本项目级接口用于获取管理员在后台配置的项目公共字段（所有用户共享的全局配置），而非某个用户的个人数据。支持按字段或分组筛选。

请求 Header：

X-API-Key: your_api_key
X-User-Token: user_token   // 可选，部分字段需要

请求参数：

响应示例：

{
    "code": 200,
    "message": "Success",
    "data": {
        "fields": [
            {
                "field_name": "site_title",
                "field_type": "varchar",
                "value": "我的项目",
                "is_encrypted": false,
                "require_auth": false,
                "description": "网站标题",
                "is_required": false,
                "is_readonly": false
            },
            {
                "field_name": "site_logo",
                "field_type": "varchar",
                "value": "https://example.com/logo.png",
                "is_encrypted": false,
                "require_auth": false,
                "description": "网站 Logo",
                "is_required": false,
                "is_readonly": false
            }
        ]
    }
}

未携带 X-User-Token 时，require_auth = 1 的字段不会出现在结果中，响应会增加 auth_required_count 字段表示因权限被隐藏的字段数量。

4.5.3 获取字段定义

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": "ok",
    "data": {
        "guest": true,
        "token": "guest_xxxxxx...",
        "expires_at": "2026-05-02 19:10:41",
        "max_requests": 100
    }
}

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": {
        "valid": true,
        "request_count": 5,
        "max_requests": 100,
        "expires_at": "2026-05-02 19:10:41"
    }
}

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 团队接口说明

跨项目隔离

团队成员必须来自同一项目，系统自动校验 user.project_id == team.project_id。不同项目的用户无法加入同一团队，通过邀请码加入时也会校验项目归属。

认证要求

所有团队接口均需携带：

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

角色与权限等级

系统使用 等级制 管理角色层级，level 越小权限越大，同级不可互操作。

等级规则

1. 上级管理下级：操作者的 level 必须 严格小于 目标成员的 level，才能修改其角色或移除
2. 同级不可互操作：相同 level 的角色之间不能互相修改角色或移除
3. 不能越级赋权：操作者只能将成员的角色修改为 自己的 level 或更低（即 level ≥ 自己的角色）
4. 角色定义管理仅限创建者：创建、修改、删除角色定义仅限 creator（level=1）
5. 普通用户(level=0)特殊规则：

• level=0 的用户不能管理任何人
• 任何非0等级的用户都可以管理 level=0 的用户
• level=0 不参与等级比较

昵称规则

团队成员昵称必须符合以下规则：

重要：昵称是展示层概念，数据库存储真实昵称值。API 返回成员列表时，当前登录用户的昵称会显示为"我"（由后端动态判断），其他成员显示真实昵称。"我"不得作为昵称存入数据库。

账号脱敏

为保护用户隐私，微信小程序用户的 account 字段在 API 响应中会自动脱敏为 wechat_user，不暴露真实的 openid。

---

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

从团队中软移除成员（仅 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

更新团队成员的角色（仅 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 权限位说明

default_permissions 是一个 JSON 对象，包含 17 个细粒度权限位，每个值为 true（有权限）或 false（无权限）：

系统角色默认权限对照表：

admin 权限说明：管理员拥有基础的数据查看、成员管理和数据操作权限，但无字段管理权限（不能创建/编辑/删除自定义字段和分组），也无角色管理权限。

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

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
    }
}

---

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,
    include_user_data: true
});

// 3. 读写用户数据
const userData = await request('GET', '/api/user/field-values', {}, {
    '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..." }

---

附录：接口速查表