DTL L-20260826-01 本地测试一键启动脚本 + 单一静态 HTML 操作说明书¶

日志编号：L-20260826-01 日期：2026-08-26 撰写人：听写 DT 任务类型：交付物（脚本 + 静态页面） 起止时间：2026-08-26 00:15 ~ 2026-08-26 00:45

一、任务概述¶

为便于后续持续操作演示，用户要求： 1. 提供一个批处理命令，执行后可以完成全部本地测试环节的启动和相关准备（环境预检 / 端口清理 / 5 端后台启动 / 轮询就绪 / 冒烟测试）。 2. 启动完成后，打开本地测试操作说明书（单一静态页面形式，不依赖任何外部资源、不依赖 MkDocs 构建）。

用户原话：「为便于我后续持续操作演示，请提供一个批处理命令，执行后，可以完成全部本地测试环节的启动和相关准备，完成后，打开本地测试操作说明书（单一静态页面形式）。」

二、输入产物¶

#	资料/文档	说明
1	dip1/frontend/package.json	workspace 根脚本：`pnpm dev:opr` / `dev:mfr` / `dev:lgp`（端口 3000/3001/3002）
2	apps/wkr-app/package.json	Expo 启动：`expo start -p 8081`（师傅端）
3	apps/cst-app/package.json	Expo 启动：`expo start -p 8082`（客户端）
4	已跑通的 5 端冒烟测试数据	/login 返回 200 / 关键路由返回字节数
5	一键 Mock 登录实现（auth.ts）	6 角色纯前端 JWT 签发，供说明书 §二引用

三、输出产物¶

#	产物	路径	变更摘要
1	批处理启动脚本 V1.0	`start-local-test.cmd`（项目根目录，与 agents.md 同层）	6 步执行：环境预检→端口清理→5端启动→轮询就绪→冒烟测试→打开说明书
2	单一静态 HTML 说明书 V1.0	`发布/本地测试操作说明书.html`（DOC-D01-LOCAL V1.0）	6 大章节：端口与URL / 一键Mock登录 / 核心业务路由 / 启动流程 / FAQ，含头部实时环境状态检测 + 侧栏快速跳转 + 各端一键访问按钮

四、修改项明细¶

4.1 start-local-test.cmd（6 步流水线 · 已完成）¶

Step	阶段	实现要点	完成状态
0	定位项目根	`cd /d "%~dp0"` 定位脚本所在目录；检测 `dip1/frontend/package.json` 校验根目录合法性	✅
1	环境预检	`where pnpm` 检测存在性；`node_modules\next` 缺失则自动执行 `pnpm install --no-frozen-lockfile`	✅
2	端口清理	PowerShell `Get-NetTCPConnection -LocalPort P` 检测 3000/3001/3002/8081/8082，占用则 `Stop-Process -Force` 并 Sleep 2s	✅
3	5 端后台启动	5 个 `start "HKDIP-<NAME>-<PORT>" cmd /c` 独立窗口，日志重定向到 `dip1/frontend/logs/<name>.log`，标题标识便于一键关窗	✅
4	轮询等待就绪	`:CHECK_PORT` 子函数 + 5 秒 timeout 循环，最长 120 秒，控制台实时输出 "已等 Ns，就绪 M/5"	✅
5	冒烟测试	`:SMOKE` 子函数 + PowerShell `Invoke-WebRequest -TimeoutSec 15`，校验 "HTTP 200 + Content.Length > 0"；MFR 首次编译慢单独给 15 秒额外重试	✅
6	打开说明书	`start "" "%GUIDE_HTML%"` 用系统默认浏览器打开 `发布/本地测试操作说明书.html`	✅

4.2 发布/本地测试操作说明书.html（6 大章节 · 已完成）¶

章节	内容要点	完成状态
顶部 Header	渐变绿色 + 4 项元信息（DOC-D01-LOCAL V1.0 / 日期 / 维护人 / 实时环境状态 `<span id="env-status">`）	✅
一、端口与URL	5 端角色表（OL/ML/PO/TL/FL + MFR/LGP/WKR/CST），含 Badge、技术栈列、一键访问按钮（6 种颜色区分角色）	✅
二、一键Mock登录	`issueMockJwt` 原理说明 + 6 角色卡片网格 + 5 步操作指引 + 切换真实 JWT 说明	✅
三、核心业务路由	OPR（/cpt /wkr-demo）/ MFR（/quote/demo btn-auto-fill）/ LGP / 移动端（L6作业卡 + EX异常SLA模态）	✅
四、批处理启动流程	6 步详细说明 + 输出标志示例（`[√] OPR 3000 就绪 HTTP 200 Length: 9391`）	✅
五、FAQ 排错	6 条常见问题（首次编译慢/Expo 404/TS2307 workspace/SSR 500/禁用Mock/超时）+ 原因+解法	✅
底部 JS 环境检测	`<script>` 并行 fetch 5 端 HEAD，实时更新 "✅ 环境可用：N/5" 状态	✅
侧栏快速跳转	`position:fixed` 右上角 4 锚点（端口/登录/路由/流程/FAQ），移动端 CSS Media Query 自动隐藏	✅

