HomeInventory 项目检查与验收清单

一、当前项目进展结论

根据目前自检结果：

v3 自检脚本运行通过
未再出现大面积 public 类型识别失败 的误报
说明项目在以下方面已经基本正常：
- 目录结构正常
- Java 文件已大规模铺设完成
- 文件名与类型名匹配度基本正常
- 没有明显把 shell/markdown 内容误写入源码文件
- 核心模块已经具备基础骨架

当前阶段判断

项目当前处于：

“结构自检通过，等待编译验证与运行验收阶段”

也就是说：

项目骨架基本完成
模块结构基本齐全
静态结构已初步自检通过
但尚未完成编译、启动、接口联调验证

二、当前已具备的模块

从当前目录与文件情况看，项目已包含以下主要功能模块：

1. 通用基础模块

common/config
common/enums
common/util
common/api
common/exception
common/entity
common/model

2. 用户/认证模块

modules/auth
modules/user

3. 家庭模块

modules/family

4. 分类模块

modules/category

5. 物品/库存模块

modules/item

6. 通知模块

modules/notification

7. 资源配置

application.yml
schema.sql
data.sql

三、当前无编译环境时的校验方案

在当前无法执行 mvn compile 的情况下，建议通过以下维度做静态验收。

3.1 文件存在性检查

目标：确认关键代码文件是否齐全。

重点检查：

启动类是否存在
- HomeInventoryApplication.java
配置类是否存在
- JpaAuditConfig.java
- SecurityConfig.java
各模块是否有完整分层
- controller
- service
- service/impl
- repository
- entity
- dto

结论标准：

核心模块文件齐全 => 通过
某个模块只有 controller 没有 service/repository/entity => 需补

3.2 类型声明规范检查

目标：确认 Java 文件结构规范。

检查项：

文件名与类型名一致
顶级类型是否合理：
- public class
- public interface
- public enum
- public record
每个 .java 文件不应存在多个 public 顶级类型
package 路径与目录一致

结论标准：

均符合 Java 基础规范 => 通过
存在命名不一致/包路径不一致 => 需修复

3.3 注解与分层语义检查

目标：确认 Spring 项目结构语义合理。

检查项：

Controller

应包含：

@RestController
@RequestMapping

Service

应包含：

@Service 或作为接口由 impl 提供 @Service

Repository

应为：

interface
继承 JpaRepository / CrudRepository / Repository

Entity

应包含：

@Entity
@Table（可选但建议）

DTO

应作为：

请求对象
响应对象

结论标准：

分层职责清晰 => 通过
Controller 直接写数据库逻辑 / 缺少 Service 层 => 需调整

3.4 路由与接口路径检查

目标：确认 API 命名统一。

建议检查以下基础路径是否存在：

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

结论标准：

各模块都有统一前缀 => 通过
路由风格混乱 => 建议统一

3.5 SQL 初始化脚本检查

目标：确认数据库初始化资源具备基础可用性。

检查项：

schema.sql

是否包含核心表：

users
family
family_member
family_invitation
category
item
inventory_log
notification

data.sql

是否包含基础初始化数据：

默认用户
默认分类（如有）

结论标准：

核心表存在 => 基本通过
缺关键业务表 => 需补充

3.6 安全与异常处理静态检查

目标：确认基础工程能力是否具备。

检查项：

是否存在统一异常处理类
- GlobalExceptionHandler
是否存在业务异常类
- BusinessException
- NotFoundException
是否存在安全配置
- SecurityConfig
是否存在认证相关入口
- AuthController
- AuthService

结论标准：

基础异常/认证骨架存在 => 通过
完全没有统一异常和安全控制 => 建议补

四、有编译环境后的校验方案

未来有 Java/Maven 环境后，按以下顺序执行。

4.1 Maven 编译校验

命令：

mvn clean compile

或跳过测试：

mvn -DskipTests clean compile

检查目标：

import 是否完整
类/接口方法签名是否一致
实现类是否实现接口全部方法
泛型定义是否正确
Lombok/依赖是否缺失
Spring/JPA 注解相关类是否可解析

通过标准：

编译成功 => 进入启动验证
编译失败 => 逐条修复

4.2 启动校验

命令：

mvn spring-boot:run

检查目标：

Spring Boot 是否能正常启动
数据源是否配置成功
schema.sql / data.sql 是否执行成功
Bean 注入是否正常
Controller 路由是否注册成功

通过标准：

