business-compliance

业务合规性

对 Hexagone Web 应用的页面或组件运行完全自主的领域合规审计。该技能会在 docs/domain/ 中发现已记录的业务规则，提取目标屏幕的实体和限界上下文，匹配适用规则，检测是否违反领域不变量，并输出附有强制引用的结构化报告——不会修改任何文件。**这是一项仅生成报告的技能。**它绝不会自动修复业务规则违规，因为其语义和患者安全影响过于重大，不适合交由机器判断。

使用此技能的时机

用户出现以下情况时启用：

• 说“business-compliance”，后面跟着 URL、组件名称或页面名称
• 要求审计屏幕上的领域规则、业务规则或不变量
• 说“检查业务逻辑”“审计领域规则”“业务审查”
• 想验证屏幕是否执行了 docs/domain/ 中记录的不变量

与 design-compliance 的关系

design-compliance 和 business-compliance 是互补但彼此独立的技能：

	design-compliance	business-compliance
审计对象	视觉／呈现层	领域／业务逻辑层
真相来源	hexagone-preset.js、CLAUDE.md、设计规则	docs/domain/（采用 DDD 结构的 Markdown）
模式	自动修复所有违规	仅生成报告，绝不修复
风险概况	低（外观问题）	高（患者安全、法规合规）
审查者	前端开发人员	领域专家、临床 PO、合规人员

不要将它们合并。需要时分别运行。统一的 screen-compliance 聚合器不在 v1 的范围内。

核心原则

1. 完全自主

• 整个流程运行期间不会提问
• 如果未提供参数，则询问用户要审查什么，然后自主运行
• **不会修改任何文件。**报告只会输出到终端

2. 仅生成报告，不自动修复

在医疗软件中自动修复业务规则违规绝对不安全。机器“修复”可能会：

• 将警告变成阻止（中止合理的医疗服务）
• 将阻止变成警告（使走捷径这一反模式制度化）
• 在没有人工审查的情况下，悄然改变临床语义

该技能只会呈现、记录并引用问题——由人工（开发人员 + 领域专家）决定如何修复。

3. 架构优先

该技能要求 docs/domain/ 遵循结构化规则架构（参见 reference/rule-schema.md）。如果不符合该架构，技能将拒绝审计并输出迁移检查清单。输入垃圾，输出的结果就会是臆造的发现。这一点不可妥协。

4. 确定性匹配流程

将规则匹配到屏幕时，必须先经过确定性流程，再进行任何 LLM 推理：

1. 屏幕提取（确定性）——路由、Pinia 状态库、API 端点、TypeScript 类型
2. 限界上下文预筛选（确定性）——通过规则 frontmatter 中的 api_prefixes
3. 实体查找（确定性）——将提取的类型与规则的 entities: 列表匹配
4. 规则推理（LLM）——仅针对筛选出的规则进行

LLM 仅用于第 4 步。第 1 至第 3 步均为机械流程。

5. 宁可敏感，也不过度追求精确

在医疗领域，漏报后果灾难性，误报则令人烦扰。该技能会优先保证敏感度：遇到不确定情况时，会将状态设为 NEEDS_CLINICAL_REVIEW 并报告，而不是悄然忽略该规则。

6. 必须提供引用

每条发现都必须引用：

• docs/domain/ 中确切的规则文件和行号（或标题锚点）
• 违规代码所在的确切文件和行号
• 稳定的 rule_id（例如 ADM-001、PRESC-014）

缺少以上任一项引用的发现都会从报告中剔除。没有引用 = 没有发现。

事实来源（优先级顺序）

1. docs/domain/ 中的规则文件 — 唯一权威业务规则来源
2. 规则架构 — reference/rule-schema.md（此技能对规则结构的约定）
3. 通用语言 — 如果存在，则使用 UBIQUITOUS_LANGUAGE.md 来协调实体命名

此技能不会自行编造规则。如果 docs/domain/ 中未记录某条规则，则此技能视其不存在。

输入模式

与 design-compliance 的三种输入模式相同：

URL 模式

