MD6 同步移动体验规约与角色视图治理

2026-05-11 13:35:21 +08:00
@@ -82,6 +82,13 @@ AGENTS.md 只放硬约束和入口，不复制长规则。

 可自动化的体验检查先自动化，例如 Playwright PC、移动、企业微信 UA 和 DOM 指标；真实企业微信登录、手机应用消息到达、真实通知权限和财务制度决策必须保留人工确认记录。

+移动页治理必须收敛到同一套事实源和组件体系：
+
+- 改移动页面前先读 `docs/product-design-rules.md`，确认是否属于底部一级 Tab、首页图标宫格、卡片列表、深层 Push 页、顶部返回、吸底主操作或安全区问题。
+- 新移动页默认纳入统一响应式 token 和跨视口视觉矩阵，覆盖 320、360、375、390、393、414、430px；不得只按某一台手机打补丁。
+- 角色差异采用“同框架、按角色裁剪内容和动作”：员工、审批人、财务、管理员、负责人看到不同入口和动作，但不创建互不一致的角色专属移动 UI。
+- 真机验证暂停时记录为 `PAUSED`；自动化通过不能替代代表性真机确认，也不能关闭仍待人工确认的移动阻断。
+
 ### 7. 提交要小批次、中文、可回滚

 一次需求可以有多个 commit，但每个 commit 应该能说明一个清晰主题：
@@ -29,8 +29,10 @@ R6 之后的 PC、移动和审批体验参考国内主流协同/OA 产品的共

 - PC 是高密度工作台，服务筛选、批量查看、审批、财务复核、导出和管理配置。
 - 移动端是消息驱动的轻入口，服务提交、补材料、查状态、处理待办和从企业微信消息回流。
+- PC 高密度、移动轻任务是双端分工底线；不得把桌面表格和批量管理能力原样搬到手机端。
 - 企业微信只做入口、绑定、免登录、个人应用消息和 deeplink，不替代 OA 正式审批页。
 - 审批体验以“待办聚合、清晰状态、明确下一步、可催办和可追溯”为目标；催办、超时提醒和效率统计属于 R6 后续优化，不混入 R6 首轮试运行门禁。
+- 竞品资料只用于抽象原则；不得复制钉钉、飞书、企业微信、WeUI 或 Ant Design 的页面文案、视觉细节和专有交互。

 参考资料：

@@ -41,7 +43,9 @@ R6 之后的 PC、移动和审批体验参考国内主流协同/OA 产品的共
 - Ant Design 表单页：https://4x.ant.design/docs/spec/research-form-cn
 - Ant Design 表格：https://012x.ant.design/docs/pattern/table
 - Ant Design 导航：https://ant.design/docs/spec/navigation/
- WeUI：https://www.npmjs.com/package/weui
+- Ant Design Mobile/Mini TabBar：https://0x-mini.ant.design/components/tab-bar
+- Ant Design Mobile/Mini SafeArea：https://0x-mini.ant.design/components/safe-area
+- WeUI：https://github.com/Tencent/weui

 ## 文案规则

@@ -93,22 +97,27 @@ R6 之后的 PC、移动和审批体验参考国内主流协同/OA 产品的共
 - 发票、附件上传使用自定义中文控件，不暴露浏览器原生 `Choose File` 文案。
 - 弹窗只承担单一任务，不在弹窗里解释整个业务流程。

-## 手机和企业微信页面模式
+## 移动统一页面范式

+- 所有 `/mobile` 页面默认复用同一套移动 Shell、响应式 token、底部导航、安全区和视觉矩阵；不允许单页自造布局体系解决局部拥挤。
 - 手机端默认隐藏 PC 侧边栏和顶栏，使用移动首页、底部导航和轻量卡片。
 - 菜单不应占用大量空间；常用入口放底部导航，更多入口放“我的”。
 - 移动底部导航固定为“首页、审批、报销、我的”；票据上传作为首页快捷入口和报销页内操作，不作为底部一级 Tab。
 - 移动端必须按响应式规则自动适配，不按单个机型写补丁；验收至少覆盖 320、360、375、390、393、414、430px 宽度。
