---
name: sn-domainmap
description: 从业务文档（手册/流程/PRD/数据字典）提取结构化领域知识图谱（实体、流程、规则、术语表，D4 含页面流程、配置影响、运行态采集与 CodeMap 深度交叉引用）。当用户要求"分析业务文档"、"提取业务流程"、"创建 domainmap/业务知识图谱"或输入 /sn-domainmap、/domainmap 时使用。
---

# Domain Map 业务领域知识图谱生成 (sn-domainmap)

## 功能概述

从业务文档中提取结构化的领域知识：

**基础能力（D1–D3，executor 已实现）**：
- 业务实体：核心业务对象及其状态机定义
- 业务流程：工作流、阶段、角色、Mermaid 图
- 业务规则：校验规则、计算规则、流转规则
- 术语表：业务专有名词定义和口径
- 交叉引用：与 CodeMap 的基础关联（实体→代码、流程→API、术语→符号）

**可选扩展（D4，见下文）**：
- 页面流程：页面→API→方法→表的完整链路
- 配置影响：配置项对功能的影响映射
- 运行态事实：系统截图、菜单树、表单字段
- CodeMap 深度引用：与 formulas、decisions、errors、thresholds 关联

---

## 核心理念

```
CodeMap 回答 "系统能做什么"（Capability）
DomainMap 回答 "系统应该怎么做"（Intent & Contract）
两者结合形成完整的语义网络
```

---

## 分析等级

### D1–D3（executor 覆盖）

| 等级 | 名称 | 内容 | 适用场景 |
|------|------|------|----------|
| **D1** | 快速扫描 | 实体 + 术语，不提取流程/规则 | 快速了解业务概念 |
| **D2** | 标准分析 | 实体 + 流程 + 规则 + 术语 | 日常参考（默认） |
| **D3** | 完整生成 | D2 全量 + CodeMap 基础交叉引用 | 完整文档 |

### D4 可选扩展

executor 的执行流程覆盖 D1–D3。以下内容为**按需扩展**，模板已备在 `templates/`（config_impact / runtime / screen_flow），schemas 中有对应校验定义，但 executor 未内置生成步骤——需要时由执行代理参照模板手动生成：

- `screen_flows/`：页面→API→方法→表链路（模板 `screen_flow.template.yaml`）
- `config_impact/`：配置项对功能的影响（模板 `config_impact.template.yaml`）
- `runtime/`：运行态采集（模板 `runtime.template.yaml`）。**仅当 chrome-devtools MCP 可用时才采集**；不可用时直接跳过，不阻塞 D1–D3 产出。
- 深度交叉引用：`rule-to-code`、`screen-to-api`、`screen-to-formula`、`screen-to-decision`、`config-to-formula`（依赖 CodeMap 的 formulas/decisions 等 L4 产物存在）

---

## 执行流程（Phase）

执行时**先加载 `executor.yaml`** 作为执行指引；`templates/` 与 `schemas/` 在各 Phase 的生成/校验步骤中按需查阅。

| Phase | 名称 | 说明 |
|-------|------|------|
| -1 | 交互式初始化 | 询问分析等级（D1/D2/D3）、文档目录、输出目录、CodeMap 关联 |
| 0 | 文档扫描与分类 | 扫描文档目录，按类型分类（手册/流程/PRD/数据字典） |
| 1 | 业务实体提取 | 生成 `entities/*.yaml` + 索引 |
| 2 | 业务流程提取 | 生成 `processes/*.yaml` + 索引（D1 跳过） |
| 3 | 业务规则提取 | 生成 `rules/**/*.yaml` + 索引（D1 跳过） |
| 4 | 术语表构建 | 生成 `glossary/terms/*.yaml` + 索引 |
| 5 | CodeMap 交叉引用 | 生成 `xrefs/` 3 个基础映射（提供 codemap 路径时） |
| 6 | 索引生成与完整性检查 | 生成 `_index.yaml`、`state.yaml`，对照 schemas 校验关键产物 |

---

## 输出目录结构

输出根目录统一为 `domainmap/`（即 `{{output_dir}}/domainmap`）：

```
domainmap/
├── _index.yaml                    # 项目主索引
├── .domainmap/state.yaml          # 分析状态（断点续跑）
│
├── entities/                      # 业务实体
│   ├── _entities_index.yaml
│   └── {entity-name}.yaml
│
├── processes/                     # 业务流程
│   ├── _processes_index.yaml
│   └── {process-name}.yaml
│
├── rules/                         # 业务规则（rule_set 包装结构）
│   ├── _rules_index.yaml
│   ├── validation/
│   │   └── {rule-name}.yaml
│   ├── calculation/
│   │   └── {rule-name}.yaml
│   └── transition/
│       └── {rule-name}.yaml
│
├── glossary/                      # 术语表
│   ├── _glossary_index.yaml
│   └── terms/
│       └── {domain}-terms.yaml
│
├── xrefs/                         # 基础交叉引用（D3，提供 codemap 时）
│   ├── _xrefs_index.yaml
│   ├── entity-to-code.yaml        # 实体→代码符号
│   ├── process-to-api.yaml        # 流程→API
│   └── term-to-symbol.yaml        # 术语→符号
│
├── screen_flows/                  # 页面流程（可选扩展 D4）
│   └── {flow-name}.yaml
│
├── config_impact/                 # 配置影响（可选扩展 D4）
│   ├── by_table/
│   └── by_function/
│
└── runtime/                       # 运行态事实（可选扩展 D4，需 chrome-devtools MCP）
    ├── system_access.yaml
    ├── menu_tree.yaml
    ├── pages/
    └── screenshots/
```