/business-compliance http://localhost:5173/hexagone-etab/vue/prescriptions/123

1. 使用 URL 在路由器配置中解析路由
2. 找到该路由对应的组件文件
3. 递归解析组件树

组件名称模式

/business-compliance PrescriptionEditor

1. 使用 glob 查找匹配的文件：**/PrescriptionEditor.vue、**/prescription-editor.vue
2. 解析路由（如果有），以推断有界上下文
3. 递归解析组件树

页面名称模式

/business-compliance Prescriptions

1. 在路由器配置中搜索匹配的路由名称或路径
2. 找到指定的组件
3. 递归解析组件树

无参数

/business-compliance

询问用户要审计什么。不要自行假设。

工作流

步骤 1：验证规则架构

开始任何操作前，验证 docs/domain/ 是否符合必需的架构：

1. 定位项目中的 docs/domain/。如果不存在，则中止并输出：

   "未找到 docs/domain/ 目录。business-compliance 需要已记录的领域规则。请参阅 reference/rule-schema.md 了解必需格式。"

2. 解析 docs/domain/ 中的每个 .md 文件，并验证其 frontmatter：

   • 必需字段：bounded_context、entities、api_prefixes（可以是空列表）、rule_id 或包含各自 rule_id 的规则列表、severity、layer
   • severity 的可接受值：P1、P2、P3、P4
   • layer 的可接受值：client、server、both

3. 如果有任何文件未通过验证，则中止审计并输出迁移检查清单：

   docs/domain/ schema violations — audit aborted
   
   | File | Missing fields | Action |
   |------|----------------|--------|
   | docs/domain/prescriptions.md | severity, layer | Add frontmatter fields |
   | ... | ... | ... |
   
   Fix the rule files before re-running. See skills/business-compliance/reference/rule-schema.md.
   

4. 如果所有文件均通过验证，则构建标准化的内存规则索引：

   • 按 (bounded_context, entity, rule_id) 作为键
   • 每个条目包含：规则文本、severity、layer、api_prefixes、源文件 + 行号

步骤 2：解析目标文件

采用与 design-compliance 相同的解析策略：