- 移动首页一级快捷入口使用图标宫格：图标在上、短标题在下，4 项等宽，辅助说明不在小屏常驻展示，避免图标和文字挤压。
+- 移动首页一级快捷入口使用图标宫格：图标在上、短标题在下，4 项等宽，辅助说明不在小屏常驻展示，避免图标和文字挤压；标题单行省略，不允许逐字换行。
 - 移动端页面边距、卡片间距、底部导航高度和吸底操作高度使用统一 token；不通过 viewport 缩放字体解决拥挤问题。
 - 次级入口和信息字段可按最小宽度自动从两列变一列；核心操作按钮必须保持明确可点，不得被内容、安全区或底部栏遮挡。
 - 报销详情、审批详情等深层 Push 页隐藏底部导航，使用顶部返回和上下文吸底操作，避免底部 Tab 在深层页面假选中。
 - 企业微信个人应用消息 deeplink 应直达移动待办或业务详情；首次进入如需点击进入工作台，应保持后续可直接回到目标页。
 - 移动列表使用卡片和状态标签，首屏优先展示“谁提交、什么事项、金额/天数、当前状态和下一步”。
 - 列表使用卡片，不直接显示桌面表格。
- 表单字段纵向排列，按钮宽度稳定，首屏优先完成“新建/继续编辑/提交”。
+- 详情页按摘要、业务字段、发票/附件、审批流、日志分区展示；普通员工移动端不默认展示后台审计细节。
+- 表单单列优先，字段纵向排列，按钮宽度稳定，首屏优先完成“新建/继续编辑/提交”。
+- toast、dialog、actionsheet、tabbar、cell、button 等语义参考微信生态习惯；样式必须回到 hyb-oa 自身品牌和组件规则。
 - 企业微信入口应尽量免登录；绑定失败或权限不足时显示明确下一步，而不是让用户反复登录。
 - 头像 fallback 遵循国内中文习惯：中文/CJK 姓名默认取首个可见字符，英文或拼音姓名保留两段首字母。
+- 移动角色差异采用“同框架、按角色裁剪内容和动作”：员工、审批人、财务、管理员、负责人看到不同入口、摘要、动作和敏感信息，但不做多套角色专属移动 UI。
+- 移动验收必须包含跨视口自动化和代表性真机确认；若真机验证暂缓，只能记为 `PAUSED`，不能把相关移动阻断标为完成。

 ## 报销专项规则

@@ -54,7 +54,7 @@ cd client && npm run build
 页面或交互改动优先用 Playwright 验证：

 - PC viewport: 1440x960。
- mobile viewport: 390x844。
+- mobile viewport: 基础 390x844；涉及移动布局、企业微信或 R6 移动反馈时必须扩展到 320x568、360x740、375x667、390x844、393x873、414x896、430x932。
 - 企业微信 UA 使用 iPhone + `wxwork` 标识。
 - 截图放在 `output/playwright/<issue-id>/`。

@@ -62,10 +62,13 @@ cd client && npm run build

 - 没有桌面表格。
 - `scrollWidth <= viewportWidth + 2`。
- 底部导航高度合理。
+- 底部导航高度合理，四个 Tab 中心点 `elementFromPoint` 命中自身或子元素。
 - 当前选中项不是黑色空心样式。
 - 弹窗不会默认聚焦搜索框导致键盘弹出。
 - 无明显文字截断、遮挡、按钮样式不一致。
+- 首页一级入口使用图标宫格时，图标、标题和容器不重叠，标题不逐字换行。
+- 深层 Push 页隐藏底部 Tab，使用顶部返回；吸底主操作不遮挡内容。
+- 移动验收采用“跨视口自动化 + 代表性真机确认”：自动化证明响应式基线，iPhone 11、Redmi K60 或同类代表设备确认真实企业微信 WebView 行为。

 ## 企业微信验证

