unis-oa/docs/todo-inbox-unified-design.md

20 KiB
Raw Permalink Blame History

一张待办装下所有要我看的东西:取件箱、红点与「待阅」的消失

状态:已落地。读模型在 backend/app/service/inbox.py,三个口子在 backend/app/api/runtime.py(GET /task/inbox、POST /task/inbox/seen、 POST /task/inbox/execute),界面在 frontend/src/views/oa/TodoListView.vue(同一份 segments 喂电脑端的 tab 与手机端的圆角钮)、views/oa/ReadListView.vue(只剩已阅一档)、 components/oa/mobile/MobileHome.vue(四张卡)、components/portal/TaskPanel.vue。 判据在 backend/scripts/check_inbox_read.py(37 项)与 frontend/src/views/oa/TodoListView.inbox.spec.ts。历史数据脚本 sql/upgrade/20261116_inbox_seen_preferences.sql。 2026-11 第二次口径(办完归已办、看过归已阅 + 处理意见选填)见 §7,判据 backend/scripts/check_done_cc_split.py,改动落在 backend/app/service/completed.py (已办读两本账)与 backend/app/api/runtime.py(/read/completed、/task/completed)。

0. 一页看完

三条口径来自用户,逐条落成一句话:

  1. 抄送需处理的都进待办,跟自己的待办同一张列表、同一套批量;每条待办有一枚红点说 "还没看过",看过红点灭但行还在待办里,只有真把它办了(单条或批量处理)才移进已办。
  2. 转发需处理的同一条路。转发在库里就是 oa_read 上的一行(read_type 仍是 cc, 靠 forwarded 分细),所以引擎不需要为它另开一档。
  3. 抄送 / 转发不需处理的也在待办里,看过就直接归进已阅。界面上不再有「待阅」那一屏。
  4. 两种收尾去的是两个地方:按过「处理」的算已办,只是看过的算已阅。从前两边都堆在 已阅里,已办那一屏看不出「这张单我也表过态」。(2026-11 第二次口径,见 §7)

于是待办变成取件箱:三档互斥、加起来就是整张列表,一屏之内决定"这条要动手还是扫一眼"。

档 kind 落在哪张表 红点认哪一列 灭红点 离开待办的条件 去哪
approval 待我办 oa_task view_time 打开审批页 / 批量标记已读 单条或批量处理(走完出口) 已办
cc_action 抄送需处理 oa_read 且 requires_action=1 seen_time(新增列) 批量标记已读 / 打开单据 / 交处理意见 本人按下处理(那一句意见可留空) 已办(带处理时间与意见,done_source="cc")
cc_read 只需阅 oa_read 且 requires_action=0 seen_time 同上 看过就算完(点开单据或点「标记已阅」) 已阅

三个容易混的点,界面上必须分得开:

  • 已读 ≠ 已办。红点灭掉只说明"我看过了",行照旧压在待办里;这一条是第 1 条口径的骨头。
  • 需处理 ≠ 环节上的待办。抄送需处理没有出口可选、没有表单必填,要的就是一句"我按要求 办了",所以它落 oa_read 的处理时间与意见,不进 oa_task_completed 那张审批流水。
  • 「标记已读」对三档动的是不同的事:approval 只盖 view_time、cc_action 只盖 seen_time、cc_read 直接归进已阅。同一颗钮,三种收尾,后端按档位分家(见 §3)。

1. 为什么是「并页」而不是「抄送也搬进 oa_task」

抄送落地时写一条 oa_task,读模型就退回一张表,看着更省事,代价在三处:

  • 待办行上全是环节语义(activity / route_name_list / form / 时限 / 挂起),抄送没有环节, 要么塞一堆假值,要么每处读它的人都得判一次"这行是真的么";
  • 批量出口那一路(engine.execute_task)会收到根本没有路由可走的行,_advance 之前必须先加 一道分派,等于把档位判断从读侧挪到写侧,还挪不掉;
  • 已办 oa_task_completed 会凭空多出没表过态的行,审批记录、「他签过没」那套判据 (engine._approved_persons)跟着说谎。

