platform-prototype/项目背景.md

健康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 文件必须是完整的、可独立在浏览器中打开的自包含文件：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[模块名] - [页面名] | 健康CQ原型</title>
  <style>
    /* 所有样式内联，不依赖外部 CSS 文件 */
  </style>
</head>
<body>
  <!-- 页面内容 -->
  <script>
    /* 交互逻辑内联，不依赖外部 JS 文件 */
  </script>
</body>
</html>

关键要求：

• 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 统一设计令牌

/* 品牌色 */
--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 页面间跳转约定

由于每个页面是独立文件，页面间通过相对路径跳转：

// 同模块内跳转
window.location.href = './detail.html';

// 跨模块跳转
window.location.href = '../health-consult/consult-list.html';

// 弹窗页面（在当前页面中以 iframe 或 overlay 方式展示）
// 建议在页面内通过注释标注关联的弹窗文件
// <!-- 关联弹窗: ./filter-dialog.html -->

3.3 交互注释标注

在 HTML 中使用注释标注交互说明，便于评审和墨刀导入后的理解：

<!-- [交互] 点击跳转至: ../health-record/detail.html -->
<div class="card" onclick="location.href='../health-record/detail.html'">

<!-- [交互] 点击打开弹窗: ./filter-dialog.html -->
<button onclick="openDialog()">筛选</button>

<!-- [状态] 当前为: 已选中态 -->
<div class="tab active">全部</div>

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 风格，简洁明了：

.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 时重新截取