@mycodemap/mycodemap 0.4.2 → 0.5.1

package/docs/product-specs/MVP3-ARCHITECTURE-REDESIGN-PRD.md

@@ -54,9 +54,9 @@ MVP3 重构的原始目的，是把 CodeMap 从“CLI 直接拼接分析逻辑
 |------|------|------|
 | `filesystem` | shipped | 默认、最稳定 |
 | `memory` | shipped | 测试/内存场景 |
-| `kuzudb` | shipped | 当前图存储主线 |
-| `auto` | shipped surface | 配置面存在，但当前仍保守落到 `filesystem` |
-| `neo4j` | removed | 不再是正式支持 backend；旧配置返回显式迁移错误 |
+| `sqlite` | shipped | 当前图存储主线 |
+| `auto` | shipped surface | 配置面存在，当前优先选择 `sqlite`；SQLite 不可用时回退 `filesystem` |
+| `neo4j` / `kuzudb` | removed | 不再是正式支持 backend；旧配置返回显式迁移错误 |
 
 ### 3.3 解析器能力
 
@@ -108,7 +108,7 @@ analyze / ci / workflow / export / ship
 | 需求 | 当前状态 |
 |------|----------|
 | 五层架构与命名边界稳定 | 已满足 |
-| Kùzu-only 图存储主线 | 已满足 |
+| SQLite 图存储主线 + 显式迁移诊断 | 已满足 |
 | 历史 `neo4j` 配置迁移诊断 | 已满足 |
 | 解析器注册机制与 3 类实现 | 已满足 |
 | `analyze` / `workflow` / `server` 边界收口 | 已满足 |
@@ -122,7 +122,7 @@ analyze / ci / workflow / export / ship
 | Java / Rust / C/C++ 等更多 parser 实现 | Deferred |
 | `viz` / `tui` / 更丰富 CLI 可视化 | Deferred |
 | 公共 HTTP API / `mycodemap server` 产品面 | Deferred |
-| 更深的 Kùzu-native 查询优化 | Deferred |
+| 更深的 SQLite / in-memory 协同查询优化 | Deferred |
 
 ### 4.3 明确不在当前基线内
 
@@ -170,8 +170,8 @@ analyze / ci / workflow / export / ship
 
 当前交付：
 
-- `filesystem` / `memory` / `kuzudb` / `auto` 为正式配置面
-- 旧 `neo4j` 配置会显式报错，不再静默 fallback
+- `filesystem` / `memory` / `sqlite` / `auto` 为正式配置面
+- 旧 `neo4j` / `kuzudb` 配置会显式报错，不再静默 fallback
 
 ---
 
@@ -194,7 +194,7 @@ analyze / ci / workflow / export / ship
 
 更准确的当前表达是：
 
-- Kùzu 路径已接入正式产品面
+- SQLite 路径已接入正式产品面；显式 `sqlite` 缺少 `better-sqlite3` 或 Node.js `<20` 时会返回 `SQLITE_NOT_AVAILABLE`
 - 更激进的 DB-native 查询优化属于后续候选项，而非 `v1.3` 既成事实
 
 ---
@@ -206,7 +206,7 @@ analyze / ci / workflow / export / ship
 | `v1.0` | AI-first 定位、公共 CLI 收口、analyze/workflow/ship/docs guardrail 基线 |
 | `v1.1` | 插件扩展点产品化 |
 | `v1.2` | 图数据库后端生产化 |
-| `v1.3` | Kùzu-only 收敛、高信号 debt 清偿、docs/CI 自动验证闭环 |
+| `v1.3` | SQLite 主线收口、高信号 debt 清偿、docs/CI 自动验证闭环 |
 
 ---
 
@@ -216,7 +216,7 @@ analyze / ci / workflow / export / ship
 |------|----------|----------|
 | 文档继续把历史设计写成当前现实 | 高信号风险 | 持续运行 `docs:check` 与 `ci check-docs-sync` |
 | `Server Layer` 与公共 `server` 命令再次混淆 | 高信号风险 | 在 README / AI docs / 架构文档统一措辞 |
-| `auto` 被误读为“已完成智能切换” | 中 | 文档明确写明当前仍保守落到 `filesystem` |
+| `auto` 被误读为“已完成智能切换” | 中 | 文档明确写明当前优先选择 `sqlite`，仅在 SQLite 不可用时回退 `filesystem` |
 | repo-wide lint warnings 演变成阻断项 | 中 | 单独开新 milestone 清理 warning baseline |
 
 ---

