---
name: "cross-doc-consistency-check"
version: "1.0.0"
origin: "captured"
generation: 0
parent_skill_ids: []
status: "stable"
description: "跨文档一致性校验。当切片涉及 2+ 份设计文档时，沿 8 个维度（CC-01~CC-08）检测文档间的术语、枚举、桥接键、状态、表名、角色权限、流程衔接和逆向流程跨域协调的不一致。在架构切片、Schema Guardian 和 Drift Check 阶段触发。"
trigger_phases: ["design-review", "architecture"]
applicable_agents: ["Copilot Architect", "Copilot Drift Check"]
priority: 20
---

# Cross-Document Consistency Check

> **定位**：当一个实施切片或业务域涉及 2 份及以上设计文档时，检测文档间在 8 个维度上的不一致，避免实现时产生跨域矛盾。

## 何时触发

| 触发条件 | 说明 |
|---|---|
| 切片涉及 2+ 份设计文档 | Orchestrator 或 Architect 在路由时识别多文档依赖 |
| 跨模块集成设计 | 涉及 Feign 调用、事件驱动、共享数据表的模块边界 |
| Schema Guardian 发现跨表命名冲突 | 不同模块的表/字段命名不一致时触发深度检查 |
| Drift Check 发现跨域实现偏差 | 实现与设计在模块边界处不一致时回溯文档一致性 |

## 谁来调用

| Agent | 职责 |
|---|---|
| **Copilot Architect** | 架构切片阶段执行全量 CC-01~CC-08 检查 |
| **Copilot Schema Guardian** | DDL/Entity 一致性检查中发现跨模块命名冲突时触发 CC-03, CC-05 |
| **Copilot Drift Check** | 实现偏差回溯时触发 CC-04, CC-07, CC-08 |

---

## §1 一致性维度定义（CC-01 ~ CC-08）

### CC-01 术语一致性

**检查目标**：同一业务概念在不同文档中的名称是否统一。

| 检查项 | 示例 |
|---|---|
| 实体中文名是否一致 | 文档A称"设备台账"，文档B称"资产清册" → 需统一 |
| 实体英文名/表名是否一致 | `eam_asset` vs `eam_equipment` → 需确认是同一实体还是不同实体 |
| 字段含义是否一致 | 文档A的"负责人"指设备负责人，文档B的"负责人"指维护负责人 → 需区分 |

**输出**：术语对照表，标注冲突项和建议统一名称。

### CC-02 枚举/字典一致性

**检查目标**：共享的枚举/字典值在不同文档中定义是否一致。

| 检查项 | 示例 |
|---|---|
| 相同字典编码的值列表是否一致 | 文档A定义设备状态 = {运行中,停机,报废}，文档B = {运行,停机,待报废,已报废} → 不一致 |
| 枚举值的编码方式是否一致 | 文档A用数字编码 (1,2,3)，文档B用字符编码 (RUNNING,STOPPED) → 不一致 |
| 是否引用了同一个 BladeX 字典表 | 两份文档定义了功能重叠的不同字典 → 建议合并 |

**输出**：枚举对照矩阵，标注重叠/冲突/缺失项。

### CC-03 桥接键一致性

**检查目标**：模块间通过外键/引用关系连接的字段类型和语义是否一致。

| 检查项 | 示例 |
|---|---|
| FK 字段类型是否一致 | 文档A的 `asset_id` 为 Long/BIGINT，文档B引用的 `asset_id` 为 VARCHAR(64) → 类型冲突 |
| FK 字段指向的实体是否明确 | 文档A的 `product_id` 指向共享产品表，文档B的 `product_id` 指向本地物料表 → 语义冲突 |
| 引用方向是否一致 | 文档A认为 A→B 是主从关系，文档B认为 B→A → 方向冲突 |

**输出**：桥接键映射表，标注类型/语义/方向冲突。

### CC-04 状态定义一致性

**检查目标**：共享实体或流程衔接点的状态定义是否一致。

