BUSINESS_RULES

1. 文档说明

本文档用于描述 HomeInventory 项目的核心业务规则，帮助开发、测试、联调和后续维护时统一理解业务行为。

适用范围：

• 用户认证
• 家庭管理
• 家庭成员与邀请
• 分类管理
• 物品与库存管理
• 通知规则
• 通用约束规则

说明：

• 本文档为业务规则草案，可根据实际实现继续修订
• 若代码行为与本文档不一致，以最终确认后的业务规则为准
• 建议与 API_LIST.md、DB_DESIGN.md 配套使用

2. 系统角色与核心对象

2.1 核心对象

系统中的核心业务对象包括：

• 用户 User
• 家庭 Family
• 家庭成员 FamilyMember
• 家庭邀请 FamilyInvitation
• 分类 Category
• 物品 Item
• 库存变更日志 InventoryLog
• 通知 Notification

2.2 基本业务关系

• 用户可以注册并登录系统
• 用户可以创建家庭
• 家庭包含多个成员
• 家庭成员可协作维护分类与物品
• 物品属于某个分类
• 物品有库存数量
• 库存变化会生成日志
• 系统可基于业务事件生成通知

3. 用户与认证规则

3.1 用户注册规则

1. 用户名必须唯一
2. 邮箱如果启用，应具备唯一性或至少格式合法
3. 密码不得以明文存储
4. 注册成功后应返回用户基础信息，不能返回密码
5. 注册时必须校验必要字段：
   • username
   • password
   • 昵称/邮箱等字段按实现决定是否必填

3.2 用户登录规则

1. 用户需使用合法账号和密码登录
2. 登录失败时不能泄露过多系统内部信息
3. 用户登录成功后应获得认证凭证：
   • JWT Token，或
   • Session，视实现而定
4. 登录后可访问受保护接口
5. 未登录用户不能访问受保护接口

3.3 用户信息规则

1. 获取用户信息时不能返回密码
2. 如果包含邮箱、手机号等隐私字段，应按实际需求决定是否返回
3. 用户状态如果存在禁用字段，则禁用用户不能正常登录或访问业务接口

4. 家庭业务规则

4.1 创建家庭规则

1. 已登录用户可以创建家庭
2. 创建家庭时至少应填写家庭名称
3. 家庭创建成功后，创建者自动成为该家庭的拥有者或管理员
4. 家庭应具备唯一标识
5. 家庭创建后可维护基本信息：
   • name
   • description
   • status（如有）

4.2 家庭归属规则

以下两种模式需二选一，并在实现中保持一致：

模式 A：一个用户只能加入一个家庭

• 用户创建家庭后，默认归属于该家庭
• 用户如果已在家庭中，则不能再加入其他家庭
• 更适合“单家庭库存”场景

模式 B：一个用户可加入多个家庭

• 用户可同时属于多个家庭
• 请求中需明确当前操作的家庭上下文
• 更适合“多组织协作”场景

建议当前 MVP 优先采用 模式 A：一个用户只能加入一个家庭，可降低复杂度。

4.3 家庭信息修改规则

1. 只有家庭拥有者或管理员可修改家庭信息
2. 普通成员不能修改家庭信息
3. 修改时应校验家庭是否存在
4. 非家庭成员不能查看或修改受保护的家庭信息

5. 家庭成员与邀请规则

5.1 家庭成员角色规则

建议家庭成员角色包含：

• OWNER：家庭拥有者
• ADMIN：家庭管理员
• MEMBER：普通成员

角色建议权限如下：

OWNER

• 修改家庭信息
• 邀请成员
• 移除成员
• 修改成员角色
• 删除家庭（如支持）
• 转移拥有者（如支持）

ADMIN

• 邀请成员
• 查看家庭成员
• 管理库存、分类、物品
• 是否可移除成员，视实现而定

MEMBER

• 查看家庭信息
• 查看分类与物品
• 新增/修改物品（按权限策略决定）
• 一般不允许修改家庭核心配置

5.2 邀请成员规则

1. 只有有权限的成员才可发起邀请
2. 被邀请对象必须是有效用户
3. 同一用户在同一家庭下不能重复产生多个未处理邀请
4. 已在家庭中的用户不能再次被邀请进入同一家庭
5. 邀请应包含：
   • familyId
   • invitedUserId
   • inviterUserId
   • status
   • createdAt

5.3 邀请状态规则

建议邀请状态包括：

• PENDING：待处理
• ACCEPTED：已接受
• REJECTED：已拒绝
• CANCELLED：已取消（如支持）
• EXPIRED：已过期（如支持）

状态流转建议：

• 新建邀请 -> PENDING
• 接受邀请 -> ACCEPTED
• 拒绝邀请 -> REJECTED
• 邀请方取消 -> CANCELLED
• 超过有效期 -> EXPIRED

