ironweave 1.0.0

package/skills/docs-output/scripts/docs_manager.py

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""
+docs-output: 文档产出管理脚本（模块文档 + 进度记录）
+
+用法:
+    python docs_manager.py create   --root <project_root> --module <模块名> --name <文档名> [--title <标题>]
+    python docs_manager.py progress --root <project_root> --topic <主题> --type <类型> --summary <摘要> [--files <JSON>] [--decisions <决策>] [--todos <遗留>]
+    python docs_manager.py list     --root <project_root>
+    python docs_manager.py validate --root <project_root>
+    python docs_manager.py archive  --root <project_root> [--older-than <天数>]
+"""
+
+import argparse
+import json
+import os
+import re
+import secrets
+import shutil
+import subprocess
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+DOCS_DIR = "docs"
+PROGRESS_DIR = "progress"
+ARCHIVE_DIR = "archive"
+
+
+def get_docs_dir(root: str) -> Path:
+    return Path(root).resolve() / DOCS_DIR
+
+
+def get_progress_dir(root: str) -> Path:
+    return Path(root).resolve() / DOCS_DIR / PROGRESS_DIR
+
+
+def extract_title(filepath: Path) -> str:
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line.startswith("# "):
+                    return line[2:].strip()
+        return ""
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def get_git_user(root: str) -> dict:
+    """获取 Git 用户信息。"""
+    info = {"name": "unknown", "email": ""}
+    try:
+        name = subprocess.run(
+            ["git", "config", "user.name"], capture_output=True, text=True, cwd=root
+        ).stdout.strip()
+        email = subprocess.run(
+            ["git", "config", "user.email"], capture_output=True, text=True, cwd=root
+        ).stdout.strip()
+        if name:
+            info["name"] = name
+        if email:
+            info["email"] = email
+    except (OSError, FileNotFoundError):
+        pass
+    return info
+
+
+def session_hash() -> str:
+    """生成 6 位会话 hash。"""
+    return secrets.token_hex(3)
+
+
+def now_date() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def scan_modules(docs_dir: Path) -> dict[str, list[dict]]:
+    """扫描模块文档（排除 progress/）。"""
+    modules: dict[str, list[dict]] = {}
+    if not docs_dir.exists():
+        return modules
+
+    for item in sorted(docs_dir.iterdir()):
+        if item.is_dir() and item.name != PROGRESS_DIR:
+            docs = []
+            for md in sorted(item.rglob("*.md")):
+                title = extract_title(md)
+                rel = str(md.relative_to(docs_dir))
+                docs.append({"name": md.stem, "file": rel, "title": title})
+            if docs:
+                modules[item.name] = docs
+
+    return modules
+
+
+def scan_progress(progress_dir: Path, days: int | None = None) -> list[dict]:
+    """扫描进度记录。"""
+    results = []
+    if not progress_dir.exists():
+        return results
+
+    cutoff = None
+    if days is not None:
+        cutoff = (datetime.now(timezone.utc) - timedelta(days=days)).strftime("%Y-%m-%d")
+
+    for date_dir in sorted(progress_dir.iterdir(), reverse=True):
+        if not date_dir.is_dir() or date_dir.name == ARCHIVE_DIR:
+            continue
+        if cutoff and date_dir.name < cutoff:
+            continue
+        for md in sorted(date_dir.iterdir()):
+            if md.suffix == ".md":
+                title = extract_title(md)
+                results.append({
+                    "date": date_dir.name,
+                    "hash": md.stem,
+                    "title": title,
+                    "file": f"{PROGRESS_DIR}/{date_dir.name}/{md.name}",
+                })
+
+    return results
+
+
+# ── 命令实现 ──────────────────────────────────────────────
+
+def cmd_create(root: str, module: str, name: str, title: str | None = None):
+    docs_dir = get_docs_dir(root)
+    module_dir = docs_dir / module
+    module_dir.mkdir(parents=True, exist_ok=True)
+
+    filename = f"{name}.md"
+    filepath = module_dir / filename
+
+    if filepath.exists():
+        print(json.dumps({"status": "error", "message": f"File already exists: {module}/{filename}"}, ensure_ascii=False))
+        return
+
+    doc_title = title or name
+    content = f"# {doc_title}\n\n"
+    filepath.write_text(content, encoding="utf-8")
+
+    print(json.dumps({
+        "status": "ok",
+        "file": f"{module}/{filename}",
+        "module": module,
+        "path": str(filepath),
+    }, ensure_ascii=False))
+
+
+PROGRESS_TEMPLATE = """# {topic}
+
+- **日期**: {date}
+- **开发者**: {developer}
+- **类型**: {record_type}
+
+## 任务摘要
+
+{summary}
+
+## 变更文件
+
+{files}
+
+## 决策记录
+
+{decisions}
+
+## 遗留问题
+
+{todos}
+"""
+
+
+def cmd_progress(root: str, topic: str, record_type: str, summary: str,
+                 files: str | None = None, decisions: str | None = None, todos: str | None = None):
+    progress_dir = get_progress_dir(root)
+    date = now_date()
+    date_dir = progress_dir / date
+    date_dir.mkdir(parents=True, exist_ok=True)
+
+    h = session_hash()
+    filepath = date_dir / f"{h}.md"
+    # 极小概率碰撞
+    while filepath.exists():
+        h = session_hash()
+        filepath = date_dir / f"{h}.md"
+
+    # 获取 Git 用户
+    git_user = get_git_user(root)
+    developer = f"{git_user['name']} <{git_user['email']}>" if git_user["email"] else git_user["name"]
+
+    # 解析变更文件
+    files_text = "（无）"
+    if files:
+        try:
+            file_list = json.loads(files)
+            files_text = "\n".join(f"- `{f['path']}` — {f.get('reason', '')}" for f in file_list)
+        except (json.JSONDecodeError, KeyError, TypeError):
+            files_text = files
+
+    content = PROGRESS_TEMPLATE.format(
+        topic=topic,
+        date=date,
+        developer=developer,
+        record_type=record_type,
+        summary=summary,
+        files=files_text,
+        decisions=decisions or "（无）",
+        todos=todos or "（无）",
+    )
+
+    filepath.write_text(content, encoding="utf-8")
+
+    print(json.dumps({
+        "status": "ok",
+        "file": f"{PROGRESS_DIR}/{date}/{h}.md",
+        "developer": developer,
+        "path": str(filepath),
+    }, ensure_ascii=False))
+
+
+def cmd_list(root: str):
+    docs_dir = get_docs_dir(root)
+    modules = scan_modules(docs_dir)
+    progress = scan_progress(get_progress_dir(root), days=30)
+
+    total_modules = sum(len(docs) for docs in modules.values())
+    print(json.dumps({
+        "status": "ok",
+        "modules": modules,
+        "module_docs_total": total_modules,
+        "recent_progress": progress,
+        "progress_count": len(progress),
+    }, ensure_ascii=False))
+
+
+def cmd_validate(root: str):
+    docs_dir = get_docs_dir(root)
+    if not docs_dir.exists():
+        print(json.dumps({"status": "error", "message": "docs/ directory does not exist"}))
+        return
+
+    issues = []
+    kebab = re.compile(r"^[a-z0-9\u4e00-\u9fff]+(-[a-z0-9\u4e00-\u9fff]+)*$")
+
+    # 根目录散落文件
+    for item in docs_dir.iterdir():
+        if item.is_file() and item.suffix == ".md":
+            issues.append({
+                "type": "root_file",
+                "file": item.name,
+                "message": "文件应放入模块子目录",
+            })
+
+    # 空模块目录
+    modules = scan_modules(docs_dir)
+    for item in docs_dir.iterdir():
+        if item.is_dir() and item.name not in (PROGRESS_DIR,) and item.name not in modules:
+            issues.append({"type": "empty_module", "module": item.name})
+
+    # 命名检查
+    for module_name, docs in modules.items():
+        if not kebab.match(module_name):
+            issues.append({"type": "naming", "module": module_name, "message": "模块名应使用 kebab-case"})
+        for doc in docs:
+            stem = Path(doc["file"]).stem
+            if not kebab.match(stem):
+                issues.append({"type": "naming", "file": doc["file"], "message": "文件名应使用 kebab-case"})
+
+    total = sum(len(docs) for docs in modules.values())
+    print(json.dumps({
+        "status": "ok" if not issues else "warning",
+        "total_docs": total,
+        "issues": issues,
+    }, ensure_ascii=False))
+
+
+def cmd_archive(root: str, older_than: int = 30):
+    progress_dir = get_progress_dir(root)
+    if not progress_dir.exists():
+        print(json.dumps({"status": "error", "message": "progress/ directory does not exist"}))
+        return
+
+    cutoff = (datetime.now(timezone.utc) - timedelta(days=older_than)).strftime("%Y-%m-%d")
+    archived = 0
+
+    for date_dir in sorted(progress_dir.iterdir()):
+        if not date_dir.is_dir() or date_dir.name == ARCHIVE_DIR:
+            continue
+        if date_dir.name >= cutoff:
+            continue
+
+        month = date_dir.name[:7]
+        archive_month = progress_dir / ARCHIVE_DIR / month
+        archive_month.mkdir(parents=True, exist_ok=True)
+
+        dest = archive_month / date_dir.name
+        shutil.move(str(date_dir), str(dest))
+        archived += 1
+
+    print(json.dumps({"status": "ok", "archived_days": archived, "cutoff": cutoff}))
+
+
+# ── CLI 入口 ──────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(description="docs-output: 文档产出管理")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_create = sub.add_parser("create", help="创建模块文档")
+    p_create.add_argument("--root", required=True, help="项目根目录路径")
+    p_create.add_argument("--module", required=True, help="模块名称")
+    p_create.add_argument("--name", required=True, help="文档名称（不含扩展名）")
+    p_create.add_argument("--title", default=None, help="文档一级标题（默认使用 name）")
+
+    p_progress = sub.add_parser("progress", help="记录会话进度")
+    p_progress.add_argument("--root", required=True)
+    p_progress.add_argument("--topic", required=True, help="主题")
+    p_progress.add_argument("--type", required=True, dest="record_type",
+                            choices=["需求开发", "Bug修复", "技术方案", "重构", "其他"])
+    p_progress.add_argument("--summary", required=True, help="任务摘要")
+    p_progress.add_argument("--files", default=None, help="变更文件JSON数组")
+    p_progress.add_argument("--decisions", default=None, help="决策记录")
+    p_progress.add_argument("--todos", default=None, help="遗留问题")
+
+    p_list = sub.add_parser("list", help="列出文档和进度")
+    p_list.add_argument("--root", required=True)
+
+    p_val = sub.add_parser("validate", help="校验目录健康状态")
+    p_val.add_argument("--root", required=True)
+
+    p_archive = sub.add_parser("archive", help="归档旧进度记录")
+    p_archive.add_argument("--root", required=True)
+    p_archive.add_argument("--older-than", type=int, default=30, dest="older_than",
+                           help="归档N天前的记录（默认30）")
+
+    args = parser.parse_args()
+
+    if args.command == "create":
+        cmd_create(args.root, args.module, args.name, getattr(args, "title", None))
+    elif args.command == "progress":
+        cmd_progress(args.root, args.topic, args.record_type, args.summary,
+                     getattr(args, "files", None), getattr(args, "decisions", None),
+                     getattr(args, "todos", None))
+    elif args.command == "list":
+        cmd_list(args.root)
+    elif args.command == "validate":
+        cmd_validate(args.root)
+    elif args.command == "archive":
+        cmd_archive(args.root, args.older_than)
+
+
+if __name__ == "__main__":
+    main()

package/skills/engineering-principles/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: engineering-principles
+description: >-
+  工程原则匹配器——根据当前任务和项目上下文，从原则库中筛选出适用的开发原则和约束，输出可执行的指导清单。不强推不适用的原则（如无测试依赖的旧项目不推TDD），只输出经上下文验证后确实适用的原则。被动调用，不会主动触发。
+  务必在以下场景使用本 skill：编码规范、设计原则、架构指导、代码质量、可维护性、可扩展性、TDD、DDD、SOLID、设计模式、工程实践、代码审查、engineering principles、code quality、best practices、ddd、tdd、bdd、solid、clean code、重构建议。
+---
+
+# 工程原则匹配器
+
+本 Skill 解决一个核心问题：**模型写代码时缺乏工程纪律**。不是所有原则都适用于所有项目——旧项目没有测试框架就不该强推 TDD，小项目不需要 DDD 分层。
+
+本 Skill 的核心逻辑：**先感知项目上下文 → 再匹配适用原则 → 输出可执行约束**。
+
+## 核心机制
+
+```mermaid
+graph LR
+    TASK["当前任务"]
+    CTX["项目上下文扫描<br/>技术栈·测试框架·项目规模·目录结构"]
+    MATCH["原则匹配<br/>上下文条件 → 适用原则"]
+    OUT["输出<br/>适用原则清单 + DO/DON'T"]
+
+    TASK --> CTX --> MATCH --> OUT
+
+    style TASK fill:#e3f2fd,stroke:#1976d2
+    style CTX fill:#fff3e0,stroke:#f57c00
+    style MATCH fill:#f3e5f5,stroke:#7b1fa2
+    style OUT fill:#e8f5e9,stroke:#388e3c
+```
+
+## 原则分类与适用条件
+
+每个原则类别有明确的**适用前置条件**——条件不满足则跳过。
+
+| 分类 | 包含原则 | 适用条件 |
+|------|---------|---------|
+| **SOLID** | SRP, OCP, LSP, ISP, DIP | 项目使用 OOP 语言（TS/Java/Python class） |
+| **DDD 分层** | 聚合、限界上下文、领域服务、值对象 | 项目有明确的业务领域且模块 ≥ 3 个 |
+| **TDD** | 红绿重构、测试先行、测试金字塔 | 项目已配置测试框架（jest/vitest/junit/pytest） |
+| **BDD** | Gherkin 验收、场景驱动 | 项目有 E2E 测试工具（cypress/playwright） |
+| **设计模式** | 小尺度(Guard Clause/表驱动/Pipe)、经典GoF(工厂/建造者/装饰器/策略/观察者/状态机/命令/责任链)、中尺度(管道/断路器/工作池/仓库)、前端/后端/跨域模式 | 代码中存在可识别的模式适用场景 |
+| **架构模式** | 分层架构、六边形/Clean Architecture、微内核/插件、模块化单体、微服务、事件驱动、Serverless | 涉及系统架构决策或项目初始化 |
+| **反模式** | 上帝对象、循环依赖、散弹式修改、过度抽象、贫血模型等 | 代码审查或重构任务 |
+| **Clean Code** | 命名、函数长度、注释、可读性 | **始终适用**（无条件） |
+| **错误处理** | 异常分级、边界校验、防御式编程 | **始终适用**（无条件） |
+| **可测试性** | 依赖注入、纯函数、接口隔离 | 项目有测试框架 或 新建项目 |
+| **性能意识** | 避免 N+1、懒加载、缓存策略 | 涉及数据库查询或 API 调用的任务 |
+| **安全实践** | 输入校验、SQL 注入防护、XSS、CSRF | 涉及用户输入、API 端点、认证 |
+
+> 每个分类的完整原则和 DO/DON'T 见 → `references/` 下对应文件
+>
+> 设计模式按尺度分文件：`design-patterns.md`（总表索引）→ `patterns-small-scale.md` / `patterns-classic.md` / `patterns-module.md` / `patterns-frontend.md` / `patterns-backend.md` / `patterns-crosscut.md` / `patterns-architecture.md` / `anti-patterns.md`（按需加载）
+
+## 上下文扫描
+
+匹配原则前，先扫描项目上下文确定以下信息：
+
+### 自动检测项
+
+| 检测项 | 检测方式 | 影响选择 |
+|-------|---------|---------|
+| 语言/框架 | package.json, pom.xml, pyproject.toml, tsconfig | SOLID/DDD/设计模式的适用方式 |
+| 测试框架 | jest.config, vitest.config, pytest.ini, build.gradle | TDD/BDD 是否适用 |
+| 项目规模 | 文件数量、模块数量 | DDD 分层是否值得引入 |
+| 目录结构 | 是否已有分层（controller/service/repository） | 分层实践是否延续 |
+| 已有测试 | __tests__/, *.test.*, *.spec.* | 测试覆盖现状 |
+| E2E 工具 | cypress/, playwright.config | BDD 是否适用 |
+| ORM/数据库 | prisma/, typeorm, mybatis, sequelize | 性能意识、数据建模原则 |
+
+### 上下文分级
+
+| 项目类型 | 特征 | 默认适用原则 |
+|---------|------|------------|
+| **新项目** | 无 src/, 无 package.json 或空项目 | Clean Code + SOLID + 可测试性（推荐 TDD） |
+| **小项目** | < 50 文件, 单模块 | Clean Code + SOLID + 错误处理 |
+| **中型项目** | 50-500 文件, 2-5 模块, 有测试 | 全部可选（按检测结果） |
+| **大型项目** | > 500 文件, 多模块 | DDD + SOLID + 性能 + 安全（按检测结果） |
+| **遗留项目** | 无测试框架, 无明确分层 | Clean Code + 错误处理 + 渐进式改善 |
+
+## 输出格式
+
+### 原则清单
+
+```markdown
+# 工程原则匹配报告
+
+## 项目上下文
+- 语言/框架: TypeScript + NestJS
+- 测试框架: vitest（已配置）
+- 项目规模: 中型（~200 文件）
+- 目录结构: DDD 分层（controller/service/repository）
+
+## 适用原则
+
+### ✅ 始终适用
+- **Clean Code**: 函数 ≤ 30 行, 有意义的变量名, 避免 magic number
+- **错误处理**: 业务异常 vs 系统异常分级, 不吞异常
+
+### ✅ 经检测适用
+- **SOLID (OOP)**: 检测到 class 使用 → SRP, OCP, DIP 适用
+- **TDD**: 检测到 vitest → 新功能应先写测试
+- **DDD 分层**: 检测到已有 controller/service/repository 结构 → 延续
+- **可测试性**: 依赖注入已使用（NestJS @Injectable） → 继续遵循
+- **性能**: 涉及数据库 → 注意 N+1, 添加必要索引
+
+### ⏭️ 不适用（跳过理由）
+- **BDD**: 未检测到 E2E 框架（无 cypress/playwright）
+- **设计模式-工厂/策略**: 当前任务不涉及多态/策略选择场景
+```
+
+### 单原则约束（嵌入编码）
+
+当模型执行编码任务时，适用的原则以简短约束形式嵌入：
+
+```
+[原则约束]
+- SRP: 每个类/函数只做一件事
+- OCP: 通过接口扩展，不修改已有类
+- TDD: 先写失败测试 → 通过 → 重构
+- 错误处理: 用自定义异常类，不用字符串
+```
+
+## Python 脚本
+
+```bash
+python scripts/principles_matcher.py match --root <project_root> [--task <任务描述>] [--format json|markdown]
+```
+
+- `--root`：项目路径，用于扫描上下文
+- `--task`：任务描述（可选），辅助匹配更精确的原则
+- 无 `--root` 时仅基于任务描述做通用匹配
+
+> 脚本实现见 → `scripts/principles_matcher.py`

package/skills/engineering-principles/references/anti-patterns.md

@@ -0,0 +1,144 @@
+# 反模式识别与改进
+
+> 代码审查和重构时的常见问题。识别信号 → 判断严重度 → 选择改进方向。
+
+## 快速识别表
+
+| 反模式 | 识别信号 | 严重度 | 改进方向 |
+|--------|---------|--------|---------|
+| **上帝对象** | 文件 > 500 行，职责 > 3 项 | 高 | 按职责拆分为独立模块 |
+| **循环依赖** | A → B → A | 高 | 提取公共模块 / 依赖反转 / 事件解耦 |
+| **散弹式修改** | 一个需求改 > 5 个文件 | 高 | 识别变化原因，聚合受同因驱动的代码 |
+| **隐式时序耦合** | 必须按特定顺序调用 | 高 | Builder / FSM 强制顺序 |
+| **平台型 if-else** | 条件分支 > 3 层 | 高 | 策略模式 / 多态 / 表驱动 |
+| **过度抽象** | 抽象层 > 实现层 | 中 | 删除不必要中间层 |
+| **过长参数列表** | 参数 > 5 个 | 中 | 参数对象化 / Builder |
+| **数据泥团** | 同组数据总一起传递 | 中 | 提取为独立类/接口 |
+| **贫血模型** | 数据和操作完全分离 | 中 | 将相关行为内聚到实体 |
+| **僵尸代码** | 无人调用但不敢删 | 低 | 确认无引用后删除 |
+
+## 重构优先级
+
+```
+P0: 阻碍当前任务 / 导致 bug         → 立即修复
+P1: 当前路过且改动成本低             → 顺手修复
+P2: 影响范围大但不紧急               → 记录技术债
+P3: 不美观但不影响功能               → 不修
+```
+
+## 详细改进策略
+
+### 上帝对象
+
+```
+步骤：
+1. 列出当前对象的所有职责
+2. 按"谁关心这数据"分组
+3. 每组提取为独立模块/类
+4. 原对象降级为协调者（Facade）或删除
+```
+
+```typescript
+// BEFORE: UserService 做了太多事
+class UserService {
+  register() { ... }
+  login() { ... }
+  sendEmail() { ... }
+  generateReport() { ... }
+  managePermissions() { ... }
+}
+
+// AFTER: 按职责拆分
+class AuthService { register() { ... }; login() { ... } }
+class EmailService { send() { ... } }
+class ReportService { generate() { ... } }
+class PermissionService { manage() { ... } }
+```
+
+### 循环依赖
+
+四种解法，按优先级排序：
+
+| 方案 | 适用场景 |
+|------|---------|
+| **提取公共模块** | 共享类型/接口导致循环 |
+| **依赖反转** | A 依赖 B 的具体实现 → A 定义接口，B 实现 |
+| **事件解耦** | 双方不需要同步返回值 |
+| **合并模块** | 两个模块本就是一个概念 |
+
+```typescript
+// BEFORE: 循环依赖
+// order.service.ts
+import { PaymentService } from './payment.service' // A → B
+
+// payment.service.ts
+import { OrderService } from './order.service'     // B → A
+
+// AFTER: 事件解耦
+// order.service.ts
+this.eventBus.emit('orderCreated', order)
+
+// payment.service.ts
+this.eventBus.on('orderCreated', (order) => this.process(order))
+```
+
+### 散弹式修改
+
+```
+步骤：
+1. 识别"变化原因"——是需求驱动还是技术驱动
+2. 聚合受同一原因驱动的代码到一个模块
+3. 考虑引入注册机制（策略注册/插件注册）
+```
+
+### 隐式时序耦合
+
+```typescript
+// BEFORE: 必须按顺序调用，但编译器不强制
+service.init()
+service.configure()
+service.start()  // 如果没调 configure 会崩
+
+// AFTER: Builder 强制顺序
+const service = ServiceBuilder.create()
+  .withConfig(config)   // 必须先配置
+  .build()              // build 时校验
+  .start()              // 配置完才能 start
+```
+
+### 过度抽象
+
+识别信号：
+- 接口只有一个实现，且没有可预见的替换场景
+- 中间层只做转发，不加任何逻辑
+- 3 行代码被包了 2 个 class
+
+```
+原则: 抽象的收益 > 阅读理解成本时才保留
+行动: 删除只有 1 个实现且不需要 mock 的接口
+```
+
+### 贫血模型 vs 充血模型
+
+```typescript
+// BEFORE: 贫血模型——数据和操作分离
+class Order { status: string; items: Item[]; total: number }
+class OrderService {
+  cancel(order: Order) {
+    if (order.status !== 'pending') throw new Error('...')
+    order.status = 'cancelled'
+    order.total = 0
+  }
+}
+
+// AFTER: 充血模型——行为内聚到实体
+class Order {
+  cancel() {
+    if (this.status !== 'pending') throw new Error('...')
+    this.status = 'cancelled'
+    this.total = 0
+  }
+}
+```
+
+> 注意：贫血模型在 CRUD 简单场景是合理的，只有在业务规则复杂时才需要转向充血模型。

package/skills/engineering-principles/references/ddd-patterns.md

@@ -0,0 +1,66 @@
+# DDD 模式指南
+
+## 适用条件
+
+- 项目有明确的业务领域（不是纯工具/脚本）
+- 模块 ≥ 3 个，存在模块间协作
+- 项目规模中等以上（> 50 文件）
+
+## 核心概念
+
+### 限界上下文 (Bounded Context)
+
+每个业务子域有独立的模型定义，同一个词在不同上下文中含义不同。
+
+- **DO**: 订单上下文的 `Product` 只包含 `id, name, price`；商品上下文的 `Product` 包含完整属性
+- **DON'T**: 全局共用一个 `Product` 实体，所有模块往里加字段
+
+### 聚合 (Aggregate)
+
+一组紧密关联的实体和值对象，通过聚合根统一访问和修改，保证业务一致性。
+
+- **DO**: `Order`（聚合根）包含 `OrderItem`（实体），通过 `Order.addItem()` 修改
+- **DON'T**: 直接操作 `OrderItem` 绕过 `Order`
+
+### 领域服务 (Domain Service)
+
+不属于任何实体的业务逻辑，放在领域服务中。
+
+- **DO**: `PricingService.calculateDiscount(order, user)` — 涉及多个聚合
+- **DON'T**: 把折扣逻辑放在 `Order` 实体中（它不仅依赖订单，还依赖用户等级）
+
+### 值对象 (Value Object)
+
+无标识的不可变对象，通过属性值判等。
+
+- **DO**: `Money(amount: 100, currency: 'CNY')` — 不可变，值相等即相同
+- **DON'T**: 用 `number` 直接表示金额（丢失币种信息，可比较性差）
+
+### 仓储 (Repository)
+
+对聚合的持久化抽象，领域层定义接口，基础设施层实现。
+
+- **DO**: 领域层 `interface OrderRepository { findById(id): Order }`
+- **DON'T**: 领域层直接依赖 `TypeORM.getRepository(Order)`
+
+## 分层架构
+
+```
+表现层 (Presentation)     → Controller / Handler / GraphQL Resolver
+  ↓ 调用
+应用层 (Application)      → ApplicationService / UseCase（编排，不含业务逻辑）
+  ↓ 调用
+领域层 (Domain)           → Entity, ValueObject, DomainService, Repository接口
+  ↑ 实现
+基础设施层 (Infrastructure) → RepositoryImpl, 外部API适配, ORM配置
+```
+
+**依赖方向**：上层依赖下层，领域层不依赖任何外层。
+
+## 渐进式采用
+
+不必一步到位全面 DDD：
+
+1. **第一步**：至少做到分层（Controller vs Service vs Repository）
+2. **第二步**：识别核心聚合，用实体方法替代贫血模型
+3. **第三步**：对复杂模块引入限界上下文和领域事件