| 检查项 | 示例 |
|---|---|
| 上游模块的终态是否是下游模块的起始条件 | 采购单"已入库"是库存模块的触发前提，但采购文档终态只有"已完成" → 衔接断裂 |
| 相同实体在不同文档中的状态枚举是否一致 | 工单在文档A有 6 个状态，在文档B只引用了 4 个 → 缺失 |
| 状态迁移条件是否兼容 | 文档A要求"已审批"才能执行，文档B允许"待审批"就开始执行 → 冲突 |

**输出**：状态衔接矩阵，标注断裂和冲突点。

### CC-05 表名/实体引用一致性

**检查目标**：文档间引用的数据库表名、实体名是否指向同一个物理对象。

| 检查项 | 示例 |
|---|---|
| 跨文档引用的表名是否存在 | 文档A引用 `mdm_product` 表，但 MDM 文档中表名为 `mdm_material` → 引用错误 |
| 表的字段集是否匹配 | 文档A假设 `mdm_product` 有 `spec` 字段，但实际主数据文档中无此字段 → 字段假设错误 |
| 表的归属模块是否明确 | 两个文档都声称 `shared_attachment` 表归自己管理 → 归属冲突 |

**输出**：表引用交叉索引，标注引用错误和归属冲突。

### CC-06 角色/权限一致性

**检查目标**：跨文档引用的角色定义和权限假设是否一致。

| 检查项 | 示例 |
|---|---|
| 角色名称是否统一 | 文档A称"设备管理员"，文档B称"资产管理员" → 是否同一角色 |
| 权限范围是否一致 | 文档A赋予"维护主管"审批权限，文档B未提及该角色可审批 → 权限假设不一致 |
| 数据权限范围是否兼容 | 文档A按部门过滤，文档B按产线过滤 → 粒度冲突 |

**输出**：角色权限交叉矩阵，标注名称冲突和权限假设不一致。

### CC-07 流程衔接一致性

**检查目标**：模块间业务流程的上下游衔接是否完整且无矛盾。

| 检查项 | 示例 |
|---|---|
| 上游输出是否满足下游输入要求 | 维护计划输出"工单创建请求"，但工单文档要求的必填字段在计划文档中未定义 → 字段缺失 |
| 触发机制是否一致 | 文档A说通过 Feign 同步调用创建工单，文档B说通过消息队列异步接收 → 集成方式冲突 |
| 流程边界是否清晰 | 文档A的流程覆盖到"工单创建"，文档B的流程从"工单分配"开始 → 创建环节无人负责 |

**输出**：流程衔接链路图，标注断点和冲突。

### CC-08 逆向流程跨域一致性

**检查目标**：当一个模块的逆向流程（回退/撤回/冲销）影响到另一个模块时，两边的处理是否协调。

| 检查项 | 示例 |
|---|---|
| 上游回退时下游是否有处理逻辑 | 采购单撤回时，已触发的入库单如何处理？入库文档是否定义了"上游撤回"场景 |
| 级联回退范围是否双方一致 | 文档A说回退时通知下游取消，文档B未定义接收取消通知的逻辑 → 单边处理 |
| 补偿事务是否跨域对齐 | 文档A说失败时自动冲销，但下游文档B不支持被动冲销 → 补偿断裂 |
| 外部系统失败时的跨域恢复 | ERP 回传失败后，MES 侧的单据恢复逻辑与 ERP 侧的重试逻辑是否匹配 |

**输出**：跨域逆向流程协调矩阵，标注单边处理、补偿断裂和未定义场景。

---

## §2 检查流程

```
1. 收集本次切片涉及的所有设计文档路径
2. 从每份文档中提取关键元素：
   a. 术语表 / 核心实体名称
   b. 枚举/字典定义
   c. 外键/引用字段
   d. 状态枚举和状态迁移矩阵
   e. 引用的外部表名/实体名
   f. 角色/权限定义
   g. 流程起止点和上下游触发
   h. 逆向流程描述（回退/撤回/冲销/补偿）
3. 逐维度 CC-01~CC-08 交叉比对：
   → 每个维度输出: CONSISTENT / CONFLICT / PARTIAL / NOT_APPLICABLE
4. 对 CONFLICT 项输出具体冲突描述和建议修复方案
5. 对 PARTIAL 项输出覆盖差异和补完建议
6. 汇总输出一致性报告
```