一旦进入终态，一般不应再次修改。

5.4 接受邀请规则

1. 只有被邀请人本人可接受邀请
2. 邀请必须处于 PENDING 状态
3. 接受邀请后：
   • 用户加入家庭
   • 邀请状态改为 ACCEPTED
   • 可生成通知
4. 如果系统采用“单用户单家庭”模式，则需先校验用户当前是否已加入其他家庭

5.5 拒绝邀请规则

1. 只有被邀请人本人可拒绝邀请
2. 邀请必须处于 PENDING 状态
3. 拒绝后状态改为 REJECTED
4. 可通知邀请人处理结果

5.6 移除成员规则

1. 只有 OWNER 或具备权限的 ADMIN 可移除成员
2. 不能随意移除家庭拥有者
3. 被移除成员移出家庭后，不再拥有家庭相关访问权限
4. 如存在“当前家庭唯一拥有者”概念，则删除或移除前需保证家庭管理可持续

5.7 退出家庭规则

1. 普通成员可以主动退出家庭
2. 家庭拥有者是否可直接退出，需满足以下之一：
   • 先转移拥有者
   • 或删除家庭
3. 退出后用户失去该家庭的数据访问权限

6. 分类业务规则

6.1 分类归属规则

分类归属建议采用以下其中一种模式：

模式 A：分类属于家庭

• 同一家庭成员共享分类
• 更符合家庭协作场景
• 推荐采用

模式 B：分类属于个人

• 每个用户拥有自己的分类
• 家庭协作价值较弱

建议当前项目采用 分类属于家庭 的设计。

6.2 分类创建规则

1. 只有已登录且属于家庭的用户可创建分类
2. 分类名称不能为空
3. 同一家庭下分类名称建议唯一
4. 分类应具备：
   • 名称
   • 描述（可选）
   • 所属家庭

6.3 分类修改规则

1. 仅家庭成员可修改该家庭下分类
2. 修改时需校验分类是否存在
3. 不能修改到与同家庭其他分类重名

6.4 分类删除规则

1. 仅有权限的家庭成员可删除分类
2. 删除分类前应检查是否有关联物品
3. 如存在关联物品，建议：
   • 禁止删除，或
   • 先迁移物品分类
4. 删除策略应统一：
   • 物理删除，或
   • 逻辑删除

建议当前 MVP 采用：有关联物品时禁止删除分类

7. 物品业务规则

7.1 物品归属规则

1. 物品应归属于某个家庭
2. 物品可归属某个分类
3. 非家庭成员不能访问该家庭物品

7.2 物品创建规则

1. 物品名称不能为空
2. 所属分类必须存在，且属于当前家庭
3. 初始库存应大于等于 0
4. 物品可包含以下信息：
   • 名称
   • 分类
   • 库存数量
   • 单位
   • 备注
   • 图片（如支持）
   • 保质期（如支持）
   • 最低库存阈值（如支持）

7.3 物品修改规则

1. 仅家庭成员可修改物品
2. 修改时需校验物品是否存在
3. 若修改分类，目标分类必须属于同一家庭
4. 不建议通过“物品信息修改接口”直接任意覆盖库存，库存应通过专门库存接口变更

7.4 物品删除规则

1. 仅有权限成员可删除物品
2. 删除策略需统一：
   • 物理删除
   • 逻辑删除
3. 删除后库存日志是否保留，应提前明确

建议：删除物品后保留库存日志，以便审计。

8. 库存业务规则

8.1 库存变更类型

建议库存变更类型包括：

• IN：入库
• OUT：出库
• ADJUST：调整

8.2 库存增加规则

1. 增加库存数量必须大于 0
2. 变更前应确认物品存在
3. 增加后库存 = 原库存 + 增加数量
4. 应记录库存日志

8.3 库存减少规则

1. 减少库存数量必须大于 0
2. 变更前应确认物品存在
3. 默认不允许库存变成负数
4. 若库存不足，应拒绝操作并返回业务错误
5. 应记录库存日志

建议当前项目采用：不允许负库存

8.4 库存调整规则

1. 调整库存通常用于盘点修正
2. 调整后的目标库存必须大于等于 0
3. 调整操作应记录原库存和目标库存
4. 应记录调整原因或备注

8.5 库存日志规则

每次库存变化必须记录日志，日志建议至少包含：

• itemId
• familyId
• operatorUserId
• changeType
• quantity
• beforeStock
• afterStock
• remark
• createdAt

8.6 库存日志不可随意修改

1. 库存日志属于审计数据
2. 原则上不允许普通接口修改或删除库存日志
3. 如确需修复，应通过管理员或数据库层处理

9. 查询与筛选规则

9.1 分类查询规则

