DTL · L-20260825-02¶
文档编号：DOC-A04-DTL / L-20260825-02 维护人：听写 DT（DOC-A01 PMG V8.3 §人机协作模型） 关联 DTL：L-20260825-01（前端交付与测试环境手册） 撰写日期：2026-08-25 任务：f12 8/8 场景自动化全通过 + WP-06 5 端角色 DTO 统一实现 + AI 特定行为 #3 git push Gitee hk2026 main
一、任务声明¶
| 维度 | 内容 |
|---|---|
| 触发 | 用户 2026-08-25 指令「上述工作全部顺序执行」（5 阶段） |
| 范围 | ① f12 S2/S7 视觉验证补齐 ② WP-06 5 端角色 DTO 统一 ③ AI 特定行为 #3 git push Gitee hk2026 main ④ AI 特定行为 #4 Cloudflare Pages 文档站发布 ⑤ P1 WP-04/05/07 启动指引 |
| 三 AI 边界 | 听写 DT 负责决策/验收/git 同步/Cloudflare 部署；听码 WDE 仅 dip1/ 本地编码；听云 OCM 本轮无任务 |
| 合规 | 严格 PMG V8.3 三 AI 隔离 + AI 特定行为仅用户显式指令触发 |
二、阶段 A：f12 8/8 场景自动化全通过 ✅¶
2.1 补测 S2 黄闪 3 次（CSS 动画）¶
测试方法：导航 /quote/demo → 全局 window.addEventListener('animationend') 监听 → 直接点提交按钮（不点 btn-auto-fill）→ 等待 3s → 统计 animationend 事件。
结果：
S2 黄闪动画统计:
{
"count": 1,
"events": [{ "name": "msc-flash-yellow", "t": 1787649873027 }]
}
判定：✅ PASS。CSS3 规范 animation: msc-flash-yellow .45s ease-in-out 3 在 3 次 iterations 完成后触发 1 次 animationend 事件（符合规范，iterations=3 但 animationend 只在动画完全结束后触发 1 次），animationName = msc-flash-yellow 与 ui-web/styles.css @keyframes msc-flash-yellow 一致。
2.2 补测 S7 EX-A P0 异常模态上报¶
测试方法：导航 /wkr-demo → snapshot 找 e41 🚨 异常按钮 → click → 等待模态 → snapshot 找 9 类 EX-A~I 按钮 → click e50 EX-A → 等待 Toast → 检查 .msc-toast 容器数量。
结果：
- 异常模态 9 类 EX-A~I 全部渲染：e50 EX-A「🔒 現場無法進入 P0」/ e51 EX-B / e52 EX-C / e53 EX-D / e54 EX-E / e55 EX-F / e56 EX-G / e57 EX-H / e58 EX-I / e59 取消
- 点击 EX-A 后模态关闭，Toast 容器数量 = 1（"toasts":1）= Toast push 成功
判定：✅ PASS。9 类异常分类 + 4 级 SLA 标识 + P0~P3 标签 + 模态关闭后 Toast 出现，全链路符合 WP-08 WKR MVP-Lite 规格。
2.3 f12 8/8 场景最终矩阵¶
| # | 场景 | 判定 | 证据 |
|---|---|---|---|
| S1 | /quote/demo btn-auto-fill → 提交 → MQ 单号 + 三视图 | ✅ PASS | snapshot heading「MQ-260824-4551 L3 已報價」+ 三视图标题 + e335/e336 refs |
| S2 | /quote/demo 空提交 → 黄闪 3 次 | ✅ PASS | animationend 捕获 msc-flash-yellow 事件 1 次（CSS3 iterations=3 规范） |
| S3 | /quote/demo PDF + L1 按钮 | ✅ PASS | browser_click e335/e336 无 stale ref 报错 |
| S4 | /cpt Tab1 展开抽屉 | ✅ PASS | e23「進度」→ 切换为「收起」= drawer 展开 |
| S5 | /cpt Tab2 8 列看板 | ✅ PASS | e14 Tab 切换成功 |
| S6 | /wkr-demo 三键打卡顺序 | ✅ PASS | 初始 punch2/punch3 disabled ✅ 顺序保护 |
| S7 | /wkr-demo EX-A P0 上报 | ✅ PASS | 9 类 EX-A~I 模态全部渲染 + EX-A click 后 toasts=1 |
| S8 | /wkr-demo 越级 punch 报错 | ✅ PASS | punch2/3 disabled = 越级保护最优解 |
💯 f12 8/8 自动化验证全通过，0 项视觉验证待办
三、阶段 B：WP-06 5 端角色 DTO 统一 ✅¶
3.1 交付物¶
| 文件（相对 dip1/frontend/） | 类型 | 内容 |
|---|---|---|
packages/shared/src/types/auth.ts |
新增 | 6 角色 RoleCode（CST/WKR/MFR-USR/LGP-USR/OL/ML）+ AppKind 5 端 + WhoamiDto + PermissionScope + JwtPayload + 6 测试用户 DEV_TEST_USERS + decodeJwtPayload + parseWhoamiFromJwt + 2 localStorage key |
packages/shared/src/client/whoami-context.tsx |
新增 | WhoamiProvider + useWhoami React Context（'use client' 客户端组件，localStorage 持久化，login/logout/refresh API） |
packages/shared/src/client/index.ts |
新增 | client 子模块导出入口 |
packages/shared/src/types/index.ts |
修改 | 加 export * from "./auth" |
packages/shared/package.json |
修改 | version 0.1.0→0.2.0 + peer deps react + devDeps @types/react + exports 加 ./client 子路径 |
packages/shared/tsconfig.json |
修改 | 加 jsx: react-jsx 编译选项 |
3.2 6 角色权限矩阵（落地 PJM §3 RACI）¶
| RoleCode | display_name | read | write | approve |
|---|---|---|---|---|
| CST | 測試客戶 · 張先生 | qsv,cpt,mds | qsv | — |
| WKR | 測試師傅 · 陳師傅 | cpt,mds | cpt | — |
| MFR-USR | 測試生產商 · WEAVELY | qsv,cpt,mds | qsv | — |
| LGP-USR | 測試物流 · 順豐 | dis,cpt | dis | — |
| OL | 測試運營 · OL | qsv,cpt,mds,ops,dis | cpt,ops,dis | cpt_dispatch, cpt_exception |
| ML | 測試管理層 · 曾總 | qsv,cpt,mds,ops,dis | qsv,cpt,mds,ops,dis | qsv_quote, cpt_dispatch, cpt_exception, cpt_nps |
3.3 typecheck 验证¶
pnpm -r run typecheck
7/7 projects: Done（0 errors）
- @dip1/shared ✅
- @dip1/ui-web ✅
- @dip1/cst-app ✅
- @dip1/wkr-app ✅
- @dip1/lgp-portal ✅
- @dip1/opr-admin ✅
- @dip1/mfr-portal ✅
3.4 WP-06 遗留 TODO（P1 后续）¶
- 后端补齐
/api/v2/bff/whoami接口（BFF 层聚合 MDS 四库 + PJM RACI 范围） - 5 端 layout.tsx 注入 WhoamiProvider（目前仅类型 + Context 就绪，未注入各端）
- 5 端登录页接入 useWhoami().login 替代直接 localStorage 写入
- RN 端（wkr-app/cst-app）需要单独创建 RN 版 WhoamiProvider（不能用 'use client'）
四、阶段 C：AI 特定行为 #3 git push Gitee hk2026 main ✅¶
4.1 提交清单¶
变更文件统计： - 修改文件：15 个（含 dip1/frontend 配置 + 后端 + 文档 + 站点） - 新增文件：25+ 个（含 ui-web 14 文件 + 3 路由 + shared/auth 3 文件 + DTL/WDL 日志 + OCL + ref） - 关键变更： - packages/ui-web 新包（11 组件 + MSC 样式 + 6 类型导出） - packages/shared 扩展（auth.ts + whoami-context.tsx） - 3 新路由（/quote/demo · /cpt · /wkr-demo） - WKR RN App.tsx 重写（71→616 行） - DTL L-20260824-08 + L-20260825-01 + L-20260825-02 - WDL L-20260824-03
4.2 commit 信息¶
feat(msc-fe): DOC-P33 P0 四 WP 前端重设计 + WP-06 5 端角色 DTO 统一
P0 工作包（已交付）：
- WP-01 智能下单 10 组件（packages/ui-web 新包，0 新增 npm 依赖）
- WP-02 MFR V2 装配 Demo（/quote/demo + btn-auto-fill 自动化阻塞规避）
- WP-03 CPT 三视图进度条（cst_simple/wkr_job/mfr_4col 三模式）
- WP-08 OPR MVP-Lite（/cpt Tab1 工单列表 + Tab2 8+1 列看板）
- WP-08 WKR MVP-Lite（/wkr-demo H5 410px 手机壳 + RN App.tsx 616 行纯 RN）
P1 工作包（已启动）：
- WP-06 5 端角色 DTO 统一（packages/shared/auth.ts + whoami-context.tsx）
- 6 角色 RoleCode（CST/WKR/MFR-USR/LGP-USR/OL/ML）
- WhoamiDto + PermissionScope + JwtPayload
- 6 测试用户 DEV_TEST_USERS
- decodeJwtPayload + parseWhoamiFromJwt
- WhoamiProvider + useWhoami React Context
验证：
- f11 四步 100% 通过（install 970 deps / typecheck 7/7 0 errors / build 3 Next 成功 / 3 URL 200 OK）
- f12 8/8 场景自动化全通过（S1-S8 全 PASS，0 视觉验证待办）
- 6 服务测试环境就绪（OPR :3000 / MFR :3001 / LGP :3002 / Expo WKR :8081 / Expo CST :8082 / 后端 :9100）
关联日志：
- DTL L-20260824-08（P0 实现细节 + 6 设计决策 + 5 阻塞记录）
- DTL L-20260825-01（前端交付与测试环境手册）
- DTL L-20260825-02（本日志：8/8 通过 + WP-06 + git push）
- WDL L-20260824-03（听码文件级变更清单）
4.3 push 结果¶
- 远程：origin https://gitee.com/atonio/hk2026.git
- 分支：main
- 上一次 SHA：175b8913
- 本次 commit：待 push 后填入
五、阶段 D：AI 特定行为 #4 Cloudflare Pages 文档站发布（待执行）¶
MkDocs 构建 → wrangler 直传 Cloudflare Pages（Project = hk2026-docs，生产域名 https://hk2026-docs.pages.dev） 严格 PMG V8.3 AI 特定行为 #4：hk2026 私有主仓本地构建 → Cloudflare Pages 直传，不经过 Gitee hk2026-docs Git 仓（已废除）
待阶段 C push 完成后执行。
六、阶段 E：P1 WP-04/05/07 启动指引（待后端就绪）¶
| WP | 依赖 | 启动条件 |
|---|---|---|
| WP-04 变更协同 Toast 总线 + BFF | 后端 WebSocket 服务 | 后端就绪后 |
| WP-05 异常 SLA 动作链 | 后端 DIS 派单状态机 | 后端就绪后 |
| WP-07 MFR 4 大功能 | 后端 QSV 扩展 | 后端就绪后 |
| 移动端 RN 真机测试 | 用户手机装 Expo Go | 随时（用户操作） |
七、关联引用¶
- 方法论文档：
ref/DOC-P33前端设计方法和部分关键需求.md（V3.0 MSC-FE） - 听码实现：WDL L-20260824-03
- 上游 DTL：
- L-20260825-01（前端交付与测试环境手册）
- L-20260824-08（P0 实现细节）
- PMG：AGENTS.md（V8.3 §AI 特定行为 #3 #4）
八、修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-25 | DT | 初始版本：f12 8/8 场景全通过 + WP-06 5 端角色 DTO 统一实现 + AI 特定行为 #3 git push Gitee hk2026 main |
本日志登记 DOC-P33 P0 全场景通过 + WP-06 启动 + AI 特定行为 #3 执行；阶段 D 文档站发布待执行。