INITIAL_REQUIREMENTS_V2

1. 项目背景

HomeInventory 是一个面向家庭场景的库存与整理管理系统，用于帮助家庭成员统一管理日常物品、分类、库存数量、库存变动记录、通知信息，以及围绕“整理 / 断舍离”开展协作。

项目不只是一个基础库存系统，还应支持对家庭物品进行清点、筛选、整理、清理和留存记录，帮助用户减少囤积、识别闲置、处理临期或不再需要的物品。

2. 项目目标

系统需要满足以下核心目标：

1. 支持用户注册与登录
2. 支持以家庭为单位进行库存协作管理
3. 支持家庭成员邀请与加入
4. 支持分类管理
5. 支持物品管理
6. 支持库存入库、出库、调整
7. 支持库存变更日志记录
8. 支持通知中心
9. 支持家庭整理 / 断舍离流程
10. 提供统一、清晰、可扩展的 REST API
11. 具备基础权限控制与数据隔离能力

3. 功能范围

3.1 用户与认证

功能要求

• 用户可以注册账号
• 用户可以使用账号密码登录
• 登录成功后获取认证凭证（如 JWT）
• 登录后可获取当前用户信息
• 用户密码必须加密存储
• 系统不得返回明文密码

基础规则

• 用户名唯一
• 邮箱可选，如启用则建议唯一
• 未登录用户只能访问注册、登录等开放接口
• 已登录用户可访问受保护业务接口

3.2 家庭管理

功能要求

• 用户可以创建家庭
• 家庭创建者默认为家庭拥有者
• 用户可查看自己所属家庭信息
• 家庭拥有者或管理员可修改家庭信息
• 系统应支持家庭成员列表查询

基础规则

• 家庭是库存数据归属主体
• 家庭创建后，创建者必须自动成为该家庭成员
• 一个用户默认只能加入一个家庭（如项目采用单家庭模式）
• 非家庭成员不能访问该家庭数据

3.3 家庭成员与邀请管理

功能要求

• 家庭拥有者或管理员可邀请其他用户加入家庭
• 被邀请用户可查看收到的邀请
• 被邀请用户可接受或拒绝邀请
• 家庭成员列表应可查看成员角色信息
• 支持后续扩展成员移除、退出家庭

基础规则

• 邀请必须记录邀请人、被邀请人、家庭、状态、时间
• 同一家庭下，不应对同一用户存在多个未处理邀请
• 接受邀请后，用户自动加入对应家庭
• 已加入家庭的用户不能重复加入
• 非法状态流转应被拦截

3.4 分类管理

功能要求

• 家庭成员可创建分类
• 家庭成员可查看本家庭分类列表
• 家庭成员可修改分类信息
• 家庭成员可删除分类

基础规则

• 分类属于家庭
• 同一家庭下分类名称唯一
• 非本家庭成员不得操作分类
• 删除分类前应检查是否仍有关联物品

3.5 物品管理

功能要求

• 家庭成员可创建物品
• 家庭成员可查看本家庭物品列表
• 家庭成员可查看物品详情
• 家庭成员可修改物品基础信息
• 家庭成员可删除物品

物品字段要求

物品应至少支持以下信息：

• 名称
• 分类
• 当前库存
• 单位
• 备注
• 最低库存阈值
• 图片地址（可选）
• 过期日期（可选）
• 最近使用时间（可选，便于识别闲置物品）
• 状态标签（可选，如正常、待整理、已整理）

基础规则

• 物品属于家庭
• 物品可挂载分类，也可无分类
• 若设置分类，则分类必须属于同一家庭
• 物品基础信息修改与库存修改建议分离
• 非本家庭成员不得操作物品

3.6 库存管理

功能要求

• 支持物品入库
• 支持物品出库
• 支持库存调整
• 可查询物品库存变更记录

基础规则

• 库存不得为负数
• 每次库存变化必须记录日志
• 库存日志至少记录：操作类型、数量、前值、后值、操作人、时间
• 出库时必须校验库存是否足够
• 库存调整应具备备注能力
• 普通物品更新接口不应绕过库存日志直接修改库存

3.7 通知中心

功能要求

• 用户可查看自己的通知列表
• 用户可标记通知为已读
• 系统可生成业务通知

通知场景建议

系统至少支持以下通知类型：

• 家庭邀请通知
• 邀请被接受通知
• 低库存提醒
• 系统通知
• 物品临期提醒
• 整理 / 断舍离提醒

