---
name: docmap
description: |
  项目文档架构生成技能。从代码、SQL、接口定义、文档中提炼产品视角的架构文档。
  输出：《产品整体架构文档》+ 各模块《功能模块拆解文档》+ 系统能力模型。
  适用场景：新项目入手、产品知识基座构建、PRD 生成前的背景探索。
  触发关键词：分析项目架构、生成产品文档、生成架构文档、理解系统、/docmap
---

# docmap — 项目文档架构生成

## 触发条件
- 用户说"分析项目架构"、"生成产品文档"、"生成架构文档"
- 用户说"帮我理解这个系统"、"先了解项目再写 PRD"
- 直接输入 `/docmap [项目路径]`

---

## 角色定位
资深产品架构师 + 系统架构师 + 技术产品经理。从代码和文档中提炼产品层逻辑，而非重复代码结构。

---

## Phase 0：资源发现与确认

扫描以下资源路径（以项目根为准，默认路径为本项目实际结构）：

| 资源 ID | 默认路径                                  | 内容 | 优先级 |
|---------|---------------------------------------|------|--------|
| SRC-KNOWLEDGE | `assets/codemap/`、`assets/domainmap/` | 已有结构化知识（YAML 知识图谱），存在时优先消费 | P0 |
| SRC-FEAT | `prds/`                               | 功能需求文档 | P0 |
| SRC-CODE | `codes/`（源码子仓库）                       | 代码结构 | P0 |
| SRC-SQL | `docs/sql/` 或各仓库内 SQL                 | 数据库设计 | P1 |
| SRC-API | `docs/open-api/`                      | 接口定义 | P1 |
| SRC-REVIEW | `docs/` 下评审类目录                        | 评审报告 | P2 |

**路径发现策略：**
1. 检查默认路径是否存在
2. 不存在时扫描项目根目录寻找对应内容
3. 向用户确认发现的路径，确认后把最终路径映射写入 `materials_index.md`

**输出：** `materials_index.md`（资料索引）

---

## 输入来源与技能边界

- codemap / domainmap 产出**结构化事实**（YAML 知识图谱：符号、API、调用链、数据对象、实体、流程、规则等）；docmap **消费其产出**，撰写叙事性产品文档，不重复生成结构化事实。
- 当 `assets/codemap/`、`assets/domainmap/` 存在时，模块边界、数据流、业务流程等分析应**优先引用**其中的结构化事实，而非从原始代码重新挖掘；原始代码仅用于补充知识图谱未覆盖的细节。
- 引用结构化知识时按 `[SRC-KNOWLEDGE]` 标注证据（见"证据标注"节）。

---

## Phase 1：项目深度理解

6 个维度分析（每个维度必须有输出）：

| 维度 | 分析问题 | 主要资源 |
|------|---------|---------|
| 系统目标 | 产品要解决什么问题？核心价值是什么？ | SRC-FEAT |
| 核心业务流程 | 主流程是什么？关键节点有哪些？ | SRC-FEAT + SRC-CODE |
| 系统角色 | 有哪些用户角色？各自的操作边界？ | SRC-FEAT |
| 模块边界 | 系统拆分为哪些模块？边界如何划定？ | SRC-CODE |
| 数据流 | 数据从哪里来、流向哪里？生命周期？ | SRC-SQL + SRC-API |
| 系统依赖 | 内外部依赖有哪些？集成点在哪？ | SRC-API + SRC-CODE |

**输出：** `phase1_analysis.md`

---

## Phase 2：输出文档生成

### 2.1 产品整体架构文档

**文件：** `outputs/01-产品整体架构.md`

必须包含：
1. 产品定位（目标、价值、用户、场景）
2. 系统整体架构（分层、技术概览、依赖关系）
3. 业务架构图（Mermaid）
4. 核心业务流程说明（Mermaid 流程图）
5. 数据架构（实体、关系、生命周期）
6. 权限与角色体系（角色定义、权限分层）
7. 系统扩展点分析

### 2.2 功能模块拆解文档

**目录：** `outputs/02-功能模块/`  
**命名：** `{序号}-{模块名}.md`

每个模块包含：
1. 模块定位
2. 功能清单（表格）
3. 核心逻辑（规则、校验、状态流转 Mermaid）
4. 数据结构（表、字段、关联）
5. 对外接口（API、事件、回调）
6. 异常与边界处理

---

## Phase 3：系统能力模型

**文件：** `outputs/03-系统能力模型.md`

包含：
1. 核心能力清单（不超过 10 项）
2. 能力依赖关系图（Mermaid）
3. 可复用能力清单（表格）
4. 平台级能力
5. 业务定制能力

---

## Phase 4：质量检查

执行验证脚本检查输出完整性：

```bash
python3 scripts/validate_output.py {workdir}/outputs
```

- **参数：** `outputs` 子目录路径（脚本位于本技能 `scripts/` 下，参数可写相对项目根路径或绝对路径）
- **报告输出：** `{workdir}/validation_report.md`（即 outputs 的父目录）
- **退出码：** 存在失败项时为非零；仅有警告项时为零

检查项（与脚本口径一致）：
- 目录结构完整（`01-产品整体架构.md`、`02-功能模块/`、`03-系统能力模型.md`）
- 架构文档 7 个章节完整
- 架构文档至少 2 个 Mermaid 图
- 模块文档都有功能清单表格
- 能力模型包含能力依赖关系图（Mermaid）及平台级/业务定制能力区分
- 模块文档 stateDiagram 状态流转图（警告项，不阻断：无状态机的模块可豁免）
- 模糊表述（"等"、"等情况"、"等多种"等；警告项，不阻断）

**输出：** `validation_report.md`

---

## 写作原则

- **产品视角**，不重复代码结构
- **逻辑严谨**，不泛泛而谈
- **可长期维护**
- 禁止模糊表达："等情况"、"等多种"、"其他相关"

### 证据标注
- `[SRC-KNOWLEDGE]` - 已有结构化知识库（codemap / domainmap）
- `[SRC-FEAT]` - 功能文档
- `[SRC-CODE]` - 代码结构
- `[SRC-SQL]` - 数据库设计
- `[SRC-API]` - 接口定义
- `[ASSUMPTION]` - 无证据推断

---

## 工作目录结构

```
{workdir}/
├── materials_index.md
├── phase1_analysis.md
├── outputs/
│   ├── 01-产品整体架构.md
│   ├── 02-功能模块/
│   │   └── {序号}-{模块名}.md
│   └── 03-系统能力模型.md
└── validation_report.md
```

---

## 使用 bundled resources

### 参考模板
- `references/architecture_template.md` - 架构文档模板
- `references/module_template.md` - 模块文档模板
- `references/capability_template.md` - 能力模型模板

### 验证脚本
- `scripts/validate_output.py` - 输出质量检查脚本

---

## 版本历史

- **v1.1**（2026-08）输入源对齐项目实际结构（`codes/`、`prds/`、`docs/` 子目录）；新增"输入来源与技能边界"，消费 codemap/domainmap 已有产出；Phase 4 补验证脚本调用示例，检查项口径与脚本实现对齐
- **v1.0** 初始版本