# iBoard V0.2 任务模块 设计文档 — 框架设计 | 项 | 内容 | | --- | --- | | 版本 | V0.2（对应分支 `dev-0.2`，应用版本 `0.2.0`） | | 文档状态 | **设计基线**（待评审；不含实现代码） | | 上游文档 | `任务模块需求文档.md`（需求编号 `T-*` 原文见该文档，本文按编号逐条对应） | | 配套文档 | `任务模块功能设计.md`（功能设计，需求点一一对应）、`任务模块数据库设计文档.md`、`任务模块界面设计.html` | | 技术栈 | Tauri 2 + React 18 + antd-mobile + React Router v6 + Express 4 + Prisma / MariaDB | | 设计基线 | 移动端优先，视口 420×820，375~430px 自适应；时区统一 `Asia/Shanghai` | > **编号约定**：本文多处出现需求编号（如 `T-BD-14`），其完整描述与验收要点以《任务模块需求文档》为准。每个模块的「需求点 → 设计落点」对照见《任务模块功能设计》。 --- ## 1. 总体设计 ### 1.1 目标与范围 在既有 iBoard 之上新增**任务模块**，并把它作为**顶级 Tab 插入「打卡」之后**（顺序：打卡 → **任务** → 宏观 → 监控 → 我，默认首页仍为打卡，T-PM-06）。 模块解决的问题与核心隐喻： | 视图 / 概念 | 解决的问题 | 核心隐喻 | | --- | --- | --- | | **列表视图** | 快速记录、逐条推进 | Todoist 式条目 + 一级子任务缩进 | | **看板视图** | 多人分工下的阶段流转 | 列（阶段）× 卡片（任务），长按拖拽换列 | | **项目** | 数据与权限的隔离单位 | 项目即"工作区"，成员可见即可读写 | | **列-状态绑定** | 让"拖动列"与"改状态"两个动作不必重复做 | 列是**空间**，状态是**属性**，绑定是二者之间的**可选桥** | | **列保留选项** | 已完成任务不淹没在列表里 | 每列自己的"保质期" | **设计的关键取舍**：把「看板列」与「任务状态」设计成**两个独立维度**，再用**项目级、逐列的绑定配置**把它们关联起来。这样既支持"拖动即改状态"的一体化体验，也支持"这一列只是分类、不进状态机"的轻量用法——这正是需求中 `Action` 默认不绑定状态的意图。 ### 1.2 架构总览 ``` ┌──────────────────── 前端 (React + antd-mobile，打包进 Tauri / OTA) ────────────────────┐ │ App.jsx 路由 │ │ └ /task ──► TaskPage (首屏: 上=RecentProjects 条, 下=当前项目 ProjectView) │ │ /task/list ──► ProjectList (完整项目列表, 从「更多项目」进入) │ │ /task/:pid ──► TaskPage (打开指定项目, 供深链) │ │ ProjectView ──┬── ListView (列表 + 子任务缩进折叠) │ │ ├── BoardView (看板 + 长按拖拽) │ │ └── ProjectManage (项目管理: 成员 / 列设置 / 项目信息) │ │ 组件: TaskCard / SubtaskRow / StatusDot / ExtrasCard / UserPicker / RecentProjects │ │ 状态: TaskStore (项目内单例) / ReorderableList / useLongPressDrag │ │ 工具: src/pages/task/date.js (与后端同口径的自然日边界) │ │ src/pages/task/prefs.js (设备端: 视图记忆 / 上次项目 / 最近项目手动排序) │ └──────────────────────────────┬─────────────────────────────────────────────────────────┘ │ HTTPS + JWT (Authorization: Bearer) ┌──────────────────────────────▼─────────────────────────────────────────────────────────┐ │ Express │ │ /api/projects/* ─► routes/projects.js ─┐ │ │ /api/tasks/* ─► routes/tasks.js ─┤─► middleware.authRequired │ │ /api/columns/* ─► routes/columns.js ─┤─► requireProjectMember (项目成员校验) │ │ └─► task-domain/ ← 【领域逻辑唯一来源】 │ │ resolveStatus() 列/状态联动裁决 │ │ resolveColumn() 自动归位 │ │ retentionWindow() 保留窗口 │ │ copyTask() 跨项目拷贝 │ └──────────────────────────────┬─────────────────────────────────────────────────────────┘ ▼ MariaDB: Project / ProjectMember / BoardColumn / Task / TaskMember / TaskTag ``` ### 1.3 分层与职责 | 层 | 位置 | 职责 | | --- | --- | --- | | 页面 | `src/pages/task/*.jsx` | 视图编排、本地状态、乐观更新与回滚 | | 组件 | `src/components/task/*.jsx` | 纯展示 + 局部交互（卡片、列、子任务行、状态点、扩展卡片） | | 设备端偏好 | `src/pages/task/prefs.js` | `viewMode` / `lastProjectId`（**仅设备端**，T-VW-06、T-VW-07） | | 日期工具 | `src/pages/task/date.js` | 自然日边界计算，**与后端 `task-domain/date.js` 同口径，改一处必须同步另一处** | | API 封装 | `src/api/task.js` | 统一走既有 `api()`（自带 token / 错误解析） | | 路由 | `server/routes/tasks.js`、`projects.js`、`columns.js` | 参数校验、鉴权、组装展示态 | | 领域逻辑 | `server/task-domain/*.js` | **列-状态裁决、自动归位、保留窗口、拷贝**（唯一口径） | | 持久化 | Prisma Client | 表操作 | > **与打卡模块的区别**：打卡的周期口径只有 `period.js` 一个文件；任务模块的领域规则（三条）彼此有依赖（归位依赖列序、保留依赖完成时间与列配置），统一收敛到 `task-domain/` 目录，**前后端不得各自实现一遍裁决逻辑**——前端只做乐观更新，最终以服务端返回为准。 ### 1.4 目录结构（本次新增/修改） ``` prisma/ schema.prisma # +6 个 model，User 加反向关系 migrations/20261024xxxxxx_add_task_module/ # 新建表 + 外键 + 索引 server/ task-domain/ date.js # 自然日边界（今天/本周/本月） resolveStatus.js # 列→状态、状态→列、自动归位 retention.js # 列保留窗口 → 可见性 copyTask.js # 跨项目深拷贝 routes/ projects.js # /api/projects/* columns.js # /api/columns/* tasks.js # /api/tasks/* index.js # 挂载三个路由 src/ api/task.js # projectApi / columnApi / taskApi pages/task/ date.js # 与后端同口径 prefs.js # 设备端偏好（视图记忆/上次项目/最近项目手动排序） TaskPage.jsx # 首屏容器: RecentProjects 条 + 当前项目 ProjectView ProjectList.jsx # 完整项目列表（/task/list, 从「更多项目」进入） ProjectView.jsx # 列表/看板容器 ListView.jsx # 列表视图 BoardView.jsx # 看板视图 ColumnSettings.jsx # 列管理 + 绑定 + 保留选项（由项目管理进入） TaskDetail.jsx # 任务详情（含扩展卡片 / 子任务；底部安全距离） ProjectMembers.jsx # 成员管理（由项目管理进入） ProjectManage.jsx # 项目管理: 成员 / 列设置 / 项目信息 三区 components/task/ TaskCard.jsx SubtaskRow.jsx StatusDot.jsx ExtrasCard.jsx UserPicker.jsx useLongPressDrag.js RecentProjects.jsx # 首屏最近项目条（卡片可长按排序） components/BottomNav.jsx # Tab 增「任务」，位于打卡之后 components/TabIcon.jsx # 增 task 图标 App.jsx # +/task、/task/:pid styles/globals.css # .task-* 样式段 docs/V0.2/任务模块/ # 需求 / 框架 / 功能 / 数据库 / 界面 ``` ### 1.5 数据流总览 ``` 用户操作 ──► 前端乐观更新（本地 store 立即变） │ ▼ PUT /api/tasks/:id { columnId?, status?, done? } │ ▼ requireProjectMember（非成员 403） │ ▼ resolveStatus() ── 读项目 columnBindings（列序 + 绑定） │ ① 目标列绑定状态 ⇒ status = boundStatus │ ② 目标列不绑定 ⇒ 保留原 status │ ③ 状态变了且当前列不绑定该状态 ⇒ 自动归位（列序首个匹配） │ ④ 无匹配列 ⇒ 列不动 ▼ 写库（status + columnId 同时落库） │ ▼ 返回最新任务 ──► 前端以响应覆盖本地乐观值（不一致则纠正） ``` --- ## 2. 领域规则设计（重点） > 本模块所有"难"的地方都集中在**列与状态的双向联动**上。下面把规则收敛为一组**无歧义的判定函数**，前后端都以此为准。 ### 2.1 两个正交维度的定义 | 维度 | 字段 | 取值 | 谁决定 | | --- | --- | --- | --- | | **空间** | `Task.columnId` | 指向项目内某个 `BoardColumn` | 用户拖拽 / 自动归位 | | **属性** | `Task.status` | `todo`（未开始）/ `doing`（执行中）/ `done`（完成） | 用户勾选 / 列绑定联动 | **二者独立落库**，不做互相推导（见《数据库设计文档》§2）。原因： 1. 未绑定的列（如默认 `Action`）要求二者**完全正交**，任何推导都会丢失信息； 2. 同一状态可被多列绑定（T-BD-03），状态无法反推唯一列； 3. 保留选项依赖"完成时间"而非列，推导会引入隐式状态。 ### 2.2 三种联动场景与判定函数 设项目列列表为 `C = [c₁, c₂, …, cₙ]`（按 `sortOrder` 升序），每列 `c.boundStatus ∈ {todo, doing, done, null}`。 **场景 A · 拖拽换列（`T-BD-04/07/08`）** ``` function onColumnChange(task, targetColumnId): c = columnById(targetColumnId) if c.boundStatus != null: task.status = c.boundStatus # 列决定状态 else: # 目标列不绑定 ⇒ 保留原状态（T-BD-07、T-EX-05） pass task.columnId = targetColumnId ``` > **注意**：这里**不存在「从某列拖出即回退状态」的规则**。是否改状态只看**目标列**。这是评审中明确修正过的口径（原设计曾写"拖出回退为未开始"，已废弃）。 **场景 B · 改状态（勾选/选择器，`T-BD-14/15/16`）** ``` function onStatusChange(task, newStatus): task.status = newStatus # 当前列是否已经"匹配"这个状态？ if task.column.boundStatus == newStatus: return # 已匹配，列不动 # 不匹配 ⇒ 自动归位，按列序取第一个绑定 newStatus 的列（T-BD-15） target = first(c in C where c.boundStatus == newStatus) if target != null: task.columnId = target.id else: # 无匹配列 ⇒ 不移动，保留原列（T-BD-16） pass ``` **场景 C · 子任务（`T-BD-13`）** ``` if task.parentId != null: # 子任务完全跳过上述两种联动 persist(status, columnId) as-is ``` ### 2.3 判定矩阵（可转写为单测） 以默认配置 `plan→todo, doing→doing, action→null, done→done` 为例： | # | 初始（列 / 状态） | 操作 | 结果（列 / 状态） | 覆盖需求 | | --- | --- | --- | --- | --- | | 1 | plan / todo | 拖到 doing | doing / doing | T-BD-04 | | 2 | plan / todo | 拖到 action（不绑定） | action / **todo**（保留） | T-BD-07、T-BD-08 | | 3 | action / todo | 改为 done | **done** / done（自动归位） | T-BD-14、T-BD-15 | | 4 | action / todo | 改为 doing | doing / doing | T-BD-14 | | 5 | done / done | 拖到 action | action / **done**（保留） | T-BD-07、T-EX-05 | | 6 | done / done | 改为 doing | doing / doing | T-BD-14 | | 7 | plan / todo | 改为 todo | plan / todo（已匹配，不动） | T-BD-14 | | 8 | 全部列不绑定 done，任务在 action | 改为 done | action / done（**无匹配不移动**） | T-BD-16 | | 9 | 父任务 done，子任务在 action | 改父任务状态 | 子任务完全不受影响 | T-BD-13 | | 10 | 两列都绑定 done（done、action） | 改为 done | 列序靠前者（done） | T-BD-06、T-BD-15 | > 第 8 行是评审中特别确认的：**没有「已完成统一归到 Done 列」的强制规则**，那只是默认配置下的自然效果。用户取消全部绑定后，任务就停在原列。 ### 2.4 列配置变更的语义（`T-BD-11`、`T-COL-08`） **核心原则：配置变更只影响后续操作，不批量改写历史数据。** | 变更 | 处理 | | --- | --- | | 列 A 由「绑定 done」改为「不绑定」 | 已在 A 中且状态为 done 的任务**保持不动**（列与状态都保留），见 T-EX-03 | | 列 A 绑定状态由 doing 改为 done | 已在 A 中的任务状态**不回写**；后续拖入 A 的任务才按 done 处理（T-BD-11） | | 删除列 A | 二次确认 → 列内任务迁移到指定列（默认相邻列）→ 迁移后**按目标列重新裁决状态**；A 的绑定解除（T-COL-08、T-EX-16） | | 新增列 | 取默认值 `retention=forever`、`boundStatus=null`，**不继承相邻列**（B-18） | > 为什么删除列要"重新裁决"而改绑定不裁决：删除是**数据搬家**（任务必须有个列），搬家后必须与目标列的语义自洽；而改绑定只是改了"未来的规则"，不该动已有数据。 ### 2.5 空归属与一致性保障 | 风险 | 保障 | | --- | --- | | 删除列后任务 `columnId` 悬空 | 迁移在同事务内完成；`Task.columnId` 为 `NOT NULL`，外键 `ON DELETE RESTRICT` 从库层面阻止误删 | | 列被删后 `boundStatus` 残留 | `BoardColumn` 是实体，列删则绑定自然消失，无残留（优于早期 JSON 方案） | | 并发拖拽同一任务 | 服务端以「读-判定-写」在同一事务内完成；前端防抖 + 版本号（可选） | | 状态改了但归位列不存在 | 判定函数显式处理「无匹配列」分支（T-BD-16），不抛异常 | --- ## 3. 重点流程设计 ### 3.1 看板拖拽（长按 → 跨列 → 落到子任务） 这是本模块交互最复杂的一条链路，同时涉及**换列**与**降级为子任务**两种语义。 ``` 长按 300ms ─► 卡片抬起（缩小 + 浮层跟随手指） │ ├─ 拖到【另一列空白区】 │ └─ 松手 → onColumnChange(任务, 目标列) │ → 按 §2.2 场景 A 裁决 │ → 乐观更新本地列与状态 → PATCH（失败回滚 + Toast） │ ├─ 拖到【另一列某卡片上】 │ └─ 该卡片高亮为"落点" │ 松手 → 若落点是顶层任务且被拖任务无子任务 ⇒ 降为子任务 │ ├─ 是子任务 ⇒ 拒绝（T-ST-13） │ ├─ 被拖任务有子任务 ⇒ 拒绝（T-ST-14） │ └─ 拖到自己/后代 ⇒ 拒绝（T-EX-15） │ └─ 拖到【原列】→ 视为排序（本期仅更新 sortOrder） ``` **难点与对策**： | 难点 | 对策 | | --- | --- | | 移动端长按与滚动冲突 | 长按 300ms 后才进入拖拽态；进入后 `touch-action:none` 并锁定滚动容器 | | 看板横向滚动 vs 拖拽换列 | 拖拽时容器允许横向自动滚动（边缘 24px 触发），松手位置决定列 | | 落点判定（列 vs 卡片） | 用 `elementFromPoint` 命中 `[data-column-id]` / `[data-task-id]`，卡片优先 | | 误操作 | 拒绝场景统一 Toast 说明原因；松手动画回弹原位 | | 降为子任务后卡片消失 | 子任务不出独立卡片（T-ST-10），故从其原列移除，父任务卡片内出现该子任务行（T-ST-06） | > 兜底：无法拖拽时（如长按被系统手势占用），卡片「⋯」菜单提供「移动到列 / 移动到子任务」的等价操作（T-UI-07）。 ### 3.2 保留选项的可见性计算与"当场消失" **窗口计算**（后端 `task-domain/retention.js`，自然日口径）： ``` function retentionStart(option, now): today = startOfDay(now) # Asia/Shanghai 00:00 switch option: never => 返回"不可见" forever => 返回"无下界"（全可见） today => today 3d => today - 2 天 # 含今天共 3 天 week => 本周一 00:00 month => 本月 1 日 00:00 可见性判定：task.status == done ? (doneAt != null && doneAt >= retentionStart(该任务所属列的 option)) : true # 未完成任务始终可见（T-FL-12） ``` **判定依据**：`Task.doneAt`（完成时刻），**与任务当前所在列无关**（T-FL-10）；归属哪一列决定用哪一列的选项（T-FL-11）。 **前端"当场消失"**（T-EX-18）： ``` 每分钟（以及跨日/跨周/跨月边界整点）执行一次： 重新计算当前可见集合 对"由可见变不可见"的任务卡片： 加 .is-leaving（透明 + 高度收缩，约 240ms） 动画结束移除 DOM 其余卡片通过布局动画平滑重排（不做全局刷新） ``` > 也允许退化为"刷新时计算"——需求明确接受该实现方式（§5 决策 23）。跨周期边界用**定时器 + 页面可见性变化（`visibilitychange`）**双保险。 ### 3.3 跨项目拷贝 拷贝是**深拷贝**，且要处理目标项目成员差异（T-CP-07）与绑定差异（T-CP-09）。 ``` POST /api/tasks/:id/copy { projectId: 目标项目 } │ ├─ 校验：源任务可读、目标是本人成员（T-CP-06） ├─ 事务内： │ newTask = create({ │ ...全部业务字段（标题/描述/状态/列/扩展卡片/标签） │ creatorId = 当前操作者 ← T-CP-04 │ projectId = 目标项目 │ columnId = 目标项目中"列名相同"的列，找不到则取第一列 │ }) │ assigneeId = 目标项目成员？保留 : 置 null ← T-CP-07 │ taskMembers = 过滤出目标项目成员中的交集 ← T-CP-07 │ for 每个子任务：同法 create（parentId = newTask.id） ← T-CP-03、T-CP-08 │ 状态与列不强行纠正（T-EX-14） └─ 返回 { task, dropped: { assignee, members[] } } ← 提示被丢弃的人员 ``` **新旧任务完全独立**（T-CP-05）：拷贝后无任何关联字段，是两条独立记录。 ### 3.4 个人默认项目的创建与保护 ``` 创建时机：用户首次访问 /api/projects（或注册时）→ 不存在 isPersonal 项目则创建 name = `${user.name}的任务`（T-PJ-04，可改名） 保护规则（服务端强制，前端不提供入口）： DELETE /api/projects/:id → isPersonal ⇒ 400（T-PJ-02、T-EX-09） POST /api/projects/:id/members → isPersonal ⇒ 400（T-PJ-03、T-EX-09） PUT /api/projects/:id → 允许改名（T-PJ-04） ``` ### 3.5 成员清空后的项目 删除最后一名成员时**不删除项目**，只删 `ProjectMember` 记录（B-11、T-PJ-08）： - 项目成为"无成员项目"，任何人都不可见（T-PJ-10）； - 前端不做特判、不报错（T-EX-11）； - 数据保留，由后台维护流程后续处理（不在本模块范围，§1.5）。 > 副作用：曾为该项目任务的负责人 / 成员会显示为「已退出」（T-EX-06），因为其 `userId` 已不是项目成员。 --- ## 4. 状态管理与性能 ### 4.1 前端状态 | 状态 | 存放 | 生命周期 | | --- | --- | --- | | 当前项目、任务列表、列配置 | `TaskStore`（项目内单例） | 进入项目时加载，切换项目时替换 | | 视图（list/board） | **设备端** `localStorage.iboard_task_prefs` | 按 `projectId` 分键（T-VW-03/06） | | 上次访问项目 | **设备端** 同上 | 单个 key（T-VW-07） | | 折叠状态（子任务） | 内存（组件内） | 会话内，不持久化 | | 弹窗 / 拖拽态 | 组件内 | 操作结束即清 | ### 4.2 性能设计 | 场景 | 目标 | 手段 | | --- | --- | --- | | 首屏加载（T-NF-01） | < 1.5s | 任务与列配置**一次请求返回**；子任务随父任务同批返回 | | 交互响应（T-NF-01） | < 300ms | 乐观更新，不等接口返回 | | 千级任务（T-NF-05） | 可用 | 索引覆盖（`projectId+columnId`、`projectId+status`）；列表虚拟化（按需） | | 保留计算 | 不额外请求 | 前端本地按 `doneAt` + 列选项实时过滤，切换档位零请求 | | 看板拖拽 | 60fps | 拖拽期只用 transform，不改布局；落下后才重排 | ### 4.3 一致性与容错 - **乐观更新 + 回滚**：失败时恢复快照并 Toast（T-EX-02）。 - **幂等**：拖拽/勾选 500ms 内重复提交合并（T-EX-01）。 - **配置变更即时生效**：保存列配置后服务端返回最新列列表，前端整体替换并重算可见集合，无需刷新（T-BD-12）。 --- ## 5. 风险与权衡 | # | 风险 / 权衡 | 说明与对策 | | --- | --- | --- | | 1 | **列与状态双维度带来的认知成本** | 默认配置下二者一一对应（除 Action），用户"不懂也不会错"；只有主动改配置时才需要理解绑定 | | 2 | **自动归位可能让用户"找不到"任务** | 任务从当前列跳走。对策：归位后该卡片带一次高亮动画；提供 Toast「已移至 <列名>」 | | 3 | **保留选项与"未绑定完成的已完任务"** | 状态为 done 但所有列都不绑定 done 时，任务停在不绑定列，其可见性按该列选项判定（T-FL-11）——语义自洽但需要文案说明 | | 4 | **列可增删导致看板横向过宽** | 上限暂定 10 列（T-COL-06，**待确认**）；超出时看板横向滚动 + 列头悬浮 | | 5 | **子任务状态与父任务不一致的展示** | 卡片内嵌子任务带**小状态标记**（T-ST-09），避免"父已完成但子未做"的信息丢失 | | 6 | **跨项目拷贝丢弃人员** | 返回被丢弃的名单并在前端提示，避免静默丢数据（T-EX-08） | | 7 | **无成员项目的数据残留** | 本期不处理（T-PJ-08），需后台维护；在数据库设计文档中标注为"孤儿项目" | | 8 | **前后端日期口径不一致** | `date.js` 双份实现是既有项目的做法；本期继续沿用并在两处加注释互指，写单测覆盖边界（周日 23:59 / 周一 00:00 / 月末） | --- ## 6. 测试与验证要点 | 类别 | 要点 | | --- | --- | | **领域规则单测** | §2.3 判定矩阵 10 条全覆盖；`retentionStart()` 六档边界（含周日/月末跨点） | | **接口测试** | 非项目成员访问 403；个人默认项目的两个保护接口返回 400；拷贝后源任务不变 | | **交互验证** | 拖拽换列 / 降为子任务 / 拒绝场景 Toast；保留档位切换任务当场消失并重排 | | **兼容性** | Android WebView + 移动浏览器（T-NF-02）；375 / 390 / 430 三档视口 | | **两视图一致** | 列表与看板可见条数一致（T-FL-11、T-FL-14）；任一处修改另一处即时可见（T-UI-03） | --- ## 7. 重点设计（2026-10-24 二轮评审） ### 7.1 任务拖动方案（重做） 旧版（手指跟随浮层 + 落点命中即转子任务）在真机上不可靠：浮层遮挡视线、touch 事件与滚动冲突、拖到卡片上误触转子任务。重做后的方案收敛为「**一个可靠手势 + 一个可靠菜单**」： | 场景 | 交互 | 实现 | | --- | --- | --- | | 看板换列 | 长按 400ms 激活（激活前移动 >10px 视为滚动，自动取消）→ 卡片**原位抬起**（不跟随手指、无浮层、无任务名）→ 指针划过列高亮 → 松手落列 | `useColumnDrag`：Pointer Events + `setPointerCapture`（触摸/鼠标统一、捕获后不丢事件、天然吞掉 pointercancel）；`elementFromPoint` 命中 `[data-column-id]`；指针靠近容器边缘时 rAF 自动横滚，可拖到屏幕外的列 | | 列表移动 | 长按 500ms → 弹「移动到列」ActionSheet（当前列打勾） | `TaskRow` 长按计时 → `ProjectView.openMoveMenu`；列表是纵向滚动流，不做自由拖动 | | 转为子任务 | 不走拖拽（已移除「拖到卡片上」路径，误触率高） | 详情页「层级」区：选父任务转为子任务 / 一键转为顶层 | 关键细节：卡片 `touch-action: pan-y`（纵向滚动留给浏览器，水平位移给拖动）；激活与提交都以同一元素的 pointer 事件为准；`pointercancel` 与 `pointerup` 同样清理状态。换列后的状态仍由服务端按目标列绑定统一裁决（§2.2 不变）。 ### 7.2 键盘遮挡统一方案 多个底部弹层（任务详情、信息块编辑、人员选择、拷贝）都出现过"输入框被输入法遮挡"。逐个组件接键盘逻辑不可维护，统一为**一个全局信号 + 一个 CSS 类**： 1. **信号源**：`App` 级唯一监听器 `useKeyboardInsetWatcher`，同时监听 `visualViewport` 的 resize/scroll 与 `window.resize`（配合 `index.html` 的 `interactive-widget=resizes-content`，Chromium 系 WebView 键盘弹出会整体收缩布局视口）；以"见过的最大视口高"为基线计算键盘插入量，写入 CSS 变量 **`--kb-inset`**（>90px 才视为键盘，过滤地址栏抖动）。 2. **消费端**：底部弹层统一挂 **`.kb-safe`** 类 —— `padding-bottom: calc(安全区 + 20px + var(--kb-inset))`、`max-height` 用 `dvh` 随视口收缩并内部滚动。组件不再各自 import 键盘 hook、不再写内联 padding。 3. **兜底**：长输入区（子任务输入、信息块 textarea）聚焦 300ms 后 `scrollIntoView({block:'center'})`，双保险。 新增弹层只要挂 `.kb-safe` 即自动获得键盘避让，无需再处理。