diff --git a/docs/superpowers/specs/2026-06-26-workspace-daily-report-design.md b/docs/superpowers/specs/2026-06-26-workspace-daily-report-design.md new file mode 100644 index 0000000..ffc0870 --- /dev/null +++ b/docs/superpowers/specs/2026-06-26-workspace-daily-report-design.md @@ -0,0 +1,138 @@ +# 与我相关:个人日报列设计 + +## 背景 + +“与我相关”当前定位是当前登录人的个人工作台,聚合本人负责的调研、产品方案、UI 设计、开发任务、测试用例和 Bug。用户希望在内容页最右侧增加“日报”列,用于督促个人记录当天做了什么,并能快速汇总今日工作内容。 + +项目负责人和管理人员需要查看团队日报,但该能力后续拆成独立管理模块,本次不混入“与我相关”。 + +## 目标 + +- 在“与我相关”页面最右侧增加“今日日报”列。 +- 只展示当前登录人的今天日报汇总。 +- 基于现有 `task-worklogs` 数据派生日报,不新增日报实体。 +- 显示今日总工时、登记条数、每条工作内容和对应任务。 +- 当天没有记录时,明确提示“今日暂无日报记录”。 + +## 非目标 + +- 不做项目负责人/管理人员的团队日报视图。 +- 不做定时任务、未填提醒、企业微信/钉钉推送。 +- 不做规则引擎。 +- 不做日报审批、锁定、补交或归档快照。 +- 不把日报作为独立业务流程。 + +## 方案选择 + +采用轻量派生方案:日报列直接从 `useTaskWorklogStore.worklogs` 中筛选当前登录人和当天日期的记录,并补充任务标题、版本上下文等展示信息。 + +理由: + +- 现有 `TaskWorklog` 已包含 `userId`、`date`、`hours`、`workContent`,足够支撑日报汇总。 +- 当前项目架构偏向通过 `workspace-engine` 等纯函数派生视图,日报也应保持这种模式。 +- 页面打开时实时计算即可,不需要定时任务生成数据。 +- 未来管理模块可以复用同一套派生函数,按成员维度汇总团队日报。 + +## 数据设计 + +复用现有数据: + +```ts +interface TaskWorklog { + id: string; + taskId: string; + userId: string; + date: string; + hours: number; + workContent: string; + createdAt: string; +} +``` + +新增派生 helper,而不是新增存储结构: + +```ts +getWorkspaceDailyReport({ + worklogs, + workItems, + userId, + date, +}) +``` + +返回建议: + +```ts +{ + totalHours: number; + totalCount: number; + items: Array<{ + id: string; + taskId: string; + taskTitle: string; + workContent: string; + hours: number; + versionName?: string; + projectName?: string; + productName?: string; + }>; +} +``` + +如果 `taskId` 找不到对应 `WorkItem`,保留日志内容并将任务标题显示为“未知任务”,避免丢失日报记录。 + +## UI 设计 + +页面结构调整为四列: + +- 左侧第一列:产品 / 项目 / 版本树,保持现状。 +- 左侧第二列:环节分类,保持现状。 +- 中间主区域:任务列表,保持现状但让出最右侧空间。 +- 最右侧:固定宽度的“今日日报”列。 + +日报列内容: + +- 顶部标题:“今日日报”。 +- 日期显示:当天日期。 +- 概览:`今日合计 3.5h`、`已登记 4 条`。 +- 列表:每条展示工作内容、小时数、任务标题和版本上下文。 +- 空状态:显示“今日暂无日报记录”,辅助文案提示从任务详情里登记工时。 + +本次不在日报列中直接新增编辑表单。登记仍从任务详情里的工时记录入口完成,避免日报列变成另一个任务编辑入口。 + +## 数据流 + +1. `WorkspacePage` 加载现有工作台数据。 +2. 页面额外调用 `useTaskWorklogStore.fetchWorklogs()`。 +3. 使用当前登录用户 `user.name` 和今天日期筛选 `worklogs`。 +4. 使用 `workItems` 为日志补齐任务标题和版本上下文。 +5. 将派生结果传给 `DailyReportPanel` 展示。 + +## 边界与异常 + +- 未登录或没有用户信息时,日报列显示空状态。 +- 当日无日志时,不写入任何数据,只显示空状态。 +- 日志存在但任务已删除或不在当前工作台筛选范围内时,仍展示日志本身。 +- 日期按本地当天 `YYYY-MM-DD` 计算,和现有工时登记日期格式保持一致。 + +## 测试 + +- 为日报派生 helper 增加单元测试: + - 只统计当前用户当天数据。 + - 排除其他日期和其他人员数据。 + - 正确累计工时和条数。 + - 找不到任务时仍保留日志。 +- 页面变更后运行 TypeScript 检查。 +- 如本地服务可用,访问 `/workspace` 验证页面渲染正常。 + +## 后续扩展 + +后续项目负责人/管理人员模块可以复用日报派生逻辑,但会增加: + +- 按项目、版本、成员筛选。 +- 成员日报填写状态。 +- 未填写人员列表。 +- 定时提醒。 +- 每日归档快照或导出。 + +这些能力不进入本次“与我相关”个人日报列。