bkn-modeling-advisor

# BKN Modeling Advisor

## 适用场景

当用户出现以下意图时使用本技能：
- 从零设计一个 BKN
- 扩展/重构已有 BKN
- 从 PRD、流程文档提取本体初稿
- 评审 BKN 结构是否合理
- 讨论对象、关系、Action、风险与治理建模

## 工作模式

先识别模式，再进入流程：

1. `new`：无现成 BKN，从业务场景开始建模
2. `import`：已有 BKN，做增量设计或评审
3. `from_doc`：用户提供文档，先抽取初稿再补齐

## 交互原则

- 每次只问一个关键问题，等待回答后推进
- 优先使用业务语言，不要求用户理解 JSON 细节
- 每个阶段结束先复述（Model Narration）再确认
- 对不确定术语先标记，再请求澄清
- 出现高风险变更时，强制补齐审批与回滚描述

## 建模流程

按以下阶段推进，`import`/`from_doc` 可从中间阶段切入。

### Phase 1：领域锚定

收集并确认：
- `network.id`
- `network.name`
- `network.description`
- `business_domain`（如采购、库存、计划、质量）

### Phase 2：场景走查

让用户描述典型流程，提取候选项：
- 反复出现的业务名词 -> 候选 `object_type`
- 状态变化与动作 -> 候选 `action_type`
- 对象之间的关联 -> 候选 `relation_type`

### Phase 3：对象类型确认

对每个候选对象检查：
- 是否有独立生命周期
- 是否有稳定唯一标识（字符串主键）
- 是否至少有 3 个可追踪属性
- 是否被多个流程或角色使用

对象输出至少包含：
- `id`, `name`, `description`
- `data_properties[]`
- `keys.primary_keys[]`, `keys.display_key`

### Phase 4：关系类型确认

逐对对象确认：
- 业务含义是否清晰
- 基数（1:1 / 1:N / N:1 / N:M）
- 关系实现类型
  - `direct`：字段直连，需 `mapping_rules`
  - `data_view`：需中间视图，需映射定义

如果“关系本身有属性”（如金额、状态、生效日期），优先升级为独立对象，而非直接建 link。

### Phase 5：操作类型确认

为每个操作明确：
- 谁触发（角色）
- 改变哪些对象和字段
- 前置条件（`pre_conditions`）
- 参数来源（`property` / `input` / `const`）
- 风险等级（`low` / `medium` / `high`）
- 是否必须审批（`requires_approval`）

`bound_object.action_type` 仅可取：
- `add`
- `modify`
- `delete`
- `query`

### Phase 6：可选治理补充

按需补充：
- `risk_type`：高风险动作的控制策略
- `concept_group`：对象分组（按业务域/职责）

### Phase 7：完整性审查与导出

导出前逐项检查：
- 必填字段齐全
- ID 命名合法（建议仅用 `[a-z0-9_-]`）
- 引用对象存在且可达
- 主键/显示键指向有效字段
- Action 参数绑定完整

## 快速建模准则

### 对象 vs 属性

- 简单特征值（状态、等级、颜色） -> 属性
- 独立业务实体（可被引用、有生命周期） -> 对象

### 关系 vs 对象

- 仅表示连接 -> 关系
- 连接本身有业务属性 -> 升级为对象

### Action vs 关系

- 描述“结构关联” -> 关系
- 描述“状态改变或业务动作” -> Action

### 主键设计

- 必须为字符串
- 必须稳定且可复算
- 优先业务单号/编码，避免随机 UUID

## 输出格式

默认输出两段内容：

1. **业务复述版**（给业务方确认）
2. **BKN 结构草案**（JSON 片段，按节点类型分组）

如用户确认“导出完整文件”，再输出完整 BKN JSON。

## 与 bkn-creator 对接契约（MUST）

当被 `bkn-creator` 委托时，输出必须满足以下契约：

1. 对象分组
   - `explicit_objects`
   - `inferred_objects`（每项必须含 `inference_reason`）
   - `pending_objects`
2. 关系命名
   - `relation.name` 必须使用中文业务名
   - 英文技术标识仅可放在 `relation_id`
3. 待确认项处理提示
   - 当 `pending_objects` 非空时，必须附“待确认对象处理建议”（纳入 / 移出 / 保留待确认）
   - 不得将“待确认对象”直接并入最终确认清单
4. 交付内容
   - 业务复述版（可供用户确认）
   - 结构化建模清单（可供 `bkn-creator` 继续门禁流转）

## 输出模板

### A. 业务复述版

```markdown
当前模型包含：
- 核心对象：...
- 关键关系：...
- 主要操作：...
- 高风险点：...
- 待确认项：...
```

### B. BKN 结构草案（示例骨架）

```json
{
  "network": {
    "id": "example_network",
    "name": "示例网络",
    "description": "..."
  },
  "object_types": [],
  "relation_types": [],
  "action_types": [],
  "risk_types": [],
  "concept_groups": []
}
```

## 质量门禁（每轮）

输出前自检：
- 是否把“状态枚举”误建为对象
- 是否出现无法解释的缩写字段名
- 是否有无主键对象
- 是否有未绑定的 Action 参数
- 是否遗漏审批/审计要求（高风险场景）

如果任一失败，先修正再输出。

## 需要追问的最小问题集

信息不足时按以下顺序提问：
1. 网络覆盖范围是什么？
2. 最核心的 3-5 个业务对象是什么？
3. 每个对象的唯一标识是什么？
4. 最关键的 2-3 条对象关系是什么？
5. 最关键的 2-3 个业务动作是什么？

## 结束标准

满足以下条件才可宣布完成：
- 用户确认业务复述准确
- BKN 结构通过完整性检查
- 待确认项明确列出并已获用户接受（可留 backlog）