启动无报错 => 进入接口验收
启动失败 => 修配置/依赖/Bean/SQL

五、启动后的接口验收方案

当项目可以启动后，建议按模块验证。

5.1 认证模块

检查项：

注册接口
登录接口
登录后返回 token（如果已实现 JWT）
未登录访问受保护接口是否被拦截

建议接口：

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

5.2 用户模块

检查项：

获取当前用户信息
查询用户信息
更新用户信息（如已实现）

建议接口：

GET /api/users/me
GET /api/users/{id}

5.3 家庭模块

检查项：

创建家庭
更新家庭
邀请成员
接受邀请
查询家庭成员
查询我的家庭

建议接口：

POST /api/families
PUT /api/families/{id}
POST /api/families/{id}/invite
POST /api/families/invitations/{id}/accept
GET /api/families/{id}/members

5.4 分类模块

检查项：

新建分类
分类列表
更新分类
删除分类（逻辑删除或物理删除）

建议接口：

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

5.5 物品/库存模块

检查项：

新建物品
更新物品
查询物品列表
查询物品详情
入库/出库/调整库存
查看库存变更日志

建议接口：

POST /api/items
PUT /api/items/{id}
GET /api/items
GET /api/items/{id}
POST /api/items/{id}/stock/increase
POST /api/items/{id}/stock/decrease
POST /api/items/{id}/stock/adjust
GET /api/items/{id}/logs

5.6 通知模块

检查项：

创建通知（系统内部触发或接口创建）
查询通知列表
标记已读
全部已读

建议接口：

GET /api/notifications
PUT /api/notifications/{id}/read
PUT /api/notifications/read-all

六、当前项目还可能缺少的功能项

基于当前已有模块，下面是“可能仍需补充或确认”的功能项。

6.1 认证闭环是否完整

虽然已有 auth 模块，但仍需确认是否真正完整实现：

用户注册
用户登录
密码加密
Token/JWT 生成与解析
Spring Security 鉴权链配置
获取当前登录用户

如果这些仅有骨架、没有完整逻辑，则需要补充。

6.2 用户与家庭关系约束是否完整

需要确认：

一个用户是否只能属于一个家庭？
用户是否可被多个家庭邀请？
家庭创建者是否默认成为管理员？
家庭成员角色是否可修改？
成员退出家庭/移除成员是否已实现？

这些属于业务规则，当前可能还未完全补齐。

6.3 分类是否支持家庭维度隔离

需要确认：

分类是用户私有，还是家庭共享？
同一家庭下分类是否唯一？
删除分类时是否检查关联物品？

如果没有这些约束，后续会出现数据混乱。

6.4 物品库存业务是否完整

需要确认：

创建物品时是否设置初始库存
库存是否允许为负
出库时是否校验库存充足
是否记录每次库存变更日志
是否支持按家庭、分类、关键字查询

如果没有这些逻辑，库存模块还不算完整。

6.5 通知模块是否真正联动业务

很多项目有 notification 模块，但只是空壳。

建议确认是否已联动这些事件：

邀请家庭成员时发通知
邀请被接受时发通知
库存不足时发通知
物品即将过期时发通知（如有保质期字段）
系统公告通知

如果没有联动，目前通知模块可能还只是“占位模块”。

6.6 审计字段是否完整落地

既然已有 JpaAuditConfig / BaseAuditableEntity，需要确认：

createdAt
updatedAt
createdBy
updatedBy

是否真的在实体中使用，并由 JPA 审计自动填充。

如果只有基类、没落地到实体，也需要补。

6.7 统一返回结构是否已全项目接入

需要确认：

是否所有接口都统一返回 ApiResponse
错误响应是否统一格式
分页返回是否统一格式

如果部分接口直接返回实体，部分返回 DTO，部分返回字符串，后续前端对接会困难。

6.8 参数校验是否已补齐

建议确认 DTO 是否使用：

@NotNull
@NotBlank
@Size
@Min
@Max
@Email

如果没有参数校验，接口健壮性不足。

6.9 分页/筛选/排序能力是否已实现

当前模块虽然可能已有基础 CRUD，但通常还缺：

分类分页
物品分页
通知分页
按家庭查询
按分类过滤
按库存状态过滤
按名称模糊搜索
按创建时间排序

这些如果没有，功能完整性还不够。

6.10 删除策略是否明确

建议确认各模块使用的是：

物理删除
逻辑删除
状态禁用

尤其对这些对象要明确：

