20 KiB
一张待办装下所有要我看的东西:取件箱、红点与「待阅」的消失
状态:已落地。读模型在
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. 一页看完
三条口径来自用户,逐条落成一句话:
- 抄送需处理的都进待办,跟自己的待办同一张列表、同一套批量;每条待办有一枚红点说 "还没看过",看过红点灭但行还在待办里,只有真把它办了(单条或批量处理)才移进已办。
- 转发需处理的同一条路。转发在库里就是
oa_read上的一行(read_type仍是cc, 靠forwarded分细),所以引擎不需要为它另开一档。 - 抄送 / 转发不需处理的也在待办里,看过就直接归进已阅。界面上不再有「待阅」那一屏。
- 两种收尾去的是两个地方:按过「处理」的算已办,只是看过的算已阅。从前两边都堆在 已阅里,已办那一屏看不出「这张单我也表过态」。(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 端
一屏从上到下:
- 页眉:
共 N 条 · 3 条未读 · 超期 2,右边导出 / 刷新 / 发起流程。未读与超期都在 计数那一行,不占独立控件。 - 档位 tab(
oa-todo-segments):全部 / 待我办 / 抄送需处理 / 只需阅,每档带条数。 这一排是"一张列表摆三类东西"唯一的分辨开关——没有它,"还有 3 条要我动手"和"另外 12 条 只是抄送给我看"就混在一个总数里说不清。换档即换一屏:挂着的勾与"整片按筛选选中"一次收掉。 - 筛选行:关键词、来源(抄送 / 分享 / 批注 @ 我,只对抄送那两档有效,选了「待我办」
就自己收掉)、流程、流程状态、日期、那颗「只看未读」(
oa-todo-filter-unread)、重置。 - 表格:混摆时多一列类型(
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退回它本来说的那件事—— 「谁把这一条递到我手上」。超时那一列对抄送画横杠:它没有办理时限。 - 行内动作按档位分派:
approval与cc_action给「处理」,cc_read给「标记已阅」;cc_action再多一颗「详情」(写意见之前得先看单子写了什么);deletable那几条给删除。 - 批量:勾选 / 整片选中之后底部那一横条给「批量处理」「标记已读」。桌面是居中弹窗,
里面按这批的组成长得不一样:
- 有真待办 → 摆「流转路由」下拉(取这批的共同出口交集,没有共同出口就说这句、让人回详情逐条办);
- 整批都是抄送 → 出口那一格根本不摆,也不说"没有共同出口"——它不走流转,问走哪条出口 是问错人,"没有共同出口"是句吓唬人的废话;
- 只要这批里有抄送 → 一句
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 |
四个决定,每一个都对应一个不说就一定会踩的坑:
- 不搬库、不改表、不回填:判据
requires_action在归档行上本来就有,从前只是读侧 没拿它分家。所以历史上那些「办完却一直躺在已阅里」的行,今天一打开就自己在已办, 一条UPDATE都不用(sql/upgrade/20261117_done_cc_split.sql只有核账SELECT)。 真出问题回滚的也只是读法,不是数据。 - 不往
oa_task_completed插行:那张表是审批流水——「他签过没」 (engine._approved_persons)、按比例会签数票、撤回已办按行号定点撤,三套判据都按行算。 抄送处理没走环节、没有出口,插一行进去等于让一张没走过的环节说「我批过了」。行仍留在oa_read_completed,读的时候翻译成已办那一份形状(serializers.read_completed_as_done)。 - 已办按(单 × 来源)折叠:同一张单我既批过一步、又被抄送要求处理过,是两件事,
摆两条,各数各的
handle_count。合成一条会把后发生的那件藏起来。总数跟着换成组数, 与分组同一条语句(窗口函数),页眉的数和翻得到的条数不会分家。 /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 的写法):
oa_read加seen_time(可空 datetime);users加preferences(JSON,NOT NULL)。MySQL 8 不接受ADD COLUMN直接给 JSON 默认值,所以走三步:加可空列 →UPDATE ... CAST('{}' AS JSON)→MODIFY ... NOT NULL;- 回填:
view_time不是空的照抄成seen_time(看过的人不该在改版第二天看见一堆红点复活);requires_action=1且已经在oa_read_completed里的那些也补上(已经办完的更不该亮)。 sql/schema.sql跟着重新生成。
脚本在开发库的副本上验过两遍:第一遍 0 失败,第二遍只剩重复加列那 1060 条噪声 (幂等允许噪声,不许改数据);探针行(一条从未打开的抄送、一条已阅的抄送、一条办完的需处理) 三档行为都对。
10. 还没做的
- 已阅那一屏不给批量:它已经是终点,勾它没有下一步动作。真要"重新看一遍已阅", 那是收藏夹 / 标签,不是这一版口径要的东西。
- 红点不带"读了多久"。真要统计阅读率,
seen_time已经在库里,不必现在定口径。 - 待办里的
cc_action不催办、不计超时、不参与代理与交接(这三件事都是环节语义)。 环节自动抄送那些"要求处理"的提醒仍走站内信与企业微信那几条链路。