ftb-project-management/docs/specs/2026-06-11-dev-task-module-design.md

title, date, module, status

title	date	module	status
开发任务模块（DevTask）设计规格	2026-06-11	dev-task	approved

开发任务模块（DevTask）— 设计规格

1. 定位与层级

DevTask 是"执行层"实体，归属于版本下某条需求，代表一个可分配、可追踪工时的开发工作项。

Version（版本）
├── VersionPlan（计划层：调研/产品/UI）← 已有
├── DevTask（执行层：开发任务）← 本文档
│   └── 归属于 Requirement（需求）
│       └── TaskWorklog（工时记录）
└── TestCase / Bug（后续）

归属关系

• DevTask 必须归属于一条需求（requirementId 必填）
• versionId 从需求推导，不冗余存储
• 通过 Requirement → Version 链路追溯到版本和产品

2. 数据模型

2.1 DevTask（开发任务）

interface DevTask {
  id: string;
  taskNo: string;              // 自动生成，DEV-001、DEV-002...

  requirementId: string;       // 所属需求（必填）

  title: string;
  description?: string;

  categoryId: string;          // 任务类型（字典表 TaskCategory）
  assigneeId: string;          // 负责人
  reviewerId?: string;         // 验收人（预留，V1 可选不填）
  priority: 'P0' | 'P1' | 'P2' | 'P3';  // 默认继承需求优先级，允许覆盖

  estimateHours: number;       // 预计工时（小时）
  actualHours: number;         // 实际工时（只读，= Σ TaskWorklog.hours）

  startDate?: string;          // 开始日期 YYYY-MM-DD
  dueDate?: string;            // 截止日期 YYYY-MM-DD
  completedAt?: string;        // 完成日期 YYYY-MM-DD

  status: DevTaskStatus;
  isBlocked: boolean;          // 阻塞标记（正交于 status）
  blockReason?: string;        // 阻塞原因
  blockedById?: string;        // 造成阻塞的任务 ID（可选）

  predecessorIds?: string[];   // 前置任务 ID 列表

  riskLevel?: 'low' | 'medium' | 'high';  // 系统计算字段，不可手动编辑

  createdBy: string;
  createdAt: string;
  updatedAt: string;
}

type DevTaskStatus = 'todo' | 'in_progress' | 'testing' | 'submitted' | 'done';

2.2 TaskWorklog（工时记录）

interface TaskWorklog {
  id: string;
  taskId: string;              // 所属 DevTask
  userId: string;              // 登记人
  date: string;                // YYYY-MM-DD
  hours: number;               // 当日投入小时数
  workContent: string;         // 工作内容（必填，为日报系统提供数据源）
  createdAt: string;
}

• DevTask.actualHours = 该任务下所有 TaskWorklog.hours 的累加
• actualHours 字段只读，不允许直接编辑
• workContent 必填，格式示例："完成排班页面基础布局"、"对接排班接口"
• V2 与加班记录、日报模块打通，统一为"工时记录中心"
• 日报可直接聚合当日 workContent 生成：排班页面布局（4h）+ 接口联调（2h）= 6h

2.3 TaskCategory（任务类型字典）

interface TaskCategory {
  id: string;
  name: string;                // 显示名称
  group: 'development' | 'testing' | 'implementation' | 'other';  // 分组，用于报表统计
  color?: string;              // 图表配色
  sortOrder: number;           // 排列顺序
  isSystem: boolean;           // 系统预置不可删除
}

系统预置值：

名称	分组	说明
前端开发	development	Web/移动端页面
后端开发	development	API/服务层
数据库设计	development	表结构/迁移
接口联调	development	前后端对接
测试验证	testing	测试执行
缺陷修复	testing	Bug 修复
数据处理	implementation	ETL/数据清洗
实施支持	implementation	部署/实施

管理员可在"系统管理"中增删自定义类型。

3. 状态机

todo → in_progress → testing → submitted → done
                ↑         │          │
                └─────────┘          │
                ↑                    │
                └────────────────────┘

状态	含义	推导进度
todo	待开发	0%
in_progress	开发中	50%
testing	自测	80%
submitted	提测	90%
done	已完成	100%

状态流转规则

正向流转：

• todo → in_progress → testing → submitted → done

允许回退（有限）：

• testing → in_progress（自测发现需要返工）
• submitted → in_progress（测试打回）

禁止回退：

• done → 任何状态（完成是终态，返工走新任务或 Bug）
• todo → 非 in_progress（不能跳级）

回退时记录操作日志（操作人、时间、原因）。

4. 阻塞设计（正交标记）

阻塞不是状态枚举值，而是叠加在任何状态之上的标记：

字段	类型	说明
isBlocked	boolean	是否被阻塞
blockReason	string?	阻塞原因描述
blockedById	string?	造成阻塞的任务 ID

示例场景：

• status=in_progress + isBlocked=true：开发中但等后端接口
• status=testing + isBlocked=true：自测发现问题等需求确认
• status=todo + isBlocked=true：依赖的前置任务未完成

工作台筛选 isBlocked=true 可一键拉出所有阻塞项。

5. 进度计算规则

5.1 单任务进度

由 status 推导（见状态机表），不设人工填写的百分比字段。

5.2 需求级开发进度

