concept-modeling

Lens A —— 概念建模

架构的本质是**概念的识别与组织**。这是优先级最高的 lens。

0. 先取词：领域统一语言从哪来

判断"概念识别对不对"前，先确立这个项目的**统一语言（ubiquitous language）**，否则全是猜。优先从这些来源取真实概念词：

• **数据库 schema / 迁移文件**：表名、字段名 = 最硬的领域名词。
• **API 表面**：路由、DTO、GraphQL schema 暴露的资源名。
• **领域文档 / README / ADR / 需求**：业务方用的词。
• **核心实体类型命名**：已有的 entity/model/aggregate。

把这些词列出来，再看代码里的类/模块命名是否与之对齐——错位、缺失、技术词替代业务词，都是这一 lens 的 finding（带 `file:line` 证据）。

1. 概念识别 (Concept Identification)

**检查项：**

• [ ] 核心领域概念是否被正确识别和命名
• [ ] 概念边界是否清晰（这个类/模块代表什么？）
• [ ] 命名是否准确反映业务语义（统一语言）
• [ ] 是否存在概念混淆（一个类代表多个概念）
• [ ] 是否存在概念碎片化（一个概念散落多处）

**违规模式：**

• 命名模糊：`DataHandler`、`InfoManager`、`ProcessHelper`
• 概念混合：`UserOrderService` 混合了用户和订单两个领域
• 概念缺失：业务中的核心概念没有对应的代码实体
• 技术命名替代业务命名：`StringProcessor` vs `EmailValidator`

> 置信度提示：概念碎片化（一个概念散落多处，改一处漏三处）通常是 75–100 分的真问题；单纯"名字不够好听"是 ≤25 分，不报。

2. 抽象质量 (Abstraction Quality)

**检查项：**

• [ ] 抽象层次是否一致（同一层级的概念粒度相近）
• [ ] 抽象是否稳定（不随实现细节变化）
• [ ] 抽象是否完整（覆盖了概念的核心行为）
• [ ] 是否过度抽象（抽象没有实际价值）← 高发假阳性来源，谨慎
• [ ] 是否抽象不足（具体实现暴露在外）

**抽象层次检查：**

✅ 良好的抽象层次：
   Application Layer  →  OrderService, PaymentService
   Domain Layer       →  Order, Payment, Customer
   Infrastructure     →  MySQLOrderRepository, StripePaymentGateway

❌ 混乱的抽象层次：
   同一目录下混合了 Order, MySQLConnection, validateEmail(), config.json

> 注意：**建议"增加抽象"前，必须证明有 ≥2 个真实实现或真实变化点**，否则这是 YAGNI 违规，按假阳性处理。

3. 封装评估 (Encapsulation)

**检查项：**

• [ ] 实现细节是否被隐藏
• [ ] 对外接口是否最小化
• [ ] 内部状态是否被保护
• [ ] 变化是否被隔离在边界内

**违规模式：**

• 过多 public 方法/属性
• 内部数据结构直接暴露
• 实现细节泄漏到接口
• 调用者需要了解内部工作原理

4. 实体关系 (Entity Relationships)

**检查项：**

• [ ] 实体间关系是否清晰（依赖、聚合、组合、关联）
• [ ] 关系方向是否正确（谁依赖谁）
• [ ] 是否存在循环依赖
• [ ] 关系强度是否合理（是否过度耦合）

**关系类型审查：**

依赖关系图应呈现：
├── 单向依赖（✅ A → B）
├── 层次依赖（✅ 上层 → 下层）
├── 抽象依赖（✅ 具体 → 抽象）
└── 避免：循环依赖、跨层依赖、向上依赖