@@ -83,6 +86,13 @@ cd client && npm run build
 node scripts/qa/create-real-device-report.mjs
 ```

+真机验证状态允许使用：
+
+- `PASS`：代表性真机和必要人工确认均通过。
+- `FAIL`：真机复现阻断或严重问题，必须登记设备、账号、URL、步骤和证据位置。
+- `BLOCKED`：缺少测试账号、企业微信后台配置、样票或网络等前置条件。
+- `PAUSED`：用户或现场条件暂停验证；自动化通过也不能据此关闭真机门禁或把相关 Issue 标为完成。
+
 公网 live smoke 和真实 OCR 准备按 [`docs/trialrun/live-smoke-readiness.md`](trialrun/live-smoke-readiness.md) 执行：

 ```bash
@@ -46,7 +46,7 @@

 | ID | 级别 | 角色 | 入口/设备 | 流程 | 复现步骤 | 当前处理 | 负责人 | 状态 | 关联 Issue |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| R6-ISSUE-001 | 阻断 | 审批人 / 员工 | iPhone 11 / 企业微信 WebView | 移动底部导航、审批入口、首页快捷卡 | iPhone 11 使用企业微信打开 OA，底部菜单第二项“审批”点不了，首页快捷卡图标和文字挤在一起；用户反馈单点适配不足，需要像主流移动网页/App 一样自动适配不同分辨率 | 已从单机型热修升级为移动响应式体系修复并部署；首页快捷入口改为图标宫格，公网 320/360/375/390/393/414/430 视觉矩阵通过；待 iPhone 11 / Redmi K60 真机确认后关闭或降级 | Codex / 待指派 | open | `issues/2026-05-11_12-17-07-r6-mobile-responsive-system-hotfix.csv` |
+| R6-ISSUE-001 | 阻断 | 审批人 / 员工 | iPhone 11 / 企业微信 WebView | 移动底部导航、审批入口、首页快捷卡 | iPhone 11 使用企业微信打开 OA，底部菜单第二项“审批”点不了，首页快捷卡图标和文字挤在一起；用户反馈单点适配不足，需要像主流移动网页/App 一样自动适配不同分辨率 | `PAUSED`：已从单机型热修升级为移动响应式体系修复并部署；首页快捷入口改为图标宫格，公网 320/360/375/390/393/414/430 视觉矩阵通过；用户暂时暂停真机验证，待 iPhone 11 / Redmi K60 真机确认后关闭或降级 | Codex / 待指派 | open | `issues/2026-05-11_12-17-07-r6-mobile-responsive-system-hotfix.csv` |

 级别定义：

@@ -9,6 +9,7 @@
 - 测试日期：
 - 测试人：
 - 公网地址：`https://oa.hyinda.com`
+- 验收状态：`TODO` / `PASS` / `FAIL` / `BLOCKED` / `PAUSED`
 - 账号角色：专用测试员工 / 测试主管 / 测试负责人 / 测试财务 / 测试财务主管 / 测试管理员
 - 设备：iPhone / Android
 - 系统版本：
@@ -33,6 +34,15 @@
 - 登录后默认进入适合手机的入口或可明确进入移动工作台。
 - 页面无横向滚动、文字遮挡、按钮溢出。

