# StarTask

**Repository Path**: ppshux/star-task

## Basic Information

- **Project Name**: StarTask
- **Description**: 家庭劳动组织小程序（Web网页版）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-11
- **Last Updated**: 2026-01-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ⭐ 星星任务 - 家庭任务管理系统

一个简单的家庭内部"做任务赚星星"系统，帮助家长管理孩子的日常任务。

## 功能特点

### 用户角色
- **家长（Admin）**：创建任务、审核任务、管理奖励、查看用户信息
- **孩子（User）**：领取任务、完成任务、查看星星余额、兑换奖励

### 核心功能
1. **任务管理**：
   - 家长可以创建任务，设置星星奖励
   - 支持任务刷新功能，让已完成的任务可以重新被领取
   - 任务启用/停用控制
2. **任务领取**：
   - 孩子可以领取感兴趣的任务
   - 已领取的任务显示灰色"已领取"标签
   - 每个孩子对同一任务只能领取一次（除非家长刷新任务）
3. **任务提交**：完成任务后提交审核，支持填写备注
4. **任务审核**：
   - 家长审核通过后，孩子获得星星奖励
   - 支持驳回并填写驳回原因
5. **我的任务**：
   - 三个标签分类展示：进行中/已完成/已驳回
   - 根据状态显示不同时间标签（领取时间/提交时间/完成时间/驳回时间）
   - 已驳回的任务可以删除
6. **星星流水**：
   - 记录所有星星变动历史（任务通过、奖励兑换）
   - 相对时间显示（刚刚/X分钟前/X小时前）
   - 家长可查看所有孩子的流水记录
7. **奖励商店**：
   - 孩子可以用星星兑换奖励
   - 支持库存限制，库存为0时不可兑换
   - 家长可以管理库存（编辑库存数量）
8. **兑换记录**：记录所有兑换历史
9. **多家庭支持**：支持多个家庭，数据完全隔离

## 技术栈

### 后端
- Django 4.2.7
- Django REST Framework 3.14.0
- djangorestframework-simplejwt 5.3.0（JWT 认证）
- django-cors-headers 4.3.1（CORS 支持）
- Gunicorn（生产环境WSGI服务器）
- SQLite（数据库，生产环境建议使用PostgreSQL）

### 前端
- Vue 3.2.13
- Vue CLI 5.0.0（构建工具）
- Vue Router 4.0.3
- Pinia 2.1.7（状态管理）
- Axios 1.6.0（HTTP 请求）

## 快速开始

### 后端启动

1. **进入后端目录**
```bash
cd backend
```

2. **安装依赖**
```bash
pip install -r requirements.txt
```

3. **执行数据库迁移**
```bash
python manage.py makemigrations
python manage.py migrate
```

4. **初始化数据（创建示例任务和奖励）**
```bash
python manage.py init_data
```
**注意**：此命令只会创建默认家庭、示例任务和奖励，不会创建用户。请在Django Admin中创建用户。

5. **创建超级用户（用于访问Django Admin）**
```bash
python manage.py createsuperuser
```

6. **启动后端服务**
```bash
python manage.py runserver
```

后端将运行在 `http://localhost:8000`

### 前端启动

1. **进入前端目录**
```bash
cd web/star_task
```

2. **安装依赖**
```bash
npm install
```

3. **启动开发服务器**
```bash
npm run serve
```

前端将运行在 `http://localhost:8080`（或其他可用端口）

## 用户管理

### 创建用户

系统不会自动创建测试账号。请按以下步骤创建用户：

1. **访问Django Admin**
   - 本地开发：`http://localhost:8000/admin/`
   - 生产环境：`https://app7581.acapp.acwing.com.cn/admin/`
   - 使用超级用户账号登录

2. **创建用户**
   - 在"认证和授权" -> "用户"中点击"增加用户"
   - 填写用户名和密码，保存

3. **创建家庭成员关系（Membership）**
   - 在"核心" -> "成员关系"中点击"增加成员关系"
   - 选择用户、家庭和角色（admin=家长，kid=孩子）
   - 保存

4. **创建用户资料（UserProfile）**
   - 在"核心" -> "用户资料"中点击"增加用户资料"
   - 选择用户和家庭，设置初始星星余额（默认为0）
   - 保存

**提示**：创建用户后，即可使用该用户名和密码在前端登录。

## 使用说明

### 系统概述

星星任务系统是一个家庭任务管理工具，通过"做任务赚星星"的激励机制，帮助家长管理孩子的日常任务。系统采用前后端分离架构，支持多家庭、多用户，数据完全隔离。

