From db5fb8862789dd658c68f936a1a928480f089aa0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=8E=E4=BD=97?= Date: Sat, 6 Jun 2026 11:12:02 +0800 Subject: [PATCH] =?UTF-8?q?docs(specs):=20=E6=B7=BB=E5=8A=A0UI=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E9=93=81=E5=BE=8B=E6=B3=95=E5=88=99=20-=20=E5=8D=81?= =?UTF-8?q?=E5=A4=A7=E8=AE=BE=E8=AE=A1=E6=B3=95=E5=88=99+=E5=8C=BB?= =?UTF-8?q?=E7=96=97HIS=E4=B8=93=E9=A1=B9=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 MD/specs/UI_DESIGN_IRON_RULES.md (404行) - 十大UI设计铁律法则: 希克/费茨/米勒/雅各布/格式塔/多赫蒂/尼尔森/泰斯勒/峰终/冯雷斯托夫 - HIS医疗系统专项UI规范: 色彩体系/间距系统/字体/表格/表单/弹窗/交互反馈 - 医疗特殊交互: 危急值/医嘱/处方/费用/电子签名/打印 - 设计文档必备模板: UI布局+交互清单+调用流程+状态流转+异常处理 - 违反检查清单 - 更新铁律体系 - RULES.md: 新增铁律14 - 设计文档必须包含UI设计和调用流程 - MD/specs/IRON_RULES.md: 新增铁律#9详细说明 - MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md: 新增UI设计法则速查表 - 同步7个AI工具配置: AGENTS.md/.cursorrules/.copilot/.windsurf/.cline/.qwen/.aider --- .aider.conf.yml | 14 +- .clinerules | 16 +- .cursorrules | 16 +- .github/copilot-instructions.md | 16 +- .qwenrules | 16 +- .windsurfrules | 16 +- AGENTS.md | 16 +- MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md | 31 ++ MD/specs/IRON_RULES.md | 34 ++ MD/specs/UI_DESIGN_IRON_RULES.md | 404 ++++++++++++++++++++++ RULES.md | 14 +- 11 files changed, 571 insertions(+), 22 deletions(-) create mode 100644 MD/specs/UI_DESIGN_IRON_RULES.md diff --git a/.aider.conf.yml b/.aider.conf.yml index 813660372..f44f5264a 100644 --- a/.aider.conf.yml +++ b/.aider.conf.yml @@ -76,7 +76,7 @@ instructions: | - 这是诚实原则，不是效率问题 - **铁律11: 设计文档确认后自主开发（铁律）** + **铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -92,13 +92,23 @@ instructions: | **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 - **铁律11: 文档统一管理** + **铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + + **铁律14: 设计文档必须包含UI设计和调用流程** + - 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 + - 没有明确UI设计的模块，禁止直接编码 + - 详见 + - 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 + - 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + + --- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 diff --git a/.clinerules b/.clinerules index cf36b1b6a..1f654c008 100644 --- a/.clinerules +++ b/.clinerules @@ -78,7 +78,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -94,13 +94,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -476,4 +486,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/.cursorrules b/.cursorrules index f21e4ad2a..8a47889ff 100644 --- a/.cursorrules +++ b/.cursorrules @@ -78,7 +78,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -94,13 +94,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -476,4 +486,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1c3fda641..2dcafd07c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -78,7 +78,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -94,13 +94,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -476,4 +486,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/.qwenrules b/.qwenrules index 490b5900d..c4000163b 100644 --- a/.qwenrules +++ b/.qwenrules @@ -78,7 +78,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -94,13 +94,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -476,4 +486,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/.windsurfrules b/.windsurfrules index 521067a99..5c4df8653 100644 --- a/.windsurfrules +++ b/.windsurfrules @@ -78,7 +78,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -94,13 +94,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -476,4 +486,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/AGENTS.md b/AGENTS.md index fd81dfa6f..98c81eb5c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,7 +79,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -95,13 +95,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。 @@ -477,4 +487,4 @@ git status && git add -A && git commit -m "feat(module): desc" && git push origi --- -> 📅 最后同步: 2026-06-06 11:05 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` +> 📅 最后同步: 2026-06-06 11:11 | 源文件: RULES.md | 重新同步: `bash scripts/sync-ai-rules.sh` diff --git a/MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md b/MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md index 0e5377d68..d4a6e342c 100644 --- a/MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md +++ b/MD/specs/FRONTEND_DEVELOPMENT_STANDARD.md @@ -521,3 +521,34 @@ test('registration flow', async ({ page }) => { > **文档版本**: v1.0 > **最后更新**: 2026-06-06 + + +--- + +## 七、UI设计铁律法则 + +> 所有前端页面设计和开发必须遵守以下法则，详见 `MD/specs/UI_DESIGN_IRON_RULES.md` + +### 核心设计法则速查 + +| 法则 | 核心思想 | HIS应用 | +|------|---------|---------| +| 希克定律 | 选项越少决策越快 | 菜单≤7项，表单≤12字段 | +| 费茨定律 | 目标大且近操作快 | 按钮≥44px，危险操作远离安全操作 | +| 米勒定律 | 记忆负荷≤7±2 | 信息分组，Tab≤6个 | +| 雅各布定律 | 遵循用户已有习惯 | 若依标准布局模式 | +| 格式塔原则 | 视觉分组要清晰 | 间距系统、颜色体系 | +| 多赫蒂阈值 | 响应<400ms | loading态、骨架屏、分页 | +| 尼尔森十大原则 | 全面可用性 | 操作反馈、防错、容错 | +| 泰斯勒定律 | 复杂性守恒 | 智能默认值、常用模板 | +| 峰终定律 | 关键时刻做好 | 成功动画、错误优雅处理 | +| 冯·雷斯托夫 | 不同的更容易记住 | 危急值红色脉冲、徽标通知 | + +### 设计文档必备 + +每个新页面/模块的设计文档必须包含： +1. 页面UI布局描述（组件位置、栅格、比例） +2. 交互效果清单（每个操作→效果→反馈） +3. 前后端调用流程（操作→API→处理链→渲染） +4. 状态流转图 +5. 异常/边界处理方案 diff --git a/MD/specs/IRON_RULES.md b/MD/specs/IRON_RULES.md index 3c5bb1cd9..f93248310 100644 --- a/MD/specs/IRON_RULES.md +++ b/MD/specs/IRON_RULES.md @@ -20,6 +20,7 @@ | #6 | 测试通过后才提交 | P0 | 代码提交 | | #7 | 前后端API路径对齐 | P0 | 接口开发 | | #8 | 铁律和规范文档放MD目录 | P1 | 规范文档 | +| #9 | 设计文档必须包含UI设计和调用流程 | P0 | 设计文档/前端开发 | --- @@ -265,3 +266,36 @@ npm run lint > **文档版本**: v2.0 > **最后更新**: 2026-06-06 + + +--- + +### 铁律 #9: 设计文档必须包含UI设计和调用流程 + +**所有新模块/页面的设计文档必须包含以下要素，缺一不可：** + +#### 必备要素 + +| # | 要素 | 说明 | +|---|------|------| +| 1 | 页面UI布局 | 每个区域放什么组件、尺寸比例、栅格布局（文字描述或线框图） | +| 2 | 交互效果清单 | 每个按钮/操作触发什么效果（弹窗、抽屉、跳转、动画） | +| 3 | 前后端调用流程 | 每个用户操作 → 对应API → 参数 → 返回数据 → 前端渲染 | +| 4 | 系统调用关系 | Controller → AppService → Service → Mapper 完整链路 | +| 5 | 方法函数调用关系 | 关键方法签名、参数、返回值、异常处理 | +| 6 | 状态流转图 | 数据状态变化 → UI如何响应 | +| 7 | 异常/边界处理 | 空数据、加载中、错误状态的UI表现 | + +#### 前后端调用流程模板 + +``` +用户操作: [具体按钮/操作] + → 前端: [HTTP方法] [API路径] {参数} + → 后端: Controller.method() → AppService.method() → Service.method() → Mapper.method() + → 返回: {code, msg, data} + → 前端: [渲染逻辑] +``` + +#### 详细规范 +参见 `MD/specs/UI_DESIGN_IRON_RULES.md` + diff --git a/MD/specs/UI_DESIGN_IRON_RULES.md b/MD/specs/UI_DESIGN_IRON_RULES.md new file mode 100644 index 000000000..492523842 --- /dev/null +++ b/MD/specs/UI_DESIGN_IRON_RULES.md @@ -0,0 +1,404 @@ +# HealthLink-HIS UI 设计铁律 + +> **文档类型**: 设计规范 +> **适用范围**: 全项目前端UI设计与交互 +> **版本**: v1.0 +> **编制日期**: 2026-06-06 +> **最后更新**: 2026-06-06 + +--- + +## 一、总则 + +> **设计文档必须写清楚：前端页面UI布局、交互效果、前后端调用流程。** +> 没有明确UI设计的模块，禁止直接编码。 + +### 设计文档必备要素 + +每个新模块/页面的设计文档必须包含： + +| # | 要素 | 说明 | +|---|------|------| +| 1 | **页面线框图/布局描述** | 每个区域放什么组件、尺寸比例、栅格布局 | +| 2 | **交互效果清单** | 每个按钮/操作触发什么效果（弹窗、抽屉、跳转、动画） | +| 3 | **前后端调用流程** | 每个用户操作 → 对应API → 参数 → 返回数据 → 前端渲染 | +| 4 | **状态流转图** | 数据状态变化 → UI如何响应 | +| 5 | **异常/边界处理** | 空数据、加载中、错误状态的UI表现 | +| 6 | **响应式断点** | 不同屏幕尺寸下的布局适配方案 | + +--- + +## 二、十大UI设计铁律法则 + +> 以下法则源自认知心理学、人机交互学、HCI经典理论。 +> 医疗HIS系统因涉及生命安全，**全部铁律等级提升为P0**。 + +### 法则1: 希克定律 (Hick's Law) — 选择越少越好 + +> **决策时间 = a + b × log₂(选项数量)** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 菜单层级 | 一级菜单 ≤ 7项，二级菜单 ≤ 9项 | 医生工作站左侧导航 | +| 表单字段 | 单页表单 ≤ 12个字段，超出用分步表单 | 患者登记、医嘱录入 | +| 按钮组 | 主要操作按钮 ≤ 3个/区域 | 处方页面：保存/提交/打印 | +| 弹窗选项 | 弹窗内选项 ≤ 5个 | 确认对话框不超过3个按钮 | + +**违反案例**: 某页面一次展示20个筛选条件 → 医生找不到关键字段 +**正确做法**: 默认显示5个常用条件，"更多筛选"展开高级选项 + +### 法则2: 费茨定律 (Fitts's Law) — 目标要大要近 + +> **移动时间 = a + b × log₂(距离/尺寸 + 1)** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 可点击区域 | 最小 44×44px（移动端 48×48px） | 移动护理PDA场景 | +| 主要操作 | 放在用户视线自然落点（右下/顶部） | 保存按钮固定在表单右下 | +| 危险操作 | 与安全操作保持物理距离 ≥ 100px | 删除按钮远离保存按钮 | +| 快捷入口 | 高频操作提供快捷键/快捷入口 | F2=保存, F3=打印 | + +**违反案例**: "确认发药"和"取消发药"按钮紧挨着 → 误点 +**正确做法**: 确认按钮绿色大按钮，取消按钮灰色小按钮，间距 ≥ 80px + +### 法则3: 米勒定律 (Miller's Law) — 记忆负荷 ≤ 7±2 + +> **短时记忆容量：7 ± 2 个信息块** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 信息分组 | 每组 ≤ 7个条目 | 检验报告分组显示 | +| 导航层级 | 总层级 ≤ 4层 | 菜单→子菜单→功能→详情 | +| 表格列数 | 默认显示 ≤ 8列，其余可配置 | 处方列表核心列8个 | +| 标签页 | Tab标签 ≤ 6个，超出用下拉 | 患者详情Tab | + +**违反案例**: 患者信息页一次展示30个字段 → 医生记不住哪个要改 +**正确做法**: 按"基本信息/病史/过敏/诊断"分组，每组 ≤ 7个字段 + +### 法则4: 雅各布定律 (Jakob's Law) — 用户要的是熟悉感 + +> **用户把时间花在别的系统上，期望你的系统有一样的操作方式** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 布局模式 | 遵循医疗软件行业惯例 | 左导航+顶部栏+内容区 | +| 表格操作 | 行末操作按钮（编辑/删除/查看） | 与主流HIS系统一致 | +| 搜索模式 | 顶部搜索栏+筛选条件+表格 | 通用管理后台模式 | +| CRUD流程 | 列表→新增弹窗→编辑弹窗→详情抽屉 | 标准若依模式 | + +**违反案例**: 新模块把"新增"放在表格底部 → 用户习惯在顶部找 +**正确做法**: "新增"按钮统一在表格上方左侧 + +### 法则5: 格式塔原则 (Gestalt Principles) — 分组要明确 + +| 子原则 | 规则 | HIS场景 | +|--------|------|---------| +| **接近性** | 相关元素间距 < 不相关元素间距 | 表单label与input间距8px，字段组间距24px | +| **相似性** | 同类操作用相同颜色/形状 | 所有"保存"用蓝色，所有"删除"用红色 | +| **连续性** | 视觉引导线引导阅读流 | 表单从上到下、从左到右 | +| **封闭性** | 卡片/分组用边框或背景色区分 | 患者信息分区用卡片包裹 | +| **图底关系** | 内容层 > 背景层，弹窗要有遮罩 | Dialog背景半透明遮罩 | + +**违反案例**: 表单字段间距不一致 → 视觉混乱 +**正确做法**: 统一间距系统：8/12/16/24/32px + +### 法则6: 多赫蒂阈值 (Doherty Threshold) — 响应要快 + +> **系统响应 < 400ms 时，用户生产力提升4倍** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 接口响应 | 核心接口 ≤ 200ms，普通 ≤ 500ms | 挂号、查询必须 ≤ 200ms | +| 加载反馈 | 等待 > 200ms 显示loading | el-table加载用v-loading | +| 操作反馈 | 点击后 ≤ 100ms 有视觉响应 | 按钮点击立即变灰防重复提交 | +| 列表分页 | 默认20条/页，禁止一次加载全部 | 处方列表分页 | +| 骨架屏 | 首屏加载用Skeleton占位 | 患者列表页骨架屏 | + +**违反案例**: 查询接口3秒无响应 → 用户反复点击 +**正确做法**: 200ms内显示loading，超时5s提示"查询超时" + +### 法则7: 尼尔森十大可用性原则 (Nielsen's 10 Heuristics) + +| # | 原则 | HIS应用规则 | +|---|------|------------| +| 1 | **系统状态可见** | 每个操作后显示结果：保存成功✓、提交成功✓、审批中⏳ | +| 2 | **贴近真实世界** | 使用医疗术语（挂号、处方、医嘱），不用技术术语（CRUD、API） | +| 3 | **用户控制与自由** | 每个操作可撤销：提交可撤回、删除有确认、编辑可取消 | +| 4 | **一致性和标准** | 全系统统一：按钮颜色、弹窗样式、表格样式、表单校验 | +| 5 | **防错优先** | 危险操作二次确认；必填字段标红*；格式校验实时提示 | +| 6 | **识别而非记忆** | 下拉选择 > 手动输入；最近使用列表；搜索联想 | +| 7 | **灵活高效** | 快捷键；批量操作；常用模板；收藏功能 | +| 8 | **简洁美观** | 去掉无关信息；留白适度；视觉层次清晰 | +| 9 | **容错帮助** | 错误信息说人话："身份证号格式错误"而非"Invalid input" | +| 10 | **帮助文档** | 复杂功能提供操作引导；Help Tooltip | + +**违反案例**: 删除后无提示 → 用户不确定是否成功 +**正确做法**: 删除后 `ElMessage.success('删除成功')` 并刷新列表 + +### 法则8: 泰斯勒定律 (Tesler's Law) — 复杂性守恒 + +> **每个系统都有不可消除的复杂性，必须 somewhere 被处理** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 简单前端复杂后端 | 用户操作尽量简单，复杂逻辑放后端 | 医保结算：用户点"结算"，后端算所有费用 | +| 智能默认值 | 80%场景用默认值，减少用户输入 | 科室默认当前科室，药品默认常用规格 | +| 渐进式披露 | 先展示核心信息，高级选项折叠 | 医嘱默认常用，"更多选项"展开完整 | +| 自动化 | 能自动填充的不手动输入 | 选择患者自动填充病历号、性别、年龄 | + +**违反案例**: 开医嘱要手动输入药品剂量、频次、途径 → 复杂 +**正确做法**: 提供"常用医嘱模板"，一键套用，仅需微调 + +### 法则9: 峰终定律 (Peak-End Rule) — 关键时刻要做好 + +> **用户记住的是体验的峰值和结束时刻** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 操作峰值 | 关键操作给正向反馈 | 挂号成功→大✓动画+患者信息卡 | +| 结束体验 | 流程结束给明确结果 | 收费完成→打印凭条+成功提示 | +| 错误峰值 | 错误也要优雅处理 | 校验失败→精确定位错误字段+红色高亮 | +| 批量操作 | 批量完成后给统计 | "成功导入58条，失败2条" | + +**违反案例**: 批量导入完成后无提示 → 用户不知道是否成功 +**正确做法**: 弹出结果面板："✓ 成功58条 / ✗ 失败2条（点击查看）" + +### 法则10: 冯·雷斯托夫效应 (Von Restorff Effect) — 隔离记忆 + +> **在相似事物中，与众不同的那个更容易被记住** + +| 维度 | 规则 | HIS场景 | +|------|------|---------| +| 紧急标记 | 危急值用红色醒目样式 | 危急值报告→红色闪烁标签 | +| 当前选中 | 选中项明显高亮 | 菜单选中项蓝色背景+左侧条 | +| 重要操作 | 主要按钮用强调色 | "提交处方"蓝色实心，"取消"灰色描边 | +| 通知徽标 | 未读消息用Badge | 右上角铃铛红点+数字 | + +**违反案例**: 危急值和普通信息用同一颜色 → 医生忽略 +**正确做法**: 危急值红色脉冲动画 + 声音提醒 + +--- + +## 三、HIS医疗系统专项UI规范 + +### 3.1 色彩体系 + +| 用途 | 颜色 | HEX | 说明 | +|------|------|-----|------| +| 主色 | 医疗蓝 | #1890ff | 品牌色、主要按钮 | +| 成功 | 安全绿 | #52c41a | 操作成功、正常状态 | +| 警告 | 警示橙 | #faad14 | 注意、待处理 | +| 危险 | 危急红 | #ff4d4f | 危急值、删除、错误 | +| 信息 | 信息灰 | #909399 | 辅助信息、次要文本 | +| 背景 | 浅灰 | #f5f7fa | 页面背景 | +| 卡片 | 白色 | #ffffff | 卡片/弹窗背景 | + +**状态色标准**: +``` +待诊 → #909399(灰) 已诊 → #1890ff(蓝) +已收费 → #52c41a(绿) 已发药 → #722ed1(紫) +危急 → #ff4d4f(红脉冲) 已完成 → #b7eb8f(浅绿) +``` + +### 3.2 间距系统 (8px基准) + +| Token | 值 | 用途 | +|-------|-----|------| +| xs | 4px | 图标与文字间距 | +| sm | 8px | 表单项内间距、紧凑行距 | +| md | 12px | 表单项之间间距 | +| lg | 16px | 卡片内边距、区块间距 | +| xl | 24px | 区域分隔 | +| xxl | 32px | 页面级边距 | + +### 3.3 字体规范 + +| 场景 | 字号 | 字重 | 说明 | +|------|------|------|------| +| 页面标题 | 20px | 600 | h1 | +| 区块标题 | 16px | 600 | h2 | +| 正文 | 14px | 400 | 默认 | +| 辅助文字 | 12px | 400 | 说明、提示 | +| 数据突出 | 24px | 700 | 统计数字、金额 | +| 危急值 | 16px | 700 | 红色加粗 | + +### 3.4 表格设计规范 + +| 规则 | 说明 | +|------|------| +| 列数 | 默认 ≤ 8列，超出用横向滚动或配置列 | +| 行高 | 48px（紧凑40px，宽松56px） | +| 操作列 | 固定右侧，宽度 ≥ 160px | +| 排序 | 默认按时间倒序，支持点击列头排序 | +| 分页 | 20条/页，可切换10/20/50/100 | +| 空状态 | 无数据时显示空状态插画+文字"暂无数据" | +| 加载 | v-loading指令，骨架屏或旋转图标 | +| 斑马纹 | 奇偶行交替背景色 #fafafa | + +### 3.5 表单设计规范 + +| 规则 | 说明 | +|------|------| +| 布局 | 简单表单用inline，复杂用labelWidth=120px | +| 必填标记 | 红色 * 号在label前 | +| 校验时机 | blur时校验（非实时），提交时全量校验 | +| 错误提示 | 字段下方红色文字，与字段左对齐 | +| 按钮位置 | 表单底部右侧，主按钮在右 | +| 禁用态 | 禁用字段灰底+灰字+禁止光标 | +| 加载态 | 提交按钮loading态，防重复提交 | + +### 3.6 弹窗/抽屉规范 + +| 类型 | 适用场景 | 规则 | +|------|---------|------| +| Dialog | 简单表单（≤6字段） | 宽度400-600px，标题+内容+底部按钮 | +| Drawer | 复杂表单/详情查看 | 宽度60%，右侧滑入，含关闭按钮 | +| Modal | 确认操作 | 标题+内容+确认/取消，危险操作红色确认 | +| Fullscreen | 大表单/复杂编辑 | 全屏，顶栏标题+关闭，底部操作栏 | + +### 3.7 交互反馈规范 + +| 操作 | 反馈方式 | 示例 | +|------|---------|------| +| 保存成功 | ElMessage.success | "保存成功" | +| 保存失败 | ElMessage.error | "保存失败：XXX原因" | +| 删除确认 | ElMessageBox.confirm | "确定要删除该记录吗？" | +| 表单校验 | 字段下方红色文字 | "请输入患者姓名" | +| 加载中 | v-loading | 旋转图标覆盖表格 | +| 空数据 | 空状态组件 | 插画+"暂无挂号记录" | +| 网络错误 | ElMessage.error | "网络异常，请重试" | +| 无权限 | ElMessage.warning | "您没有该操作权限" | + +### 3.8 医疗HIS特殊交互 + +| 场景 | 交互要求 | +|------|---------| +| **危急值** | 红色脉冲动画 + 弹窗强制确认 + 声音提醒 + 操作记录 | +| **医嘱审核** | 双人审核弹窗，审核人签章，不可撤销提示 | +| **处方开具** | 药品搜索联想 + 剂量自动计算 + 相互作用预警弹窗 | +| **费用结算** | 费用明细折叠/展开 + 医保/自费分类 + 打印预览 | +| **患者搜索** | 模糊搜索+拼音首字母+身份证号+病历号 多维度 | +| **电子签名** | 手写板签名+密码验证 双重认证 | +| **打印功能** | 套打对齐微调 + 批量打印 + 预览 | +| **权限控制** | 按钮级权限 v-hasPermi + 数据权限过滤 | + +--- + +## 四、设计文档模板 + +> 每个新模块必须按此模板编写设计文档 + +```markdown +# 模块名 设计文档 + +## 1. 页面列表 +| 页面 | 路由 | 类型 | 说明 | +|------|------|------|------| +| 列表页 | /module/list | 管理页 | ... | +| 新增弹窗 | - | Dialog | ... | + +## 2. 页面布局设计 +### 2.1 列表页 +``` +┌─────────────────────────────────┐ +│ 搜索区 [关键词] [筛选] [搜索] │ +├─────────────────────────────────┤ +│ 操作区 [+新增] [导出] [批量删除] │ +├─────────────────────────────────┤ +│ 数据表格 (el-table) │ +│ 列1 | 列2 | 列3 | ... | 操作 │ +├─────────────────────────────────┤ +│ 分页 [1] [2] [3] ... │ +└─────────────────────────────────┘ +``` + +## 3. 交互效果清单 +| 操作 | 触发方式 | 效果 | 反馈 | +|------|---------|------|------| +| 点击"新增" | 按钮click | 打开Dialog | - | +| 点击"保存" | 按钮click | 提交API→关闭Dialog→刷新列表 | success消息 | +| 点击"删除" | 按钮click | 二次确认弹窗→调用API→刷新 | success消息 | +| 表单校验 | blur/submit | 字段下方提示 | error文字 | + +## 4. 前后端调用流程 +### 4.1 查询列表 +``` +用户操作: 页面加载/点击搜索 + → 前端: GET /api/v1/module/list?pageNum=1&pageSize=20&keyword=xxx + → 后端: Controller.list() → AppService.query() → Service.page() + → 返回: {code:200, data:{rows:[...], total:100}} + → 前端: el-table渲染 rows，pagination渲染 total +``` + +### 4.2 新增记录 +``` +用户操作: 点击"新增"→填写表单→点击"保存" + → 前端: POST /api/v1/module {field1, field2, ...} + → 后端: Controller.add() → AppService.create() → Service.save() + → 返回: {code:200, msg:"操作成功"} + → 前端: ElMessage.success → 关闭Dialog → getList() +``` + +## 5. 状态流转 +| 状态 | 值 | 下一状态 | 触发条件 | +|------|-----|---------|---------| +| 草稿 | 0 | 已提交 | 用户点击提交 | +| 已提交 | 1 | 已审核 | 审核人点击审核 | + +## 6. 异常处理 +| 场景 | UI表现 | +|------|--------| +| 网络断开 | ElMessage.error("网络异常") | +| 数据为空 | 空状态插画+"暂无数据" | +| 权限不足 | 按钮隐藏/v-if控制 | +| 加载中 | v-loading覆盖 | +``` + +--- + +## 五、违反检查清单 + +> 代码审查时对照此清单逐项检查 + +``` +□ 页面布局是否遵循左导航+顶部栏+内容区？ +□ 每页功能按钮是否 ≤ 3个主要操作？ +□ 表单字段是否 ≤ 12个？超出是否分步/折叠？ +□ 可点击区域是否 ≥ 44px？ +□ 危险操作是否与安全操作保持距离？ +□ 加载等待是否显示loading？ +□ 操作成功/失败是否有明确反馈？ +□ 删除操作是否有二次确认？ +□ 表格是否分页？是否默认20条？ +□ 空数据是否有空状态提示？ +□ 色彩是否符合色彩体系？ +□ 间距是否使用8px基准系统？ +□ 字体是否符合字体规范？ +□ 弹窗类型选择是否合理？ +□ 表单校验是否blur触发？ +□ 医疗特殊交互（危急值/医嘱等）是否按规范实现？ +□ 设计文档是否包含：UI布局+交互清单+调用流程？ +``` + +--- + +## 六、参考文献 + +| 来源 | 内容 | +|------|------| +| Hick (1952) | Hick's Law — 选择反应时间 | +| Fitts (1954) | Fitts's Law — 运动时间与目标尺寸 | +| Miller (1956) | Miller's Law — 7±2信息块 | +| Jakob Nielsen | 10 Usability Heuristics | +| Gestalt Psychology | 接近性/相似性/连续性/封闭性/图底 | +| Doherty & Thadhani (1982) | 400ms响应阈值 | +| Larry Tesler | 复杂性守恒定律 | +| Kahneman | 峰终定律 | +| Hedwig von Restorff | 隔离效应 | +| ISO 9241-210 | 以人为中心的交互系统设计 | +| GB/T 33758-2017 | 人机交互系统人机界面设计原则 | +| WS/T 500-2017 | 电子病历共享文档规范 | + +--- + +> ⚠️ 本文件是UI设计铁律的唯一信源。所有前端模块设计文档必须遵守本规范。 diff --git a/RULES.md b/RULES.md index 71691dc18..6984622fc 100644 --- a/RULES.md +++ b/RULES.md @@ -72,7 +72,7 @@ - 这是诚实原则，不是效率问题 -**铁律11: 设计文档确认后自主开发（铁律）** +**铁律12: 设计文档确认后自主开发（铁律）** - 设计文档（如 `MD/architecture/GRADE3A_GAP_ANALYSIS_AND_DESIGN.md`）一旦确认，后续开发**必须按文档自主执行** - **禁止反复询问"是否继续""下一步做什么""是否开始"**——直接按计划推进 - 每完成一个 Sprint，自动提交推送，然后立即开始下一个 Sprint @@ -88,13 +88,23 @@ **铁律10: 验证后信** - 每次修改后必须验证编译通过，不信记忆 -**铁律11: 文档统一管理** +**铁律13: 文档统一管理** - 所有文档存储在 `MD/` 目录 - 文件名：大写英文+下划线（如 `BACKEND_CHECKLIST.md`） - 文档头部必须包含元数据块（文档类型、版本、日期） --- + +**铁律14: 设计文档必须包含UI设计和调用流程** +- 所有新模块/页面的设计文档必须包含：UI布局描述、交互效果清单、前后端调用流程 +- 没有明确UI设计的模块，禁止直接编码 +- 详见 +- 设计文档必须写清楚：系统调用关系、方法函数调用关系、完整业务流程 +- 设计文档中每个用户操作必须对应：前端事件 → API调用 → 后端处理链路 → 返回数据 → UI渲染 + +--- + ## 三、Karpathy 编码准则 > 减少 LLM 常见编码错误。偏向谨慎而非速度。