|
|
@@ -0,0 +1,159 @@
|
|
|
+# 统一任务系统设计
|
|
|
+
|
|
|
+**优先级:** P0
|
|
|
+**预计工时:** 后端 5d + 前端 3d + 迁移 1d
|
|
|
+**状态:** 设计已确认（待写实现计划）
|
|
|
+**日期:** 2026-09-04
|
|
|
+
|
|
|
+## 1. 背景与问题
|
|
|
+
|
|
|
+当前系统存在**多套并行任务体系**，各自独立演进，数据模型、接口、页面完全割裂：
|
|
|
+
|
|
|
+| 体系 | 表 | 用途 | 问题 |
|
|
|
+|------|-----|------|------|
|
|
|
+| 家庭任务 | `tasks` | 创建/下发/接受/审核/完成 | 核心，字段膨胀（40+） |
|
|
|
+| 成长任务 | `growth_task` + `growth_task_log` | DAILY/NEWBIE/AI 三类，进度+领取 | 独立模型，与 tasks 割裂 |
|
|
|
+| 新人引导 | `onboarding_task` | 新用户系统派发 | 独立表 |
|
|
|
+| 训练方案 | `task_plan_instances` + `task_plan_items` + `training_plan_tasks` | 方案实例化 | 与模板套餐重复 |
|
|
|
+| 任务模板 | `task_templates`（旧）+ `admin_task_templates` + `task_template_packages` | 快速创建 | 双轨并存，命名混乱 |
|
|
|
+
|
|
|
+**核心矛盾**：用户需在多个任务入口（`tasks.vue` 家庭任务、`daily-tasks.vue` 成长任务、`child/tasks.vue` 孩子任务）间跳转，体验割裂；后端多套模型维护成本高。
|
|
|
+
|
|
|
+**目标**：将任务系统合并为**一套**，`tasks` 表作为唯一执行态表，用 `source_type` 区分来源；任务模板作为快速创建任务的配置；训练方案和新人引导也是任务来源。
|
|
|
+
|
|
|
+## 2. 范围决策（已与用户确认）
|
|
|
+
|
|
|
+| 决策项 | 结论 |
|
|
|
+|--------|------|
|
|
|
+| 合并深度 | **单表统一**：所有执行态任务落到 `tasks` 表 |
|
|
|
+| 奖励机制 | **自动发放**：完成/进度达标即自动加分，删除 `claimed` 概念 |
|
|
|
+| 进度型任务 | `deadline` 改可空 + 新增 `is_daily_progress` 标志 |
|
|
|
+| 进度存储 | 复用 `task_executions` 表（`extra JSON` 存进度），`tasks` 加 `target_value` |
|
|
|
+| 新人引导 | 复用任务模板表（`admin_task_templates` + `onboarding_sequence`），执行实例落 `tasks` |
|
|
|
+| 训练方案 | 方案定义复用 `task_template_packages`，实例保留 `task_plan_instances`，执行落 `tasks` |
|
|
|
+| 家庭挑战 | **本次不合并**（多人协作语义独立，后续单独评估） |
|
|
|
+| 五维打卡 | **本次不合并**（数据记录型，与行为型任务本质不同，聚合展示即可） |
|
|
|
+| 每日重置 | 复用 `RepeatTaskGenerator`，DAILY 每天生成新实例 |
|
|
|
+| 模板层 | 两层归一：`admin_task_templates`（单任务模板）+ `task_template_packages`（打包方案），废弃旧 `task_templates` |
|
|
|
+| 前端 | 统一任务中心 `tasks.vue`，废弃 `daily-tasks.vue` |
|
|
|
+| 迁移 | 一次性迁移 + 旧表软废弃（保留只读备份） |
|
|
|
+
|
|
|
+## 3. 任务来源枚举
|
|
|
+
|
|
|
+`tasks.source_type` 最终枚举：
|
|
|
+
|
|
|
+| source_type | 含义 | 生成方式 | source_id |
|
|
|
+|-------------|------|---------|-----------|
|
|
|
+| `self` | 用户创建给自己 | 手动 | — |
|
|
|
+| `assigned` | 他人分配（家庭/规划师） | 手动（创建者角色由 creator_id + role 判断） | — |
|
|
|
+| `plan` | 方案实例化 | `task_plan_instances` 激活后生成 | plan_instance_id |
|
|
|
+| `onboarding` | 新人引导 | 系统自动，按 `onboarding_sequence` 批量生成 + 前置链 | — |
|
|
|
+| `ai` | AI 对话生成 | AIChatService → createTask(source_type=ai) | conversation_id |
|
|
|
+| `template` | 模板快速创建 | 从 `admin_task_templates` 实例化 | template_id |
|
|
|
+| `article` | 文章阅读联动 | 已有逻辑 | article_id |
|
|
|
+| `activity` | 活动签到联动 | 已有逻辑 | activity_id |
|
|
|
+| `purchase` | 购买/消费联动 | parent_task_id 链 | — |
|
|
|
+
|
|
|
+> **说明**：原 `family`（家庭任务）与 `teacher`（规划师任务）合并为 `assigned`，创建者角色通过 `creator_id` 关联 user 的 role 判断，避免枚举冗余。
|
|
|
+
|
|
|
+## 4. 数据模型设计
|
|
|
+
|
|
|
+### 4.1 `tasks` 表（唯一执行态表）
|
|
|
+
|
|
|
+**新增/调整字段：**
|
|
|
+
|
|
|
+| 字段 | 类型 | 变更 | 说明 |
|
|
|
+|------|------|------|------|
|
|
|
+| `source_type` | varchar(32) | 扩展枚举 | 见第 3 节 |
|
|
|
+| `deadline` | datetime | **改为可空** | 进度型任务为 NULL |
|
|
|
+| `is_daily_progress` | tinyint | 新增 | 1=每日进度型（无 deadline，每日重置） |
|
|
|
+| `target_value` | int | 新增 | 进度目标值（原 growth_task.target_value） |
|
|
|
+| `source_id` | bigint | 复用 | plan_instance_id / template_id / article_id 等来源 ID |
|
|
|
+
|
|
|
+**保留字段**：`prerequisite_task_id`（前置任务，onboarding 顺序链复用）、`parent_task_id`（购买任务→子任务链）、`action_type`/`action_config`（联动动作）、`dimension_code`/`dimension_weights`（五维）、`member_only`（会员任务）、`repeat_type`（重复类型）、`bonus_rule`/`points_expire_days`（积分规则）等。
|
|
|
+
|
|
|
+### 4.2 `task_executions` 表（进度存储）
|
|
|
+
|
|
|
+复用现有表，`extra JSON` 字段存进度数据（如 `{"progress": 15, "target": 30}`）。`tasks` 表只存 `target_value` 目标值，当前进度存 `task_executions`。
|
|
|
+
|
|
|
+### 4.3 配置表（保留）
|
|
|
+
|
|
|
+| 表 | 用途 | 变更 |
|
|
|
+|----|------|------|
|
|
|
+| `admin_task_templates` | 单任务模板（快速创建） | + `onboarding_sequence` 字段 |
|
|
|
+| `task_template_packages` + `task_template_items` | 打包方案模板（可售卖） | 保留 |
|
|
|
+| `task_plan_instances` | 方案实例（生命周期：激活/审核/确认） | 保留，执行落 tasks |
|
|
|
+
|
|
|
+### 4.4 废弃表（软废弃，保留只读备份）
|
|
|
+
|
|
|
+**`growth_task` 三种类型的迁移去向（按 type 区分）：**
|
|
|
+
|
|
|
+| growth_task.type | 迁移去向 |
|
|
|
+|-----------------|---------|
|
|
|
+| `DAILY`（每日进度） | 定义 → `admin_task_templates`（is_daily_progress=1 标记）；每日实例落 `tasks`（source_type=template） |
|
|
|
+| `NEWBIE`（新人） | 定义 → `admin_task_templates`（`onboarding_sequence` 排序）；实例落 `tasks`（source_type=onboarding） |
|
|
|
+| `AI_GENERATED` | 实例落 `tasks`（source_type=ai，source_id=conversation_id） |
|
|
|
+
|
|
|
+> **消除重复**：`growth_task` 的 NEWBIE 类型与 `onboarding_task` 表都是"新人任务"，本次统一为 `admin_task_templates` + `onboarding_sequence` + `source_type=onboarding`，两个来源合并。
|
|
|
+
|
|
|
+**废弃表总清单：**
|
|
|
+
|
|
|
+| 表 | 迁移去向 |
|
|
|
+|----|---------|
|
|
|
+| `growth_task` | 定义 → `admin_task_templates`（按 type 区分，见上）；实例 → `tasks` |
|
|
|
+| `growth_task_log` | → `task_executions`（进度/完成记录） |
|
|
|
+| `onboarding_task` | → `tasks`（source_type=onboarding） |
|
|
|
+| `task_plan_items` | → `task_template_items`（字段重合） |
|
|
|
+| `training_plan_tasks` | → `tasks`（source_id=plan_instance_id 关联） |
|
|
|
+| `task_templates`（旧） | → `admin_task_templates` |
|
|
|
+
|
|
|
+## 5. 奖励机制
|
|
|
+
|
|
|
+- **统一自动发放**：任务完成/进度达标即自动加分，删除 `claimed` 概念。
|
|
|
+- `PointsService` + `EnergyService` 统一发放。
|
|
|
+- 前端改为"完成 → 通知已加分"，进度条展示保留（进度型任务）。
|
|
|
+
|
|
|
+## 6. 每日重置机制
|
|
|
+
|
|
|
+- 复用 `RepeatTaskGenerator`：DAILY 成长任务每天凌晨生成新实例（`is_daily_progress=1`）。
|
|
|
+- 历史记录天然保留（每天一条实例），与现有家庭重复任务机制一致。
|
|
|
+
|
|
|
+## 7. 前端设计
|
|
|
+
|
|
|
+### 7.1 统一任务中心 `tasks.vue`
|
|
|
+
|
|
|
+- Tab：待完成 / 今日 / 我创建的 / 待审核
|
|
|
+- 进度型任务在"今日任务"Tab 展示进度条
|
|
|
+- 废弃 `daily-tasks.vue`，其进度展示能力并入 `tasks.vue`
|
|
|
+
|
|
|
+### 7.2 保留页面
|
|
|
+
|
|
|
+- `child/tasks.vue`（孩子视角）保留，数据源统一到 tasks 接口
|
|
|
+- `tasks/review.vue`（审核）、`tasks/create-task.vue`（创建）保留
|
|
|
+
|
|
|
+## 8. 迁移策略
|
|
|
+
|
|
|
+- **一次性迁移脚本**：把 `growth_task`/`growth_task_log`/`onboarding_task`/`task_plan_items`/`training_plan_tasks`/`task_templates` 数据搬到 `tasks` 表（含 source_type 标记）。
|
|
|
+- **旧表软废弃**：保留只读备份，跑通后再物理删除。
|
|
|
+- 迁移入口：`DatabaseInitializer.runMigrations()`。
|
|
|
+
|
|
|
+## 9. 范围边界（明确不做）
|
|
|
+
|
|
|
+| 不做 | 原因 |
|
|
|
+|------|------|
|
|
|
+| 家庭挑战合并 | 多人协作语义独立，后续单独评估 |
|
|
|
+| 五维打卡合并 | 数据记录型，与行为型任务本质不同 |
|
|
|
+| 旧表物理删除 | 保留只读备份，跑通后再删 |
|
|
|
+| 前端一次性全量重构 | 统一任务中心优先，其余页面渐进改造 |
|
|
|
+
|
|
|
+## 10. 验收标准
|
|
|
+
|
|
|
+- [ ] `tasks` 表新增 `source_type`/`is_daily_progress`/`target_value` 字段，`deadline` 可空
|
|
|
+- [ ] 所有任务来源（self/assigned/plan/onboarding/ai/template/article/activity/purchase）能落到 `tasks` 表
|
|
|
+- [ ] 完成任务自动发放积分+能量，无 `claimed` 概念
|
|
|
+- [ ] DAILY 成长任务每天凌晨生成新实例，历史保留
|
|
|
+- [ ] 新人引导按 `onboarding_sequence` 批量生成 + 前置链解锁
|
|
|
+- [ ] 方案实例化任务落 `tasks` 表（source_id=plan_instance_id）
|
|
|
+- [ ] 迁移脚本把旧表数据搬到 `tasks` 表，旧表软废弃
|
|
|
+- [ ] 前端统一任务中心 `tasks.vue` 展示所有来源任务，`daily-tasks.vue` 废弃
|
|
|
+- [ ] 通过 `mvn clean compile` 编译验证
|
E2E Test Bot