需求开发进度 = Σ(任务.estimateHours × 任务状态推导进度) / Σ(任务.estimateHours)

示例：

任务	预计工时	状态	推导进度	加权
排班界面	16h	done	100%	16
排班规则组件	8h	in_progress	50%	4
排班算法接口	24h	todo	0%	0

需求进度 = (16 + 4 + 0) / (16 + 8 + 24) = 20 / 48 = 41.7%

5.3 版本开发进度

版本开发进度 = Σ(版本下所有 DevTask.estimateHours × 状态推导进度) / Σ(estimateHours)

5.4 工时投入展示（辅助指标，不参与进度）

工时投入比 = Σ actualHours / Σ estimateHours

展示为：已投入 32h / 预计 56h (57%)

用途：工时偏差分析、健康度评估、加班趋势关联。

6. 工时展示规则

存储单位始终为小时(h)。展示时自动转换：

值	展示
4h	4h
8h	8h（1人天）
16h	16h（2人天）
24h	24h（3人天）

转换规则：1人天 = 8h，仅当 ≥ 8h 时附带人天标注。

7. 优先级继承

Requirement.priority = P1
    ↓ 创建任务时默认继承
DevTask.priority = P1（可覆盖为 P0/P2/P3）

UI 行为：创建任务弹窗中，优先级字段预填为需求优先级，允许手动修改。

8. 前置任务（依赖）

字段	说明
predecessorIds	string[]，前置任务 ID 列表

V1 功能范围：

• 创建/编辑时可选择同版本内的其他 DevTask 作为前置
• 详情页展示前置任务列表，可跳转
• 前置任务未完成时，系统不阻止本任务开始（仅展示提示）

V2 扩展：

• 甘特图依赖线
• 关键路径计算
• 自动阻塞提醒

9. 风险等级（系统自动计算，不可手动编辑）

V1 预留 riskLevel 字段，由系统自动计算，UI 上不提供手动编辑入口。

V2 自动规则：

条件	风险等级
actualHours > estimateHours × 1.5	high
today > dueDate 且 status ≠ done	high
isBlocked 持续超过 2 天	high
actualHours > estimateHours × 1.2	medium
today > dueDate - 3天	medium
其他	low

风险逐层汇总：任务 → 需求 → 版本 → 项目，与已有 version.riskLevel 计算保持一致。

设计原则：风险等级反映客观数据，不允许人为干预（避免"明明很危险但负责人填低风险"）。

10. "与我相关"统一聚合层

10.1 统一工作项模型（锁定契约）

所有可分配实体必须遵守以下统一语义，新增实体类型时不得打破此契约：

type WorkItem = {
  entityType: 'plan' | 'devTask' | 'testCase' | 'bug';
  entityId: string;
  title: string;
  status: string;
  isBlocked?: boolean;
  assigneeId: string;          // 必须：负责人
  reviewerId?: string;         // 可选：验收人
  versionId: string;           // 必须：从各实体推导
  versionName?: string;
  priority?: string;           // 必须：优先级
  dueDate?: string;            // 必须：截止日期
  categoryLabel?: string;      // 任务类型名称
};

未来新增实体（发布任务、实施任务、运维任务等）只需实现此接口，即可自动接入工作台，无需修改聚合逻辑。

10.2 工作台分组

左侧导航扩展：

分组	数据来源	状态
全部待办	所有 entityType	—
调研	VersionPlan(type=research)	已有
产品方案	VersionPlan(type=product)	已有
UI设计	VersionPlan(type=ui)	已有
开发任务	DevTask	本次新增
测试/Bug	TestCase + Bug	后续

10.3 右侧状态视图

按状态分列展示：

• 待处理（todo / pending）
• 进行中（in_progress）
• 阻塞（isBlocked = true，跨所有状态）
• 待验收（testing / submitted）

10.4 联动规则

• 创建 DevTask 并指定 assigneeId → 自动出现在该成员"与我相关"
• 变更 assigneeId → 从原负责人工作台移除，加入新负责人工作台
• 状态变更 → 自动在工作台内移动列

11. 与加班模块的关系

已有加班记录存储小时数。未来数据链路：

TaskWorklog（任务工时）
    ↓ 当日工时 > 8h 部分
OvertimeRecord（加班记录）
    ↓ 按月汇总
加班统计仪表盘

V1 两个模块独立运行。V2 建立工时 → 加班自动关联。

12. 涉及新增文件（预估）

路径	说明
apps/web/lib/dev-task.ts	DevTask 类型定义 + 进度计算函数
apps/web/lib/task-worklog.ts	TaskWorklog 类型 + 聚合函数
apps/web/lib/task-category.ts	TaskCategory 类型 + 预置数据
apps/web/stores/useDevTaskStore.ts	DevTask 状态管理（localStorage V1）
apps/web/stores/useTaskWorklogStore.ts	工时记录状态管理
apps/web/components/dev-task/	DevTask 相关组件目录
apps/web/app/versions/[id]/	版本详情页 DevTask Tab

13. 不在本次范围

• 甘特图依赖线渲染
• 风险等级自动计算
• 工时 → 加班自动关联
• 测试用例 / Bug 模块
• 后端 API 实现（V1 全部 localStorage）