所以选另一头:读时并页,写侧一动不动。并页写法照抄已有那套 union 分页 (api/runtime._work_union_page):数据库排序、切片、数总数,只回本页的 (主键, 档位, 来源表),再按主键把两类行各捞回来。条件只有一份(inbox.Filters), 两边各自翻译成自己的 WHERE(task_conditions / read_conditions), 不会出现"页眉 12 条、批量只动 8 条"。

并页留下两个必须处理的细节:

  • 同一秒到达一条待办和一条抄送是真会发生的(批量抄送、办结时现抄)。只按 sort_time DESC 时 MySQL 不保证两次查询同一个先后,翻页就会出现某条在两页各出现一次、 另一条一次都不出现。次级排序钉死:sort_time DESC, source_table, row_id。
  • 数完总数到捞回来之间被办掉了(别人刚批完、自己另一个标签页)。这一条不摆, 总数照实回,界面上少一行,下一屏自己回来。不拿它编一行假的。

2. 红点:三档同一枚,两张表两个时间戳

红点是这一版的招牌,也是最容易做错的一格,因为它看起来只是一个布尔值。

  • 权威算在哪一侧:后端。每行出参直接带 unread(serializers.read_row / inbox.payload),前端不拿两个时间戳自己比。省一次口径分家。
  • 抄送那一侧的"看过"不能复用 view_time。view_time 在 oa_read_completed 上是 NOT NULL、语义是已阅时刻(进了已阅才算数),而需处理那条"打开过但还没办完"不能算已阅。 所以新开一列 oa_read.seen_time(可空):只说"本人打开过这一条"。
  • 升级要回滚:engine._refresh_read 在把不需处理那条改成需处理时清 seen_time。 以前看过一眼,现在这事要我了,红点得重新亮起来。
  • 打开单据即灭点:抄送能从待办、首页待办中心、右上角通知三处点进来,指望每处都记得调 一次接口迟早漏一处,结果是一行一直红着。口径收在 utils/oa.ts::markReadsOpened 一处, 顺手 refreshBadgeCounts() 重数角标。
  • 点红点那一条不许只灭点:openRow 按档位分派——approval 去审批页、cc_action 就地弹处理意见(弹窗底下留一条「查看单据」,新标签页打开,当前这屏的草稿留着)、 cc_read 直接去单据页并当场归进已阅。
  • 页眉上「N 条未读」与那颗「只看未读」(viewed=0)吃的是同一个数(count_breakdown.unread), 两处不是一个来源时人会说"写着 3 条未读,筛出来 5 条"。

3. 三个口子,一份选择逻辑

接口 干什么 逐条口径
GET /task/inbox 并好的一页 kind(逗号分隔多档)/ source / viewed / expired / work_status / 日期 / 关键词
POST /task/inbox/seen 批量"看过了" 按 source_table 分头走 mark_tasks_viewed / mark_reads_seen,cc_read 顺手 mark_read 归已阅;只盖时间戳,不表态不流转
POST /task/inbox/execute 批量"处理" task 走 engine.execute_task(选出口、过必填);read 走 engine.mark_read(handling=True)——意见留空也办得掉,办完的那几条归已办

选择逻辑两边共用:勾了哪几条以 ids 为准(屏幕上勾着什么就动什么), 没勾给 scope(当前筛选整片)走 ids_for_scope 取,一批上限 50,被上限留在外面的条数 单列 truncated 报出来——不报人就以为整批都办完了。勾上来的 id 认不出归哪张表, 按两张表各问一条 IN(这一页最多 50 条,两条 IN 不贵),两张都认不出的原样按待办交下去, 由逐条那一路报"不存在或不是本人名下",条数不吞。

GET /task/processing/count 加了 inbox=true 默认参数:默认回统一待办的分档数 (total / approval / cc_action / cc_read / unread / expired),inbox=false 退回从前 只数 oa_task 的算法。手机首页那几张卡、流程监控那些"就看压在手上的真待办"的调用方还在用 老口径,抄送并进来会把数报大,这一档不砍。老的 /task/batch-execute 也留着: 流程监控与单据页那些只动待办的调用方不必跟着改。

