幻的小屋

【AI生成】HomeInventory 项目API_LIST

蛋蛋 2026年04月23日 3 0

API_LIST

说明：以下为 HomeInventory 项目接口清单草案。
实际路径、字段名、响应结构请以代码实现为准。
建议统一返回结构：

{
  "code": 0,
  "message": "success",
  "data": {}
}

1. Auth 认证模块

1.1 用户注册

  • Method: POST
  • Path: /api/auth/register

Request Body

{
  "username": "testuser",
  "password": "123456",
  "nickname": "测试用户",
  "email": "test@example.com"
}

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1,
    "username": "testuser"
  }
}

1.2 用户登录

  • Method: POST
  • Path: /api/auth/login

Request Body

{
  "username": "testuser",
  "password": "123456"
}

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "token": "jwt-token",
    "userId": 1,
    "username": "testuser"
  }
}

2. User 用户模块

2.1 获取当前用户信息

  • Method: GET
  • Path: /api/users/me

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "nickname": "测试用户",
    "email": "test@example.com"
  }
}

2.2 根据 ID 查询用户

  • Method: GET
  • Path: /api/users/{id}

Path Param

  • id: 用户 ID

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "testuser",
    "nickname": "测试用户"
  }
}

3. Family 家庭模块

3.1 创建家庭

  • Method: POST
  • Path: /api/families

Request Body

{
  "name": "我的家庭",
  "description": "家庭库存管理"
}

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "我的家庭",
    "description": "家庭库存管理"
  }
}

3.2 更新家庭

  • Method: PUT
  • Path: /api/families/{id}

Path Param

  • id: 家庭 ID

Request Body

{
  "name": "新的家庭名称",
  "description": "更新后的描述"
}

3.3 获取家庭详情

  • Method: GET
  • Path: /api/families/{id}

3.4 获取我的家庭列表 / 当前家庭

  • Method: GET
  • Path: /api/families/my

3.5 获取家庭成员列表

  • Method: GET
  • Path: /api/families/{id}/members

Response

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "userId": 1,
      "username": "owner",
      "role": "OWNER"
    },
    {
      "userId": 2,
      "username": "member1",
      "role": "MEMBER"
    }
  ]
}

3.6 邀请家庭成员

  • Method: POST
  • Path: /api/families/{id}/invite

Request Body

{
  "userId": 2
}

或

{
  "username": "member1"
}

3.7 接受邀请

  • Method: POST
  • Path: /api/families/invitations/{invitationId}/accept

Path Param

  • invitationId: 邀请 ID

3.8 拒绝邀请

  • Method: POST
  • Path: /api/families/invitations/{invitationId}/reject

3.9 获取邀请列表

  • Method: GET
  • Path: /api/families/invitations

3.10 退出家庭

  • Method: POST
  • Path: /api/families/{id}/leave

3.11 移除成员

  • Method: DELETE
  • Path: /api/families/{id}/members/{userId}

4. Category 分类模块

4.1 创建分类

  • Method: POST
  • Path: /api/categories

Request Body

{
  "name": "食品",
  "description": "食品分类"
}

4.2 更新分类

  • Method: PUT
  • Path: /api/categories/{id}

Request Body

{
  "name": "日用品",
  "description": "更新描述"
}

4.3 删除分类

  • Method: DELETE
  • Path: /api/categories/{id}

4.4 查询分类详情

  • Method: GET
  • Path: /api/categories/{id}

4.5 查询分类列表

  • Method: GET
  • Path: /api/categories

Query Params

  • keyword 可选
  • page 可选
  • size 可选

Response

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "食品",
      "description": "食品分类"
    }
  ]
}

5. Item 物品模块

5.1 创建物品

  • Method: POST
  • Path: /api/items

Request Body

{
  "name": "大米",
  "categoryId": 1,
  "stock": 10,
  "unit": "袋",
  "remark": "5kg/袋"
}

5.2 更新物品

  • Method: PUT
  • Path: /api/items/{id}

Request Body

{
  "name": "东北大米",
  "categoryId": 1,
  "unit": "袋",
  "remark": "更新备注"
}

5.3 删除物品

  • Method: DELETE
  • Path: /api/items/{id}

5.4 查询物品详情

  • Method: GET
  • Path: /api/items/{id}

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "大米",
    "categoryId": 1,
    "categoryName": "食品",
    "stock": 10,
    "unit": "袋",
    "remark": "5kg/袋"
  }
}

5.5 查询物品列表

  • Method: GET
  • Path: /api/items

Query Params

  • keyword 可选
  • categoryId 可选
  • page 可选
  • size 可选

5.6 增加库存

  • Method: POST
  • Path: /api/items/{id}/stock/increase

Request Body

{
  "quantity": 5,
  "remark": "采购入库"
}

5.7 减少库存

  • Method: POST
  • Path: /api/items/{id}/stock/decrease

Request Body

{
  "quantity": 2,
  "remark": "日常使用"
}

5.8 调整库存

  • Method: POST
  • Path: /api/items/{id}/stock/adjust

Request Body

{
  "quantity": 20,
  "remark": "盘点修正"
}

5.9 查询库存变更日志

  • Method: GET
  • Path: /api/items/{id}/logs

Response

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "changeType": "IN",
      "quantity": 5,
      "beforeStock": 10,
      "afterStock": 15,
      "remark": "采购入库",
      "createdAt": "2025-01-01T10:00:00"
    }
  ]
}

6. Notification 通知模块

6.1 查询通知列表

  • Method: GET
  • Path: /api/notifications

Query Params

  • read 可选
  • page 可选
  • size 可选

Response

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": 1,
      "type": "INVITATION",
      "title": "家庭邀请",
      "content": "你收到一个家庭邀请",
      "read": false,
      "createdAt": "2025-01-01T10:00:00"
    }
  ]
}

6.2 查询通知详情

  • Method: GET
  • Path: /api/notifications/{id}

6.3 标记通知已读

  • Method: PUT
  • Path: /api/notifications/{id}/read

6.4 全部标记已读

  • Method: PUT
  • Path: /api/notifications/read-all

6.5 创建通知（如保留内部接口）

  • Method: POST
  • Path: /api/notifications

Request Body

{
  "userId": 2,
  "type": "SYSTEM",
  "title": "系统通知",
  "content": "欢迎使用 HomeInventory"
}

7. 通用响应码建议

成功

  • 0 成功

通用错误

  • 4000 请求参数错误
  • 4001 参数校验失败
  • 4003 无权限访问
  • 4004 资源不存在
  • 4009 数据冲突

业务错误

  • 5001 用户不存在
  • 5002 用户名或密码错误
  • 5003 家庭不存在
  • 5004 邀请不存在
  • 5005 邀请状态非法
  • 5006 分类不存在
  • 5007 物品不存在
  • 5008 库存不足
  • 5009 通知不存在

系统错误

  • 9999 系统异常

8. 鉴权说明建议

除以下接口外，其余接口建议都需要登录：

白名单接口

  • POST /api/auth/register
  • POST /api/auth/login

需要登录的接口

  • /api/users/**
  • /api/families/**
  • /api/categories/**
  • /api/items/**
  • /api/notifications/**

9. 后续可补充字段

用户

  • avatar
  • phone
  • status

家庭

  • code
  • ownerId
  • status

分类

  • sort
  • status

物品

  • imageUrl
  • expireDate
  • minStock
  • barcode

通知

  • bizType
  • bizId
  • readAt
Last Updated: 2026/04/23 21:31:59
【AI生成】HomeInventory 项目README 【AI生成】HomeInventory 项目TODO