家庭物品管理系统 (House Keeper)

家庭物品管理系统是一个用于跟踪、管理和组织家庭物品的应用程序。它允许用户记录物品的位置、类型、提醒事项等信息，帮助用户更好地管理家庭物品。

功能特点

• 用户认证：注册、登录、个人资料管理
• 物品管理：
  • 添加、编辑、删除、查看物品列表
  • 支持图片上传和多类别筛选
  • 按位置筛选功能
  • 支持搜索物品名称和描述
• 位置管理：
  • 创建分层的位置结构
  • 支持图片上传
  • 查看位置下所有物品
  • 卡片式视图展示
• 提醒管理：
  • 设置与物品相关的提醒
  • 支持重复提醒
  • 到期和即将到期提醒显示
  • 提醒计数实时更新
• 统计分析：
  • 物品分类分布
  • 位置物品分布
  • 本周趋势图
  • 热门位置统计
• 全局搜索：
  • 从任何页面快速搜索物品和位置
  • 支持 cmd+f 快捷键
  • 搜索结果浮窗展示
• 夜间模式：支持深色/浅色主题切换
• 个人资料管理：用户信息维护

技术栈

后端

• FastAPI：高性能的Python Web框架
• SQLAlchemy：ORM工具
• PostgreSQL：关系型数据库
• JWT：用户认证
• Alembic：数据库迁移
• pytest：测试框架

前端

• React 18：前端框架
• TypeScript 4.9+：类型系统
• Material-UI 5：UI组件库
• React Router：路由管理
• Axios：HTTP客户端
• Recharts：图表库
• date-fns：日期处理

容器化

• Docker：容器化工具
• Docker Compose：多容器应用管理
• Nginx：前端服务器，处理静态资源和API代理

快速开始

使用Docker（推荐）

项目完全容器化，可以使用Docker Compose轻松启动整个应用：

1. 克隆仓库

   git clone https://github.com/yourusername/house-keeper.git
   cd house-keeper

2. 创建环境变量文件

   cp .env.prod.example .env

3. 启动开发环境

   docker compose up -d

4. 访问应用

   • 前端: http://localhost:3000
   • 后端API: http://localhost:8000/api/v1
   • API文档: http://localhost:8000/docs

本地开发

如果您不想使用Docker，可以在本地设置开发环境。详细步骤请参阅 docs/开发指南.md。

项目结构

项目采用前后端分离的架构，详细的目录结构请参阅 docs/网站目录结构.md。

开发状态

项目当前处于MVP阶段，基础功能已经完成。已实现的功能包括：

• 用户认证系统
• 物品管理（CRUD、图片上传、多类别筛选、位置筛选）
• 位置管理（层级结构、图片上传）
• 提醒管理（重复提醒、到期提醒）
• 统计分析（真实数据展示）
• 全局搜索
• 夜间模式

正在进行的工作：

• 提高测试覆盖率（后端已完成，前端进行中）
• 用户文档编写

详细开发路线图请参阅docs/开发路线图.md。

文档

• 开发指南：详细的开发环境设置、工作流程和最佳实践
• 开发路线图：项目开发计划和未来功能
• 网站目录结构：详细的项目结构说明
• 项目代码架构设计：系统架构和设计决策

许可证

MIT