# 分组维度推导详细方法

> 本文件包含分组推导的完整信号表、推导流程和评判标准。
> 在执行工作流 Phase 2（分组推导）时读取本文件。

---

## 📋 目录

1. [推导信号](#推导信号)
2. [架构模式识别](#架构模式识别)
3. [四阶段推导流程](#四阶段推导流程)
4. [分组质量评判标准](#分组质量评判标准)
5. [已有文档的处理策略](#已有文档的处理策略)
6. [现场调研机制](#现场调研机制)

---

## 推导信号

### 第一层：显式边界（🤖 确定性高）

从构建系统直接获取的硬边界：

| 信号来源 | 检测方式 | 推导意义 |
|---------|---------|---------|
| Maven `<modules>` | 解析 pom.xml | Java 模块列表 |
| npm workspaces | 解析 package.json | JS/TS 包列表 |
| CMake `add_subdirectory` | 解析 CMakeLists.txt | C/C++ 子项目列表 |
| Cargo workspace | 解析 Cargo.toml | Rust crate 列表 |
| Go modules | go.mod + 目录结构 | Go 包列表 |
| .NET Solution | 解析 .sln 文件 | C# 项目列表 |
| 目录结构 | `find . -maxdepth 2 -type d` | 层级组织模式 |
| 入口文件 | main.*/index.*/app.* | 应用边界 |

### 第二层：架构模式（🤖👤 半确定性）

从代码组织方式推断：

| 代码模式 | 推断的架构 | 推荐的分组思路 |
|---------|----------|-------------|
| Controller/Service/Repository | 分层架构 | 按层或按模块 |
| Entity/Component/System | ECS 架构 | 按系统 |
| 独立部署的服务 + Gateway | 微服务 | 按服务 × 关注点 |
| Pipeline/Stage/Pass | Pipeline 架构 | 按阶段 |
| Plugin/Extension/Hook | 插件架构 | 按插件 |
| Feature/ 目录切片 | Feature-Sliced Design | 按功能切片 |
| Pages/Routes/Components | SPA/前端 | 按页面/组件 |
| HAL/Driver/App | 嵌入式分层 | 按抽象层 |

### 第三层：关注点（🤖👤 半确定性）

从配置和代码模式提取横切关注点：

| 信号 | 来源 | 关注点 |
|------|------|-------|
| CI/CD 配置文件 | .github/workflows, Jenkinsfile, .gitlab-ci.yml | DevOps |
| linter/formatter 配置 | .eslintrc, checkstyle.xml, .prettierrc | 编码规范 |
| 安全审计配置 | SAST/DAST 配置, 安全策略文件 | 安全 |
| i18n 资源文件 | messages_*.properties, locale/ | 国际化 |
| 测试框架配置 | jest.config, pytest.ini, *_test.go | 测试 |
| Docker/K8s 配置 | Dockerfile, docker-compose, *.yaml | 部署 |
| 性能监控配置 | APM 配置, profiling 配置 | 性能 |
| 错误追踪配置 | Sentry, Bugsnag 配置 | 错误处理 |

---

## 架构模式识别

### 识别方法

1. **目录名模式匹配**：扫描顶级和二级目录名，匹配常见模式
2. **文件命名模式**：如 `*_controller.*`、`*_service.*`、`*_test.*`
3. **依赖方向分析**：检查 import/require 语句的依赖方向
4. **配置文件分析**：框架配置文件揭示架构选择

### 常见技术栈的典型分组参考

> 以下仅供参考（启发提示），不作为强制模板。实际分组以实时分析为准。

| 技术栈 | 典型分组维度 | 说明 |
|--------|------------|------|
| Java Spring Boot | 问题×关注点×模块 | 架构文档按问题，规范按关注点，模块按构建单元 |
| React/Vue | 组件×页面×关注点 | 组件文档按组件类型，页面按路由，规范按关注点 |
| 微服务 | 服务×关注点×协议 | 每个服务独立文档，跨切面按关注点 |
| 游戏引擎 | 系统×资源×管线×工具链 | 按游戏子系统组织 |
| 嵌入式 | 层(HAL/Driver/App)×协议×板级 | 按抽象层组织 |
| 编译器 | 阶段×IR层×优化pass | 按编译流水线阶段 |
| 数据工程 | Pipeline×数据域×质量 | 按数据流组织 |
| CLI 工具 | 命令×插件×解析器 | 按命令和扩展点 |
| 移动端 | 屏幕×服务×导航 | 按页面和平台服务 |
| DevOps | Pipeline×监控×告警 | 按运维关注点 |

---

## 四阶段推导流程

### Phase 1: 探测显式边界

```
1. 检测构建文件 → 提取模块/包/子项目列表
2. 扫描目录结构 → 识别层级组织模式
3. 检测入口文件 → 确定应用边界
4. 输出: 模块边界清单（JSON 格式）
```

### Phase 2: 识别架构模式

```
1. 分析代码组织 → 匹配架构模式（分层/ECS/微服务/Pipeline/插件...）
2. 分析依赖方向 → 判断单向/环形/网状
3. 分析测试结构 → 识别关注点分离方式
4. 输出: 架构模式判定 + 推荐分组方向
```

### Phase 3: 识别关注点

```
1. 扫描配置文件 → 提取横切关注点
2. 分析代码模式 → 识别异常处理/日志/缓存等关注点
3. 分析依赖库 → 列出框架能力
4. 输出: 关注点清单
```

### Phase 4: 综合推导 + 用户确认

```
1. 将 Phase 1-3 结果综合:
   - 模块边界 → "模块"类文档的分组基础
   - 架构模式 → "架构"类文档的分组基础
   - 关注点 → "规范/约束"类文档的分组基础

2. 职责检查: 每个分组是否有独立的文档职责？
3. 内聚检查: 分组内文档是否回答同一类问题？

4. 展示推导过程 + 结果 → 用户确认/调整
```

---

## 分组质量评判标准

以**职责**为核心评判维度：

| 标准 | 问题 | 权重 |
|------|------|------|
| **内聚度** | 分组内文档是否回答同一类问题？ | 高 |
| **可维护性** | 不同分组的文档是否有不同的维护频率/模式？ | 高 |
| **可发现性** | 读者能否根据意图快速定位到对应分组？ | 中 |
| **职责独立** | 每个分组是否承载独立的"文档职责"？ | 高 |
| **粒度适当** | 分组数量是否在 2-6 个之间？ | 中 |

**推导结果不唯一时的处理**：展示所有可行方案，标注推荐方案，由用户最终决定。

---

## 已有文档的处理策略

当项目已有 `docs/` 或其他文档目录时，向用户展示两个等价选项：

| 选项 | 说明 | 适用场景 |
|------|------|---------|
| **尊重现有 + 改进建议** | 分析现有分组结构，识别问题并给出改进建议 | 现有结构基本合理 |
| **全面重新设计** | 忽略现有结构，从零推导最优分组 | 现有结构混乱 |

**关键原则：没有默认选项。** 必须由用户主动选择。

---

## 现场调研机制

### 触发条件

- 不熟悉的项目类型（如 FPGA、内核开发等小众领域）
- 推导结果的置信度较低
- 用户要求参考业界实践

### 调研内容

- 该技术栈/领域的业界常见文档组织方式
- 该领域开发者通常期望的文档结构
- 该领域特有的文档关注点

### 调研结果的使用

- 作为推导的**辅助输入**，不作为唯一依据
- 与实时分析结果对比，取最优
- 向用户展示调研结果和推导结果的差异
- **偏离提示**：当实时分析结果与模式库/调研结果偏离过大时，主动向用户提示偏离内容并解释原因，但不强制修正——用户做出最终决定