基础规则

• 通知归属于用户
• 用户只能查看自己的通知
• 用户只能操作自己的通知状态

3.8 整理 / 断舍离管理

功能要求

• 家庭成员可将物品标记为待整理 / 待断舍离
• 家庭成员可为物品设置整理原因
• 家庭成员可指定处理方式
• 家庭成员可查看家庭断舍离清单
• 家庭成员可更新断舍离状态
• 家庭成员可完成或取消断舍离流程
• 系统可保留断舍离历史记录

建议处理方式

• 捐赠
• 丢弃
• 转送
• 出售
• 回收
• 暂存待定

建议原因类型

• 已过期
• 即将过期
• 长期未使用
• 重复购买
• 库存过多
• 物品损坏
• 不再需要
• 占空间
• 其他

建议状态流转

• NORMAL：正常状态
• PENDING_DECLUTTER：待整理
• PENDING_DONATE：待捐赠
• PENDING_DISPOSE：待丢弃
• PENDING_TRANSFER：待转送
• PENDING_SELL：待出售
• PENDING_RECYCLE：待回收
• COMPLETED_DECLUTTER：已完成断舍离
• CANCELLED_DECLUTTER：已取消断舍离

基础规则

• 断舍离对象必须属于当前家庭
• 非家庭成员不得操作断舍离数据
• 同一物品在未完成前，不应重复发起相同断舍离流程
• 断舍离不等于直接物理删除物品
• 完成断舍离后应保留处理记录
• 删除物品前，建议先完成断舍离流程或显式确认
• 系统可基于过期、闲置、积压等条件提供候选提示

3.9 闲置 / 临期识别

功能要求

• 系统可识别长期未使用物品
• 系统可识别即将过期物品
• 系统可识别已过期物品
• 可将识别结果用于通知或断舍离候选清单

基础规则

• 闲置判断规则可先采用简单方案，例如最近 N 天无使用 / 无库存变更
• 临期判断可根据过期日期和当前日期计算
• 候选识别结果应仅作为辅助提醒，不应直接替用户执行删除或出库

3.10 权限与数据隔离

功能要求

• 未登录用户不可访问受保护业务接口
• 登录用户只能访问自己有权限的数据
• 家庭维度数据必须隔离

基础规则

• 非家庭成员不得查看或操作该家庭下分类、物品、库存、断舍离信息
• 用户只能查看自己的通知
• 需要区分基本角色权限，例如：
  • OWNER
  • ADMIN
  • MEMBER

权限建议

• OWNER：家庭拥有者，具备最高权限
• ADMIN：家庭管理员，可管理部分家庭事务
• MEMBER：普通成员，可参与物品、分类、库存、断舍离操作

3.11 审计与日志

功能要求

• 关键业务数据建议保留创建时间、更新时间
• 核心表建议保留创建人、更新人
• 库存变更日志应长期保留，用于追溯
• 断舍离记录应保留，用于整理复盘

基础规则

• 库存日志默认只增不改
• 不建议提供普通删除接口删除库存日志
• 断舍离记录应作为业务历史保留，而不是被简单覆盖

3.12 接口风格

功能要求

• 提供 RESTful 风格接口
• 使用统一请求与响应结构
• 支持后续前端联调与接口文档维护

建议

• 返回统一结构，例如：
  • code
  • message
  • data
• 对分页接口返回统一分页结构
• 对异常返回统一错误格式

4. 非功能需求

4.1 安全性

• 密码加密存储
• 鉴权接口与业务接口隔离
• 避免敏感字段泄漏
• 对关键操作进行权限校验

4.2 可维护性

• 分层清晰：Controller / Service / Repository / Entity / DTO
• 统一异常处理
• 统一返回结构
• 文档完善

4.3 可扩展性

• 后续可扩展成员移除、退出家庭
• 后续可扩展图片上传
• 后续可扩展系统配置
• 后续可扩展操作日志、消息推送
• 后续可扩展断舍离统计、整理建议、推荐规则

4.4 可部署性

• 支持 Maven 打包
• 支持 Jar 运行
• 后续支持 Docker 部署
• 配置应尽量支持环境变量覆盖

5. 数据模型范围

系统应至少包含以下核心实体：

1. 用户 User
2. 家庭 Family
3. 家庭成员 FamilyMember
4. 家庭邀请 FamilyInvitation
5. 分类 Category
6. 物品 Item
7. 库存日志 InventoryLog
8. 通知 Notification

