mellowfox/tidyquest

🏠 TidyQuest

将家务转变为史诗般的家庭冒险

TidyQuest 是一款自托管Web应用，通过RPG机制将家务游戏化。完成任务、赚取金币、解锁成就，并与家人在排行榜上竞争。

!https://img.shields.io/badge/version-0.6.0-blue.svg !https://img.shields.io/badge/docker-ready-brightgreen.svg !https://img.shields.io/badge/license-AGPL--3.0-blue.svg https://img.shields.io/badge/***-%E5%8A%A0%E5%85%A5%E6%88%91%E4%BB%AC-5865F2?logo=***&logoColor=white]([***]

---

[!WARNING] 早期阶段项目 — TidyQuest 正在积极开发中。您可能会遇到错误、功能不完整或版本间的破坏性变更。请定期备份数据，如有问题可随时https://github.com/mellow-fox/TidyQuest/issues%E3%80%82

---

✨ 什么是 TidyQuest？

TidyQuest 将枯燥的家务变成冒险任务：

• 🎯 健康条：每个任务都有随时间衰减的视觉健康指示器
• 💰 金币与奖励：完成任务赚取金币，兑换家庭奖励
• 🔥 连续 streak：建立每日/每周连续完成记录以保持动力
• 🏆 排行榜：与家庭成员竞争排名
• 🎖️ 成就系统：解锁里程碑徽章（完成100个任务、30天连续 streak 等）
• 📅 日历视图：一目了然地查看即将到期的任务
• 🌍 多语言支持：英语、法语、德语、西班牙语、意大利语
• 📱 通知功能：通过 *** 或 ntfy 发送可选提醒

完美适用于以下家庭：

• 希望让孩子觉得家务有趣
• 跟踪家庭责任
• 通过游戏化鼓励团队合作
• 建立持续的清洁习惯

---

📸 截图

点击查看截图

仪表盘

!仪表盘 显示任务概览、连续 streak 和快速统计的主仪表盘

房间与任务

!房间 带有任务健康条和完成跟踪的房间视图

排行榜

!排行榜 家庭竞争周/月排名

奖励

!奖励 奖励目录和兑换系统

成就

!成就 完成里程碑解锁徽章

---

🚀 快速开始

先决条件

• Docker 与 Docker Compose
• 100MB 磁盘空间
• 可用端口 3020

安装

选择部署方式：

选项 A：Unraid 社区应用（最简单）

如果您运行 Unraid，TidyQuest 可直接从 Community Applications 目录获取：

1. 在 Unraid 仪表板中打开 Community Applications
2. 搜索 TidyQuest
3. 点击 安装 并填写您的 JWT_SECRET
4. 完成！

选项 B：Docker Compose — Docker Hub 镜像（推荐）

在任何 Linux 服务器上使用预构建的多平台镜像快速启动：

1. 创建项目目录

   bash
   mkdir tidyquest && cd tidyquest
   

2. 创建 docker-compose.yml

   yaml
   services:
     tidyquest:
       image: mellowfox/tidyquest:latest
       container_name: tidyquest
       ports:
         - "3020:3000"
       environment:
         - NODE_ENV=production
         - JWT_SECRET=将此替换为至少32字符的安全随机字符串
         - TZ=Europe/Paris  # 您的时区 — 用于日/周边界和通知
       volumes:
         - ./data:/app/data
       restart: unless-stopped
   

3. 生成安全的 JWT_SECRET

   bash
   openssl rand -base64 32
   # 复制输出并替换 docker-compose.yml 中的 JWT_SECRET
   

4. 启动

   bash
   docker compose up -d
   

   通过 http://localhost:3020 访问

选项 C：从源码构建

用于开发或自定义：

1. 克隆仓库

   bash
   git clone https://github.com/mellow-fox/TidyQuest.git
   cd TidyQuest
   

2. 配置环境

   bash
   cp .env.example .env
   # 编辑 .env 并设置安全的 JWT_SECRET
   # 生成方法：openssl rand -base64 32
   

3. 构建并启动

   bash
   docker compose up -d --build
   

   通过 http://localhost:3020 访问

首次登录

首次启动时数据库为空，通过 注册 页面创建管理员账户。

---

🎮 功能