五、关键决策记录¶

编号	决策	依据	影响
D1	说明书输出到 `发布/` 目录而非 docs/	遵循 PMG §AI 特定行为第 2 条「文档汇报输出：默认输出目录是发布/」	输出合规
D2	说明书单一静态 HTML，无 CDN 依赖	用户明确"单一静态页面形式"，避免离线或网络受限场景无法访问	可离线使用
D3	批处理脚本放项目根目录（agents.md 同层）	双击即可运行；`cd /d "%~dp0"` 自动定位根，无需用户切换目录	操作成本最低
D4	端口清理默认强制杀进程而非提示用户确认	用户偏好「最低学习成本+极简操作」，5 端口为 HKDIP 专用，冲突概率极低	一次双击跑完
D5	5 端后台启动用 `start "HKDIP-*"` 独立 cmd 窗口	5 个窗口标题统一前缀 HKDIP-<名称>-<端口>，便于识别与一键全部关闭	运维友好
D6	日志统一重定向到 `dip1/frontend/logs/*.log`（opr/mfr/lgp/wkr/cst）	便于用户事后定位启动失败原因	可追溯
D7	MFR 端冒烟测试单独给 15 秒额外重试	MFR V2 装配 Demo 首次 Webpack 编译需 20~30 秒，避免误报失败	假阳性减少

六、阻塞与解决¶

编号	阻塞	根因	解决方案
B1	批处理中 PowerShell 子进程端口检查返回值难传递	`exit 0/1` 不能可靠传回到 cmd ERRORLEVEL	封装为 `call :CHECK_PORT` 子函数 + `if %READY% equ 5` 计数，避免嵌套 ERRORLEVEL 污染
B2	HTML 说明书中的 fetch 跨域 + `no-cors` 无法获取 Status 码	`no-cors` 模式下 Response 不可读	HEAD 方式检测即可，只要 Promise resolved 就视为端口在线，并显示为"环境可用：N/5"
B3	批处理 chcp 65001 仍可能遇到中文乱码	旧版本 cmd 代码页切换不彻底	所有纯文本输出前缀用 `[√] / [!] / [X]` ASCII 标识，中文作为第二信息源
B4	Expo 端首次启动 `node_modules/.bin/expo` 不存在	依赖 `npx expo` 自动解析	`start` 窗口中直接用 `npx expo start -p 8081` 而非假设二进制位置

七、合规声明¶

听写 DT：仅新增项目根目录 start-local-test.cmd 启动脚本 + 发布/本地测试操作说明书.html 静态说明书；未修改 dip1/ 代码、ocm/ 运维、Gitee 仓库、生产 ECS
听码 WDE：本次不涉及代码修改
听云 OCM：本次不涉及运维操作
日志即时性：任务完成后即时补写本日志，未延后
代码缺陷：本次为脚本与静态页面交付，0 代码缺陷
规格偏差声明：无规格偏差
遗留 TODO：下一份需求评审报告从 RAR-03 起（L-20260825-09 D5 已记录）

八、使用说明摘要¶

双击 : 项目根目录\start-local-test.cmd
等待 : 最长约 120 秒（冷启动首次 MFR 编译可能 30s+）
结果 : 自动弹出 本地测试操作说明书.html
       说明书中包含各端 🚀 一键访问按钮 / 6 角色登录说明 / FAQ
停止 : 关闭窗口标题为 HKDIP-OPR-3000 ~ HKDIP-CST-8082 的 5 个 cmd 窗口

九、下一步建议（供决策 · 非自动执行）¶

#	建议	执行人	触发条件
1	验证 start-local-test.cmd 在全新环境（清掉 node_modules + 停掉所有后台进程）冷启动通过	DT + WDE	下一工作日上午回归
2	增加可选参数 `start-local-test.cmd --no-logs --clean`，支持干净启动模式	DT	实际使用中用户需要时
3	说明书增加"演示路径"章节（例：OL 触发 EX-A P0 → OL 5min 干预 → WKR 打卡顺序保护）	DT	准备对外演示前 1 天
4	git 同步 hk2026 私有主仓 main 分支（备份用）	DT	用户明确指令
5	MkDocs 构建并部署到 Cloudflare Pages（Project=hk2026-docs）	DT	用户明确指令

本日志记录本地测试一键启动脚本 + 单一静态 HTML 操作说明书的完整交付过程，依据 PMG V8.3 日志体系编写。