### 核心概念

- **任务（Task）**：家长创建的任务，每个任务都有对应的星星奖励
- **领取（Claim）**：孩子领取任务后生成的记录，状态包括：已领取 → 已提交 → 已通过/已驳回
- **星星余额（Stars Balance）**：孩子完成任务获得的星星总数，可用于兑换奖励
- **奖励（Reward）**：可用星星兑换的物品或特权，每个奖励都有价格和库存
- **家庭（Household）**：数据隔离的单位，每个家庭的数据完全独立

### 家长端使用指南

#### 1. 登录与导航

- 使用在Django Admin中创建的家长账号登录
- 登录后自动进入"任务管理"页面
- 顶部导航栏包含：任务管理、待审核、奖励管理、用户管理

#### 2. 任务管理

**创建任务**：
- 点击"创建新任务"按钮
- 填写任务信息：
  - **任务名称**：简洁明了的任务描述（如"洗碗"、"倒垃圾"）
  - **星星数**：完成该任务可获得的星星数量（建议范围：3-20星）
  - **完成标准**：详细说明任务要求（可选，但建议填写，便于孩子理解）
  - **是否启用**：启用后孩子才能看到并领取该任务
  - **是否可重复**：可重复任务可以被多次领取（如每日任务），不可重复任务只能领取一次
- 点击"保存"创建任务

**管理任务**：
- 在任务列表中查看所有已创建的任务
- 可以编辑任务信息（点击任务卡片）
- 可以启用/停用任务（停用后孩子无法看到）
- 可以删除任务（删除后相关记录保留）

**使用技巧**：
- 建议为不同类型的任务设置不同的星星数（简单任务3-5星，复杂任务10-20星）
- 对于每日重复任务（如"洗碗"），建议设置为"可重复"
- 对于一次性任务（如"整理房间"），建议设置为"不可重复"
- 完成标准要清晰具体，避免模糊表述

#### 3. 任务审核

**查看待审核任务**：
- 进入"待审核"页面
- 查看所有状态为"已提交"的任务
- 每个任务卡片显示：任务名称、提交人、提交时间、备注

**审核操作**：
- **通过审核**：
  - 点击"通过"按钮
  - 系统自动增加孩子的星星余额
  - 任务状态变为"已通过"
  - 生成星星流水记录
- **驳回任务**：
  - 点击"驳回"按钮
  - 必须填写驳回原因（便于孩子了解问题）
  - 任务状态变为"已驳回"
  - 孩子可以重新提交（对于可重复任务）

**使用技巧**：
- 建议及时审核，保持任务的时效性
- 驳回时要填写具体原因，帮助孩子改进
- 对于可重复任务，可以通过后让孩子再次领取

#### 4. 奖励管理

**创建奖励**：
- 进入"奖励管理"页面
- 点击"创建新奖励"按钮
- 填写奖励信息：
  - **奖励名称**：清晰的奖励描述（如"可乐"、"游戏30分钟"）
  - **价格**：兑换所需的星星数
  - **描述**：奖励的详细说明（可选）
  - **库存**：奖励的数量（设置为0时表示已兑完）
  - **是否启用**：启用后孩子才能看到并兑换
- 点击"保存"创建奖励

**管理奖励**：
- 可以编辑奖励信息（如调整价格、库存）
- 可以启用/停用奖励
- 可以删除奖励

**使用技巧**：
- 建议设置不同价位的奖励（20-100星），满足不同需求
- 对于限量奖励，及时更新库存
- 可以根据季节或需要定期更新奖励内容

#### 5. 用户管理

- 进入"用户管理"页面
- 查看所有家庭成员的星星余额
- 可用于快速了解每个孩子的任务完成情况

### 孩子端使用指南

#### 1. 登录与首页

- 使用在Django Admin中创建的孩子账号登录
- 登录后进入首页，显示当前星星余额和可领取的任务列表
- 顶部导航栏包含：首页、我的任务、星星商店、星星流水

#### 2. 任务流程

**查看任务**：
- 在首页浏览所有可领取的任务
- 每个任务卡片显示：任务名称、星星数、完成标准
- 点击"领取任务"按钮领取感兴趣的任务

**完成任务**：
- 进入"我的任务"页面
- 查看所有已领取的任务及其状态
- 完成任务后，点击"提交完成"按钮
- 可选填写备注（说明完成情况）
- 任务状态变为"待审核"

**查看任务状态**：
- **已领取**：已领取但未提交
- **待审核**：已提交，等待家长审核
- **已通过**：审核通过，已获得星星奖励
- **已驳回**：审核未通过，显示驳回原因