## §3 严重性分级

| 级别 | 条件 | 动作 |
|---|---|---|
| **CRITICAL** | CC-03 桥接键类型冲突、CC-04 状态衔接断裂、CC-08 逆向流程补偿断裂 | **BLOCKED** — 必须在架构阶段解决 |
| **HIGH** | CC-01 核心实体术语冲突、CC-05 表引用错误、CC-07 流程边界断点 | **WARNING** — 必须在实施前解决 |
| **MEDIUM** | CC-02 枚举值部分不一致、CC-06 角色名称不统一 | **WARNING** — 建议实施前解决 |
| **LOW** | CC-02 编码风格差异、CC-06 数据权限粒度不同 | **INFO** — 记录并在实施时统一 |

## §4 输出格式

```markdown
## 跨文档一致性检查报告

**涉及文档**:
1. <文档A名称> — <路径>
2. <文档B名称> — <路径>
3. ...

**检查日期**: YYYY-MM-DD
**总体判定**: CONSISTENT / BLOCKED / WARNING

### 一致性维度摘要

| 维度 | 编号 | 判定 | 冲突数 | 严重级别 |
|---|---|---|---|---|
| 术语一致性 | CC-01 | CONSISTENT / CONFLICT | 0 / N | — / HIGH |
| 枚举一致性 | CC-02 | CONSISTENT / PARTIAL | 0 / N | — / MEDIUM |
| 桥接键一致性 | CC-03 | CONSISTENT / CONFLICT | 0 / N | — / CRITICAL |
| 状态定义一致性 | CC-04 | CONSISTENT / CONFLICT | 0 / N | — / CRITICAL |
| 表名引用一致性 | CC-05 | CONSISTENT / CONFLICT | 0 / N | — / HIGH |
| 角色权限一致性 | CC-06 | CONSISTENT / CONFLICT | 0 / N | — / MEDIUM |
| 流程衔接一致性 | CC-07 | CONSISTENT / CONFLICT | 0 / N | — / HIGH |
| 逆向流程跨域一致 | CC-08 | CONSISTENT / CONFLICT | 0 / N | — / CRITICAL |

### 冲突详情

#### [CRITICAL] CC-03-001: asset_id 类型冲突
- **文档A** (EAM设备台账): `asset_id` BIGINT / Long
- **文档B** (维护工单): `asset_id` VARCHAR(64) / String
- **影响**: Feign 调用参数类型不匹配，运行时类型转换异常
- **建议**: 统一为 BIGINT/Long，遵循 BladeX TenantEntity 主键规范

#### [HIGH] CC-07-001: 工单创建流程断点
- **文档A** (维护计划): 流程终止于"触发工单创建"
- **文档B** (维护工单): 流程起始于"工单已创建，待分配"
- **缺口**: 谁负责实际的工单创建行为？Feign 还是消息？
- **建议**: 在文档A中补充创建机制，或在文档B中补充接收创建请求的入口

### 补完建议汇总

| 优先级 | 文档 | 维度 | 补完内容 |
|---|---|---|---|
| CRITICAL | 文档B | CC-03 | 将 asset_id 类型统一为 BIGINT |
| HIGH | 文档A+B | CC-07 | 补充工单创建的集成机制 |
| ... | ... | ... | ... |
```

## §5 与其他 Skill 的协作

| 协作 Skill | 协作方式 |
|---|---|
| `design-doc-completeness-check` | completeness-check 检查单文档结构完整性；本 skill 检查跨文档间的一致性 |
| `constraint-first-protocol` | CC-08 逆向流程跨域冲突可直接输入失败矩阵 |
| `physical-data-model-review` | CC-03 桥接键冲突和 CC-05 表名冲突可触发物理模型审查 |
| `fk-field-detection` | CC-03 发现的 FK 类型冲突可作为 FK 检测的补充输入 |
| `design-doc-to-page-coverage-check` | 跨文档共享字段的页面覆盖需在两个模块的页面中都体现 |