package/docs/product-specs/MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md

@@ -87,7 +87,7 @@ src/
 ### 4.1 当前类型契约
 
 ```typescript
-export type StorageType = 'filesystem' | 'kuzudb' | 'memory';
+export type StorageType = 'filesystem' | 'sqlite' | 'memory';
 
 export interface StorageConfig {
   type: StorageType | 'auto';
@@ -106,27 +106,31 @@ export interface StorageConfig {
 |------|------|----------|
 | `filesystem` | `FileSystemStorage` | shipped |
 | `memory` | `MemoryStorage` | shipped |
-| `kuzudb` | `KuzuDBStorage` | shipped |
-| `auto` | `StorageFactory.determineStorageType()` | shipped surface，但当前保守返回 `filesystem` |
+| `sqlite` | `SQLiteStorage` | shipped |
+| `auto` | `StorageFactory.determineStorageType()` | shipped surface，当前优先返回 `sqlite`，不可用时 warning 后回退 `filesystem` |
 
 ### 4.3 已移除的正式产品面
 
-`neo4j` 已不再是正式支持 backend。
+`neo4j` 与 `kuzudb` 已不再是正式支持 backend。
 
 当前技术语义：
 
 - 旧配置若出现 `neo4j`，`StorageFactory` 会抛出 `UNSUPPORTED_STORAGE_TYPE`
-- 文档和实现都不再承诺 Neo4j runtime surface
+- 旧配置若出现 `kuzudb`，`StorageFactory` 会抛出 `STORAGE_BACKEND_MIGRATED`
+- 显式选择 `sqlite` 且运行时缺少 `better-sqlite3` 或 Node.js `<20` 时，`StorageFactory` 会抛出 `SQLITE_NOT_AVAILABLE`
+- 文档和实现都不再承诺 Neo4j / Kùzu runtime surface
 
 ### 4.4 `auto` 的真实状态
 
-`autoThresholds` 仍保留在契约里，但当前 `StorageFactory` 的保守行为是：
+`autoThresholds` 仍保留在契约里，但当前 `StorageFactory` 的实际行为是：
 
 ```typescript