批量处理里那三档账单要分开说:succeeded / failed / skipped / already / truncated。 skipped(这一趟只盖章、那几条要本人亲自点「处理」)不是失败——混在一批里报成失败,人会以为那几条出了岔子; already(勾到时已经办完)也不是失败。前端 utils/oa.ts::reportBatchOutcome 是两边共用的 那一份措辞,待办与已阅两页不会各说一套。

4. PC 端

一屏从上到下:

  1. 页眉:共 N 条 · 3 条未读 · 超期 2,右边导出 / 刷新 / 发起流程。未读与超期都在 计数那一行,不占独立控件。
  2. 档位 tab(oa-todo-segments):全部 / 待我办 / 抄送需处理 / 只需阅,每档带条数。 这一排是"一张列表摆三类东西"唯一的分辨开关——没有它,"还有 3 条要我动手"和"另外 12 条 只是抄送给我看"就混在一个总数里说不清。换档即换一屏:挂着的勾与"整片按筛选选中"一次收掉。
  3. 筛选行:关键词、来源(抄送 / 分享 / 批注 @ 我,只对抄送那两档有效,选了「待我办」 就自己收掉)、流程、流程状态、日期、那颗「只看未读」(oa-todo-filter-unread)、重置。
  4. 表格:混摆时多一列类型(badge 说清这一行是"待我办 / 抄送需处理 / 只需阅 / 分享 / 批注@我 / 办结后转发"),选了「待我办」那一档这一列跟着收掉。标题前一枚红点 (oa-unread-{id},title 悬浮说明)。「发起人 / 递送人」那一格两类行画的都是发起人, 抄送行在第二行部门后面补一句「来自 递送人」。第一版这里对抄送画的是 sender, 而环节上配的自动抄送把 sender 写成触发这次抄送的那位经手人:最后一环批完就归档 抄送,于是整屏"发起人"都是最后一个审批人,标题里真正的发起人反倒不见了 (2026-11-17 线上截图)。修法是待阅行自己带上发起人快照 oa_read.creator_person / creator_unit_name(抄自单据,口径同 oa_task 同名两列;判据 backend/scripts/check_read_starter_snapshot.py,存量回填 sql/upgrade/20261117_read_creator_snapshot.sql),sender 退回它本来说的那件事—— 「谁把这一条递到我手上」。超时那一列对抄送画横杠:它没有办理时限。
  5. 行内动作按档位分派:approval 与 cc_action 给「处理」,cc_read 给「标记已阅」; cc_action 再多一颗「详情」(写意见之前得先看单子写了什么);deletable 那几条给删除。
  6. 批量:勾选 / 整片选中之后底部那一横条给「批量处理」「标记已读」。桌面是居中弹窗, 里面按这批的组成长得不一样:
    • 有真待办 → 摆「流转路由」下拉(取这批的共同出口交集,没有共同出口就说这句、让人回详情逐条办);
    • 整批都是抄送 → 出口那一格根本不摆,也不说"没有共同出口"——它不走流转,问走哪条出口 是问错人,"没有共同出口"是句吓唬人的废话;
    • 只要这批里有抄送 → 一句 oa-batch-cc-hint:这几条只登记你写的这句意见,不走流转;
    • 有抄送却一句没写 → 按钮按下先在这儿挡一句(后端那道 skipped 是第二道), 省一次白闪。

5. 手机端