D4 深度交叉引用文件（`rule-to-code.yaml`、`screen-to-api.yaml`、`screen-to-formula.yaml`、`screen-to-decision.yaml`、`config-to-formula.yaml`）属于可选扩展，生成时放入 `xrefs/` 并在 `_xrefs_index.yaml` 中登记。

---

## 完整性检查（Phase 6）

```
业务实体：entities/*.yaml 文件数 >= _entities_index.yaml 声明总数
业务流程：processes/*.yaml 文件数 >= _processes_index.yaml 声明总数
业务规则：rules/**/*.yaml 文件数 >= _rules_index.yaml 声明规则集总数
术语表：glossary/terms/*.yaml 条目数 >= _glossary_index.yaml 声明总数
Schema 校验：关键产物（索引、实体、流程、规则、术语、xref）对照 schemas/ 校验，
           校验失败项列入完整性报告
```

---

## 上下文管理

### 分批执行（大型项目）

| 内容类型 | 批次大小 |
|----------|----------|
| 文档分析 | 5 个/批 |
| 实体生成 | 10 个/批 |
| 流程生成 | 5 个/批 |
| 规则提取 | 20 条/批 |

### 断点续跑

```bash
/sn-domainmap --resume
```

状态保存在 `domainmap/.domainmap/state.yaml`，支持中断后继续。

---

## 使用场景

- 用户说"分析业务文档"、"提取业务流程"
- 用户说"创建 domainmap"、"业务知识图谱"
- 用户想要理解业务规则和流程
- 用户想要将业务知识与代码关联
- 直接输入 `/sn-domainmap` 或 `/domainmap`

## 命令格式

```
/sn-domainmap [<docs_path>] [options]

选项：
  --output, -o        输出目录（产物写入 {output}/domainmap/）
  --link-codemap, -l  关联的 CodeMap 目录
  --focus, -f         聚焦特定业务域
  --level             分析等级 (D1/D2/D3)
  --resume            从上次中断处继续
```

---

## 支持的文档类型

| 类型 | 格式 | 提取内容 |
|------|------|----------|
| 使用手册 | .md, .docx | 功能入口、字段规则、操作流程 |
| 流程手册 | .md, .docx | 业务流程、角色职责、状态流转 |
| 需求文档 | .md, .docx | 功能定义、验收标准、业务规则 |
| 数据字典 | .xlsx | 字段口径、枚举定义、取值范围 |

---

## 与 CodeMap 的关系

### 基础交叉引用（D3，executor 已实现）

| 类型 | DomainMap | CodeMap | 说明 |
|------|-----------|---------|------|
| entity-to-code | entities/*.yaml | dataobjects/{lang}/、symbols/{lang}/ | 业务实体→代码实体 |
| process-to-api | processes/*.yaml | api/{lang}/_api_catalog.yaml、callchains/{lang}/ | 业务流程→API/调用链 |
| term-to-symbol | glossary/terms/*.yaml | symbols/{lang}/ | 术语→枚举/常量 |

### 深度交叉引用（可选扩展 D4）

| 类型 | 说明 |
|------|------|
| rule-to-code | 业务规则→Service 方法 |
| screen-to-api | 页面→API |
| screen-to-formula | 页面→计算公式（需 CodeMap formulas/） |
| screen-to-decision | 页面→决策点（需 CodeMap decisions/） |
| config-to-formula | 配置→公式（需 CodeMap formulas/） |

### 推荐组合

```
CodeMap（代码知识图谱）+ DomainMap（业务知识图谱）
= 完整的业务-代码语义网络
```

---

## 版本历史

| 版本 | 更新内容 |
|------|----------|
| v3.0 | 统一等级体系为 D1/D2/D3（消除 standard/brief/deep 双轨）；D4 转为可选扩展并删除自相矛盾的强制框；修复 process-to-api 的 CodeMap 数据源断链（补加载 api/ 与 callchains/）；统一输出路径为 domainmap/；补齐 rule 与索引模板；Phase 6 增加 schema 校验 |
| v2.1 | 曾声称新增 D4 等级，但 executor 未实现对应 Phase（已纠正） |
| v2.0 | 添加生成等级定义（D1/D2/D3） |
| v1.1 | 新增页面流程、配置影响、运行态采集 |
| v1.0 | 初始版本 |

当前版本：v3.0