为支持整理 / 断舍离，建议新增：

9. 断舍离记录 DeclutterRecord

6. 关键业务规则汇总

1. 用户名唯一
2. 密码必须加密存储
3. 家庭创建者必须自动成为家庭成员
4. 同一家庭下分类名称唯一
5. 物品必须归属家庭
6. 分类若被引用，不允许直接删除
7. 库存不得为负数
8. 每次库存变更必须记录日志
9. 普通物品修改不得绕过库存日志直接改库存
10. 通知只能由所属用户查看和操作
11. 非家庭成员不得访问该家庭数据
12. 接受邀请后用户自动加入家庭
13. 已加入家庭用户不得重复加入
14. 邀请状态必须合法流转
15. 断舍离对象必须属于当前家庭
16. 断舍离流程不等于直接删除物品
17. 同一物品未完成前不应重复发起同类断舍离流程
18. 断舍离记录应保留用于追溯
19. 临期 / 闲置识别只作辅助提醒
20. 系统接口应具备统一返回与异常处理能力

7. 建议的最小可交付能力（MVP）

第一阶段建议至少完成以下能力：

MVP 必做

• 用户注册
• 用户登录
• 获取当前用户信息
• 创建家庭
• 查看家庭信息
• 邀请成员
• 接受/拒绝邀请
• 分类增删改查
• 物品增删改查
• 入库 / 出库 / 调整库存
• 库存日志查询
• 通知列表 / 标记已读
• 发起断舍离
• 查询断舍离清单
• 完成 / 取消断舍离

MVP 可暂缓

• 成员移除
• 主动退出家庭
• 文件上传
• 批量通知处理
• 高级筛选
• 复杂统计报表
• WebSocket 实时通知
• 多家庭模式
• 自动闲置识别规则引擎
• 自动断舍离推荐
• 断舍离月报 / 统计分析

8. 建议 API 范围

用户与认证

• POST /api/auth/register
• POST /api/auth/login
• GET /api/users/me

家庭

• POST /api/families
• GET /api/families/me
• PUT /api/families/{id}
• GET /api/families/{id}/members

邀请

• POST /api/invitations
• GET /api/invitations/received
• PUT /api/invitations/{id}/accept
• PUT /api/invitations/{id}/reject

分类

• POST /api/categories
• GET /api/categories
• GET /api/categories/{id}
• PUT /api/categories/{id}
• DELETE /api/categories/{id}

物品

• POST /api/items
• GET /api/items
• GET /api/items/{id}
• PUT /api/items/{id}
• DELETE /api/items/{id}

库存

• POST /api/items/{id}/inventory/in
• POST /api/items/{id}/inventory/out
• POST /api/items/{id}/inventory/adjust
• GET /api/items/{id}/inventory/logs

通知

• GET /api/notifications
• PUT /api/notifications/{id}/read

断舍离

• POST /api/declutter
• GET /api/declutter
• GET /api/declutter/{id}
• PUT /api/declutter/{id}/status
• PUT /api/declutter/{id}/cancel

候选提醒（可选）

• GET /api/items/expiring
• GET /api/items/expired
• GET /api/items/idle

9. 当前推荐实现方式

后端技术建议

• Java 17
• Spring Boot
• Spring Security
• Spring Data JPA 或 MyBatis
• MySQL
• Maven

部署建议

• 本地开发使用 Jar 运行
• 后续部署支持 Docker 化
• 提供基础 SQL 初始化脚本
• 提供部署说明文档

10. 验收标准

项目初步完成时，应至少满足以下验收要求：

功能验收

• 用户可注册并登录
• 登录后可访问受保护接口
• 可创建家庭并自动成为成员
• 可邀请成员并完成接受/拒绝流程
• 可管理家庭分类
• 可管理家庭物品
• 可完成入库、出库、调整库存
• 可查看库存变更日志
• 可查看通知并标记已读
• 可发起断舍离
• 可查看断舍离清单
• 可完成或取消断舍离流程

规则验收

• 密码非明文存储
• 非家庭成员不能访问家庭数据
• 分类删除前会检查物品关联
• 出库不能导致负库存
• 每次库存变化都写入日志
• 通知仅本人可见
• 邀请流程状态合法
• 断舍离不等于直接删除物品
• 断舍离历史可追溯

工程验收

• 项目可通过 Maven 打包
• 项目可通过 Jar 启动
• 配置支持外部化
• 文档齐全
• 后续可平滑接入 Docker 部署