同一份口径在 375px 上的形状,原则是档位、红点、逐条动作一样不缺,容器全换:

  • 首页四张卡:待办 / 已办 / 已阅 / 我发起的。原来那张「待阅」卡删了——待阅就是待办本身, 再摆一张等于同一批东西给两个入口,人反而要分清哪边才是真的。待办那张卡的数已经是统一待办 口径,countProcessing(inbox=true) 那一份。
  • 列表页顶部是圆角胶囊档位(MobileCardList 的 segments,与桌面同一份数据), 往下滑接着给(useMobileFeed 攒页)。
  • 卡片左上角红点 (m-card-unread-{key});cc_read 那张卡在右侧直接给一颗 「标记已阅」(m-card-secondary-{key}),勾一下才进选择模式,平时不用先切模式。
  • 批量与"写处理意见"用的是从下沿推上来的那一层(MobileSheet)而不是桌面的弹窗: BaseDialog 那套尺寸在 375px 上会把「确定」顶到屏幕外;出口也不做下拉而做一排按钮—— 下拉浮在弹层里会被截掉半截。引擎逐条回的原因在桌面上是悬浮提示,手机上直接摊在那一层里, 改完意见可以只重试这几条(手机上没地方悬停)。
  • 单据页的返回:待办里的抄送点开单据带上 from=inbox,useReturnTo 认得回待办这条路 (DECLARED_ORIGINS 里的 inbox: 'my-todo')。

6. 「待阅」那一屏去哪了

  • 路由 /read 还在,语义从「待阅」变成纯已阅:meta.titleKey → nav.readDone, 侧边栏文案跟着改、角标摘掉(没人需要一个恒为 0 的角标),个人页分组、手机首页那张卡同理。
  • ReadListView.vue 收成只读一屏:没有「待阅 / 已阅」那一页签、没有勾选、没有批量、没有行内动作、 没有弹窗,只剩关键词与那一格类型筛选(抄送 / 分享 / 批注 @ 我 / 办结后转发),列是标题 / 类型 / 环节 / 发起人 / 送达人 / 已阅时间六列——发起人与送达人各占一列,同一列里不混两件事, 理由与上面那条一样。尾巴是"看单据"。原来那套批量已阅的入口整体迁到待办, 后端 /read/view /read/view/batch /read/{id}/handle 三条写路径一个都没动——它们仍是 统一待办在抄送那一侧的落点,只是没人从"待阅"这一屏调它们了。
  • 角标单一来源:stores/app.ts 里 readCount / refreshReadCount 删掉, refreshBadgeCounts() 现在就是重数待办那一个数。站内信未读仍是另一本账,别混。
  • 工作台与门户首页的数跟着并页改了口径:counts.read 仍是抄送那一侧的条数, 门户 home_counts 额外给出 read_action(其中需处理几条)、read_unseen / task_unseen (各档几条没看过,用完即从出参里摘掉)与折好的 todo_unread; 工作台统计多给一档 read_completed(已阅件),原来那一行"待阅件"读的就是它。 §7 之后这一档只数不需处理那几条(需处理的算已办),completed 那一档同步换成 已办的组数——两处都跟着列表走,否则卡片上的数比点进去翻到的多。
  • 导出也跟着走:/export/tasks?scope=processing 现在导的是统一待办,多认 kind / source / viewed / activity 四个参数,列头多一列「类型」。导出来的东西和屏幕上摆的 不是同一份,是这种改版最阴的坑——人在屏幕上勾了 12 条,Excel 里只有 5 条。

7. 已办与已阅分家(2026-11 第二次口径)

并页之后剩下的那半句:办完的抄送和扫一眼的抄送不该摆在同一屏。用户口径翻成代码是两行——

这一条怎么离开我手的 库里 去哪一屏
按下「处理」(意见可留空) oa_read_completed 且 requires_action=1、带 handle_time 已办 GET /task/completed,done_source="cc"
点开单据页 / 标记已读 同上但 requires_action=0 已阅 GET /read/completed