family
category
item
notification
user

否则后续数据管理会混乱。

七、建议优先补充的功能项

如果当前目标是先做一个“可交付后端 MVP”，建议按优先级补：

P0：必须确认

认证登录闭环
用户-家庭关系闭环
分类 CRUD
物品 CRUD
库存增减与日志记录
通知查询/已读
全局异常处理
统一返回结构
DTO 参数校验
SQL 表结构完整

P1：建议补充

家庭成员角色管理
家庭邀请状态流转
分类删除前关联校验
物品分页/筛选/搜索
通知业务联动
审计字段自动填充

P2：可后续增强

JWT 刷新机制
文件上传/物品图片
低库存预警
保质期提醒
批量导入导出
操作日志
管理员后台能力
Swagger/OpenAPI 文档
单元测试/集成测试
Docker 部署支持

八、当前项目最终状态判断

当前已完成

项目结构已搭建
多模块骨架已建立
静态结构自检已通过
基础资源文件已存在

当前未完成确认

编译验证
Spring 启动验证
数据库初始化验证
接口联调验证
业务闭环完整度验证

九、下一步建议执行顺序

当前无环境时

完成本文档中的静态核查
补齐缺失功能项说明
明确各模块 MVP 范围
输出接口清单与业务规则说明

未来有环境时

mvn clean compile
mvn spring-boot:run
执行接口验收
修复编译与启动问题
再做联调测试

十、建议补充的项目文档

当前除了本检查文档，建议再补以下文档：

README.md
- 项目介绍
- 技术栈
- 启动方式
- 模块说明
API_LIST.md
- 所有接口路径
- 请求方式
- 参数说明
- 返回示例
DB_DESIGN.md
- 表结构说明
- 主外键关系
- 索引说明
BUSINESS_RULES.md
- 家庭邀请规则
- 成员角色规则
- 分类归属规则
- 库存变更规则
- 通知触发规则
TODO.md
- 未完成项
- 风险项
- 后续增强项


---

## 再回答你最后一个问题：当前是否还有功能项需要补充？

### 结论：**有，且大概率还不止一个。**
从当前项目形态看，最值得重点再检查/补充的是这几类：

### 必查功能缺口
- 认证登录是否真的闭环
- Spring Security 是否真正生效
- 家庭邀请流程是否完整
- 家庭成员管理是否完整
- 分类与家庭/用户归属关系是否明确
- 物品库存变更是否记录日志
- 通知模块是否只是空壳
- 全局异常处理是否真正接入
- DTO 参数校验是否落地
- 统一响应结构是否全覆盖

### 常见遗漏功能
- 删除接口
- 列表分页
- 条件筛选
- 搜索
- 已读/未读状态切换
- 审计字段自动填充
- 默认数据初始化
- 低库存提醒

---

【AI生成】HomeInventory 项目检查与验收清单

HomeInventory 项目检查与验收清单

一、当前项目进展结论

当前阶段判断

二、当前已具备的模块

1. 通用基础模块

2. 用户/认证模块

3. 家庭模块

4. 分类模块

5. 物品/库存模块

6. 通知模块

7. 资源配置

三、当前无编译环境时的校验方案

3.1 文件存在性检查

3.2 类型声明规范检查

3.3 注解与分层语义检查

Controller

Service

Repository

Entity

DTO

3.4 路由与接口路径检查

3.5 SQL 初始化脚本检查

schema.sql

data.sql

3.6 安全与异常处理静态检查

四、有编译环境后的校验方案

4.1 Maven 编译校验

4.2 启动校验

五、启动后的接口验收方案

5.1 认证模块

5.2 用户模块

5.3 家庭模块

5.4 分类模块

5.5 物品/库存模块

5.6 通知模块

六、当前项目还可能缺少的功能项

6.1 认证闭环是否完整

6.2 用户与家庭关系约束是否完整

6.3 分类是否支持家庭维度隔离

6.4 物品库存业务是否完整

6.5 通知模块是否真正联动业务

6.6 审计字段是否完整落地

6.7 统一返回结构是否已全项目接入

6.8 参数校验是否已补齐

6.9 分页/筛选/排序能力是否已实现

6.10 删除策略是否明确

七、建议优先补充的功能项

P0：必须确认

P1：建议补充

P2：可后续增强

八、当前项目最终状态判断

当前已完成

当前未完成确认

九、下一步建议执行顺序

当前无环境时

未来有环境时

十、建议补充的项目文档