docs(workspace): 新增个人日报列设计

2026-06-26 14:20:28 +08:00
parent 4dcdad50c3
commit 84cb885a8e
1 changed files with 138 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-26-workspace-daily-report-design.md
+++ 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` 验证页面渲染正常。
+
+## 后续扩展
+
+后续项目负责人/管理人员模块可以复用日报派生逻辑，但会增加：
+
+- 按项目、版本、成员筛选。
+- 成员日报填写状态。
+- 未填写人员列表。
+- 定时提醒。
+- 每日归档快照或导出。
+
+这些能力不进入本次“与我相关”个人日报列。