+## 移动统一体验验收
+
+- 移动验收不再只按 iPhone 11 和 Redmi K60 两个固定机型判断；先通过 320、360、375、390、393、414、430px 跨视口自动化证明响应式基线，再用代表性真机确认企业微信 WebView 行为。
+- 所有移动页面使用同一套响应式体系：底部一级 Tab、首页图标宫格、卡片列表、深层 Push 页、顶部返回、吸底主操作和安全区预留。
+- 深层页如报销详情、审批详情隐藏底部 Tab；一级页才显示“首页、审批、报销、我的”底部导航。
+- 底部四项 Tab 必须等宽、可见、可点；不能被滚动层、卡片、安全区或遮罩覆盖。
+- 首页图标宫格必须保持图标在上、短标题在下；小屏不显示长辅助说明，标题不得逐字换行或压住图标。
+- 若现场暂时看不到真机效果或用户暂停验证，记录为 `PAUSED`；不得把 `RS6-7`、`UI6-6`、`R6-ISSUE-001` 误标完成。
+
 ## 报销流程

 - 新建报销草稿。
@@ -86,7 +96,7 @@
 | 工作台入口与免登录 | `oa_smoke_01` | `SMOKE002` | 从企业微信工作台进入 OA，已绑定后免登录 | 通过 | 用户确认；截图/录屏不提交仓库 |
 | 提交人移动报销体验 | `oa_smoke_01` | `SMOKE002` | 移动首页、报销页、详情页、PDF 发票入口可用 | 公网自动视觉通过；真机核心链路通过 | `output/playwright/r5-live-mobile-wecom-visual/` |
 | 审批人移动待办体验 | `oa_smoke_02` | `SMOKE101` | 移动审批待办、审批详情、结果反馈可用 | 公网自动视觉通过；真机审批与消息回流通过 | `output/playwright/r5-live-mobile-wecom-visual/` |
-| 移动底部导航与深层页 | `oa_smoke_01` / `oa_smoke_02` | `SMOKE002` / `SMOKE101` | 首页、审批、报销、我的固定可见；报销详情隐藏底部 Tab，吸底双按钮不遮挡 | 公网自动视觉通过；R6 继续真机观察不同设备体验 | `output/playwright/r5-live-mobile-wecom-visual/` |
+| 移动底部导航与深层页 | `oa_smoke_01` / `oa_smoke_02` | `SMOKE002` / `SMOKE101` | 首页、审批、报销、我的固定可见；报销详情隐藏底部 Tab，吸底双按钮不遮挡 | `PAUSED`：公网自动视觉通过；用户反馈仍需系统性规约治理，真机验收暂缓 | `output/playwright/r6-mobile-responsive-system-hotfix/` |
 | 通知与 deeplink | `oa_smoke_01` / `oa_smoke_02` | `SMOKE002` / `SMOKE101` | 通知能回到移动待办或详情页 | 真机通过：收到个人应用消息，点击后首次需点进入工作台，后续可直达移动审批 | `output/playwright/r5-wecom-app-message-live/` |

 自动化补充证据（用于审批链业务验收）：
@@ -101,6 +111,7 @@
 - `2026-05-11` 公网自动视觉补充：部署 `795e976` 后，Playwright 企业微信 UA 覆盖 iPhone 11/iOS14 与 Redmi K60 视口；`SMOKE002` 移动首页、报销列表、报销详情、PDF-only 上传入口通过，`SMOKE101` 移动审批列表通过；截图目录 `output/playwright/r5-live-mobile-wecom-visual/`。用户已确认真实企业微信工作台入口和免登录通过。
 - `2026-05-11` 通知与 deeplink 自动视觉补充：`SMOKE101` 现有两条未读报销待办站内通知，iPhone 11 与 Redmi K60 近似视口、企业微信 UA 下通知页无横向溢出，通知卡片和“查看”按钮可见；点击后进入 `/mobile/approvals?taskId=177b3a9e-67fe-447d-92f4-96a652a06841` 移动审批详情，无 PC 壳混入，截图目录 `output/playwright/r5-notification-deeplink-live/`。该历史待办已处理，因此本证据只证明站内通知和移动 deeplink，不证明新待办审批按钮；通知投递审计显示渠道 `R50-MOCK-007334` 为 `mock_sent`，真实企业微信外发应用消息仍待通道确认或真机记录。
 - `2026-05-11` 个人企微应用消息补充：部署 `b1ae41f` 后启用 `R5-WECOM-APP-PERSONAL / wecom_app_message`，停用旧 mock 渠道；`SMOKE002` 创建请假测试单据并生成 `SMOKE101` 待办 `936362d8-c4e0-454f-a589-9c9653bcbfda`，通知 `9ee0602e-66a5-4a6e-81e5-04d41908c782` 投递审计为 `wecom_app_sent`、`errcode=0`、无 `invaliduser`。iPhone 11 与 Redmi K60 企业微信 UA 自动视觉验证通知列表和审批详情均无横向溢出，截图目录 `output/playwright/r5-wecom-app-message-live/`。用户确认手机企业微信 `oa_smoke_02` 收到“海音达工作台”应用消息，标题正确；点击后首次进入会提示进入工作台，进入后可看到移动审批，后续再次进入可直接看到移动审批；存在消息通知但未观察到系统弹窗。