1. 解析用户的输入，以确定模式（URL、组件名称、页面名称）
2. 查找入口文件：
   • URL → 解析路径，在路由器文件（**/router/**/*.{js,ts}、**/router.{js,ts}）中搜索匹配路由，获取组件
   • 组件名称 → 使用 glob 查找 **/<name>.vue、**/<name-kebab>.vue、**/<Name>/**
   • 页面名称 → 在路由器配置中搜索匹配的路由名称或路径
3. 递归解析组件树：
   • 读取每个 .vue 文件
   • 提取所有本地导入（跳过 primevue/*、vue、vue-router、pinia、node_modules、@hexagone/shared）
   • 跟进每个导入并重复上述步骤，直到没有新的本地组件
4. 向用户报告发现的组件树

第 3 步：提取屏幕工件

对于组件树中的每个文件，提取规则匹配所需的工件：

1. 路由信息：

   • 路由路径（例如，/prescriptions/:id）
   • 从路由派生的 API 前缀（例如，/api/prescriptions）

2. Pinia store：

   • import { usePrescriptionStore } from '...'
   • Store 名称是有力的限界上下文提示

3. API 端点：

   • 搜索 axios.*、fetch('...')、useFetch(...)、$api.*
   • 捕获完整 URL 和 HTTP 方法
   • 捕获错误处理：catch (err) 代码块、4xx/5xx 处理程序

4. TypeScript 类型：

   • 从 @/types/、@hexagone/shared/types 或本地 types.ts 导入的类型
   • 关注类似实体的类型：Prescription、Admission、Patient、Order 等

5. 表单字段和绑定：

   • v-model 绑定
   • 表单验证规则（required、rules、schema、Zod/Yup/Valibot 架构）
   • 操作按钮上的 :disabled、v-if、v-show（状态机信号）

6. 操作处理程序：

   • 按钮上的点击处理程序，其标签与状态转换匹配（save、validate、discharge、sign、cancel）
   • 捕获它们通过 API 触发的状态变更

输出逐文件提取摘要：

PrescriptionEditor.vue:
  route: /prescriptions/:id
  api_prefixes: [/api/prescriptions, /api/allergies]
  stores: [usePrescriptionStore, usePatientStore]
  types: [Prescription, AllergyCheck, Patient]
  actions: [save, validate, sign]

第 4 步：将规则与屏幕匹配

对于每个文件提取的工件，匹配适用规则：

1. 限界上下文筛选：针对屏幕中的每个 api_prefix，收集其 frontmatter 中 api_prefixes 有重叠的规则
2. 实体筛选：筛选出 entities 列表包含任一已提取 TS 类型名称的规则
3. 通用语言协调：如果存在 UBIQUITOUS_LANGUAGE.md，则在匹配之前用它将代码级名称映射为领域级名称（例如，Rx → Prescription）

输出逐文件规则候选列表：

PrescriptionEditor.vue: 7 applicable rules
  - PRESC-001 (P1) — Allergy check required before validation
  - PRESC-002 (P1) — Electronic signature required on save
  - PRESC-014 (P2) — Signature requires audit log entry
  - ADM-008 (P3) — Patient must have active admission
  - ...

第 5 步：静态分析 — 检测违规

对于每个（文件、适用规则）组合，检查 5 类违规：

类别 1：缺少前置条件检查

• 规则规定操作前必须满足某项前置条件（X requires Y verified）
• 检查：UI 是否通过 :disabled、v-if、表单验证或 API 前置条件来限制该操作？
• 所需证据：操作的代码位置，以及缺少限制条件的证据
• 严重程度沿用规则

类别 2：暴露了禁止的状态转换

• 规则规定禁止某项状态转换（Discharged cannot return to Active）
• 检查：UI 是否提供了可触发该禁止转换的按钮/操作？
• 证据：按钮处理程序，以及可能导致禁止状态变更的 API 调用

类别 3：缺少必填字段

• 规则要求必须收集/显示某个字段（例如，“临床操作必须填写 INS”）
• 检查：表单模板中是否存在该字段、是否通过 v-model 绑定，以及是否通过验证强制填写？
• 证据：模板搜索结果和验证架构检查结果

类别 4：未强制执行跨实体不变量

• 规则涉及多个实体（例如，“Prescription 必须引用有效的 AllergyCheck”）
• 检查：屏幕是否加载/引用这两个实体，以及是否根据跨实体条件限制操作？
• 证据：存在两个 store/类型，以及存在针对跨实体关系的条件判断

类别 5：工作流缺口

• 规则定义了工作流步骤（例如，“口头医嘱必须在 24h 内由他人复核签名”）
• 检查：UI 是否呈现了该步骤，包括提醒或后续操作？
• 证据：与工作流步骤对应的 UI 工件是否存在

服务端规则处理

当规则具有 layer: server 或 layer: both 时：

• 不期望 UI 完全强制执行该规则
• 但期望 UI 妥善处理服务端拒绝（捕获 409/422，并向用户显示错误）
• 检查：API 调用位置是否包含适当的错误处理程序？
• 服务端强制执行的规则缺少错误处理程序，本身即构成违规（类别 1 — 缺少前置条件处理）

步骤 6：处理不确定性

当技能无法有把握地判断某条规则是否适用或是否遭到违反时：

1. 不要默默忽略该规则
2. 输出一条状态为 NEEDS_CLINICAL_REVIEW 的发现
3. 为审核者附上一个结构化问题：

   NEEDS_CLINICAL_REVIEW — PRESC-007
   Rule: Prescriptions require electronic signature.
   Screen: PrescriptionEditor.vue uses usePrescriptionStore.save() but signature step not clearly detected.
   
   Please confirm:
   (a) Rule applies, step missing → fix required
   (b) Rule applies, step present but undetected → add code annotation or test anchor
   (c) Rule does not apply → document why in commit message or rule exclusion
   

步骤 7：跟踪不可评估的规则

分析后，列出所有曾列入候选清单但无法评估的规则（例如，代码过于复杂、动态分派、调用外部库）。这样可以避免将“未发现违规”误解为“未审计”：

Non-evaluable rules (5):
  - PRESC-022 — dynamic dispatch on action name, cannot trace
  - ADM-014 — relies on backend orchestration not visible in screen code
  - ...

步骤 8：生成报告

在终端中打印结构化报告：

## Business Compliance Report

**Target:** [component/page name or URL]
**Files analyzed:** [count]
**Rules indexed:** [count from docs/domain/]
**Rules applicable to target:** [count]
**Violations detected:** [count]
**Uncertain findings (NEEDS_CLINICAL_REVIEW):** [count]
**Non-evaluable rules:** [count]

### Rule Index Summary
| Bounded Context | Rules | Files |
|-----------------|-------|-------|
| prescriptions   | 14    | docs/domain/prescriptions.md |
| admissions      | 8     | docs/domain/admissions.md |
| ...             | ...   | ... |

### Files in Component Tree
| # | File | Applicable Rules | Violations |
|---|------|------------------|------------|
| 1 | `frontend/gap-mf/src/views/PrescriptionEditor.vue` | 7 | 2 |
| 2 | `frontend/gap-mf/src/components/AllergyBanner.vue` | 2 | 0 |
| ... | ... | ... | ... |

### Violations by Severity

#### P1 — Patient Safety ([count])
- **PRESC-001** — Allergy check required before validation
  - Rule source: `docs/domain/prescriptions.md:42`
  - Code location: `frontend/gap-mf/src/views/PrescriptionEditor.vue:118`
  - Category: Missing precondition check
  - Evidence: `validate()` handler calls `prescriptionStore.validate()` without prior check on `allergyCheckStore.verified`.
  - Suggested action (NOT applied): add `:disabled="!allergyChecked"` to the Validate button, or guard inside the handler.

#### P2 — Regulatory / Compliance ([count])
...

#### P3 — Clinical Workflow Integrity ([count])
...

#### P4 — Data Quality / Interoperability ([count])
...

### NEEDS_CLINICAL_REVIEW ([count])
- **PRESC-007** — [structured question as in Step 6]

### Non-Evaluable Rules ([count])
- **PRESC-022** — dynamic dispatch on action name, static trace impossible

### Drift Signals
- Rule files unchanged in > 6 months while referenced entities evolved: [list]
- Rules with no applicable screen in this audit: [list]

### Summary
- **Total violations:** [count] (P1: [n], P2: [n], P3: [n], P4: [n])
- **Waivable by developer alone:** [count] (P3 + P4)
- **Require clinical / compliance sign-off:** [count] (P1 + P2)
- **No files modified.** Review the report, discuss with domain experts, apply fixes manually.

违规参考

5 种违规类别

#	类别	常见规则表述	所需证据
1	缺少前置条件检查	“X 要求已验证 Y”	操作处理程序 + 缺少防护检查
2	暴露了禁止的状态转换	“无法从 A 转换到 B”	操作处理程序 + 禁止的状态变更
3	缺少必需字段	“字段 F 为必填项”	模板 + 验证架构
4	未强制执行跨实体不变量	“X 必须引用 Y”	两个实体均存在 + 条件逻辑
5	工作流缺口	“步骤 S 必须在 T 时间内发生”	步骤 S 的 UI 产物

严重程度分类

严重程度	含义	升级处理
P1	患者安全——可能直接造成伤害（过敏、剂量错误、患者错误、绕过签名）	阻止合并。必须由临床 PO 批准。
P2	监管 / 合规——HDS、MDR、CNIL、审计日志、可追溯性	阻止合并。必须由合规负责人批准。
P3	临床工作流完整性——状态机、孤立实体、工作流缺口	阻止合并。临床 PO 可提供书面理由予以豁免。
P4	数据质量 / 互操作性——可选字段、代码系统、标签	发出警告。不阻止合并。开发人员可予以豁免。

P1 和 P2 不能仅由开发人员豁免。 如果请求豁免，技能必须要求在豁免元数据中指定一名临床或合规审核者。

医疗保健规则示例（Hexagone 场景）

具体示例请参阅 reference/rule-schema.md。Hexagone 中常见的规则类别：

• 安全联锁：过敏 / 禁忌症 / 剂量范围 / 药物相互作用
• 身份识别：在执行临床操作前验证 INS（Identité Nationale de Santé）
• 处方完整性：电子签名、修改审计跟踪、口头医嘱会签
• 状态机：入院 / 出院流程、医嘱 / 结果流程、诊疗路径步骤
• 互操作性：HL7/FHIR/PAM 消息完整性、分段排序（Hexaflux 领域）
• 监管：写入时记录审计日志、紧急访问理由、数据保留
• 计费级联：阻止出院的医疗行为代码、要求填写主要诊断的 GHS

边缘情况

docs/domain/ 不存在

中止审计。输出：

“未找到 docs/domain/ 目录。此技能要求按照 reference/rule-schema.md 中的架构记录领域规则。请先创建该目录并添加规则文件，再运行。”

docs/domain/ 存在但架构验证失败

按文件输出架构违规迁移清单（参见步骤 1.3），然后中止审计。不要尝试进行部分审计——不完整的数据会造成虚假的信心。

规则引用了未知实体

如果某条规则的 entities: 列表包含在代码库中任何位置都找不到的名称：

• 在索引中保留该规则
• 在报告的偏差迹象部分标记：“规则 X 引用了实体 Y，但在代码库中未找到相关用法”
• 这表明文档可能已过时，或者该实体仅存在于服务端

页面与所有规则均不匹配

报告“0 条适用规则”——并明确说明这不等同于“符合要求”。该页面可能属于未记录的有界上下文（这本身也是需要报告的偏差迹象）。

规则冲突

如果索引中的两条规则具有相同的 rule_id，或对同一实体作出相互矛盾的声明：

• 在 Drift Signals 部分报告冲突
• 不要尝试解决冲突——这是领域专家的决定

开发服务器未运行

此技能不需要开发服务器。它是静态分析与文档解析技能。视觉检查不在范围内——业务规则涉及代码行为，而非渲染效果。

大型组件树（20+ 个文件）

处理所有文件。按文件组织报告以提高可读性。仅当组件树超过 10 个文件且规则索引超过 30 条规则时，才使用并行子 Agent，以便合理控制大模型推理上下文。

混合微前端

无论文件属于哪个微前端，都应用同一规则索引。在报告中注明每个文件所属的微前端。

请求豁免

此技能不管理豁免。如果某项发现必须豁免，应由开发者在 PR 描述或此技能范围之外的专用豁免日志中处理。此技能会在下次运行时再次报告该发现——记住豁免并非此技能的职责（记住豁免属于人工流程）。

重要说明

• 此技能不会修改文件。 它严格只生成报告。如果用户说“修复它们”，请说明业务规则违规无法通过机械方式修复——报告会提供建议操作，需由人工执行。
• 每项发现都必须引用 rule_id + doc:line + code:line。 缺少这三项中任何一项的发现都是技能缺陷——不要输出此类发现。
• P1 / P2 违规需要临床或合规审核人员具名签核。 技能会在报告中明确指出这一点。
• 优先考虑灵敏度，而非特异性。 宁可提出 10 项可能的发现，再由团队排除其中 9 项，也不要漏掉 1 项 P1。
• 不确定的发现 → NEEDS_CLINICAL_REVIEW。 绝不要静默丢弃规则。
• 漂移信号属于一等事项。 当实体已发生变化但相关规则未更新时，应在报告中指出。引用未知实体的规则也应在报告中指出。
• 不可评估的规则属于一等事项。 不得将“未发现违规”与“未审计”混为一谈。始终明确列出不可评估的规则。
• 绝不自动修复。绝不推出 v2 自动修复。 如有请求，应予以拒绝：医疗语义变更需要人工判断。
• 先进行试点。 在全新部署中，先从一个范围明确的上下文开始（建议：处方——风险最高、不变量最明确），再逐步扩展。先验证该试点的信噪比，再增加其他领域。