面向所有用户

• ✅ 完成任务：标记家务为已完成，赚取金币
• 💎 兑换奖励：请求奖励，如"电影之夜选择权"或"额外游戏时间"
• 📊 跟踪进度：查看当前连续 streak、金币和成就
• 🏠 房间管理：按房间组织任务（厨房、卧室、浴室等）

面向管理员

• 👥 用户管理：创建家庭成员（管理员/成员/儿童角色）
• 📝 任务管理：创建、编辑、删除任务，自定义频率（1-365天）
• 🎁 奖励系统：批准/拒绝奖励请求，管理和自定义奖励目录
• ⚙️ 全局设置：配置按任务难度的金币数、通知（*** 或 ntfy）
• 🏖️ 假期模式：全局或按成员暂停任务健康衰减，可设置个人返回日期
• 📤 备份/恢复：将完整数据库导出为 JSON
• 👤 任务分配：将任务分配给特定用户，支持三种模式：
  • 抢先 — 第一个完成的用户获得所有金币
  • 共享 — 每个被分配者完成一次；金币平均分配
  • 自定义 — 为每个被分配者定义自定义金币百分比（如70%/30%）
• ✅ 严格模式：任务完成需管理员批准后才计入
• 💑 情侣模式：禁用游戏化元素（金币、streak、排行榜），用于简单跟踪
• 🔑 密码恢复：通过环境变量重置管理员密码

内置默认内容

• 8种房间类型：厨房、卧室、浴室、客厅、办公室、车库、洗衣房、花园
• 60+ 预设任务：常见家务，具有合理频率
• 10种预设奖励：电影之夜、冰淇淋、晚睡、游戏时间等
• 12项成就：基于活动自动解锁
• 5种语言：英语、法语、德语、西班牙语、意大利语

---

🛠️ 技术栈

核心功能零外部依赖。可选 *** 或 ntfy 集成用于通知。

---

📂 项目结构

TidyQuest/
├── client/           # React 前端
│   ├── src/
│   │   ├── components/  # UI 组件
│   │   ├── hooks/       # useAuth, useApi, useTranslation
│   │   ├── i18n/        # 翻译文件（EN/FR/DE/ES/IT）
│   │   └── App.tsx
│   └── package.json
├── server/           # Express 后端
│   ├── src/
│   │   ├── routes/      # API 端点
│   │   ├── middleware/  # JWT 认证
│   │   ├── utils/       # 健康计算、通知
│   │   └── database.ts  # SQLite 设置
│   └── package.json
├── data/             # 持久化存储（Docker 卷）
│   ├── tidyquest.db     # SQLite 数据库
│   └── avatars/         # 用户上传照片
├── Dockerfile        # 多阶段构建
├── docker-compose.yml
├── .env.example      # 配置模板
├── SECURITY.md       # 安全最佳实践
└── API.md            # API 文档

---

🔧 配置

环境变量

参见 .env.example 获取所有选项。关键变量：

通知（可选）

TidyQuest 支持两种通知提供商（仅管理员可在设置中配置）：

---

1. 通过 @BotFather 创建 *** 机器人
2. 通过 @userinfobot 获取您的聊天 ID
3. 在设置中输入机器人令牌和聊天 ID

ntfy

1. 使用 ntfy.sh 或您自己的 ntfy 服务器
2. 在设置中输入服务器 URL 和主题
3. 在手机上订阅该主题

通知类型：

• 🕐 每日到期任务：在配置时间发送（默认 09:00）
• 🎁 奖励请求：当儿童请求奖励时通知管理员
• 🎖️ 成就解锁：庆祝成就解锁

---

📖 使用方法

创建房间

1. 进入 房间 页面
2. 点击 添加房间
3. 选择房间类型（如厨房）
4. 从 60+ 默认任务中选择或创建自定义任务

完成任务

1. 打开房间
2. 点击任务行上的 ✅
3. 赚取金币（根据难度等级1-5，获得5-25金币）
4. 健康条重置为100%

兑换奖励

1. 进入 奖励 页面
2. 点击奖励上的 兑换（立即扣除金币）
3. 管理员批准/拒绝请求
4. 若被拒绝，金币将退还

假期模式

管理员可在 设置 中启用假期模式：