#### 3. 星星商店

**浏览奖励**：
- 进入"星星商店"页面
- 查看所有可用奖励及其价格
- 库存为0的奖励显示"已兑完"并禁用兑换按钮

**兑换奖励**：
- 点击"兑换"按钮
- 确认兑换信息
- 系统自动扣除星星并减少库存
- 兑换成功后可以在"我的兑换记录"中查看

**使用技巧**：
- 可以根据星星余额和奖励价格合理规划
- 库存有限的奖励要尽早兑换
- 建议先完成任务积累星星，再兑换奖励

#### 4. 星星流水

- 进入"星星流水"页面
- 查看所有星星变动历史（最近20条）
- 每条记录显示：变动原因、变动数量、时间
- 可以了解星星的来源（任务奖励）和去向（兑换奖励）

### 典型使用场景

#### 场景1：日常家务任务

1. **家长操作**：
   - 创建多个日常任务（洗碗5星、倒垃圾3星、整理房间10星）
   - 设置所有任务为"可重复"（每日任务）
   - 创建奖励（可乐20星、游戏30分钟40星）

2. **孩子操作**：
   - 每天领取感兴趣的任务
   - 完成后提交
   - 家长审核通过后获得星星
   - 积累足够星星后兑换奖励

#### 场景2：一次性大任务

1. **家长操作**：
   - 创建大任务（整理书柜30星）
   - 设置为"不可重复"（一次性任务）

2. **孩子操作**：
   - 领取任务
   - 完成后提交
   - 审核通过后获得大量星星

#### 场景3：激励特殊活动

1. **家长操作**：
   - 创建特殊任务（完成作业50星）
   - 创建高价值奖励（看电影100星、买新玩具200星）

2. **孩子操作**：
   - 完成特殊任务获得大量星星
   - 兑换高价值奖励

### 最佳实践

1. **任务设置**：
   - 任务难度与星星数成正比
   - 清晰明确的完成标准
   - 合理设置可重复性

2. **奖励设计**：
   - 多层次的奖励价格（满足不同需求）
   - 定期更新奖励内容
   - 及时管理库存

3. **审核流程**：
   - 及时审核任务（保持积极性）
   - 驳回时提供具体原因
   - 公平公正的审核标准

4. **激励机制**：
   - 结合短期奖励（小任务）和长期目标（大奖励）
   - 定期查看星星余额，调整任务和奖励
   - 鼓励孩子主动查看任务和奖励

### 注意事项

1. **数据隔离**：每个家庭的数据完全独立，不能跨家庭访问
2. **状态流转**：任务状态必须按顺序流转（已领取 → 已提交 → 已通过/已驳回）
3. **库存管理**：奖励库存为0时无法兑换，需要及时补充
4. **权限控制**：家长只能管理本家庭的任务和奖励，孩子只能查看本家庭的数据
5. **幂等性保护**：系统支持幂等性保护，重复点击不会重复扣星/加星

## API 文档

### 认证接口

#### 登录获取Token
```
POST /api/auth/token/
Body: { "username": "用户名", "password": "密码" }
Response: { "access": "...", "refresh": "..." }
```

#### 刷新Token
```
POST /api/auth/token/refresh/
Body: { "refresh": "..." }
Response: { "access": "..." }
```

#### 获取当前用户信息
```
GET /api/me/
Headers: { "Authorization": "Bearer <access_token>" }
Response: { "username": "...", "role": "...", "stars_balance": 50, "household_id": 1 }
```

### 用户端接口

#### 获取任务列表
```
GET /api/tasks/
Response: [{ "id": 1, "title": "洗碗", "stars": 5, ... }, ...]
```

#### 领取任务
```
POST /api/claims/
Body: { "task_id": 1 }
```

#### 提交任务
```
POST /api/claims/{id}/submit/
Body: { "note": "已完成" }  # note可选
```

#### 获取我的任务列表
```
GET /api/my/claims/
Response: [{ "id": 1, "task": {...}, "status": "submitted", ... }, ...]
```

#### 获取我的星星流水
```
GET /api/my/ledger/
Response: [{ "delta": 5, "reason": "Task approved: 洗碗", "created_at": "..." }, ...]
```

#### 获取奖励列表
```
GET /api/rewards/
Response: [{ "id": 1, "name": "可乐", "cost": 20, "stock": 5, ... }, ...]
```

