标题：开始之前
问题1：你对 Java/Maven 生态的熟悉程度？
选项：入门 / 熟悉 / 精通

问题2：你和这个项目的关系？
选项：完全陌生 / 大致了解 / 部分了解 / 参与开发

问题3：你想理解这个项目的目的？
选项：学习研究 / 接手维护 / 排查问题 / 二次开发

my-project/
├── pom.xml
├── core/
│   └── src/main/java/com/example/core/
├── api/
│   └── src/main/java/com/example/api/
└── service/
    └── src/main/java/com/example/service/

.project-understanding/
├── README.md                    # 阅读指南（如何使用这些文档）
├── ROADMAP.md                   # 源码阅读路线图（最重要的导航文件）
├── overview.md                  # 项目总览
├── architecture.md              # 架构设计
├── glossary.md                  # 术语表
├── exploration-log.md           # 探索日志
├── user-profile.md              # 用户画像
│
├── core/                        # ← 镜像 core 模块
│   ├── README.md                # core 模块概览
│   ├── com.example.core/        # ← 镜像包结构（用.分隔的目录名）
│   │   ├── _package.md          # 包级别说明
│   │   ├── CoreService.md       # 关键类文档（按需创建）
│   │   └── CoreConfig.md
│   └── resources.md             # 资源文件说明
│
├── api/                         # ← 镜像 api 模块
│   ├── README.md
│   └── com.example.api/
│       ├── _package.md
│       └── ApiController.md
│
└── service/                     # ← 镜像 service 模块
    ├── README.md
    └── com.example.service/
        └── _package.md

# 源码阅读路线图

> 本文档为你规划了一条理解此项目的推荐路径。
> 按顺序阅读标注了 ⭐ 的文件，可以最高效地建立对项目的整体认知。
> 每个阶段末尾有"检查点问题"，能回答这些问题说明你已理解该阶段。

## 阅读方式说明

| 标记 | 含义 |
|------|------|
| ⭐ 必读 | 理解项目的关键文件，必须仔细阅读 |
| 📖 推荐 | 有助于加深理解，建议阅读 |
| 📋 参考 | 遇到相关问题时查阅即可 |
| 🔗 | 指向对应的理解文档，阅读源码时可对照参考 |

## 阶段 1：项目全貌（预计 15 分钟）

**目标**：了解项目是做什么的、有哪些模块、怎么构建

| 优先级 | 文件 | 关注点 | 理解文档 |
|--------|------|--------|----------|
| ⭐ 必读 | `pom.xml` | modules 列表、properties、dependencyManagement | [overview.md](overview.md) |
| ⭐ 必读 | `README.md` | 项目用途、快速开始 | - |
| 📖 推荐 | `{module}/pom.xml` (逐个) | 各模块的依赖和职责 | [{module}/README.md]({module}/README.md) |

### ✅ 检查点问题
1. 用一句话描述这个项目是做什么的？
2. 项目有几个模块？它们之间的依赖关系是怎样的？
3. 项目使用了哪些核心框架/技术？

---

## 阶段 2：核心模块（预计 30 分钟）

**目标**：理解最核心模块的代码组织和关键类

| 优先级 | 文件 | 关注点 | 理解文档 |
|--------|------|--------|----------|
| ⭐ 必读 | `{core-module}/src/main/java/.../` | 包结构、核心接口定义 | [{module}/README.md] |
| ⭐ 必读 | `{关键类}.java` | 核心业务逻辑 | [{module}/{package}/{Class}.md] |
| 📖 推荐 | `{配置类}.java` | 配置项和默认值 | [{module}/{package}/{Class}.md] |

### ✅ 检查点问题
1. 核心模块的主要职责是什么？它暴露了哪些接口给其他模块？
2. {根据项目具体情况定制的问题}
3. 数据是怎么在模块间流动的？

---

## 阶段 3：关键流程（预计 45 分钟）
{按项目实际情况填充}

## 阶段 4：扩展与高级（按需）
{按项目实际情况填充}

我已经扫描了整个项目，这是一个 {项目类型}，包含 {N} 个模块。

在选择深入方向之前，我想先请你思考几个问题（不需要现在能回答，这些问题会在后续探索中逐步解答）：