• 全局：暂停整个家庭的任务健康衰减
• 按成员：单独切换假期模式，可设置不同返回日期

假期期间冻结任务健康并保护连续 streak。

管理员密码恢复

如果管理员忘记密码：

1. 向容器添加环境变量：

   yaml
   environment:
     - ADMIN_RESET_PASSWORD=您的新密码
   

2. 重启容器 — 第一个管理员的密码将被重置
3. 立即移除该变量 并再次重启

---

🔒 安全

公开暴露前，请查看 SECURITY.md 中的建议：

• 设置强 JWT_SECRET
• 使用 HTTPS 反向代理（Caddy/Nginx）
• 数据库备份策略
• *** 令牌保护

⚠️ 切勿通过 HTTP 将 TidyQuest 直接暴露到互联网。

---

🔄 更新

使用 Docker Hub 镜像

bash
docker compose pull
docker compose up -d

使用源码构建

bash
cd TidyQuest
git pull
docker compose down
docker compose up -d --build

您的数据在 ./data 卷中持久化。

---

🗄️ 备份与恢复

手动备份（通过 UI）

管理员 → 设置 → 导出数据 → 下载 JSON

文件系统备份

bash
cp data/tidyquest.db backups/tidyquest-$(date +%Y%m%d).db

恢复

管理员 → 设置 → 导入数据 → 上传 JSON

---

🌐 API 文档

参见 API.md 获取完整端点文档及示例。

快速概览：

• 认证：/api/auth/register，/api/auth/login
• 房间：/api/rooms（CRUD）
• 任务：/api/rooms/:id/tasks（CRUD + 完成）
• 仪表盘：/api/dashboard（聚合视图）
• 排行榜：/api/leaderboard?period=week|month|quarter|year
• 奖励：/api/rewards（CRUD + 兑换）
• 成就：/api/achievements

所有端点需要 Authorization: Bearer <token>（认证路由除外）。

---

🏠 Home Assistant 集成

TidyQuest 包含自定义 Home Assistant 集成，将任务公开为传感器，并允许从仪表板和自动化中完成或管理任务。

安装

1. 将 custom_components/tidyquest/ 复制到 Home Assistant 的 config/custom_components/ 目录
2. 重启 Home Assistant
3. 进入 设置 → 设备与服务 → 添加集成 并搜索 TidyQuest
4. 输入 TidyQuest URL 和凭据（管理员或成员账户）

实体

每个任务成为 sensor，其状态为任务当前健康值（0–100）。属性包括 room_name、effort、is_due、assigned_users、assignment_mode 等。

服务

示例 — 从仪表板按钮完成任务

yaml
service: tidyquest.complete_task
target:
  entity_id: sensor.kitchen_wash_dishes_health

示例 — 任务逾期时的自动化

yaml
automation:
  trigger:
    platform: numeric_state
    entity_id: sensor.kitchen_wash_dishes_health
    below: 20
  action:
    service: notify.mobile_app
    data:
      message: "该洗碗了！"

用户匹配：HA 用户名自动匹配 TidyQuest displayName（不区分大小写）。可在服务数据中用 user_name 或 tidyquest_user_id 覆盖。

参见 custom_components/tidyquest/README.md 获取完整文档。

---

🤝 贡献

欢迎贡献！请：

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开 Pull Request

---

📜 许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

含义：

• ✅ 您可以自由使用、修改和分发 TidyQuest
• ✅ 您可以商业运行（用于您的企业/家庭）
• ⚠️ 如果您修改并托管 TidyQuest 作为服务（即使是私有），您必须共享源代码
• ⚠️ 任何衍生作品也必须采用 AGPL-3.0 许可证

选择 AGPL 的原因：确保 TidyQuest 永远保持自由开源，防止专有 SaaS 分支。

参见 LICENSE 文件获取完整详情。

---

🙏 致谢

• 灵感来自经典游戏的 RPG 机制
• 为爱做家务变得有趣的家庭而构建
• 使用 https://fonts.google.com/specimen/Nunito 字体（本地捆绑）

---

📞 支持

• 🐛 错误报告：https://github.com/mellow-fox/TidyQuest/issues
• 💬 讨论：[GitHub Discussions](