+- `2026-05-11` R6 移动体验补充：RS6 响应式体系修复已完成公网自动化，320/360/375/390/393/414/430px 视觉矩阵通过；用户现场暂时看不到真机效果，验证暂停。当前记录为 `PAUSED`，不得将 `RS6-7`、`UI6-6` 或 `R6-ISSUE-001` 置为完成；R6-3 继续等待代表性真机确认。

 - 经理账号可在移动端看到审批待办。
 - 审批详情可查看申请摘要、附件、发票、审批记录。
@@ -67,7 +67,21 @@

 数据范围以服务端权限和审计日志为准。任何导出、附件下载、例外处理都必须记录操作者、时间、对象和原因。

-### 2.2 正式审批组织与角色映射
+### 2.2 角色视图与动作裁剪
+
+统一审批中心使用同一套 OA 审批数据、任务和历史记录，但 PC、移动和企业微信入口应按角色裁剪入口、摘要、动作和敏感信息。角色视图只影响展示和操作便利性，不改变服务端权限模型。
+
+| 角色视图 | 重点入口与摘要 | 允许突出动作 | 不应展示或必须隐藏 |
+| --- | --- | --- | --- |
+| 员工视图 | 新建、草稿、审批中、退回修改、通知、我的申请 | 保存草稿、提交审批、撤回、按退回意见重提、查看本人状态 | 管理配置、全量人员、财务付款、他人待办审批动作 |
+| 审批人视图 | 待处理、已处理、审批详情、附件/发票摘要、审批历史 | 通过、驳回、退回、转审、查看审批记录 | 无关员工列表、财务后处理、未分配给自己的审批按钮 |
+| 财务视图 | PC 端财务复核、付款状态、导出、重复票据例外；移动端只保留必要复核和查看 | 财务复核、付款标记、财务导出、重复发票例外处理 | 系统管理能力、非财务业务审批权、无审计的敏感附件下载 |
+| 管理员视图 | 系统配置、账号、角色、组织、通知渠道、审计日志 | 配置修复、账号启停、角色分配、通知渠道测试、审计查询 | 业务审批按钮；除非同时具备正式业务角色且不是自审，不得处理业务待办 |
+| 负责人视图 / CEO 视图 | 高额、高风险、例外待办，公司级摘要，审批效率和风险概览 | 处理分配给自己的最终审批或例外审批，查看高风险摘要 | 本人单据自审、仅凭 `admin` 权限处理业务、无配置依据的全量业务操作 |
+
+移动端也遵循上述角色视图，但不为每个角色做完全不同的页面体系：同一移动 Shell、列表卡片、详情分区、顶部返回和吸底主操作框架下，按权限显示不同内容和动作。前端隐藏无权动作只是体验优化；服务端仍必须拒绝越权、自审和状态非法操作。
+
+### 2.3 正式审批组织与角色映射

 正式运行和 R5 真机验收按以下组织口径执行；实现不得把个人姓名硬编码到业务逻辑中，应通过员工、直属上级和角色配置落地。