# 健康CQ升级 - 高保真交互原型 ## 项目概述 本项目以 HTML 方式生成「健康CQ升级」平台的高保真交互原型，覆盖 Web 管理端、员工端 APP、健康应急 APP 三大终端，用于需求确认、交互评审及后续导入墨刀进行团队协作。 --- ## 一、项目结构规范 ### 1.1 顶层目录结构 ``` prototype-user-app/ ├── index.html # 全局导航页（项目入口） ├── web-admin/ # Web 管理端原型 ├── employee-app/ # 员工端 APP 原型 ├── emergency-app/ # 健康应急 APP 原型 ├── other-terminals/ # 其他终端原型（小程序、大屏、PAD、餐厅的终端设备） ├── 项目背景.md # 本文件 - 项目约束与规范 └── README.md # 项目说明 ``` ### 1.2 全局导航页（index.html） 根目录 `index.html` 作为项目统一入口，部署到服务器后供研发人员浏览所有原型页面。 - 通过 Tab 切换四大板块（Web 管理端 / 员工端 APP / 健康应急 APP / 其他终端） - 以模块卡片展示各业务模块，点击卡片跳转至该模块主页（index.html） - 点击卡片右上角页数徽章，悬浮展示该模块所有页面和弹窗的跳转链接 - 已有原型的模块卡片带绿色边框呼吸灯动画，待开发模块为虚线灰色卡片 - 数据驱动：所有模块和页面信息维护在 `SITE_MAP` JS 对象中 - **新增原型页面时，必须同步在 `index.html` 的 `SITE_MAP` 中添加对应条目** ### 1.3 各端内部按核心功能模块分目录 **员工端 APP（employee-app/）17 个模块** ``` employee-app/ ├── ai/ # AI ├── home/ # 应用主页 ├── health-checkup/ # 健康体检 ├── weight-management/ # 体重管理 ├── nutrition/ # 营养管理 ├── exercise/ # 运动管理 ├── health-monitor/ # 健康监测 ├── health-assessment/ # 健康评估 ├── cardiovascular/ # 心脑血管病预防 ├── diabetes/ # 糖尿病预防 ├── cancer/ # 癌症预防 ├── health-consult/ # 健康咨询 ├── emergency-medical/ # 应急就医 ├── frontline-medical/ # 一线医疗 ├── health-record/ # 健康档案 ├── knowledge/ # 知识普及 └── profile/ # 个人中心 ``` **Web 管理端（web-admin/）16 个模块** ``` web-admin/ ├── system-management/ # 系统管理 ├── health-checkup/ # 健康体检 ├── weight-management/ # 体重管理 ├── nutrition/ # 营养管理 ├── exercise/ # 运动管理 ├── health-monitor/ # 健康监测 ├── health-assessment/ # 健康评估 ├── knowledge/ # 知识普及 ├── health-data/ # 健康数据 ├── health-record/ # 健康档案 ├── cardiovascular/ # 心脑血管病预防 ├── diabetes/ # 糖尿病预防 ├── cancer/ # 癌症预防 ├── health-consult/ # 专家咨询 ├── emergency-dispatch/ # 应急就医 └── frontline-medical/ # 一线医疗 ``` **健康应急 APP（emergency-app/）** 底部固定 5 个 Tab：工作台、知识库、AI助手、消息（即时通讯）、我的。 6 种角色登录后看到的工作台、知识库、我的内容不同，AI助手和消息全角色共享。 | 角色 | 英文标识 | 说明 | |------|---------|------| | 咨询专家 | expert | 专业医师/健康管理师，接收咨询、回复问题 | | 应急操作人员 | operator | 负责应急事件的调度与操作执行 | | 应急专业人员 | professional | 参与应急响应的专业技术人员 | | 应急驻场人员 | onsite | 驻扎在现场的应急保障人员 | | 咨询小助手 | assistant | 辅助答疑、常见问题推送、数据统计 | | 管理员 | admin | 应急APP端的管理与配置人员 | 目录按角色优先组织，每个角色包含自己的工作台、知识库、我的页面： ``` emergency-app/ ├── expert/ # 咨询专家（角色目录） │ ├── workbench/ # 工作台页面 │ ├── knowledge/ # 知识库页面 │ └── profile/ # 我的页面 ├── operator/ # 应急操作人员 │ ├── workbench/ │ ├── knowledge/ │ └── profile/ ├── professional/ # 应急专业人员 │ ├── workbench/ │ ├── knowledge/ │ └── profile/ ├── onsite/ # 应急驻场人员 │ ├── workbench/ │ ├── knowledge/ │ └── profile/ ├── assistant/ # 咨询小助手 │ ├── workbench/ │ ├── knowledge/ │ └── profile/ ├── admin/ # 管理员 │ ├── workbench/ │ ├── knowledge/ │ └── profile/ │ ├── ai-assistant/ # AI助手（全角色共享） │ └── index.html │ └── message/ # 消息 - 即时通讯聊天（全角色共享） ├── index.html ├── contacts.html └── im-chat.html ``` **其他终端（other-terminals/）** 包含微信小程序、应急大屏、医疗点PAD端、体检医生工作台等独立交付产物。 ``` other-terminals/ ├── mini-program/ # 微信小程序（营养管理用户端） ├── emergency-screen/ # 应急大屏 │ ├── xian-center/ # 西安应急中心大屏 │ ├── standard-center/ # 标准版中心大屏 │ └── jiuchang-center/ # 九厂应急中心大屏 ├── medical-pad/ # 医疗点PAD端 └── canteen-device/ # 餐厅终端设备 ├── index.html # 模块导航页 ├── canteen-nutrition-scale/ # 餐线营养秤 │ ├── index.html │ ├── 01-meal-start.html │ ├── 02-meal-replenish.html │ ├── 03-dish-display.html │ ├── 04-meal-pickup.html │ ├── 05-settings.html │ └── 06-dish-sampling.html ├── canteen-recharge-screen/ # 餐线充值屏 ├── checkout-device/ # 结算设备 ├── clean-veg-inventory-cabinet/ # 净菜库存柜 ├── clean-veg-kitchen-cabinet/ # 净菜厨房柜 ├── clean-veg-packaging-labeler/ # 净菜包装贴标机 ├── clean-veg-ratio-scale/ # 净菜配比秤 ├── food-safety-monitor/ # 食安监控设备 ├── nutrition-score-screen/ # 营养得分屏 ├── plate-dispenser/ # 吐盘机 ├── processing-prompt-screen/ # 加工提示屏 ├── ratio-scale/ # 配比秤 ├── raw-veg-hygiene-inspection/ # 毛菜卫检设备 ├── raw-veg-inspection-scale/ # 毛菜验收秤 ├── raw-veg-inventory-cabinet/ # 毛菜库存柜 ├── raw-veg-processing-scale/ # 加工毛菜秤 ├── raw-veg-washing-scale/ # 毛菜清洗秤 ├── stall-nutrition-scale/ # 档口营养秤 └── utility-meter/ # 水电气计量表 ``` **canteen-device 各子设备文件夹中文对照表：** | 英文路径 | 中文名称 | 说明 | |---------|---------|------| | `canteen-nutrition-scale` | 餐线营养秤 | 开餐、补餐、取餐、餐品展示、设置、采样 | | `canteen-recharge-screen` | 餐线充值屏 | 餐卡充值与余额查询 | | `checkout-device` | 结算设备 | 智能结算与支付 | | `clean-veg-inventory-cabinet` | 净菜库存柜 | 净菜库存管理与盘点 | | `clean-veg-kitchen-cabinet` | 净菜厨房柜 | 净菜暂存与保鲜存储 | | `clean-veg-packaging-labeler` | 净菜包装贴标机 | 净菜自动包装与贴标打印 | | `clean-veg-ratio-scale` | 净菜配比秤 | 净菜搭配称重与营养配比 | | `food-safety-monitor` | 食安监控设备 | 食品安全监控与预警 | | `nutrition-score-screen` | 营养得分屏 | 个人营养评分与健康建议 | | `plate-dispenser` | 吐盘机 | 自动出盘与回盘管理 | | `processing-prompt-screen` | 加工提示屏 | 加工流程提示与操作指引 | | `ratio-scale` | 配比秤 | 食材精准配比称重 | | `raw-veg-hygiene-inspection` | 毛菜卫检设备 | 毛菜卫生检测与质量判定 | | `raw-veg-inspection-scale` | 毛菜验收秤 | 毛菜到货验收与质检 | | `raw-veg-inventory-cabinet` | 毛菜库存柜 | 毛菜库存管理与出入库 | | `raw-veg-processing-scale` | 加工毛菜秤 | 毛菜初加工称重与记录 | | `raw-veg-washing-scale` | 毛菜清洗秤 | 毛菜清洗流程与称重管理 | | `stall-nutrition-scale` | 档口营养秤 | 档口菜品营养分析与称重结算 | | `utility-meter` | 水电气计量表 | 水电气能耗计量与统计 | --- ## 二、HTML 原型编写规范 ### 2.1 文件粒度原则（核心约束） > **每个独立的页面、弹窗、浮层、操作面板必须是独立的 `.html` 文件。** 这是为了兼容墨刀导入（通过 `modao-proto-mcp` 的 `import_html` 工具），墨刀以单个 HTML 文件为粒度创建页面。 - **页面**：每个可导航的页面 → 独立 `.html` 文件 - **弹窗/对话框**：每个模态弹窗 → 独立 `.html` 文件，命名如 `xxx-dialog.html` - **浮层/操作面板**：底部弹出面板、下拉菜单等 → 独立 `.html` 文件，命名如 `xxx-panel.html` - **状态变体**：同一页面的不同状态（空状态、加载中、错误态）如差异较大 → 独立文件，命名如 `xxx-empty.html`、`xxx-loading.html` ### 2.2 单文件结构规范 每个 `.html` 文件必须是完整的、可独立在浏览器中打开的自包含文件： ```html [模块名] - [页面名] | 健康CQ原型 ``` **关键要求：** - CSS 和 JS 全部内联，禁止引用外部文件（确保墨刀导入兼容性） - 图片优先使用 SVG 内联或 CSS 绘制的图形占位，避免外部图片依赖 - 图标使用 SVG 内联或 Unicode/Emoji 占位 ### 2.3 APP 端原型视觉规范 APP端（员工端、应急端）使用手机壳模拟器包裹： ``` 设备尺寸: 390 x 844 (iPhone 14 逻辑分辨率) 外壳圆角: 44px 状态栏高度: 44px 底部安全区: 34px 导航栏高度: 44px 底部Tab栏高度: 50px + 34px安全区 ``` ### 2.4 Web 端原型视觉规范 Web管理端使用标准后台布局： ``` 最小宽度: 1280px 侧边栏宽度: 240px（折叠态 64px） 顶部导航高度: 56px 内容区内边距: 24px ``` ### 2.5 其他终端原型视觉规范 **微信小程序（营养管理用户端）**使用手机壳模拟器包裹： ``` 设备尺寸: 375 x 812 (iPhone X 逻辑分辨率) 外壳圆角: 44px 状态栏高度: 44px 底部安全区: 34px 导航栏高度: 44px 底部Tab栏高度: 50px + 34px安全区 ``` **应急大屏**使用全屏深色背景布局： ``` 设计尺寸: 1920 x 1080 (Full HD) 背景色: 深色渐变（#0a1628 → #0f2847） 字体色: 浅色系（主文字 #E0F0FF，次要 #8CB8D9） 数据可视化风格，无外壳包裹 ``` **医疗点PAD端**使用平板横屏布局： ``` 设计尺寸: 1024 x 768 (iPad 横屏) 外壳圆角: 24px 状态栏高度: 24px 导航栏高度: 48px 内容区内边距: 20px ``` **体检医生WEB工作台**与Web管理端共用布局规范： ``` 最小宽度: 1280px 侧边栏宽度: 240px（折叠态 64px） 顶部导航高度: 56px 内容区内边距: 24px ``` ### 2.6 统一设计令牌 ```css /* 品牌色 */ --primary: #1890FF; /* 主色 */ --primary-light: #E6F7FF; /* 主色浅底 */ --success: #52C41A; /* 成功 */ --warning: #FAAD14; /* 警告 */ --danger: #FF4D4F; /* 危险 */ /* 中性色 */ --text-primary: #333333; /* 主文字 */ --text-secondary: #666666; /* 次要文字 */ --text-placeholder: #999999; /* 占位文字 */ --border: #E8E8E8; /* 边框 */ --background: #F5F7FA; /* 页面背景 */ /* 字号 */ --font-xs: 11px; --font-sm: 13px; --font-base: 15px; --font-lg: 17px; --font-xl: 20px; --font-xxl: 24px; /* 圆角 */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; /* 阴影 */ --shadow-sm: 0 1px 4px rgba(0,0,0,0.08); --shadow-md: 0 4px 12px rgba(0,0,0,0.12); --shadow-lg: 0 8px 24px rgba(0,0,0,0.16); ``` --- ## 三、交互效果规范 ### 3.1 必须实现的交互 - **页面导航**：点击按钮/链接可跳转至对应页面（通过 `window.location.href` 或页内锚点切换） - **Tab 切换**：底部 Tab 栏、顶部 Tab 栏的选中态切换 - **弹窗展示**：点击触发弹窗的元素时，展示弹窗的打开态（弹窗为独立文件，在预览时可用 overlay 模拟） - **表单交互**：输入框聚焦态、按钮点击态、单选/多选切换 - **列表滚动**：内容区可滚动，导航栏/Tab 栏固定 - **下拉刷新/加载更多**：提供视觉占位表现 ### 3.2 页面间跳转约定 由于每个页面是独立文件，页面间通过相对路径跳转： ```javascript // 同模块内跳转 window.location.href = './detail.html'; // 跨模块跳转 window.location.href = '../health-consult/consult-list.html'; // 弹窗页面（在当前页面中以 iframe 或 overlay 方式展示） // 建议在页面内通过注释标注关联的弹窗文件 // ``` ### 3.3 交互注释标注 在 HTML 中使用注释标注交互说明，便于评审和墨刀导入后的理解： ```html
全部
``` ### 3.4 表格操作列固定规则 - 所有列表/表格中包含「操作」列的，操作列必须使用 `position:sticky;right:0` 固定在表格右侧 - 确保横向滚动时操作列始终可见，不会因列表内容过多而被遮挡 - 操作列需添加左侧阴影（`box-shadow:-4px 0 8px rgba(0,0,0,0.04)`）以区分固定区域 - thead 的操作列表头同样需要 sticky 固定 - 操作列 td 添加 class `td-actions`，并设置白色背景避免内容穿透 --- ## 四、命名规范 ### 4.1 文件命名 - 全部使用**小写英文 + 短横线**连接：`consult-detail.html` - 页面文件：`{功能名}.html`，如 `consult-list.html` - 弹窗文件：`{功能名}-dialog.html`，如 `filter-dialog.html` - 面板文件：`{功能名}-panel.html`，如 `sort-panel.html` - 状态变体：`{功能名}-{状态}.html`，如 `list-empty.html` - 模块入口：统一使用 `index.html` ### 4.2 CSS 类命名 采用 BEM 风格，简洁明了： ```css .consult-card { } .consult-card__title { } .consult-card__status--resolved { } ``` --- ## 五、墨刀导入兼容约束 ### 5.1 导入方式 通过已配置的 `modao-proto-mcp` MCP 服务，使用 `import_html` 工具将单个 HTML 文件导入墨刀项目。 ### 5.2 兼容性要求 - **自包含**：每个 HTML 不得引用外部 CSS/JS/图片资源 - **单页面**：每个 HTML 文件仅包含一个页面/弹窗的内容 - **固定尺寸**：APP端页面内容区域控制在 390×844 内；Web端不设固定高度 - **简洁 DOM**：避免过度嵌套（建议不超过 8 层），墨刀解析有层级限制 - **内联 SVG**：图标和简单图形使用内联 SVG，复杂图形使用 CSS 绘制或色块占位 --- ## 六、项目背景参考 ### 6.1 项目背景 原健康CQ项目是CQ能源公司内部使用的综合性员工健康管理服务平台，旨在整合健康咨询、应急就医、健康体检、档案管理、健康监测、系统管理、健康干预、健康评估、一线医疗点及体重管理等多元功能，为能源员工提供全周期的健康保障。 ### 6.2 用户群体 | 用户角色 | 角色定义 | 对应原型端 | |---------|---------|-----------| | 能源员工 | CQ能源一线员工及管理人员 | 员工端 APP | | 平台管理员 | 健康管理部门后台运营人员 | Web 管理端 | | 健康咨询专家 | 专业医师/健康管理师 | 健康应急 APP | | 应急就医服务人员 | 应急调度与协调人员 | 健康应急 APP | | 营养管理用户 | 通过小程序进行营养管理的员工 | 微信小程序 | | 体检医生 | 负责体检检查的医生 | 体检医生工作台 | | 医疗点医护人员 | 一线医疗点驻点医护 | 医疗点PAD端 | | 应急中心值班人员 | 应急指挥中心大屏监控人员 | 应急大屏 | ### 6.3 核心业务模块 | 模块 | 业务概述 | 所属端 | |-----|---------|-------| | 系统管理 | 用户管理、角色权限、组织架构、系统配置 | Web 管理端 | | 健康体检 | 体检预约、报告管理、历年数据对比 | 员工端 APP / Web 管理端 | | 体重管理 | 体重记录、目标设定、进度追踪 | 员工端 APP / Web 管理端 | | 营养管理 | 用餐记录、膳食指导、营养分析 | 员工端 APP / Web 管理端 | | 运动管理 | 运动数据记录、目标设定、运动计划 | 员工端 APP / Web 管理端 | | 健康监测 | 智能手表采集心率、血压、血氧、睡眠数据 | 员工端 APP / Web 管理端 | | 健康评估 | 健康风险评估报告，识别风险等级 | 员工端 APP / Web 管理端 | | 知识普及 | 健康资讯、科普文章、视频课程 | 员工端 APP / Web 管理端 | | 健康数据 | 健康数据可视化与统计分析 | Web 管理端 | | 健康档案 | 统一归集健康数据，形成个人健康时间轴 | 员工端 APP / Web 管理端 | | 心脑血管病预防 | 心脑血管疾病风险筛查与预防管理 | 员工端 APP / Web 管理端 | | 糖尿病预防 | 糖尿病风险筛查与预防管理 | 员工端 APP / Web 管理端 | | 癌症预防 | 癌症风险筛查与预防管理 | 员工端 APP / Web 管理端 | | 健康咨询/专家咨询 | 在线健康咨询，支持图文与视频咨询 | 员工端 APP / 健康应急 APP / Web 管理端 | | 应急就医 | 应急申请、资源调度、进度跟踪的全流程管理 | 员工端 APP / 健康应急 APP / Web 管理端 | | 一线医疗 | 一线医疗点服务与管理 | 员工端 APP / Web 管理端 | | AI | 智能健康助手，AI问答与健康建议 | 员工端 APP | | 营养管理小程序 | 员工端营养管理微信小程序 | 微信小程序 | | 应急大屏 | 应急指挥中心数据可视化大屏 | 应急大屏（西安/标准版/九厂） | | 医疗点PAD | 一线医疗点平板端服务系统 | 医疗点PAD端 | | 体检医生工作台 | 体检医生检查与报告录入 | 体检医生WEB工作台 | --- ## 七、模块文档规范 ### 7.1 文档要求 每个一级功能模块目录下必须创建 `doc/` 子目录，维护以下两个文档： | 文件 | 用途 | 更新时机 | |------|------|----------| | `doc/CHANGELOG.md` | 变更记录 | 每次提交代码前自动整理并追加 | | `doc/PRD.md` | 产品需求文档 | **用户明确要求时**才编写或更新，不随原型修改自动同步 | ### 7.2 CHANGELOG.md 格式规范 - 按时间倒序排列，最新变更在最前 - 每条记录格式：`## [YYYY-MM-DD] type: 变更摘要` - type 取值：`init`（初始化）、`feat`（新增）、`fix`（修复）、`refactor`（重构） - 列出涉及的文件及具体变更说明 ### 7.3 PRD.md 编写规范 面向研发人员的产品需求文档，要求简洁、条理清晰，包含以下结构： 1. **模块概述**：一段话简要说明模块功能 + 页面导航结构树 + 状态流转图（Mermaid） 2. **页面清单**：表格列出所有功能页面、弹窗、内嵌功能页、结果态页面，页面清单根据业务分类（同一个PRD文档内公用的页面不重复罗列） 3. **逐页说明**：自动按业务流程顺序组织，WEB后台按一级菜单顺序分类罗列，APP端按每个业务线分类罗列，每个页面/弹窗/内嵌功能页/结果态页面包含以下维度： - **页面截图**：在标题下方紧跟截图引用（格式见 7.4） - **功能说明**：页面用途和核心 UI 元素 - **业务规则**：数据逻辑、状态约束、边界条件 - **交互说明**：以文字列表形式描述各元素的交互行为和跳转目标，跳转目标使用中文页面名称（如"跳转到专家主页"），不使用文件名 4. **表单字段表**：含表单提交的页面，以表格列出字段名、类型、是否必填、校验规则 ### 7.4 PRD 页面截图规范 为提升文档可读性，PRD 中每个页面说明需附带页面截图。 **截图生成方式：** - 使用浏览器自动化工具（如 Playwright、Puppeteer、Chrome DevTools 等）对 HTML 原型文件进行截图 - APP 端截图流程： 1. 通过脚本移除 `.phone-shell` 固定高度限制（`height: auto`）、移除圆角和阴影、将 `.page-content` 的 `overflow` 设为 `visible`，使内容完整展开 2. 设置视口宽度为 390px（与 phone-shell 一致），高度匹配内容实际高度 3. 截取全页面长图 - Web 端截取完整页面，视口 1440×900，设备缩放 1x - 输出格式：JPEG（质量 85%），兼顾清晰度与文件体积 - 截图体积：Web ≤ 80KB、小程序 ≤ 60KB、硬件 ≤ 80KB；优先 Puppeteer，失真时降级 chrome-devtools MCP **截图存放：** - 统一存放在模块的 `doc/screenshots/` 目录下 - 文件名与原型 HTML 文件名一致（去掉 `.html` 后缀），如 `find-expert.jpg` - 内嵌于其他页面的弹窗无需单独截图，在页面清单中标注即可 **PRD 中引用方式：** - 在每个页面/弹窗的三级标题下方紧跟插入：`![页面截图](screenshots/xxx.jpg)` - 使用相对路径（基于 `doc/` 目录），`_templates/md-viewer.html` 会自动补全为完整路径 **截图更新时机：** - 与 PRD 文档同步，仅在用户明确要求更新 PRD 时重新截取