#### 兑换奖励
```
POST /api/rewards/{id}/redeem/
Headers: { "Idempotency-Key": "<uuid>" }  # 幂等性保护
Response: { "balance": 30, "reward": {...}, "stock": 4 }
```

#### 获取我的兑换记录
```
GET /api/my/redeems/
Response: [{ "id": 1, "reward": {...}, "cost": 20, "created_at": "..." }, ...]
```

### 管理员端接口

#### 获取任务列表
```
GET /api/admin/tasks/
```

#### 创建任务
```
POST /api/admin/tasks/
Body: { "title": "洗碗", "stars": 5, "criteria": "...", "is_active": true, "is_repeatable": true }
```

#### 更新任务
```
PATCH /api/admin/tasks/{id}/
Body: { "title": "新标题", "is_active": false, ... }
```

#### 删除任务
```
DELETE /api/admin/tasks/{id}/
```

#### 获取待审核列表
```
GET /api/admin/claims/submitted/
Response: [{ "id": 1, "user": {...}, "task": {...}, "status": "submitted", ... }, ...]
```

#### 审核通过
```
POST /api/admin/claims/{id}/approve/
Headers: { "Idempotency-Key": "<uuid>" }  # 幂等性保护
Response: { "balance": 55, "claim": {...} }
```

#### 审核驳回
```
POST /api/admin/claims/{id}/reject/
Body: { "reject_reason": "未完成标准" }
```

#### 获取奖励列表
```
GET /api/admin/rewards/
```

#### 创建奖励
```
POST /api/admin/rewards/
Body: { "name": "可乐", "cost": 20, "desc": "一瓶可乐", "stock": 5, "is_active": true }
```

#### 更新奖励
```
PATCH /api/admin/rewards/{id}/
Body: { "name": "新名称", "cost": 25, "stock": 10, ... }
```

#### 删除奖励
```
DELETE /api/admin/rewards/{id}/
```

#### 获取兑换记录
```
GET /api/admin/redeems/
Response: [{ "id": 1, "user": {...}, "reward": {...}, "cost": 20, ... }, ...]
```

#### 获取所有用户（包含星星余额）
```
GET /api/admin/users/
Response: [{ "id": 1, "username": "kid1", "role": "user", "stars_balance": 50, "household_id": 1 }, ...]
```

## 数据库模型

### Household（家庭）
- name: 家庭名称
- created_at: 创建时间

### Membership（成员关系）
- user: 用户（OneToOne，确保一个用户只属于一个家庭）
- household: 家庭
- role: 角色（admin=家长，kid=孩子）
- created_at: 创建时间

### UserProfile（用户资料）
- user: 用户（OneToOne）
- household: 家庭
- stars_balance: 星星余额（>= 0）

### Task（任务）
- household: 家庭
- title: 任务名称
- stars: 星星数（>= 1）
- criteria: 完成标准
- is_active: 是否启用
- is_repeatable: 是否可重复
- created_at: 创建时间

### Claim（任务领取记录）
- task: 关联任务
- user: 关联用户
- status: 状态（claimed/submitted/approved/rejected）
- note: 备注
- reject_reason: 驳回原因
- created_at: 创建时间
- updated_at: 更新时间

### StarLedger（星星流水）
- user: 关联用户
- household: 家庭
- claim: 关联任务记录（可选）
- reward: 关联奖励（可选）
- delta: 星星变动数（正数表示增加，负数表示减少）
- reason: 变动原因
- idempotency_key: 幂等键（防止重复操作）
- created_at: 创建时间

### Reward（奖励）
- household: 家庭
- name: 奖励名称
- cost: 兑换价格（星星数，>= 1）
- desc: 描述
- stock: 库存数量（>= 0）
- is_active: 是否启用
- created_at: 创建时间

### RedeemRecord（兑换记录）
- user: 关联用户
- household: 家庭
- reward: 关联奖励
- cost: 兑换时的价格快照
- remark: 备注
- created_at: 创建时间

## 状态机

任务领取记录的状态流转：

```
claimed（已领取）
    ↓
submitted（已提交）
    ↓
approved（已通过）或 rejected（已驳回）
```

**规则**：
- 不能跳过状态
- 不能重复审核
- 只能审核 submitted 状态的任务

## 幂等性保护

所有涉及星星变动的操作（审核通过、兑换奖励）都支持幂等性保护：

1. **前端**：在请求头中添加 `Idempotency-Key: <uuid>`
2. **后端**：检查 `idempotency_key` 是否已处理，如果已处理则返回之前的结果
3. **并发安全**：使用数据库行锁（`select_for_update()`）和事务（`transaction.atomic()`）确保数据一致性