💭 思考题：
1. 看到这 {N} 个模块的名字，你觉得哪些可能是"核心"模块，哪些可能是"辅助"模块？为什么？
2. 从 pom.xml 的 dependencies 来看，你能猜到这个项目大概在做什么类型的事情吗？
3. {根据项目特点定制的思考题}

不需要回答得很准确，这只是帮助你开始建立自己的"心智模型"。
我们后续的探索会验证或修正这些直觉。

在打开 {ClassName} 之前，根据它的名字和所在的包 {package}，
你觉得它可能负责什么？它可能会依赖哪些其他类？

现在你看到了 {ClassName} 的实现。
- 它实际做的事情和你之前的预判一致吗？有什么出乎意料的地方？
- 你能解释一下 {某个方法} 的参数为什么要这样设计吗？
- 如果让你来实现同样的功能，你会怎么设计？和作者的方案有什么不同？

我们已经看了 {模块A} 和 {模块B}。
- 它们之间的边界是怎么划分的？你觉得这种划分合理吗？
- 如果要在 {模块A} 中添加一个新功能，你觉得需要改动哪些地方？
- 你能画出（或描述出）从 {入口} 到 {出口} 的完整数据流吗？

## OrderService

订单服务的核心类，负责订单的创建、查询和状态流转。

📁 **源码位置**: `service/src/main/java/com/example/service/OrderService.java`

### 关键方法

| 方法 | 行号 | 作用 | 阅读优先级 |
|------|------|------|------------|
| `createOrder()` | L45-L89 | 创建订单的主流程 | ⭐ 必读 |
| `validateOrder()` | L91-L120 | 参数校验和业务规则检查 | 📖 推荐 |
| `notifyListeners()` | L122-L145 | 通知观察者模式的实现 | 📋 参考 |

### createOrder() 详解
<!-- 前置知识: Spring 事务管理 -->

**调用链**（建议对照源码阅读）：
1. `L45`: 入参校验 → 调用 `validateOrder()`
2. `L52`: 生成订单号 → 使用 `IdGenerator`（见 [core/IdGenerator.md](../core/com.example.core/IdGenerator.md)）
3. `L58-L70`: 持久化 → 通过 `OrderRepository`
4. `L72-L85`: 发布事件 → Spring ApplicationEvent
5. `L87`: 返回结果

> 💡 注意第 L63 行的 `@Transactional` 注解，这确保了订单创建和库存扣减在同一个事务中。

你现在可以打开 OrderService.java（L45），对照着 service/com.example.service/OrderService.md 中的流程说明来阅读。
文档中标注了每一步对应的行号，你可以跳着看关键部分。

我列出了所有模块和它们的依赖关系。

💭 思考题（带着这些问题去看模块代码）：
1. 为什么 {module-A} 和 {module-B} 是分开的两个模块而不是一个？分开有什么好处？
2. 有没有哪个模块不依赖任何其他模块？为什么它可以独立存在？
3. 如果让你把这些模块分成"必须有的"和"可选的"两类，你会怎么分？

到这里为止，我们追踪了：{入口} → {中间节点} → {当前位置}

💭 暂停思考：
- 到目前为止的调用链你能复述吗？（试着不看笔记说一遍）
- {当前位置} 接下来最可能调用谁？为什么你这么猜？
- 如果这个流程出了 bug，你觉得最可能出问题的是哪一步？

想好了可以继续，或者对前面的步骤有疑问可以回头看看。

# 项目理解文档

## 这些文档是什么？

这是通过交互式探索生成的项目理解文档。文档结构镜像了项目的实际目录结构，
你可以像浏览项目源码一样浏览这些文档。

## 怎么使用这些文档？

### 方式 1：按路线图阅读（推荐新手）
打开 [ROADMAP.md](ROADMAP.md)，按照标注的阅读顺序，对照源码逐步阅读。
每个阶段末尾有检查点问题，能回答说明你已理解该阶段。

### 方式 2：按模块浏览
进入你感兴趣的模块目录，每个模块的 `README.md` 提供了该模块的概览。
包级别的 `_package.md` 说明了包的职责，类级别的 `{ClassName}.md` 提供了关键类的详细分析。

### 方式 3：搜索特定概念
查看 [glossary.md](glossary.md) 找到术语定义，
或者直接在文档目录中搜索你想了解的类名或概念。

## 文档结构
{自动生成的文档目录树}

