家庭模块

家庭鉴权接口文档

概览

• 基础路径: /api
• 文档范围: 鉴权路由中的 family 模块接口
• 鉴权方式: 请求头 X-Token
• Content-Type: application/json

鉴权头

统一响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

返回字段说明

家庭对象字段说明

家庭详情成员字段说明

1. 获取家庭列表

• 路径: /api/family/list
• 方法: POST
• 是否鉴权: 是

请求 Body

无业务参数，可传空对象：

{}

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "family_001",
      "name": "我的家庭",
      "ownerId": 1,
      "createdAt": "2026-05-09T10:00:00Z",
      "updatedAt": "2026-05-09T10:00:00Z"
    }
  ]
}

返回参数说明

失败响应示例

{
  "code": 500,
  "msg": "获取家庭列表失败",
  "data": null
}

2. 获取家庭详情

• 路径: /api/family/detail
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "id": "family_001"
}

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "family_001",
    "name": "我的家庭",
    "ownerId": 1,
    "members": [
      {
        "id": 1,
        "nickname": "小明",
        "phone": "13800138000",
        "role": "owner"
      }
    ],
    "createdAt": "2026-05-09T10:00:00Z"
  }
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "参数错误",
  "data": null
}

{
  "code": 404,
  "msg": "家庭不存在",
  "data": null
}

3. 创建家庭

• 路径: /api/family/create
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "name": "我的家庭"
}

成功响应示例

{
  "code": 200,
  "msg": "家庭创建成功",
  "data": {
    "id": "family_001",
    "name": "我的家庭",
    "ownerId": 1,
    "createdAt": "2026-05-09T10:00:00Z",
    "updatedAt": "2026-05-09T10:00:00Z"
  }
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "家庭名称不能超过30个字符",
  "data": null
}

{
  "code": 400,
  "msg": "家庭名称只能包含中文、字母、数字、下划线和短横线",
  "data": null
}

4. 修改家庭名称

• 路径: /api/family/updateName
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "familyId": "family_001",
  "name": "新家庭名称"
}

成功响应示例

{
  "code": 200,
  "msg": "家庭名称修改成功",
  "data": null
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "家庭不存在",
  "data": null
}

{
  "code": 400,
  "msg": "只有家庭创建者可以修改家庭名称",
  "data": null
}

5. 生成邀请链接

• 路径: /api/family/invite
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "familyId": "family_001"
}

成功响应示例

{
  "code": 200,
  "msg": "邀请链接已生成",
  "data": {
    "inviteCode": "a1b2c3d4",
    "inviteUrl": "https://example.com/invite/a1b2c3d4",
    "expireSeconds": 86400
  }
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "家庭不存在",
  "data": null
}

{
  "code": 400,
  "msg": "只有家庭创建者可以邀请成员",
  "data": null
}

{
  "code": 400,
  "msg": "操作失败，请重试",
  "data": null
}

{
  "code": 400,
  "msg": "生成邀请码失败，请重试",
  "data": null
}

6. 通过邀请码加入家庭

• 路径: /api/family/join
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "inviteCode": "a1b2c3d4"
}

成功响应示例

{
  "code": 200,
  "msg": "加入成功",
  "data": {
    "familyId": "family_001",
    "familyName": "我的家庭"
  }
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "参数错误",
  "data": null
}

{
  "code": 400,
  "msg": "您已是该家庭成员",
  "data": null
}

7. 移除成员

• 路径: /api/family/removeMember
• 方法: POST
• 是否鉴权: 是

请求 Body 参数

请求示例

{
  "familyId": "family_001",
  "memberId": 2
}

成功响应示例

{
  "code": 200,
  "msg": "成员已移除",
  "data": null
}

返回参数说明

失败响应示例

{
  "code": 400,
  "msg": "家庭不存在",
  "data": null
}

{
  "code": 400,
  "msg": "只有家庭创建者可以移除成员",
  "data": null
}

{
  "code": 400,
  "msg": "不能移除自己",
  "data": null
}

附录

说明

• family/list 当前实现不读取业务请求体，空对象或空 body 均可。
• 本文档仅覆盖鉴权路由，不包含公开邀请页面 /invite/:code。

失败响应示例

{
  "code": 400,
  "msg": "家庭不存在",
  "data": null
}

{
  "code": 400,
  "msg": "只有家庭创建者可以移除成员",
  "data": null
}

{
  "code": 400,
  "msg": "不能移除自己",
  "data": null
}

附录

说明

• family/list 当前不读取业务请求体，空对象或空 body 均可。
• 本文档仅覆盖鉴权路由，不包含公开邀请页面 /invite/:code。