这样可以防止重复点击或网络重试导致的重复扣星/加星。

## 项目结构

```
startask/
├── backend/                # 后端代码
│   ├── core/              # 核心应用
│   │   ├── models.py      # 数据模型
│   │   ├── serializers.py # 序列化器
│   │   ├── views.py       # 视图
│   │   ├── urls.py        # 路由
│   │   ├── permissions.py # 权限
│   │   ├── admin.py       # Django Admin配置
│   │   ├── utils.py       # 工具函数
│   │   └── management/    # 管理命令
│   │       └── commands/
│   │           └── init_data.py
│   ├── star_task/         # 项目配置
│   │   ├── settings.py    # 设置
│   │   ├── urls.py        # 主路由
│   │   ├── wsgi.py        # WSGI配置
│   │   └── asgi.py        # ASGI配置
│   ├── manage.py          # Django 管理脚本
│   └── requirements.txt   # Python 依赖
│
├── web/star_task/         # 前端代码
│   ├── src/
│   │   ├── api/           # API 接口
│   │   ├── store/         # Pinia 状态管理
│   │   ├── router/        # 路由配置
│   │   ├── utils/         # 工具函数
│   │   ├── components/    # 组件
│   │   ├── views/         # 页面组件
│   │   │   ├── LoginView.vue
│   │   │   ├── kid/       # 孩子端页面
│   │   │   └── admin/     # 家长端页面
│   │   ├── App.vue        # 根组件
│   │   └── main.js        # 入口文件
│   ├── public/            # 静态资源
│   ├── package.json       # npm 依赖
│   └── vue.config.js      # Vue CLI 配置
│
├── nginx.conf.acapp       # Nginx 配置文件（AcApp平台）
├── README.md              # 项目说明（本文件）
├── QUICKSTART.md          # 快速启动指南
├── DEPLOY.md              # 部署指南
└── DEPLOY_ACAPP.md        # AcApp平台部署指南
```

## 注意事项

1. **开发环境**：本项目默认配置为开发环境，生产环境需要额外配置
2. **CORS 设置**：后端已配置允许 `localhost:8080` 的跨域请求（Vue CLI 默认端口）
3. **Token 有效期**：Access Token 有效期 1 天，Refresh Token 有效期 7 天
4. **数据库**：使用 SQLite，生产环境建议使用 PostgreSQL 或 MySQL
5. **用户创建**：系统不会自动创建测试账号，请在Django Admin中创建用户
6. **多家庭隔离**：每个用户只属于一个家庭，所有数据按家庭隔离
7. **中文界面**：Django Admin界面已设置为中文（zh-hans）

## 常见问题

### 1. 后端启动失败
- 检查是否安装了所有依赖：`pip install -r requirements.txt`
- 检查是否执行了数据库迁移：`python manage.py migrate`

### 2. 前端无法连接后端
- 确认后端已启动在 `http://localhost:8000`
- 检查浏览器控制台的 CORS 错误
- 确认 `src/utils/request.js` 中的 `baseURL` 配置正确

### 3. 登录后跳转失败
- 清除浏览器 localStorage
- 检查 Token 是否正确保存
- 查看浏览器控制台错误信息

### 4. 任务审核后星星没有增加
- 检查后端日志是否有错误
- 确认事务是否正确提交
- 刷新页面重新获取用户信息

### 5. 兑换奖励失败
- 检查星星余额是否足够
- 检查奖励库存是否充足
- 检查奖励是否启用（is_active=true）

## 部署

### 生产环境部署

详细部署说明请参考：
- `DEPLOY.md` - 通用部署指南
- `DEPLOY_ACAPP.md` - AcApp平台部署指南

### 快速部署要点

1. **后端**：
   - 使用 Gunicorn 运行：`gunicorn star_task.wsgi:application --bind 127.0.0.1:8000 --workers 3`
   - 设置环境变量：`DEBUG=False`，`SECRET_KEY`，`ALLOWED_HOSTS`
   - 执行 `collectstatic`：`python manage.py collectstatic --noinput`

2. **前端**：
   - 构建生产版本：`npm run build`
   - 将 `dist/` 目录部署到 Nginx 或静态文件服务器

3. **Nginx**：
   - 配置前端静态文件服务（SPA路由支持）
   - 配置后端API代理（`/api/` -> `http://127.0.0.1:8000`）
   - 配置Django Admin代理（`/admin/` -> `http://127.0.0.1:8000`）

## 许可证

本项目仅供学习和参考使用。