## 文档状态标记
| 标记 | 含义 |
|------|------|
| `[确认]` | 通过代码验证的事实 |
| `[推断]` | 基于命名/结构推断，尚未验证 |
| `[待验证]` | 需要进一步确认 |
| `[待探索]` | 尚未深入分析的部分 |

## 源码对照说明
文档中标注了源码文件路径和行号，格式为：
- `📁 源码位置: path/to/File.java` — 文件级别
- `L45-L89` — 行号级别（建议用 IDE 打开源文件对照阅读）

## 阶段 2：核心模块（预计 30 分钟）

✅ 已探索 | ⭐ 必读 | `core/src/.../CoreService.java` | 核心服务接口 | [core/README.md](core/README.md)
🔲 待探索 | ⭐ 必读 | `core/src/.../CoreConfig.java` | 配置管理 | -
🔲 待探索 | 📖 推荐 | `core/src/.../util/Helper.java` | 工具方法 | -

## {日期} - {探索主题}

### 用户的思考
{记录用户对思考题的回答要点，这反映了用户对项目的当前理解}

### 关键发现
- {发现1}
- {发现2}

### 源码关键点
| 文件 | 行号 | 说明 |
|------|------|------|
| `path/to/File.java` | L45 | {为什么这行重要} |

### 为用户补充的知识
{本轮额外解释了哪些前置知识}

### 用户理解的变化
{用户之前以为 XXX，现在知道了 YYY}

我们现在已经了解了 {已探索内容}。

你在刚才的探索中提到 {用户的某个回答/疑问}，这和 {未探索的部分} 密切相关。

💭 带着这个新问题想一想：
- {关联性思考题}

建议下一步：
1. {方向1}（可以回答你刚才关于 XXX 的疑问）
2. {方向2}（和你提到的 YYY 有关）
3. 或者你现在有什么新的问题？

这里作者选择了 {方案A}，而不是：
- 方案B：{描述} — 不选它可能是因为 {推理}
- 方案C：{描述} — 不选它可能是因为 {推理}

📊 设计权衡：
得到了：{好处1}、{好处2}
放弃了：{代价1}、{代价2}
适合场景：{什么情况下这个选择是合理的}

## 设计决策

### 决策1：{用一个问题描述决策点}
**例：为什么配置管理不用 Spring @ConfigurationProperties 而是自己实现？**

- **选择**: 自实现配置类，通过 buildConf() 注册配置项
- **原因**: [推断] 该项目需要在非 Spring 环境中运行（如嵌入到其他框架时），不能依赖 Spring 容器
- **替代方案**: Spring @ConfigurationProperties — 更方便但引入了 Spring 强依赖
- **权衡**: 得到了框架无关性，代价是需要手动管理配置注册
- **源码依据**: `ConfigManager.java:L23-L45`

### 决策2：{另一个决策点}
...

我注意到这个项目的 {某个特点}。

💭 想一想：
- 如果让你设计这个功能，你的第一直觉是怎么做？
- 为什么作者没有用 {更常见的方案}？你能想到什么原因？

你的想法很有道理。实际上作者选择 {方案} 可能是因为：
{展示上面五个维度的分析}

你提到的 {用户的方案} 也是一个合理的选择，在 {某种条件下} 它可能更好。
但在这个项目中，因为 {约束条件}，所以 {作者的方案} 更合适。

你觉得这个设计有什么可以改进的地方吗？
如果项目需求发生 {某种变化}，这个设计还 hold 得住吗？

> 💡 你可能会好奇：这里为什么要把 {X} 和 {Y} 分开成两个类？
> 看起来它们做的事情很相关，放在一起不是更简单吗？
> 
> 分开的原因是 {分析}。如果合并，会导致 {问题}。
> 你可以对比看看 {X} 的调用方（`FileA.java:L30`）和 {Y} 的调用方（`FileB.java:L55`），
> 它们的使用场景确实不同。

第1层：这是什么（一句话定义）
第2层：在项目中扮演什么角色（上下文定位）
第3层：怎么工作的（机制原理）
第4层：为什么这样设计（设计决策分析 — 用上面的五个维度）
第5层：还可以怎么做（替代方案对比 — 帮助用户建立更完整的知识体系）

# 术语表

| 术语 | 含义 | 通俗解释 | 首次出现 | 相关源码 |
|------|------|----------|----------|----------|
| {term} | {精确定义} | {大白话} | {文件路径} | `path/to/File.java:L10` |