HomeInventory

家庭库存管理系统后端项目，用于管理家庭成员、分类、物品库存、库存变更日志和通知等功能。

1. 项目简介

HomeInventory 是一个基于 Spring Boot 的后端项目，目标是为家庭场景提供简单的库存管理能力，支持：

用户注册与登录
家庭创建与成员邀请
家庭成员协作管理库存
分类管理
物品管理
库存增减与调整
库存变更日志记录
通知管理

该项目当前已完成基础结构搭建和模块划分，适合作为家庭库存系统、协作库存系统或 Spring Boot 分层项目模板的基础工程。

2. 功能概览

已规划模块

认证模块 auth
用户模块 user
家庭模块 family
分类模块 category
物品模块 item
通知模块 notification
通用基础模块 common

核心能力

用户注册、登录
获取当前用户信息
创建家庭、查询家庭、更新家庭
家庭成员邀请与加入
分类增删改查
物品增删改查
库存增加、减少、调整
库存日志记录
通知查询与已读处理
全局异常处理
统一返回结构
基础 JPA 审计支持

3. 技术栈

Java
Spring Boot
Spring Web
Spring Data JPA
Spring Security
Maven
MySQL / H2（视配置而定）
Lombok（如项目已接入）
SQL 初始化脚本

4. 项目结构

src/main/java/com/example/homeinventory
├── common
│   ├── api
│   ├── config
│   ├── entity
│   ├── enums
│   ├── exception
│   ├── model
│   └── util
├── config
├── modules
│   ├── auth
│   │   ├── controller
│   │   ├── dto
│   │   ├── service
│   │   └── service/impl
│   ├── user
│   │   ├── controller
│   │   ├── entity
│   │   └── repository
│   ├── family
│   │   ├── controller
│   │   ├── dto
│   │   ├── entity
│   │   ├── repository
│   │   ├── service
│   │   └── service/impl
│   ├── category
│   │   ├── controller
│   │   ├── dto
│   │   ├── entity
│   │   ├── repository
│   │   ├── service
│   │   └── service/impl
│   ├── item
│   │   ├── controller
│   │   ├── dto
│   │   ├── entity
│   │   ├── repository
│   │   ├── service
│   │   └── service/impl
│   └── notification
│       ├── controller
│       ├── dto
│       ├── entity
│       ├── repository
│       ├── service
│       └── service/impl
└── HomeInventoryApplication.java

资源目录：

src/main/resources
├── application.yml
├── schema.sql
└── data.sql

5. 模块说明

5.1 common

通用能力模块，包含：

统一响应结构
全局异常处理
通用枚举
基础实体类
审计配置
工具类

5.2 auth

认证模块，负责：

用户注册
用户登录
Token/JWT 相关处理（如已实现）
与安全配置联动

5.3 user

用户模块，负责：

用户实体管理
当前用户信息获取
用户基础查询

5.4 family

家庭模块，负责：

创建家庭
家庭信息维护
家庭成员管理
家庭邀请处理

5.5 category

分类模块，负责：

分类创建
分类更新
分类删除
分类查询

5.6 item

物品模块，负责：

物品创建、修改、删除、查询
库存变更
库存日志记录

5.7 notification

通知模块，负责：

通知创建
通知查询
标记已读
业务事件通知联动

6. 当前项目状态

当前已完成

项目基础结构已建立
多模块目录与文件已铺设
静态结构自检已通过
资源文件已创建
基础分层已具备

当前待验证

Maven 编译
Spring Boot 启动
数据库初始化
接口联调
安全认证完整性
业务闭环完整性

当前判断

项目目前处于：

结构完成、等待编译与运行验证阶段

7. 本地运行说明

当前文档为通用模板，具体配置请以实际 application.yml 为准。

7.1 环境要求

建议环境：

JDK 17 或以上
Maven 3.8+
MySQL 8.x（如使用 MySQL）
Git

7.2 拉取项目

git clone <your-repository-url>
cd homeinventory

7.3 配置数据库

根据 src/main/resources/application.yml 修改数据库连接信息，例如：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/home_inventory?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: root

如果项目使用 H2，则按 H2 配置调整。

7.4 编译项目

mvn clean compile

7.5 启动项目

mvn spring-boot:run

或者打包后运行：

mvn clean package
java -jar target/homeinventory.jar

8. 数据库初始化

项目资源目录下已包含：

schema.sql：数据库表结构初始化脚本
data.sql：初始化测试数据脚本

如果 Spring Boot 已开启 SQL 初始化，则项目启动时会自动执行。
如果未自动执行，可手动导入数据库。

建议核对以下核心表是否存在：

user / users
family
family_member
family_invitation
category
item
inventory_log
notification

9. 接口说明

接口详细清单请见：

API_LIST.md

建议的接口前缀如下：

/api/auth
/api/users
/api/families
/api/categories
/api/items
/api/notifications

10. 返回结构说明

建议统一返回格式：

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

字段说明

code：业务状态码，0 表示成功
message：提示信息
data：返回数据

错误响应建议同样保持统一结构。

11. 安全说明

项目已规划接入 Spring Security。

建议安全策略：

注册、登录接口加入白名单
其他业务接口需要登录访问
密码使用加密存储
使用 JWT 或 Session 做认证（以实际实现为准）

白名单接口建议：

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

12. 业务规则建议

建议项目遵循以下规则：

用户

用户名唯一
密码不得明文返回
获取用户信息时不返回敏感字段

家庭

家庭创建者为默认管理员/拥有者
邀请状态应有明确流转
成员角色应有限定范围

物品

库存减少时应校验库存是否足够
每次库存变更都应记录日志
物品查询应支持按分类或关键字筛选

通知

通知应归属于具体用户
支持已读/未读状态
业务关键事件建议自动触发通知

13. 已输出文档

当前建议配套文档包括：

README.md
TODO.md
API_LIST.md
PROJECT_CHECKLIST.md
BUSINESS_RULES.md（建议补充）
DB_DESIGN.md（建议补充）

14. 当前待办重点

见 TODO.md

当前优先级最高的事项：

编译验证
启动验证
数据库初始化验证
接口联调验证
安全认证闭环验证
业务闭环补充

15. 后续增强方向

Swagger / OpenAPI 文档
单元测试与集成测试
Docker 部署
JWT 刷新机制
图片上传
低库存提醒
保质期提醒
批量导入导出
管理后台能力

16. 维护说明

如果当前环境暂时无法编译运行，建议先完成以下工作：

核对目录结构
核对实体与 SQL 是否匹配
核对接口清单与业务规则
补全文档
明确 MVP 范围

待具备编译环境后，再执行：

mvn clean compile
mvn spring-boot:run

并逐步完成接口验收。

17. License

如有需要，可在此补充开源协议，例如：

MIT
Apache-2.0

当前如未明确，可暂留空。

【AI生成】HomeInventory 项目README