四个决定,每一个都对应一个不说就一定会踩的坑:

  1. 不搬库、不改表、不回填:判据 requires_action 在归档行上本来就有,从前只是读侧 没拿它分家。所以历史上那些「办完却一直躺在已阅里」的行,今天一打开就自己在已办, 一条 UPDATE 都不用(sql/upgrade/20261117_done_cc_split.sql 只有核账 SELECT)。 真出问题回滚的也只是读法,不是数据。
  2. 不往 oa_task_completed 插行:那张表是审批流水——「他签过没」 (engine._approved_persons)、按比例会签数票、撤回已办按行号定点撤,三套判据都按行算。 抄送处理没走环节、没有出口,插一行进去等于让一张没走过的环节说「我批过了」。行仍留在 oa_read_completed,读的时候翻译成已办那一份形状(serializers.read_completed_as_done)。
  3. 已办按(单 × 来源)折叠:同一张单我既批过一步、又被抄送要求处理过,是两件事, 摆两条,各数各的 handle_count。合成一条会把后发生的那件藏起来。总数跟着换成组数, 与分组同一条语句(窗口函数),页眉的数和翻得到的条数不会分家。
  4. /read/completed 不再收 action 参数:那一格从前是用来"在已阅里挑出需处理的那几条", 现在需处理的那几条压根不在这屏,留着参数只会让人以为还能筛出一堆空结果。 导出(/export/tasks?scope=completed)同一口径,多一列「类型」写「审批办理 / 抄送处理」。

处理意见那一句同时改成选填:必填的是"本人按下了处理"这一颗钮,不是那几个字——逼人编一句 「已阅」只会把档案写脏。留空(含只有空格)不覆盖抄送时对方写的那句来意,handle_time 照盖。

判据:scripts/check_done_cc_split.py(分家 + 历史行自动归位 + 意见选填 + 折叠与角标同源 + 转发与抄送同一条判据)、 scripts/check_inbox_read.py(办完进已办、已阅只认无需处理那一半)、 scripts/check_action_surface.py(空意见也办得掉,且空格子不算说过话)。

8. 外观偏好(顺带)

深色档、字号与主题色(2026-11-18 起多这一档,users.preferences.color,六档: 青 / 蓝 / 靛蓝 / 紫 / 玫红 / 橙)以前只活在 localStorage,换台设备回到解放前。现在 users.preferences(JSON) 是权威,PUT /auth/me/preferences 写,GET /auth/me 回;localStorage 降级成缓存, 因为首屏那段防闪脚本只能在本地读(等接口回来再上色,人已经看见一次白闪)。 会话落地时 stores/auth.ts 调 adoptPreferences 把服务端的接过来。 深浅与字号读写在 utils/appearance.ts,主题色在 utils/themeColor.ts(色板本身在 style.css,JS 只带一个 id;index.html 那段防闪脚本负责画第一笔),adoptPreferences 一次把三档都接过来。入口三处:顶栏那颗外观钮(电脑端)、个人页那一格分段选择、 手机「我的」里那一栏,三处共用 components/common/AccentColorPicker.vue。

9. 上线要动库

sql/upgrade/20261116_inbox_seen_preferences.sql(幂等,按仓库那套 症状 / 原因 / 范围 / 执行 / 之后 + 收尾核账 SELECT 的写法):

  1. oa_read 加 seen_time(可空 datetime);
  2. users 加 preferences(JSON,NOT NULL)。MySQL 8 不接受 ADD COLUMN 直接给 JSON 默认值,所以走三步:加可空列 → UPDATE ... CAST('{}' AS JSON) → MODIFY ... NOT NULL;
  3. 回填:view_time 不是空的照抄成 seen_time(看过的人不该在改版第二天看见一堆红点复活); requires_action=1 且已经在 oa_read_completed 里的那些也补上(已经办完的更不该亮)。
  4. sql/schema.sql 跟着重新生成。

脚本在开发库的副本上验过两遍:第一遍 0 失败,第二遍只剩重复加列那 1060 条噪声 (幂等允许噪声,不许改数据);探针行(一条从未打开的抄送、一条已阅的抄送、一条办完的需处理) 三档行为都对。

10. 还没做的

  • 已阅那一屏不给批量:它已经是终点,勾它没有下一步动作。真要"重新看一遍已阅", 那是收藏夹 / 标签,不是这一版口径要的东西。
  • 红点不带"读了多久"。真要统计阅读率,seen_time 已经在库里,不必现在定口径。
  • 待办里的 cc_action 不催办、不计超时、不参与代理与交接(这三件事都是环节语义)。 环节自动抄送那些"要求处理"的提醒仍走站内信与企业微信那几条链路。