1. 分类查询应限制在当前家庭范围内
2. 支持关键字搜索时，应按分类名称或描述匹配
3. 如使用分页，应统一分页参数命名

9.2 物品查询规则

1. 物品查询应限制在当前家庭范围内
2. 可支持按以下维度筛选：
   • categoryId
   • keyword
   • stock status
   • createdAt range
3. 建议支持分页与排序

9.3 通知查询规则

1. 通知只能查询当前登录用户自己的通知
2. 支持按已读/未读筛选
3. 建议支持分页

10. 通知业务规则

10.1 通知归属规则

1. 通知必须归属于具体用户
2. 用户只能查看自己的通知
3. 管理员不能默认查看其他用户个人通知，除非有特殊管理需求

10.2 通知类型建议

通知类型可包括：

• INVITATION
• INVITATION_ACCEPTED
• LOW_STOCK
• SYSTEM
• ITEM_EXPIRE（如支持）

10.3 通知创建触发规则

建议在以下场景自动创建通知：

1. 邀请家庭成员时
   • 发送给被邀请人
2. 邀请被接受时
   • 发送给邀请人或家庭管理员
3. 低库存时
   • 发送给家庭管理员或相关成员
4. 系统公告时
   • 发送给目标用户

10.4 已读规则

1. 用户可将单条通知标记为已读
2. 用户可执行全部已读
3. 已读操作仅能作用于自己的通知
4. 已读后建议记录 readAt

11. 权限控制规则

11.1 基础权限

1. 未登录用户只能访问白名单接口
2. 已登录用户只能访问自己有权限的数据
3. 所有家庭、分类、物品、通知数据都应做归属校验

11.2 数据访问隔离

1. A 家庭成员不能访问 B 家庭的数据
2. 用户不能修改其他用户的个人信息（除非有管理员功能）
3. 用户不能读取其他用户通知
4. 用户不能操作不属于自己家庭的分类和物品

11.3 接口权限建议

无需登录

• 注册
• 登录

需要登录

• 用户信息
• 家庭相关
• 分类相关
• 物品相关
• 通知相关

12. 删除与状态规则

12.1 删除策略

建议明确以下对象是否采用逻辑删除：

• 分类
• 物品
• 通知
• 家庭
• 用户

12.2 当前建议

分类

• 有关联物品时禁止删除
• 无关联时可删除

物品

• 可删除
• 删除后保留库存日志

通知

• 通知通常不建议物理删除
• 可考虑仅支持已读，不支持删除
• 如支持删除，建议仅对用户视角软删除

家庭

• MVP 阶段建议不开放删除家庭接口
• 避免复杂的数据级联问题

13. 审计与日志规则

13.1 审计字段规则

建议所有核心业务实体包含以下审计字段：

• createdAt
• updatedAt
• createdBy（如已实现）
• updatedBy（如已实现）

13.2 审计规则

1. 新增数据自动写入创建时间
2. 更新数据自动写入更新时间
3. 有条件时记录操作人
4. 库存日志属于业务审计日志，必须保留

14. 异常与返回规则

14.1 统一返回规则

接口应统一返回：

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

14.2 常见异常场景

建议统一处理以下场景：

• 参数错误
• 参数校验失败
• 未登录
• 无权限
• 数据不存在
• 状态非法
• 库存不足
• 重复邀请
• 重复分类名

14.3 业务错误示例

• 用户不存在
• 家庭不存在
• 邀请不存在
• 邀请状态非法
• 分类不存在
• 物品不存在
• 库存不足
• 通知不存在

15. 推荐的 MVP 业务边界

为降低复杂度，建议当前 MVP 版本采用以下约束：

1. 一个用户只能加入一个家庭
2. 分类属于家庭
3. 不允许负库存
4. 分类删除前必须无关联物品
5. 物品删除后保留库存日志
6. 不开放家庭删除
7. 通知仅支持查询和已读
8. 默认三种家庭角色：OWNER / ADMIN / MEMBER
9. 登录后通过 JWT 或 Session 获取当前用户
10. 所有写操作都要进行当前用户归属校验

16. 后续增强方向

后续如需扩展，可考虑增加：

• 多家庭支持
• 更细粒度权限模型
• 邀请码/邀请链接
• 图片上传
• 低库存自动提醒
• 保质期提醒
• 批量导入导出
• 操作日志
• 管理后台能力

17. 待确认事项

以下内容需要在最终实现前进一步确认：

• 是否采用“单用户单家庭”模型
• 是否启用 JWT
• 分类删除采用物理删除还是逻辑删除
• 物品删除采用物理删除还是逻辑删除
• 通知是否允许删除
• 家庭成员角色权限边界是否细化
• 是否支持保质期与低库存预警
• 是否支持分页接口统一结构
• 是否需要 Swagger/OpenAPI