-const thresholds = config.autoThresholds ?? {
-  useGraphDBWhenFileCount: 1000,
-  useGraphDBWhenNodeCount: 10000,
-};
+const sqliteAvailable = await this.checkSQLiteAvailability();
+if (sqliteAvailable) {
+  return 'sqlite';
+}
+
+console.warn('[StorageFactory] SQLite unavailable, falling back to filesystem');
 
 return 'filesystem';
 ```
@@ -134,6 +138,7 @@ return 'filesystem';
 因此：
 
 - `auto` 是稳定配置面
+- `auto` 会先探测 SQLite runtime，可用时返回 `sqlite`，不可用时 warning 后回退 `filesystem`
 - 但“按规模自动切到图数据库”的更强启发式仍是未来候选，而不是当前完成能力
 
 ---
@@ -279,11 +284,11 @@ find → read → link → show
 
 | 项目 | 说明 |
 |------|------|
-| 更强的 auto storage heuristic | 当前仍保守返回 `filesystem` |
+| 更强的 auto storage heuristic | 当前仍只在 `sqlite` / `filesystem` 间切换，未按规模动态调度更多后端 |
 | 更多 parser 实现 | 接口预留，当前未交付 |
 | 公共 HTTP API 产品化 | 当前不在范围内 |
 | `viz` / `tui` / 更强交互可视化 | 当前不在公共 CLI 基线中 |
-| Kùzu-native 深度查询优化 | 后续候选，不属于 `v1.3` 已交付事实 |
+| 更深的 SQLite / in-memory 协同查询优化 | 后续候选，不属于 `v1.3` 已交付事实 |
 
 ---
 

package/docs/product-specs/README.md

@@ -11,8 +11,9 @@
 - `MVP3-ARCHITECTURE-COMPARISON.md`：把历史设计目标与 `v1.3` 已落地基线并列，防止把愿景误写成现实。
 - `MVP3-ARCHITECTURE-REDESIGN-PRD.md`：记录当前产品边界、Deferred 范围与用户价值。
 - `MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md`：记录当前技术基线、目录现实、护栏与迁移语义。
+- `DESIGN_CONTRACT_TEMPLATE.md`：当前 human-authored design contract 的 canonical 模板，供 `mycodemap.design.md` 复制使用。
 
-> 以上 3 份规格目前都属于“已交付基线同步版”，不是新的待实施 roadmap。
+> 前 3 份规格属于“已交付基线同步版”；`DESIGN_CONTRACT_TEMPLATE.md` 是当前有效输入契约模板，不是新的待实施 roadmap。
 
 ## 应放内容
 

package/docs/rules/README.md

@@ -1,16 +1,21 @@
-# docs/rules/
+# `docs/rules/` 速查索引
 
-本目录存放会直接影响开发与交付行为的规则文档。
+> 只保留会直接影响 agent / 人类开发行为的规则。每份文档都应短、可执行、可 grep。
 
-## 当前文件
+## 先读哪份文档
 
-- `engineering-with-codex-openai.md`：面向 agent 的工程原则与当前仓库 CLI / CI 护栏。
-- `testing.md`：测试框架、覆盖率、测试文件位置。
-- `validation.md`：构建、类型检查、lint、CI 验证顺序。
-- `deployment.md`：打包、发布前检查与发布边界。
+| 场景 | 文档 | 主命令 |
+|---|---|---|
+| 改 TypeScript / Python 实现，担心触发红线 | `code-quality-redlines.md` | `npm run typecheck` / `npm run lint` |
+| 改分层、依赖方向、模块边界 | `architecture-guardrails.md` | `node dist/cli/index.js deps -m "<module>"` |
+| 改测试、fixture、测试文件布局 | `testing.md` | `npm test` |
+| 改 hooks、CI、验证顺序、repo-local guardrail | `validation.md` | `npm run docs:check` / `python3 scripts/validate-rules.py code --report-only` |
+| 改 agent 执行协议、CLI/CI 工程护栏 | `engineering-with-codex-openai.md` | `node dist/cli/index.js ci check-docs-sync` |
+| 改发布/打包流程 | `deployment.md` | `npm run build` / `npm run validate-pack` |
+| 改发布前 checklist / 版本同步 | `pre-release-checklist.md` | `npm run docs:check:pre-release` |
 
-## 写作边界
+## 使用规则
 
-- 写“必须怎么做”，不写长篇设计推演。
-- 若规则来自代码事实，优先引用 `package.json`、`tsconfig.json`、CI 或 hooks。
-- 若规则变化会影响 agent 行为，应同步检查入口文档。
+- 入口文档先路由，再按需下钻；不要一次性读完整个 `docs/rules/`。
+- 若规则变化会影响 agent 行为，同步检查 `AGENTS.md`、`CLAUDE.md`、`AI_GUIDE.md` 与相关 `docs/ai-guide/*.md`。
+- 若规则来自代码事实，优先用 `package.json`、`.githooks/*`、`.github/workflows/*`、`scripts/*` 作为真相来源。

package/docs/rules/architecture-guardrails.md

@@ -1,348 +1,36 @@
-# 架构护栏规则
+# 架构护栏
 
-> MVP3 分层架构依赖规则与 Enforcement 策略
+> 当前仓库采用 MVP3 分层架构。下面只保留会影响日常改动的最小 contract。
 
-## 1. 架构分层原则（MVP3）
+## 分层地图
 
-**第一性原理**：业务逻辑必须与实现细节解耦，确保可测试性和技术栈可替换性。
+| 层 | 路径 | 允许依赖 |
+|---|---|---|
+| CLI | `src/cli/` | `src/server/`、`src/domain/`（经 Interface）、`src/interface/` |
+| Server | `src/server/` | `src/domain/`（经 Interface）、`src/interface/` |
+| Domain | `src/domain/` | `src/interface/` |
+| Infrastructure | `src/infrastructure/` | `src/domain/`（接口实现）、`src/interface/` |
+| Interface | `src/interface/` | 无 |
 
-CodeMap 采用 **MVP3 分层架构**，各层职责如下：
+## 护栏表
 
-| 层级 | 目录 | 职责 | 允许依赖 |
-|------|------|------|---------|
-| **CLI 层** | `src/cli/` | 命令解析、用户交互、平台检查 | Server, Domain (via Interface), Interface |
-| **Server 层** | `src/server/` | HTTP API 服务器、路由处理、Handler | Domain (via Interface), Interface |
-| **Domain 层** | `src/domain/` | 核心业务逻辑、领域实体、领域服务、领域事件 | Interface |
-| **Infrastructure 层** | `src/infrastructure/` | 技术实现：存储、解析器、仓库实现 | Domain (接口实现), Interface |
-| **Interface 层** | `src/interface/` | 类型定义、契约接口、配置 | 无（纯契约定义） |
+| 规则 | 命令 | 阈值/级别 | 失败后果 | 恢复方式 |
+|---|---|---|---|---|
+| 禁止跨层反向依赖 | `node dist/cli/index.js deps -m "src/domain"` | `Domain` 不得依赖 `Infrastructure` 具体实现 | 阻断设计验收 / 需返工 | 提取接口到 `src/interface/`，改走注入 |
+| 禁止 CLI 直接耦合实现细节 | `node dist/cli/index.js deps -m "src/cli"` | CLI 只依赖 Server / Interface contract | 阻断 | 下沉到 Server 或 Interface |
+| 接口放在 Interface 层 | `rg "interface|type" src/interface src/domain src/infrastructure` | 跨层共享 contract 必须位于 `src/interface/` | 阻断 | 移动 contract，再改 import |
+| 高层不直接 `new` 低层服务 | `rg "new .*Storage|new .*Parser" src/domain src/server src/cli` | 通过构造函数/工厂注入 | 返工 | 提取工厂或依赖注入 |
 
-### 分层依赖规则
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        CLI Layer                            │
-│  src/cli/ - 命令行接口，注册命令、参数解析、用户交互          │
-├─────────────────────────────────────────────────────────────┤
-│                      Server Layer                           │
-│  src/server/ - HTTP API 服务器，RESTful 端点，Handler 处理    │
-├─────────────────────────────────────────────────────────────┤
-│                       Domain Layer                          │
-│  src/domain/ - 核心业务逻辑，领域实体与服务                   │
-│  - entities/: Project, Module, Symbol, Dependency, CodeGraph │
-│  - services/: CodeGraphBuilder                              │
-│  - events/: DomainEvent                                     │
-│  - repositories/: 仓库接口（仅接口，非实现）                  │
-├─────────────────────────────────────────────────────────────┤
-│                   Infrastructure Layer                      │
-│  src/infrastructure/ - 技术实现细节                          │
-│  - storage/: FileSystemStorage, MemoryStorage, KuzuDBStorage
-│  - parser/: TypeScriptParser, GoParser, PythonParser, ParserRegistry
-│  - repositories/: CodeGraphRepositoryImpl（仓库接口实现）     │
-├─────────────────────────────────────────────────────────────┤
-│                     Interface Layer                         │
-│  src/interface/ - 类型定义与契约，跨层共享的接口              │
-│  - types/: 核心类型定义                                     │
-│  - config/: 配置接口                                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**依赖方向**（严格自上而下）：
-- CLI → Server → Domain → Infrastructure → Interface
-- **禁止跨层依赖**（如 Domain 层不得导入 CLI 模块）
-- 同层内可以相互依赖
-
----
-
-## 2. 与旧架构的关系
-
-### 2.1 历史架构（已迁移）
-
-MVP3 之前的旧架构：
-```
-src/cli/ → src/orchestrator/ → src/core/ → src/parser/
-                                    ↓
-                              src/generator/
-```
-
-### 2.2 迁移映射
-
-| 旧架构 | MVP3 新架构 | 说明 |
-|--------|------------|------|
-| `src/cli/` | `src/cli/` | 保留，职责不变 |
-| `src/orchestrator/` | 功能分散到 Server/CLI | 适配器部分移至 Infrastructure |
-| `src/core/` | `src/domain/` | 核心业务逻辑下沉到 Domain 层 |
-| `src/parser/` | `src/infrastructure/parser/` | 解析器作为基础设施 |
-| `src/generator/` | `src/domain/services/` | 生成逻辑作为领域服务 |
-| `src/types/` | `src/interface/` | 类型定义提升为独立层 |
-| 新增 | `src/server/` | MVP3 新增 HTTP API 层 |
-| 新增 | `src/infrastructure/storage/` | MVP3 新增存储抽象 |
-| 新增 | `src/infrastructure/repositories/` | MVP3 新增仓库实现 |
-
----
-
-## 3. 依赖流向规则
-
-### 3.1 禁止的依赖方向
-
-```
-Domain ←── 禁止 ── CLI 层不得直接依赖 Domain 具体实现（应通过 Interface）
-Infrastructure ←── 禁止 ── Domain 层不得依赖 Infrastructure 具体实现
-Server ←── 禁止 ── CLI 层不得直接依赖 Server 层（应通过 Interface）
-Interface ←── 禁止 ── 任何层不得修改 Interface 层（只读）
-```
-
-### 3.2 允许的依赖方向
-
-```
-CLI → Server → Domain → Infrastructure → Interface
-CLI → Interface
-Server → Interface
-Domain → Interface
-Infrastructure → Interface
-```
-
----
-
-## 4. 依赖注入规范
-
-### 4.1 原则
-
-- 高层模块不应依赖低层模块，两者都应依赖抽象（Interface 层契约）
-- 使用构造函数注入或工厂函数注入
-- 禁止在模块内部直接 `new` 高阶服务
-
-### 4.2 合规示例
-
-```typescript
-// ✅ 合规：通过 Interface 层契约注入
-// src/domain/services/CodeGraphBuilder.ts
-import type { IStorage } from '../../interface/types/storage';
-import type { IParserRegistry } from '../../interface/types/parser';
-
-export interface CodeGraphBuilderDeps {
-  storage: IStorage;
-  parserRegistry: IParserRegistry;
-}
-
-export class CodeGraphBuilder {
-  constructor(private deps: CodeGraphBuilderDeps) {}
-  
-  async build(files: string[]) {
-    const parser = this.deps.parserRegistry.getParser('typescript');
-    const ast = await parser.parse(files);
-    return this.deps.storage.save(ast);
-  }
-}
-```
-
-```typescript
-// ❌ 违规：直接实例化 Infrastructure 具体实现
-// src/domain/services/CodeGraphBuilder.ts
-import { FileSystemStorage } from '../../infrastructure/storage/FileSystemStorage';
-import { TypeScriptParser } from '../../infrastructure/parser/implementations/TypeScriptParser';
-
-export class CodeGraphBuilder {
-  private storage = new FileSystemStorage(); // 错误！硬编码实现
-  private parser = new TypeScriptParser();   // 错误！难以测试和替换
-}
-```
-
----
-
-## 5. 文件组织规范
-
-### 5.1 目录结构（MVP3）
-
-```
-src/
-  cli/                      # CLI 层
-    commands/               # 子命令实现
-    index.ts               # CLI 入口
-  server/                   # Server 层（MVP3 新增）
-    CodeMapServer.ts       # HTTP 服务器
-    handlers/              # 请求处理器
-    routes/                # 路由定义
-  domain/                   # Domain 层
-    entities/              # 领域实体
-      Project.ts
-      Module.ts
-      Symbol.ts
-      Dependency.ts
-      CodeGraph.ts
-    services/              # 领域服务
-      CodeGraphBuilder.ts
-    events/                # 领域事件
-      DomainEvent.ts
-    repositories/          # 仓库接口（仅接口）
-      CodeGraphRepository.ts
-  infrastructure/           # Infrastructure 层
-    storage/               # 存储适配器
-      FileSystemStorage.ts
-      MemoryStorage.ts
-      KuzuDBStorage.ts
-      StorageFactory.ts
-    parser/                # 解析器
-      interfaces/
-      implementations/
-      registry/
-    repositories/          # 仓库实现
-      CodeGraphRepositoryImpl.ts
-  interface/                # Interface 层
-    types/                 # 类型定义
-    config/                # 配置接口
-```
-
-### 5.2 文件命名规范
-
-- **实现文件**：`kebab-case.ts`（如 `code-graph-builder.ts`）
-- **接口文件**：`I{PascalCase}.ts`（如 `IStorage.ts`）或 `types.ts`
-- **测试文件**：`{name}.test.ts` 或 `__tests__/{name}.test.ts`
-- **实体文件**：`PascalCase.ts`（如 `CodeGraph.ts`）
-
----
-
-## 6. Enforcement 策略
-
-### 6.1 自动检测
-
-使用 `dependency-cruiser` 配置架构规则：
-
-```javascript
-// .dependency-cruiser.js（待配置）
-module.exports = {
-  forbidden: [
-    {
-      name: 'no-domain-in-cli',
-      comment: 'CLI 层不得直接依赖 Domain 层（应通过 Interface）',
-      severity: 'error',
-      from: { path: '^src/cli' },
-      to: { path: '^src/domain', pathNot: '^src/domain/[^/]+\.ts$' }
-    },
-    {
-      name: 'no-infrastructure-in-domain',
-      comment: 'Domain 层不得依赖 Infrastructure 层',
-      severity: 'error',
-      from: { path: '^src/domain' },
-      to: { path: '^src/infrastructure' }
-    },
-    {
-      name: 'no-server-in-cli',
-      comment: 'CLI 层不得依赖 Server 层',
-      severity: 'error',
-      from: { path: '^src/cli' },
-      to: { path: '^src/server' }
-    }
-  ]
-};
-```
-
-### 6.2 手动检查
-
-使用 CodeMap CLI 检查模块依赖：
+## 快速验证
 
 ```bash
-# 检查某模块的依赖
-node dist/cli/index.js deps -m "src/domain/services"
-
-# 检查某文件的影响范围
+node dist/cli/index.js deps -m "src/domain"
 node dist/cli/index.js impact -f "src/interface/types/index.ts"
-
-# 检查跨层依赖（使用 analyze）
-node dist/cli/index.js analyze -i dependency -t src/domain
-```
-
-### 6.3 CI 检查
-
-在 CI 中添加架构合规检查：
-
-```yaml
-# .github/workflows/ci-gateway.yml
-- name: Check architecture compliance
-  run: npm run check:architecture
-```
-
----
-
-## 7. 违规处理
-
-### 7.1 发现违规时
-
-1. **暂停任务**：不得继续添加更多代码
-2. **评估影响**：使用 `impact` 命令评估影响范围
-3. **重构方案**：将直接依赖改为接口注入
-4. **验证修复**：重新运行架构检查
-
-### 7.2 临时例外
-
-若因紧急需求必须暂时违规，必须按技术债务标记：
-
-```typescript
-// TODO-DEBT [L2] [日期:2026-03-20] [作者:AI] [原因:紧急修复]
-// 问题：Domain 层临时依赖 Infrastructure 具体实现
-// 风险：破坏分层架构，难以单元测试
-// 偿还计划：提取接口，通过依赖注入传递
-import { FileSystemStorage } from '../infrastructure/storage/FileSystemStorage';
-```
-
----
-
-## 8. 最佳实践
-
-### 8.1 依赖注入模式
-
-```typescript
-// 推荐：工厂函数模式
-export function createCodeGraphBuilder(deps: Partial<CodeGraphBuilderDeps> = {}) {
-  return new CodeGraphBuilder({
-    storage: deps.storage ?? createStorage(),
-    parserRegistry: deps.parserRegistry ?? createParserRegistry(),
-  });
-}
-
-// 使用
-const builder = createCodeGraphBuilder(); // 生产环境
-const testBuilder = createCodeGraphBuilder({ storage: mockStorage }); // 测试环境
-```
-
-### 8.2 接口定义位置
-
-- 接口定义在 **Interface 层**（`src/interface/`）
-- 或定义在被依赖方的接口目录
-
-```typescript
-// src/interface/types/storage.ts
-export interface IStorage {
-  save(data: unknown): Promise<void>;
-  load(): Promise<unknown>;
-}
-
-// src/infrastructure/storage/FileSystemStorage.ts
-import type { IStorage } from '../../interface/types/storage';
-export class FileSystemStorage implements IStorage { ... }
-
-// src/domain/services/CodeGraphBuilder.ts
-import type { IStorage } from '../../interface/types/storage';
-export class CodeGraphBuilder {
-  constructor(private storage: IStorage) {}
-}
+npm run check:architecture
 ```
 
----
-
-## 9. 验证清单
-
-修改架构相关代码前，检查：
-
-- [ ] 新模块的依赖方向是否符合 MVP3 分层规则
-- [ ] 是否使用了依赖注入而非直接实例化
-- [ ] 接口定义是否在 Interface 层
-- [ ] 是否可以通过 `check:architecture` 验证
-
----
-
-## 10. 相关文档
+## 常见误区
 
-- `ARCHITECTURE.md` - 系统总图与模块边界
-- `docs/rules/engineering-with-codex-openai.md` - 工程规则与 CI 护栏
-- `docs/rules/code-quality-redlines.md` - 代码质量红线
-- `docs/exec-plans/MVP3-IMPLEMENTATION-ROADMAP.md` - MVP3 重构路线图
+- `Server Layer` 是内部架构层，不等于公共产品面的 `mycodemap server`。
+- `src/domain/` 可以依赖接口，不能依赖实现。
+- 做小改动也不能顺手把跨层 import 当成“临时方便”。