@chongyan/autospec 1.0.2 → 1.0.4

package/knowledge/01-principles/05-domain-principles.md

@@ -1,539 +0,0 @@
-# 领域实践原则
-
-> **定位**: 从各领域实践中提炼的通用原则，指导具体领域的执行决策
->
-> **进化分区**: 🟡 受控区（自动提议 + 人工批准）
-
----
-
-## 原则体系总览
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  领域实践原则 (Domain Principles) — 从实战中提炼               │
-│  ─────────────────────────────────────────────────────────  │
-│  DDD 设计 | 系统设计 | 需求工程 | 编码实践 | Code Review | 知识管理  │
-│  → 位于：guides/, standards/                                 │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## 一、DDD 战术设计原则
-
-### DDP1: 统一语言原则
-
-**原则**: 代码命名与业务术语一致，消除沟通歧义。
-
-**实践要点**:
-- 文档与代码术语同步
-- 术语冲突必须消除
-- 新术语需要团队共识
-
-**违反信号**:
-- 同一概念在代码中有多个名称
-- 技术术语替代业务术语
-- 术语含义随时间漂移
-
-### DDP2: 聚合设计三原则
-
-**原则**: 小聚合优于大聚合，通过 ID 引用其他聚合，聚合边界=一致性边界。
-
-**聚合大小判断**:
-```
-理想聚合大小：
-- 1 个聚合根
-- 0-3 个内部实体
-- 若干值对象
-- 不超过 5 个字段变更频繁的属性
-```
-
-**拆分信号**:
-| 信号 | 说明 | 行动 |
-|------|------|------|
-| 并发冲突频繁 | 多用户同时修改同一聚合 | 考虑拆分 |
-| 加载性能差 | 聚合数据量大 | 考虑拆分 |
-| 事务失败率高 | 事务涉及多个独立变更 | 考虑拆分 |
-
-### DDP3: 领域事件三原则
-
-**原则**: 事件命名用过去时，事件一旦发生不可修改，同一事件多次处理结果相同。
-
-**事件设计规范**:
-- 命名：过去时（OrderCreated, PaymentCompleted）
-- 不可变：事件一旦发生不可修改
-- 幂等：同一事件多次处理结果相同
-
-### DDP4: 贫血模型反模式
-
-**原则**: 核心业务逻辑必须内聚到领域对象，Service 层只负责编排。
-
-**错误示例**:
-```java
-// ❌ 贫血模型：领域对象只有 getter/setter
-public class Order {
-    private String status;
-    // 只有 getter/setter，无业务逻辑
-}
-
-public class OrderService {
-    public void confirm(Order order) {
-        if (order.getStatus() != OrderStatus.PAYING) {
-            throw new BusinessException("订单状态不允许确认");
-        }
-        order.setStatus(OrderStatus.SUCCESS);  // 业务逻辑泄露到 Service
-    }
-}
-```
-
-**正确示例**:
-```java
-// ✅ 充血模型：业务逻辑内聚到领域对象
-public class Order {
-    private String status;
-
-    public void confirm() {
-        if (this.status != OrderStatus.PAYING) {
-            throw new BusinessException("订单状态不允许确认");
-        }
-        this.status = OrderStatus.SUCCESS;  // 业务逻辑在领域对象内
-    }
-}
-
-public class OrderService {
-    public void confirmOrder(Long orderId) {
-        Order order = repository.findById(orderId);
-        order.confirm();  // 调用领域对象的业务方法
-    }
-}
-```
-
----
-
-## 二、系统设计原则
-
-### SDP1: 两步生成法
-
-**原则**: 先大纲确认方向，再逐个细化，避免整体返工。
-
-**流程**:
-```
-Phase 1 (大纲)          Phase 2 (详设)
-    ↓                       ↓
-功能点列表            逐个功能点写详设
-全部标记 - [ ]          每完成一个打钩 - [x]
-    ↓                       ↓
-用户确认方向           进度可视化
-```
-
-**优势**:
-- 避免整体返工
-- 可中断，完成部分可直接使用
-- 进度可视化
-- 即时反馈
-
-### SDP2: 设计文档四不原则
-
-**原则**: 设计文档描述职责，不平铺实现代码；功能点职责不重叠；开关配置不滥用；共享组件变更不遗漏。
-
-| 原则 | 说明 | 违反信号 |
-|------|------|---------|
-| 不平铺代码 | 只描述方法职责、入参、输出 | 设计文档包含大量实现代码 |
-| 职责不重叠 | 每个功能点职责清晰独立 | 多个功能点重复描述同一逻辑 |
-| 不滥用配置 | 只加必要的开关配置 | 每个功能都加开关，过度配置 |
-| 不遗漏变更 | 共享组件变更必须说明 | 依赖库升级未说明 |
-
-### SDP3: 多系统设计顺序原则
-
-**原则**: 先契约后实现，先被依赖系统后调用方系统。
-
-**设计顺序**:
-```
-1. 定义契约（API Schema、数据 Schema）
-       ↓
-2. 被依赖系统设计（后端 API、数据层）
-       ↓
-3. 调用方系统设计（前端、移动端）
-       ↓
-4. 集成设计（联调、测试）
-```
-
-**可并行场景**:
-- 后端↔前端（通过 API 契约解耦）
-- 数据↔后端（通过数据 Schema 解耦）
-- AI↔后端（通过模型接口解耦）
-
-**不可并行场景**:
-- 数据库迁移
-- 核心业务流程顺序
-- AI 效果验证
-
----
-
-## 三、需求工程原则
-
-### REP1: 8 类场景检查清单
-
-**原则**: 需求分析时必须通过 8 类场景检查清单识别涉及的业务域。
-
-| 场景类型 | 检查问题 | 涉及业务域 |
-|---------|---------|-----------|
-| 外部对接 | 是否涉及外部系统、第三方服务对接？ | gateway（网关系统） |
-| 账户体系 | 是否涉及用户账户、资金账户、账务处理？ | account（账户系统） |
-| 交易链路 | 是否涉及下单、支付、确认、结算？ | trade（交易系统） |
-| 资产/资源管理 | 是否涉及资产计算、估值、登记？ | asset（资产/资源系统） |
-| 数据管道 | 是否涉及数据采集、清洗、流转、报表？ | data（数据系统） |
-| AI/模型 | 是否涉及模型训练、推理、效果评估？ | ai/ml（AI 系统） |
-| 运营营销 | 是否涉及活动、营销、用户运营？ | operation（运营系统） |
-| 监控运维 | 是否涉及监控、告警、应急、部署？ | ops（运维系统） |
-
-### REP2: 需求提案 11 章节完整性原则
-
-**原则**: 需求提案必须包含 11 个核心章节，确保需求完整、无歧义、可实现。
-
-**必填章节**:
-1. 背景与价值（业务背景、业务价值）
-2. 目标与范围（目标、范围）
-3. 业务架构设计（总体架构图、需求用例图、业务域拆解、资金流方案、用例业务流程、跨域接口、数据一致性保障）
-4. 关键决策
-5. 风险与缓解
-6. 非目标与约束
-7. Open Questions
-8. 参考资料
-
-**检查清单**:
-- [ ] 每条功能需求有明确的验收标准
-- [ ] 需求描述无歧义
-- [ ] 技术可行性已初步评估
-- [ ] 边界清晰（包含/不包含）
-- [ ] 非功能需求已覆盖（性能、安全、兼容性）
-
-### REP3: WHEN-THEN 规格描述原则
-
-**原则**: 需求描述使用 WHEN-THEN 格式（Gherkin 风格），确保无歧义。
-
-**格式**:
-```gherkin
-场景：{场景名称}
-  给定：{前置条件}
-  当：{触发事件}
-  则：{预期结果}
-  而且：{额外预期}
-```
-
-**示例**:
-```gherkin
-场景：用户购买产品
-  给定：用户账户余额充足
-    而且：当前账户状态正常
-  当：用户发起购买申请 100 元
-  则：创建购买订单，状态为"处理中"
-    而且：用户可用余额减少 100 元
-    而且：发送通知告知用户
-```
-
-### REP4: 三板斧发布原则
-
-**原则**: 需求分析阶段必须考虑灰度、监控、应急三板斧。
-
-**三板斧清单**:
-
-| 维度 | 检查项 | 本需求适用 |
-|------|--------|-----------|
-| **灰度策略** | 用户灰度/流量灰度/功能灰度/数据灰度 | Y/N |
-| **监控指标** | 业务指标/性能指标/错误指标/资源指标 | Y/N |
-| **应急预案** | 功能开关降级/限流降级/数据回滚 | Y/N |
-
----
-
-## 四、编码实践原则
-
-### CEP1: 复用优先原则
-
-**原则**: 实现前先扫描项目现有能力，优先复用已有框架、工具类、组件。
-
-**强制要求**:
-- 实现前先搜索代码库
-- 优先使用项目已有的 Helper、Util 类
-- 按已有代码的模式和风格实现
-- 绝不重复造轮子
-
-**违反信号**:
-- 项目已有工具类，却自己新建
-- 重复实现类似功能
-- 不遵循项目代码风格
-
-### CEP2: 禁止硬编码原则
-
-**原则**: 不可在代码中硬编码目录名、包名、类名、配置项等。
-
-**强制要求**:
-- 路径配置从配置文件或环境知识中读取
-- 技术栈信息从项目文件中动态识别
-- 支持不同项目的差异化配置
-
-### CEP3: 一锁二判三更新原则
-
-**原则**: 并发场景下，更新数据前必须执行"一锁二判三更新"。
-
-**流程**:
-```
-1. 一锁：锁定单点资源（单条记录）
-       ↓
-2. 二判：基于锁定的记录最新状态，判断状态、数值
-       ↓
-3. 三更新：判断通过后的处理
-```
-
-**违反信号**:
-- 不加锁直接更新
-- 加锁后缺少状态检查
-- 使用过期数据进行判断
-
-### CEP4: 异步异常处理原则
-
-**原则**: 异步方法中必须捕获和处理异常，禁止吞掉异常。
-
-**实践方式**:
-- 方式 1：显式捕获异常（try-catch）
-- 方式 2：使用带返回值的 AsyncResult，上层通过 get() 捕获异常
-
-### CEP5: ThreadLocal 清理原则
-
-**原则**: ThreadLocal 使用完毕后必须在 finally 中调用 remove() 清理。
-
-**违反信号**:
-- 使用 `set(null)` 替代 `remove()`（不被视为清理）
-- 忘记清理导致内存泄漏
-- 线程复用时数据污染
-
-### CEP6: LogUtil 优先原则
-
-**原则**: 日志打印必须使用 LogUtil 工具类，自动添加 TraceId。
-
-**错误示例**:
-```java
-// ❌ 直接使用 logger 打印，无 TraceId
-LOGGER.info("处理成功，id=" + id);
-
-// ❌ 使用 System.out
-System.out.println("处理成功");
-```
-
-**正确示例**:
-```java
-// ✅ 使用 LogUtil（带 TraceId）
-LogUtil.info(LOGGER, "处理成功，id={0}", id);
-LogUtil.error(e, LOGGER, "处理异常，id={0}", id);
-```
-
----
-
-## 五、Code Review 原则
-
-### CRP1: 24 小时响应原则
-
-**原则**: 评审人应在工作日 24 小时内响应，无法完成全部评审时应给出初步反馈。
-
-**违反信号**:
-- 超过 24 小时未响应
-- 不给出任何反馈
-- 让发起人等待过久
-
-### CRP2: 100 行合理拆分原则
-
-**原则**: 代码提交通常保持在 100 行左右较为合理，职责单一，功能独立。
-
-**违反信号**:
-- 单次提交超过 500 行
-- 多个功能混在一起
-- 职责不清晰
-
-### CRP3: 评审通过判断原则
-
-**原则**: 满足以下条件应评审通过：功能实现达标、代码设计合理、单元测试通过、测试覆盖率达标。
-
-**通过标准**:
-- 功能实现达标
-- 代码设计合理
-- 单元测试通过
-- 本次变更行的覆盖率 ≥ 工程整体覆盖率
-
-**核心原则**: 只要当前变更对系统整体代码具有一定质量提升，评审人应倾向于通过，不要苛求完美。
-
-### CRP4: 不苛求完美原则
-
-**原则**: 评审人应抓住重点反馈，不苛求每一行代码都是完美的。
-
-**实践要点**:
-- 反馈前三问：是否正确、是否必要、是否可读
-- 毫不吝啬地正向反馈：表扬、称赞、分享
-- 有质量提升就应通过
-
-### CRP5: AI 增强审查原则
-
-**原则**: 并行启动多个专业审查 Agent，从不同角度审查代码。
-
-**审查维度**:
-| 维度 | 检查内容 | AI 能力 |
-|------|---------|--------|
-| 架构 | 模块划分、依赖关系、扩展性 | ★★★☆☆ |
-| 安全 | 注入漏洞、越权、敏感数据 | ★★★★★ |
-| 性能 | 复杂度、N+1、缓存策略 | ★★★★☆ |
-| 可维护性 | 代码重复、命名、注释 | ★★★★★ |
-| 逻辑 | 业务逻辑正确性、边界条件 | ★★★☆☆ |
-
-**协作模式**:
-```
-AI 预审（快速扫描） → 人类重点审查（AI 发现的问题）
-```
-
----
-
-## 六、知识管理原则
-
-### KMP1: 三层知识架构原则
-
-**原则**: 知识库按 Metadata→SKILL.md→References 三层架构设计，渐进式加载。
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Layer 1: Metadata（元数据层）                              │
-│  · skill description（触发条件）                           │
-│  · 知识库导航（README/SUMMARY）                            │
-│  用途：快速定位，决定是否加载                               │
-├─────────────────────────────────────────────────────────┤
-│  Layer 2: SKILL.md（核心逻辑层）                           │
-│  · 执行步骤（Steps）                                      │
-│  · 输入输出（Guardrails）                                 │
-│  · 检查清单（Checklist）                                  │
-│  用途：指导 AI 执行具体任务                                 │
-├─────────────────────────────────────────────────────────┤
-│  Layer 3: References（参考文档层）                         │
-│  · 详细规范（coding-style.md 等）                         │
-│  · 最佳实践（best-practices/）                            │
-│  用途：按需加载，提供详细参考                              │
-└─────────────────────────────────────────────────────────┘
-```
-
-### KMP2: 业务技术分离原则
-
-**原则**: 业务文档描述"业务是什么"，技术文档描述"技术怎么实现"，两者不混用。
-
-**业务文档应该写**:
-- 业务流程（用户视角的流转）
-- 业务规则（准入、限制、计算规则）
-- 业务术语（定义、解释）
-- 业务场景（用例、场景描述）
-
-**业务文档不应该写**:
-- 技术实现细节（类、方法、算法）
-- 数据库设计（表结构、索引）
-- 接口定义（API、参数）
-- 架构设计（分层、模块）
-
-### KMP3: 术语管理原则
-
-**原则**: 术语解释在正文中首次出现时括号说明，不独立维护 glossary。
-
-**实践要点**:
-- 首次出现：括号解释
-- 后续出现：直接使用术语，不再解释
-- 一词多义：明确标注不同含义的使用场景
-
-### KMP4: 共用规则管理原则
-
-**原则**: 通用规则在父级文档，差异文件仅记录不同点。
-
-**示例结构**:
-```
-knowledge/03-guides/domain-product/
-├── README.md              # 产品业务通用规则
-├── purchase.md            # 购买特有规则
-├── redeem.md              # 赎回特有规则
-└── transfer.md            # 转换特有规则
-```
-
----
-
-## 原则应用矩阵
-
-### 按阶段应用
-
-| 阶段 | 适用原则 |
-|------|---------|
-| **需求分析** | REP1(8 类场景)、REP2(11 章节)、REP3(WHEN-THEN)、REP4(三板斧) |
-| **方案设计** | SDP1(两步生成)、SDP2(四不)、SDP3(多系统顺序)、DDP1~DDP4(DDD) |
-| **编码实现** | CEP1(复用优先)、CEP2(禁止硬编码)、CEP3(一锁二判)、CEP4(异步异常)、CEP5(ThreadLocal)、CEP6(LogUtil) |
-| **代码审查** | CRP1(24 小时响应)、CRP2(100 行拆分)、CRP3(通过判断)、CRP4(不苛求完美)、CRP5(AI 增强) |
-| **知识管理** | KMP1(三层架构)、KMP2(业务技术分离)、KMP3(术语管理)、KMP4(共用规则) |
-
-### 按错误类型预防
-
-| 错误类型 | 预防原则 |
-|---------|---------|
-| **需求歧义** | REP3(WHEN-THEN)、REP2(11 章节) |
-| **设计返工** | SDP1(两步生成)、SDP2(四不) |
-| **并发问题** | CEP3(一锁二判三更新) |
-| **内存泄漏** | CEP5(ThreadLocal 清理) |
-| **重复造轮子** | CEP1(复用优先) |
-| **代码异味** | CRP2(100 行拆分)、DDP4(贫血模型) |
-| **知识混乱** | KMP1(三层架构)、KMP2(业务技术分离) |
-
----
-
-## 原则检查清单
-
-### 需求分析阶段
-- [ ] 已执行 8 类场景检查清单（REP1）
-- [ ] 需求提案 11 章节完整（REP2）
-- [ ] 需求描述使用 WHEN-THEN 格式（REP3）
-- [ ] 已考虑三板斧发布（REP4）
-
-### 方案设计阶段
-- [ ] 先大纲确认方向，再逐个细化（SDP1）
-- [ ] 设计文档遵循四不原则（SDP2）
-- [ ] 多系统设计遵循顺序原则（SDP3）
-- [ ] DDD 战术设计遵循 DDP1~DDP4
-
-### 编码实现阶段
-- [ ] 优先复用项目现有能力（CEP1）
-- [ ] 无硬编码（CEP2）
-- [ ] 并发场景执行一锁二判三更新（CEP3）
-- [ ] 异步方法正确处理异常（CEP4）
-- [ ] ThreadLocal 及时清理（CEP5）
-- [ ] 使用 LogUtil 打印日志（CEP6）
-
-### 代码审查阶段
-- [ ] 24 小时内响应（CRP1）
-- [ ] 代码拆分为 100 行左右（CRP2）
-- [ ] 遵循通过判断原则（CRP3）
-- [ ] 不苛求完美（CRP4）
-- [ ] 考虑 AI 增强审查（CRP5）
-
-### 知识管理阶段
-- [ ] 遵循三层知识架构（KMP1）
-- [ ] 业务文档与技术文档分离（KMP2）
-- [ ] 术语管理遵循首次解释原则（KMP3）
-- [ ] 共用规则管理遵循父级原则（KMP4）
-
----
-
-## 参考资料
-
-- [DDD 实践指南](../guides/domain-driven-design.md)
-- [系统设计指南](../guides/system-design.md)
-- [需求工程指南](../guides/requirement-engineering.md)
-- [编码规范](../standards/coding-style.md)
-- [Code Review 规范](../standards/code-review.md)
-- [知识管理指南](../guides/knowledge-management.md)
-
----
-
-**维护者**: AutoSpec 团队
-**进化分区**: 🟡 受控区
-**关联文档**:
-- [01-first-principles.md](01-first-principles.md) - L1 第一性原则
-- [02-strategic-principles.md](02-strategic-principles.md) - L2 战略原则
-- [03-tactical-principles.md](03-tactical-principles.md) - L3 战术原则
-- [04-operational-principles.md](04-operational-principles.md) - L4 操作原则