commit 09203a989cd317b66a1db1260862fa5a97e094c5 Author: openclaw Date: Mon Mar 23 13:36:42 2026 +0000 Initial commit: arch-design-agent-skill-dashboard diff --git a/.arch-design-agent.json b/.arch-design-agent.json new file mode 100644 index 0000000..1363688 --- /dev/null +++ b/.arch-design-agent.json @@ -0,0 +1,17 @@ +{ + "project_root": ".", + "design_root": "design", + "repo_roots": ["."], + "domain_root": "design/domains", + "adr_globs": [ + "design/adr/*.md", + "design/business-architecture/adr/*.md", + "design/application-architecture/adr/*.md", + "design/data-architecture/adr/*.md", + "design/technology-architecture/adr/*.md", + "design/domains/*/adr/*.md" + ], + "history_globs": [ + "design/change-log.csv" + ] +} diff --git a/backend/app/__init__.py b/backend/app/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/main.py b/backend/app/main.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/__init__.py b/backend/app/modules/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/design/__init__.py b/backend/app/modules/design/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/design/domain/__init__.py b/backend/app/modules/design/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/design/domain/entities.py b/backend/app/modules/design/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/design/domain/services.py b/backend/app/modules/design/domain/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/design/domain/value_objects.py b/backend/app/modules/design/domain/value_objects.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/__init__.py b/backend/app/modules/editor/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/application/__init__.py b/backend/app/modules/editor/application/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/application/services.py b/backend/app/modules/editor/application/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/domain/__init__.py b/backend/app/modules/editor/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/domain/entities.py b/backend/app/modules/editor/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/infrastructure/__init__.py b/backend/app/modules/editor/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/interfaces/__init__.py b/backend/app/modules/editor/interfaces/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/interfaces/http/__init__.py b/backend/app/modules/editor/interfaces/http/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/editor/interfaces/http/router.py b/backend/app/modules/editor/interfaces/http/router.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/__init__.py b/backend/app/modules/graph/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/application/__init__.py b/backend/app/modules/graph/application/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/application/services.py b/backend/app/modules/graph/application/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/domain/__init__.py b/backend/app/modules/graph/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/domain/entities.py b/backend/app/modules/graph/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/infrastructure/__init__.py b/backend/app/modules/graph/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/interfaces/__init__.py b/backend/app/modules/graph/interfaces/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/interfaces/http/__init__.py b/backend/app/modules/graph/interfaces/http/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/graph/interfaces/http/router.py b/backend/app/modules/graph/interfaces/http/router.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/__init__.py b/backend/app/modules/impl_tracker/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/application/__init__.py b/backend/app/modules/impl_tracker/application/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/application/services.py b/backend/app/modules/impl_tracker/application/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/domain/__init__.py b/backend/app/modules/impl_tracker/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/domain/entities.py b/backend/app/modules/impl_tracker/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/infrastructure/__init__.py b/backend/app/modules/impl_tracker/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/interfaces/__init__.py b/backend/app/modules/impl_tracker/interfaces/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/interfaces/http/__init__.py b/backend/app/modules/impl_tracker/interfaces/http/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/impl_tracker/interfaces/http/router.py b/backend/app/modules/impl_tracker/interfaces/http/router.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/__init__.py b/backend/app/modules/project/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/application/__init__.py b/backend/app/modules/project/application/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/application/services.py b/backend/app/modules/project/application/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/domain/__init__.py b/backend/app/modules/project/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/domain/entities.py b/backend/app/modules/project/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/domain/repositories.py b/backend/app/modules/project/domain/repositories.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/infrastructure/__init__.py b/backend/app/modules/project/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/infrastructure/json_repository.py b/backend/app/modules/project/infrastructure/json_repository.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/interfaces/__init__.py b/backend/app/modules/project/interfaces/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/interfaces/http/__init__.py b/backend/app/modules/project/interfaces/http/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/project/interfaces/http/router.py b/backend/app/modules/project/interfaces/http/router.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/__init__.py b/backend/app/modules/scanner/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/application/__init__.py b/backend/app/modules/scanner/application/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/application/services.py b/backend/app/modules/scanner/application/services.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/domain/__init__.py b/backend/app/modules/scanner/domain/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/domain/entities.py b/backend/app/modules/scanner/domain/entities.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/__init__.py b/backend/app/modules/scanner/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/parsers/__init__.py b/backend/app/modules/scanner/infrastructure/parsers/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/parsers/csv_parser.py b/backend/app/modules/scanner/infrastructure/parsers/csv_parser.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/parsers/md_parser.py b/backend/app/modules/scanner/infrastructure/parsers/md_parser.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/parsers/openapi_parser.py b/backend/app/modules/scanner/infrastructure/parsers/openapi_parser.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/infrastructure/parsers/yaml_parser.py b/backend/app/modules/scanner/infrastructure/parsers/yaml_parser.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/interfaces/__init__.py b/backend/app/modules/scanner/interfaces/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/interfaces/http/__init__.py b/backend/app/modules/scanner/interfaces/http/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/modules/scanner/interfaces/http/router.py b/backend/app/modules/scanner/interfaces/http/router.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/__init__.py b/backend/app/shared/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/infrastructure/__init__.py b/backend/app/shared/infrastructure/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/infrastructure/config.py b/backend/app/shared/infrastructure/config.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/infrastructure/filesystem.py b/backend/app/shared/infrastructure/filesystem.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/kernel/__init__.py b/backend/app/shared/kernel/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/backend/app/shared/kernel/exceptions.py b/backend/app/shared/kernel/exceptions.py new file mode 100644 index 0000000..e69de29 diff --git a/design/README.md b/design/README.md new file mode 100644 index 0000000..96b4fd4 --- /dev/null +++ b/design/README.md @@ -0,0 +1,100 @@ +# Design Overview + +本目录是完整设计资产的根目录。 + +## 1. 顶层结构 +```text +design/ +├── README.md +├── adr/ +│ └── ADR-000-template.md +├── traceability.csv +├── change-log.csv +├── business-architecture/ +├── application-architecture/ +├── data-architecture/ +├── technology-architecture/ +└── domains/ +``` + +## 2. 四层主视图 + domain 视图 + +### 2.1 业务架构产出 +回答：**为什么做、做哪些能力、主流程和关键旅程是什么** +- 范围与目标 +- 能力地图（CSV） +- 价值流（CSV） +- 用户旅程（CSV） +- 业务 ADR + +### 2.2 应用架构产出 +回答：**系统怎么拆、系统级如何分层、模块内部如何分层、谁和谁交互、关键接口是什么、如何落到代码仓库** +- 系统上下文 +- 外部系统清单（CSV） +- 系统级分层 / 逻辑架构图 +- 模块内技术分层 / 代码分层 +- 模块清单（CSV） +- 外部集成（CSV） +- API 契约 +- 代码库对齐（CSV + 规则文档） +- 应用 ADR + +### 2.3 数据架构产出 +回答：**关键数据对象是谁、谁维护、怎么流动、怎么保护** +- 实体清单（CSV） +- 数据流（CSV） +- 数据安全分级（CSV） +- 数据 ADR + +### 2.4 技术架构产出 +回答：**用什么做、系统怎么运行、怎么发布、怎么回滚、怎么保底安全** +- 技术选型说明 + 选型 CSV +- 运行拓扑说明 + 运行组件 CSV +- 环境配置（CSV） +- 运维基线 +- 发布与回滚说明 +- 技术 ADR + +### 2.5 Domain 产出 +回答：**某个领域自己的术语、场景、模块、实体、局部决策与代码落位是什么** +- 领域概览 +- 统一语言（CSV） +- 领域场景与流程（CSV） +- 领域模块（CSV） +- 领域实体（CSV） +- 领域局部决策 +- 领域代码映射（CSV） +- 领域 ADR + +## 3. 关键依赖 +- `application-architecture/02b-solution-layering.md` 用于说明系统级逻辑分层 +- `application-architecture/02a-layered-architecture.md` 用于说明模块/服务内部代码分层与依赖方向 +- `application-architecture/02-modules.csv` 依赖 `business-architecture/02-capability-map.csv` +- `application-architecture/03-integrations.csv` 依赖 `business-architecture/03-value-flows.csv` +- `data-architecture/01-entities.csv` 依赖 `business-architecture/02-capability-map.csv` 与 `application-architecture/02-modules.csv` +- `technology-architecture/00-technology-selection.csv` 用于沉淀关键技术选型 +- `technology-architecture/01-runtime-components.csv` 体现模块到运行组件的映射 +- `application-architecture/06-codebase-alignment.csv` 用于设计到仓库结构的落地映射 +- `traceability.csv` 汇总跨目录关联关系 + +## 4. 新成员阅读顺序 +1. `business-architecture/01-scope-and-goals.md` +2. `business-architecture/03-value-flows.csv` +3. `application-architecture/01-system-context.md` +4. `application-architecture/02b-solution-layering.md` +5. `domains/README.md` +6. `domains/_shared/01-shared-terminology.csv` +7. `application-architecture/02a-layered-architecture.md` +8. `application-architecture/02-modules.csv` +9. `data-architecture/01-entities.csv` +10. `technology-architecture/00-technology-selection.md` +11. `technology-architecture/01-runtime-topology.md` +12. `application-architecture/06-codebase-alignment.csv` +13. `technology-architecture/04-release-and-rollback.md` + +## 5. 维护规则 +- 表格型数据优先 CSV +- prose 与决策说明使用 Markdown +- 全局 ADR 放 `adr/` +- 分层 ADR 放到对应目录的 `adr/` +- 领域局部内容优先维护在 `domains//` diff --git a/design/adr/ADR-000-template.md b/design/adr/ADR-000-template.md new file mode 100644 index 0000000..d0adc02 --- /dev/null +++ b/design/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 标题待定 + +- Status: draft +- Date: 2026-03-23 +- Scope: global +- Deciders: architect, tech-lead + +## Context +为什么要做这个决策？ + +## Decision +最终决定是什么？ + +## Consequences +会带来什么影响、代价、边界条件？ diff --git a/design/application-architecture/01-external-systems.csv b/design/application-architecture/01-external-systems.csv new file mode 100644 index 0000000..01f6254 --- /dev/null +++ b/design/application-architecture/01-external-systems.csv @@ -0,0 +1,5 @@ +system_id,system_name,type,protocol,direction,description,phase +EXT-FS-DESIGN,设计文件目录,filesystem,file I/O,bidirectional,读写 design/ 目录下的 CSV/MD/YAML/OpenAPI 文件,MVP +EXT-FS-CODE,代码仓库目录,filesystem,file I/O,inbound (read-only),读取项目代码目录结构用于实现进度扫描,Phase2 +EXT-FS-REGISTRY,项目注册表,data file,JSON read/write,bidirectional,项目注册信息持久化（~/.arch-design-dashboard/projects.json）,MVP +EXT-LLM,LLM 服务,api,HTTP,outbound,调用 LLM 评估模块实现完成度,Phase2 diff --git a/design/application-architecture/01-system-context.md b/design/application-architecture/01-system-context.md new file mode 100644 index 0000000..fdf537d --- /dev/null +++ b/design/application-architecture/01-system-context.md @@ -0,0 +1,41 @@ +--- +doc_id: DOC-AA-001 +title: 系统上下文 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ../business-architecture/01-scope-and-goals.md +downstream: + - ./01-external-systems.csv + - ./02b-solution-layering.md + - ./02-modules.csv +updated_at: 2026-03-23 +--- + +# 系统上下文 + +## 1. 系统边界 + +Arch Design Dashboard 是一个单体 Web 应用（前后端分离），用于管理基于 `minimal-design-template` 的架构设计过程。 + +```mermaid +flowchart LR + User["林然
(Browser)"] -->|HTTP| Dashboard["Arch Design Dashboard"] + Dashboard -->|File I/O read/write| DesignDir["设计文件目录
(design/)"] + Dashboard -->|File I/O read-only| CodeDir["代码仓库目录
(src/ 等)"] + Dashboard -->|HTTP API| LLM["LLM 服务
(Phase 2)"] +``` + +## 2. 边界说明 + +- Dashboard 是唯一的系统，没有微服务拆分 +- 设计文件是 single source of truth，dashboard 不做额外缓存/数据库 +- 代码仓库只读（dashboard 不改代码） +- LLM 服务是 Phase 2，MVP 不涉及 +- 单人使用，无认证需求 + +## 3. 外部系统 + +详见 `./01-external-systems.csv` diff --git a/design/application-architecture/02-modules.csv b/design/application-architecture/02-modules.csv new file mode 100644 index 0000000..cd0d24c --- /dev/null +++ b/design/application-architecture/02-modules.csv @@ -0,0 +1,10 @@ +module_id,module_name,layer,description,phase,depends_on,capabilities +MOD-PROJECT,项目管理,backend,项目注册/切换/配置发现,MVP,,CAP-PROJ-REG +MOD-DESIGN,架构设计领域,backend,设计领域实体定义（Capability/Module/Entity/ValueFlow等）+业务逻辑+约束规则,MVP,, +MOD-SCANNER,设计扫描与解析,backend,扫描 design/ 目录并解析 CSV/MD/YAML/OpenAPI 为 MOD-DESIGN 定义的实体并检测完成度,MVP,MOD-DESIGN,CAP-SCAN CAP-GAP CAP-PROGRESS-DESIGN +MOD-GRAPH,关系图引擎,backend,从 MOD-DESIGN 实体构建关系图（节点+边+分组）支持下钻/邻居查询,MVP,MOD-DESIGN,CAP-GRAPH-PANORAMA CAP-GRAPH-DRILL +MOD-EDITOR,文件编辑器,backend,读写设计文件和影响分析,Phase2,MOD-DESIGN MOD-SCANNER MOD-GRAPH,CAP-EDIT-CSV CAP-EDIT-MD CAP-GRAPH-IMPACT +MOD-IMPL-TRACKER,实现进度追踪,backend,扫描代码目录结构+调用 LLM 评估模块完成度+手动覆盖,Phase2,MOD-DESIGN MOD-SCANNER,CAP-PROGRESS-IMPL +MOD-FE-GRAPH,关系图前端,frontend,全景关系图渲染/下钻交互/节点状态着色/影响高亮,MVP,,CAP-GRAPH-PANORAMA CAP-GRAPH-DRILL CAP-PROGRESS-DESIGN +MOD-FE-PROJECT,项目管理前端,frontend,项目列表/切换/注册表单,MVP,,CAP-PROJ-REG +MOD-FE-EDITOR,编辑器前端,frontend,CSV 表格编辑器 + Markdown 编辑器组件,Phase2,,CAP-EDIT-CSV CAP-EDIT-MD diff --git a/design/application-architecture/02a-layered-architecture.md b/design/application-architecture/02a-layered-architecture.md new file mode 100644 index 0000000..6400801 --- /dev/null +++ b/design/application-architecture/02a-layered-architecture.md @@ -0,0 +1,126 @@ +--- +doc_id: DOC-AA-002 +title: 模块内部代码分层 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./02b-solution-layering.md +downstream: + - ./06-codebase-alignment.csv + - ./07-module-boundary-rules.md +updated_at: 2026-03-23 +--- + +# 模块内部代码分层 + +## 1. 总体规则 + +每个后端模块采用 DDD 四层结构： + +``` +modules// +├── domain/ # 纯 Python，零框架依赖 +│ ├── entities/ # 实体、值对象 +│ ├── repositories/# 仓储抽象接口（ABC） +│ └── services/ # 核心业务逻辑 +├── application/ # 用例编排，调用 domain 层 +│ └── services/ # 应用服务（use case） +├── infrastructure/ # 外部适配（文件 I/O、JSON 持久化、解析器） +│ ├── parsers/ # CSV/MD/YAML/OpenAPI 解析器 +│ └── repositories/# 仓储实现 +└── interfaces/ # HTTP 入口 + └── http/ + └── routers/ # FastAPI 路由 +``` + +## 2. 层间依赖规则 + +``` +interfaces → application → domain ← infrastructure +``` + +- **domain 层绝对不导入其他三层**，也不导入任何框架包（FastAPI、Pydantic 的 BaseModel 等） +- domain 层的实体用纯 Python dataclass 或普通类 +- infrastructure 层实现 domain 层定义的抽象接口 +- application 层通过依赖注入获取 infrastructure 的实现 +- interfaces 层只做 HTTP 协议适配（入参校验、响应序列化），不含业务逻辑 + +## 3. 各模块 domain 层内容 + +### MOD-DESIGN（架构设计领域） + +核心模块，定义所有设计领域的实体和业务规则。 + +**实体：** +- `Capability` — 能力（ID、名称、优先级、关联价值流） +- `Module` — 功能模块（ID、名称、层、依赖、关联能力） +- `Entity` — 数据实体（ID、名称、owner module） +- `ValueFlow` — 价值流（ID、触发、步骤、结果） +- `UserJourney` — 用户旅程（ID、前置条件、步骤、后置条件） +- `Integration` — 集成关系（源模块、目标、协议、方向） +- `DataFlow` — 数据流（源、目标、数据内容、触发） +- `TraceabilityLink` — 追溯关系（capability→module→entity） +- `DesignDocument` — 非结构化设计文件元数据（frontmatter: upstream/downstream/status/doc_id） +- `ExternalSystem` — 外部系统 +- `RuntimeComponent` — 运行时组件 +- `TechnologySelection` — 技术选型项 +- `Environment` — 环境定义 + +**值对象：** +- `FileStatus` — ok / sparse / missing / template-residue / placeholder-heavy +- `ArchitectureLayer` — business / application / data / technology +- `ModuleLayer` — domain / application / infrastructure / interfaces + +**约束规则（domain services）：** +- 每个 Capability 至少关联一个 Module +- 每个 Entity 必须有一个 owner Module +- TraceabilityLink 中引用的 ID 必须在对应实体列表中存在 +- DesignDocument 的 upstream/downstream 引用的文件必须存在 + +### MOD-SCANNER（设计扫描与解析） + +**domain：** +- `ScanResult` — 一次扫描的完整输出（所有解析出的 Design 实体 + 文件状态列表） +- `ScanPolicy` — 扫描策略（哪些文件类型要解析、忽略规则） + +### MOD-GRAPH（关系图引擎） + +**domain：** +- `GraphNode` — 图节点（类型、ID、标签、状态、所属分组） +- `GraphEdge` — 图边（source、target、关系类型） +- `GraphGroup` — 分组（架构层级） +- `GraphView` — 完整图视图（nodes + edges + groups），支持按层级过滤 + +### MOD-PROJECT（项目管理） + +**domain：** +- `Project` — 项目（ID、名称、设计目录路径、代码目录路径、创建时间） +- `ProjectRepository`（ABC）— 项目持久化抽象接口 + +### MOD-EDITOR（文件编辑器，Phase 2） + +**domain：** +- `EditableFile` — 可编辑文件（路径、格式、内容） +- `ImpactResult` — 影响分析结果（受影响的文件列表和原因链） + +### MOD-IMPL-TRACKER（实现进度追踪，Phase 2） + +**domain：** +- `ImplProgress` — 模块实现进度（模块 ID、百分比、来源：auto/llm/manual） +- `CodeStructure` — 代码目录结构扫描结果 + +## 4. 前端分层 + +前端模块采用 Vue 3 组件化结构： + +``` +src/modules// +├── components/ # Vue 组件 +├── composables/ # 组合式函数（业务逻辑） +├── types/ # TypeScript 类型定义 +└── api/ # 后端 API 调用封装 +``` + +共享代码放 `src/shared/`。 diff --git a/design/application-architecture/02b-solution-layering.md b/design/application-architecture/02b-solution-layering.md new file mode 100644 index 0000000..1210ab0 --- /dev/null +++ b/design/application-architecture/02b-solution-layering.md @@ -0,0 +1,53 @@ +--- +doc_id: DOC-AA-003 +title: 系统逻辑分层 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./01-system-context.md +downstream: + - ./02-modules.csv + - ./02a-layered-architecture.md +updated_at: 2026-03-23 +--- + +# 系统逻辑分层 + +## 1. 三层架构 + +```mermaid +flowchart TB + subgraph Frontend["前端 (Browser SPA)"] + FE-GRAPH["MOD-FE-GRAPH
关系图渲染与交互"] + FE-PROJECT["MOD-FE-PROJECT
项目切换 UI"] + FE-EDITOR["MOD-FE-EDITOR
编辑器组件 (Phase 2)"] + end + subgraph Backend["后端 (REST API Server)"] + PROJECT["MOD-PROJECT
项目管理"] + SCANNER["MOD-SCANNER
扫描与解析"] + GRAPH["MOD-GRAPH
关系图引擎"] + EDITOR["MOD-EDITOR
文件编辑 (Phase 2)"] + IMPL["MOD-IMPL-TRACKER
实现进度 (Phase 2)"] + end + subgraph External["外部数据源"] + FS-DESIGN["设计文件目录"] + FS-CODE["代码仓库目录"] + LLM["LLM 服务"] + end + Frontend -->|REST API| Backend + Backend -->|File I/O| External +``` + +## 2. 层间通信 + +- 前端 ↔ 后端：REST API（JSON over HTTP） +- 后端 ↔ 文件系统：直接文件 I/O +- 后端 ↔ LLM：HTTP API 调用（Phase 2） + +## 3. 关键约束 + +- 前端不直接访问文件系统，所有数据通过后端 API 获取 +- 后端无数据库，设计文件本身就是持久化层 +- 项目注册信息用 JSON 文件存储（唯一的非设计文件持久化） diff --git a/design/application-architecture/03-integrations.csv b/design/application-architecture/03-integrations.csv new file mode 100644 index 0000000..256b9ee --- /dev/null +++ b/design/application-architecture/03-integrations.csv @@ -0,0 +1,19 @@ +integration_id,source_id,target_id,target_type,direction,protocol,trigger,phase,description +INT-001,MOD-SCANNER,MOD-DESIGN,module,internal,function call,解析文件后生成 Design 实体,MVP,Scanner 解析 CSV/MD/YAML 后产出 MOD-DESIGN 定义的领域实体 +INT-002,MOD-GRAPH,MOD-DESIGN,module,internal,function call,构建图时读取 Design 实体,MVP,Graph 从 Capability/Module/Entity/TraceabilityLink 转换为 GraphNode/GraphEdge +INT-003,MOD-SCANNER,MOD-DESIGN,module,internal,function call,完成度检测调用约束规则,MVP,Scanner 调用 Design 模块的规则判定 FileStatus +INT-004,MOD-EDITOR,MOD-SCANNER,module,internal,function call,保存后重新扫描,Phase2,编辑保存后触发重新扫描刷新状态 +INT-005,MOD-EDITOR,MOD-GRAPH,module,internal,function call,保存后计算影响范围,Phase2,编辑保存后计算下游影响 +INT-006,MOD-EDITOR,MOD-DESIGN,module,internal,function call,编辑时校验约束,Phase2,编辑内容需满足 Design 模块的约束规则 +INT-007,MOD-IMPL-TRACKER,MOD-DESIGN,module,internal,function call,获取模块和 codebase-alignment 定义,Phase2,对照 Design 的 Module/CodebaseAlignment 评估实现进度 +INT-008,MOD-IMPL-TRACKER,MOD-SCANNER,module,internal,function call,获取最新扫描结果,Phase2,实现进度需要最新的设计文件扫描数据 +INT-010,MOD-FE-PROJECT,MOD-PROJECT,module,frontend→backend,REST API,用户操作项目列表,MVP,前端项目管理调用后端项目 CRUD 接口 +INT-011,MOD-FE-GRAPH,MOD-SCANNER,module,frontend→backend,REST API,用户打开项目或刷新,MVP,前端获取扫描结果（文件列表/完成度/结构化数据） +INT-012,MOD-FE-GRAPH,MOD-GRAPH,module,frontend→backend,REST API,用户浏览关系图,MVP,前端获取关系图数据（节点/边/分组） +INT-013,MOD-FE-EDITOR,MOD-EDITOR,module,frontend→backend,REST API,用户编辑文件,Phase2,前端编辑器调用后端文件读写接口 +INT-014,MOD-FE-GRAPH,MOD-IMPL-TRACKER,module,frontend→backend,REST API,用户查看实现进度,Phase2,前端获取模块实现完成百分比 +INT-020,MOD-SCANNER,EXT-FS-DESIGN,external,outbound,file I/O,扫描设计目录,MVP,读取 design/ 下所有文件 +INT-021,MOD-PROJECT,EXT-FS-REGISTRY,external,bidirectional,JSON read/write,项目注册/加载,MVP,读写 projects.json +INT-022,MOD-EDITOR,EXT-FS-DESIGN,external,bidirectional,file I/O,文件编辑,Phase2,读写设计文件 +INT-023,MOD-IMPL-TRACKER,EXT-FS-CODE,external,inbound,file I/O,扫描代码目录,Phase2,读取项目代码目录结构 +INT-024,MOD-IMPL-TRACKER,EXT-LLM,external,outbound,HTTP API,评估模块完成度,Phase2,调用 LLM 分析代码与设计的匹配度 diff --git a/design/application-architecture/04-api-contracts.openapi.yaml b/design/application-architecture/04-api-contracts.openapi.yaml new file mode 100644 index 0000000..af467b2 --- /dev/null +++ b/design/application-architecture/04-api-contracts.openapi.yaml @@ -0,0 +1,876 @@ +openapi: 3.0.3 +info: + title: Arch Design Agent Skill Dashboard API + version: 0.1.0 + description: 架构设计管理 Dashboard 后端 REST API + +servers: + - url: http://localhost:8900 + description: 开发环境 + - url: http://localhost/api + description: 生产环境（Nginx 反代） + +paths: + # === 健康检查 === + /api/health: + get: + operationId: healthCheck + summary: 健康检查 + tags: [system] + responses: + "200": + description: OK + content: + application/json: + schema: + type: object + properties: + status: + type: string + example: ok + + # === 项目管理 (MOD-PROJECT) === + /api/projects: + get: + operationId: listProjects + summary: 列出所有项目 + tags: [project] + responses: + "200": + description: 项目列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Project" + post: + operationId: createProject + summary: 注册新项目 + tags: [project] + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/CreateProjectRequest" + responses: + "201": + description: 项目已创建 + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + "400": + description: 设计目录不存在或路径无效 + + /api/projects/{project_id}: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: getProject + summary: 获取单个项目详情 + tags: [project] + responses: + "200": + description: 项目详情 + content: + application/json: + schema: + $ref: "#/components/schemas/Project" + "404": + description: 项目不存在 + delete: + operationId: deleteProject + summary: 删除项目 + tags: [project] + responses: + "204": + description: 已删除 + "404": + description: 项目不存在 + + # === 扫描 (MOD-SCANNER) === + /api/projects/{project_id}/scan: + parameters: + - $ref: "#/components/parameters/ProjectId" + post: + operationId: triggerScan + summary: 触发扫描 + tags: [scanner] + responses: + "200": + description: 扫描结果 + content: + application/json: + schema: + $ref: "#/components/schemas/ScanResult" + get: + operationId: getLatestScan + summary: 获取最近一次扫描结果（缓存） + tags: [scanner] + responses: + "200": + description: 缓存的扫描结果 + content: + application/json: + schema: + $ref: "#/components/schemas/ScanResult" + "404": + description: 尚未扫描 + + # === 关系图 (MOD-GRAPH) === + /api/projects/{project_id}/graph: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: getGraph + summary: 获取全景关系图 + tags: [graph] + responses: + "200": + description: 全景图数据 + content: + application/json: + schema: + $ref: "#/components/schemas/GraphView" + + /api/projects/{project_id}/graph/nodes/{node_id}/neighbors: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: node_id + in: path + required: true + schema: + type: string + description: 节点 ID（如 MOD-PROJECT、CAP-SCAN） + get: + operationId: getNodeNeighbors + summary: 下钻查询——获取某节点的所有邻居 + tags: [graph] + responses: + "200": + description: 邻居子图 + content: + application/json: + schema: + $ref: "#/components/schemas/GraphView" + "404": + description: 节点不存在 + + # === 实体查询 (MOD-DESIGN via MOD-SCANNER) === + /api/projects/{project_id}/entities/capabilities: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listCapabilities + summary: 列出所有能力 + tags: [entities] + responses: + "200": + description: 能力列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Capability" + + /api/projects/{project_id}/entities/capabilities/{capability_id}: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: capability_id + in: path + required: true + schema: + type: string + get: + operationId: getCapability + summary: 获取单个能力详情（含关联 modules、value-flows） + tags: [entities] + responses: + "200": + description: 能力详情 + content: + application/json: + schema: + $ref: "#/components/schemas/CapabilityDetail" + "404": + description: 能力不存在 + + /api/projects/{project_id}/entities/modules: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listModules + summary: 列出所有模块 + tags: [entities] + responses: + "200": + description: 模块列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Module" + + /api/projects/{project_id}/entities/modules/{module_id}: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: module_id + in: path + required: true + schema: + type: string + get: + operationId: getModule + summary: 获取单个模块详情（含关联 capabilities、entities、integrations、codebase-alignment） + tags: [entities] + responses: + "200": + description: 模块详情 + content: + application/json: + schema: + $ref: "#/components/schemas/ModuleDetail" + "404": + description: 模块不存在 + + /api/projects/{project_id}/entities/entities: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listEntities + summary: 列出所有数据实体 + tags: [entities] + responses: + "200": + description: 数据实体列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Entity" + + /api/projects/{project_id}/entities/entities/{entity_id}: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: entity_id + in: path + required: true + schema: + type: string + get: + operationId: getEntity + summary: 获取单个数据实体详情（含 owner module、data-flows） + tags: [entities] + responses: + "200": + description: 实体详情 + content: + application/json: + schema: + $ref: "#/components/schemas/EntityDetail" + "404": + description: 实体不存在 + + /api/projects/{project_id}/entities/integrations: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listIntegrations + summary: 列出所有集成关系 + tags: [entities] + responses: + "200": + description: 集成列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/Integration" + + /api/projects/{project_id}/entities/value-flows: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listValueFlows + summary: 列出所有价值流 + tags: [entities] + responses: + "200": + description: 价值流列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ValueFlow" + + /api/projects/{project_id}/entities/user-journeys: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listUserJourneys + summary: 列出所有用户旅程 + tags: [entities] + responses: + "200": + description: 用户旅程列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/UserJourney" + + /api/projects/{project_id}/entities/data-flows: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listDataFlows + summary: 列出所有数据流 + tags: [entities] + responses: + "200": + description: 数据流列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/DataFlow" + + /api/projects/{project_id}/entities/external-systems: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listExternalSystems + summary: 列出所有外部系统 + tags: [entities] + responses: + "200": + description: 外部系统列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ExternalSystem" + + /api/projects/{project_id}/entities/traceability-links: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listTraceabilityLinks + summary: 列出所有追溯链 + tags: [entities] + responses: + "200": + description: 追溯链列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TraceabilityLink" + + /api/projects/{project_id}/entities/runtime-components: + parameters: + - $ref: "#/components/parameters/ProjectId" + get: + operationId: listRuntimeComponents + summary: 列出所有运行组件 + tags: [entities] + responses: + "200": + description: 运行组件列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/RuntimeComponent" + + # === 文件编辑 (MOD-EDITOR, Phase 2) === + /api/projects/{project_id}/files: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: path + in: query + required: true + schema: + type: string + description: 设计文件相对路径（相对于 design/ 目录） + get: + operationId: getFile + summary: 读取设计文件内容 + tags: [editor] + responses: + "200": + description: 文件内容 + content: + application/json: + schema: + $ref: "#/components/schemas/FileContent" + "404": + description: 文件不存在 + put: + operationId: saveFile + summary: 保存设计文件（保存后自动触发重新扫描） + tags: [editor] + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/SaveFileRequest" + responses: + "200": + description: 保存成功，返回更新后的扫描结果 + content: + application/json: + schema: + $ref: "#/components/schemas/ScanResult" + + /api/projects/{project_id}/files/impact: + parameters: + - $ref: "#/components/parameters/ProjectId" + - name: path + in: query + required: true + schema: + type: string + get: + operationId: getFileImpact + summary: 影响分析——修改该文件会影响哪些下游 + tags: [editor] + responses: + "200": + description: 影响分析结果 + content: + application/json: + schema: + $ref: "#/components/schemas/ImpactResult" + + # === 实现进度 (MOD-IMPL-TRACKER, Phase 2) === + /api/projects/{project_id}/impl-progress: + parameters: + - $ref: "#/components/parameters/ProjectId" + post: + operationId: triggerImplProgress + summary: 触发实现进度评估 + tags: [impl-tracker] + responses: + "200": + description: 实现进度结果 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ImplProgress" + get: + operationId: getImplProgress + summary: 获取实现进度 + tags: [impl-tracker] + responses: + "200": + description: 实现进度列表 + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/ImplProgress" + +components: + parameters: + ProjectId: + name: project_id + in: path + required: true + schema: + type: string + format: uuid + description: 项目 ID + + schemas: + # --- Project --- + CreateProjectRequest: + type: object + required: [name, design_dir] + properties: + name: + type: string + description: 项目名称 + design_dir: + type: string + description: 设计文件目录绝对路径 + code_dir: + type: string + description: 代码仓库目录绝对路径（可选，Phase 2） + + Project: + type: object + properties: + id: + type: string + format: uuid + name: + type: string + design_dir: + type: string + code_dir: + type: string + nullable: true + created_at: + type: string + format: date-time + + # --- Scan --- + ScanResult: + type: object + properties: + project_id: + type: string + scanned_at: + type: string + format: date-time + file_statuses: + type: array + items: + $ref: "#/components/schemas/FileStatus" + summary: + type: object + properties: + total_files: + type: integer + ok: + type: integer + sparse: + type: integer + missing: + type: integer + placeholder_heavy: + type: integer + template_residue: + type: integer + + FileStatus: + type: object + properties: + path: + type: string + description: 设计文件相对路径 + status: + type: string + enum: [ok, sparse, missing, template-residue, placeholder-heavy] + content_lines: + type: integer + + # --- Graph --- + GraphView: + type: object + properties: + nodes: + type: array + items: + $ref: "#/components/schemas/GraphNode" + edges: + type: array + items: + $ref: "#/components/schemas/GraphEdge" + groups: + type: array + items: + $ref: "#/components/schemas/GraphGroup" + + GraphNode: + type: object + properties: + id: + type: string + description: 设计实体 ID（如 MOD-PROJECT、CAP-SCAN） + type: + type: string + description: 实体类型（capability、module、entity、integration 等） + label: + type: string + status: + type: string + enum: [ok, sparse, missing, template-residue, placeholder-heavy, unknown] + group_id: + type: string + description: 所属分组 ID + + GraphEdge: + type: object + properties: + source: + type: string + target: + type: string + relation: + type: string + description: 关系类型（traces_to、depends_on、owns、integrates_with 等） + + GraphGroup: + type: object + properties: + id: + type: string + label: + type: string + layer: + type: string + enum: [business, application, data, technology, cross-layer] + + # --- Design Entities --- + Capability: + type: object + properties: + capability_id: + type: string + name: + type: string + priority: + type: string + related_value_flows: + type: string + phase: + type: string + + CapabilityDetail: + allOf: + - $ref: "#/components/schemas/Capability" + - type: object + properties: + modules: + type: array + items: + $ref: "#/components/schemas/Module" + value_flows: + type: array + items: + $ref: "#/components/schemas/ValueFlow" + + Module: + type: object + properties: + module_id: + type: string + name: + type: string + layer: + type: string + depends_on: + type: string + capabilities: + type: string + phase: + type: string + + ModuleDetail: + allOf: + - $ref: "#/components/schemas/Module" + - type: object + properties: + owned_entities: + type: array + items: + $ref: "#/components/schemas/Entity" + integrations: + type: array + items: + $ref: "#/components/schemas/Integration" + codebase_alignment: + type: object + nullable: true + properties: + repo_root: + type: string + code_root: + type: string + package_name: + type: string + + Entity: + type: object + properties: + entity_id: + type: string + name: + type: string + domain: + type: string + owner_module: + type: string + + EntityDetail: + allOf: + - $ref: "#/components/schemas/Entity" + - type: object + properties: + data_flows: + type: array + items: + $ref: "#/components/schemas/DataFlow" + + Integration: + type: object + properties: + integration_id: + type: string + source: + type: string + target: + type: string + protocol: + type: string + direction: + type: string + description: + type: string + + ValueFlow: + type: object + properties: + value_flow_id: + type: string + name: + type: string + trigger: + type: string + steps: + type: string + outcome: + type: string + + UserJourney: + type: object + properties: + journey_id: + type: string + name: + type: string + precondition: + type: string + steps: + type: string + postcondition: + type: string + + DataFlow: + type: object + properties: + data_flow_id: + type: string + source: + type: string + target: + type: string + data_content: + type: string + trigger: + type: string + protocol: + type: string + + ExternalSystem: + type: object + properties: + system_id: + type: string + name: + type: string + type: + type: string + protocol: + type: string + + TraceabilityLink: + type: object + properties: + trace_id: + type: string + capability_id: + type: string + module_id: + type: string + entity_ids: + type: string + value_flow_ids: + type: string + + RuntimeComponent: + type: object + properties: + component_id: + type: string + name: + type: string + type: + type: string + technology: + type: string + port: + type: string + + # --- Editor (Phase 2) --- + FileContent: + type: object + properties: + path: + type: string + format: + type: string + enum: [csv, md, yaml, openapi] + content: + type: string + last_modified: + type: string + format: date-time + + SaveFileRequest: + type: object + required: [content] + properties: + content: + type: string + + ImpactResult: + type: object + properties: + source_file: + type: string + affected_files: + type: array + items: + type: object + properties: + path: + type: string + reason: + type: string + + # --- Impl Tracker (Phase 2) --- + ImplProgress: + type: object + properties: + module_id: + type: string + percentage: + type: number + format: float + minimum: 0 + maximum: 100 + source: + type: string + enum: [auto, llm, manual] + evaluated_at: + type: string + format: date-time diff --git a/design/application-architecture/06-codebase-alignment.csv b/design/application-architecture/06-codebase-alignment.csv new file mode 100644 index 0000000..f640687 --- /dev/null +++ b/design/application-architecture/06-codebase-alignment.csv @@ -0,0 +1,10 @@ +module_id,module_name,layer,repo_root,code_root,package_name,api_surface,phase,evolution_note +MOD-PROJECT,项目管理,backend,./backend,app/modules/project,project,/api/projects/*,MVP, +MOD-DESIGN,架构设计领域,backend,./backend,app/modules/design,design,（无直接 API——通过 Scanner/Graph 暴露）,MVP,纯 domain 层为主 +MOD-SCANNER,设计扫描与解析,backend,./backend,app/modules/scanner,scanner,/api/projects/{id}/scan + /api/projects/{id}/entities/*,MVP, +MOD-GRAPH,关系图引擎,backend,./backend,app/modules/graph,graph,/api/projects/{id}/graph/*,MVP, +MOD-EDITOR,文件编辑器,backend,./backend,app/modules/editor,editor,/api/projects/{id}/files/*,Phase2, +MOD-IMPL-TRACKER,实现进度追踪,backend,./backend,app/modules/impl_tracker,impl_tracker,/api/projects/{id}/impl-progress,Phase2, +MOD-FE-PROJECT,前端项目管理,frontend,./frontend,src/modules/project,fe-project,页面: / /project/:id,MVP, +MOD-FE-GRAPH,前端关系图,frontend,./frontend,src/modules/graph,fe-graph,页面: /project/:id/graph,MVP, +MOD-FE-EDITOR,前端编辑器,frontend,./frontend,src/modules/editor,fe-editor,页面: /project/:id/file/:path,Phase2, diff --git a/design/application-architecture/07-module-boundary-rules.md b/design/application-architecture/07-module-boundary-rules.md new file mode 100644 index 0000000..0dd91eb --- /dev/null +++ b/design/application-architecture/07-module-boundary-rules.md @@ -0,0 +1,53 @@ +--- +doc_id: DOC-AA-007 +title: 模块边界规则 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./02a-layered-architecture.md + - ./02-modules.csv +downstream: + - ./06-codebase-alignment.csv +updated_at: 2026-03-23 +--- + +# 模块边界规则 + +## 1. 跨模块依赖规则 + +### 允许的依赖方向 +- MOD-SCANNER → MOD-DESIGN（Scanner 生成 Design 实体，调用 Design 约束规则） +- MOD-GRAPH → MOD-DESIGN（Graph 读取 Design 实体转换为图结构） +- MOD-EDITOR → MOD-DESIGN, MOD-SCANNER, MOD-GRAPH（Phase 2） +- MOD-IMPL-TRACKER → MOD-DESIGN, MOD-SCANNER（Phase 2） + +### 禁止的依赖 +- MOD-DESIGN 不依赖任何其他业务模块（它是被依赖的核心） +- MOD-PROJECT 不依赖其他业务模块（独立管理项目元数据） +- MOD-GRAPH 不直接读文件系统（通过 Design 实体获取数据） +- 前端模块之间不直接调用（通过 Pinia store 或事件通信） + +## 2. 数据边界 + +- 每个模块只通过 domain 层的公共接口暴露数据 +- 模块间传递的是 domain 实体或其 DTO，不是原始文件内容 +- MOD-DESIGN 的实体是跨模块共享的"通用语言" + +## 3. 反模式清单 + +| 反模式 | 说明 | +|--------|------| +| Scanner 包含业务规则 | 业务规则（如"capability 必须关联 module"）属于 MOD-DESIGN | +| Graph 直接读文件 | Graph 应该从 Design 实体构建图，不应该自己解析文件 | +| Editor 绕过 Scanner 修改文件 | 修改后必须触发重新扫描保证数据一致 | +| Domain 层引入框架依赖 | domain 层纯 Python，不导入 FastAPI/Pydantic/SQLAlchemy 等 | +| 前端组件硬编码 API 地址 | API 调用封装在模块的 api/ 目录，组件通过 composables 调用 | +| 前端模块间直接 import 组件 | 通过 shared/ 或事件通信 | + +## 4. 演进策略 + +- MVP 阶段 MOD-DESIGN 是被动的纯模型库 +- Phase 2 可以在 MOD-DESIGN 中增加更复杂的校验服务（如跨文件一致性检查） +- 如果 MOD-SCANNER 变得过大，可以按文件类型拆分（csv-parser、md-parser、yaml-parser），但保持在 Scanner 的 infrastructure 层内 diff --git a/design/application-architecture/README.md b/design/application-architecture/README.md new file mode 100644 index 0000000..ae9d937 --- /dev/null +++ b/design/application-architecture/README.md @@ -0,0 +1,43 @@ +# Application Architecture + +回答的问题： +- 系统边界在哪里？ +- 系统级逻辑架构如何分层？ +- 模块/服务内部如何分层？ +- 模块怎么拆？ +- 模块之间如何依赖？ +- 与哪些外部系统集成？ +- 哪些接口是关键协作契约？ +- 如何与代码仓库结构对齐？ + +## 本目录产出 +- [01-system-context.md](./01-system-context.md) +- [01-external-systems.csv](./01-external-systems.csv) +- [02a-layered-architecture.md](./02a-layered-architecture.md) +- [02b-solution-layering.md](./02b-solution-layering.md) +- [02-modules.csv](./02-modules.csv) +- [03-integrations.csv](./03-integrations.csv) +- [04-api-contracts.openapi.yaml](./04-api-contracts.openapi.yaml) +- [06-codebase-alignment.csv](./06-codebase-alignment.csv) +- [07-module-boundary-rules.md](./07-module-boundary-rules.md) +- [adr/ADR-000-template.md](./adr/ADR-000-template.md) + +## 依赖 +- 依赖 [`../business-architecture/02-capability-map.csv`](../business-architecture/02-capability-map.csv) +- 依赖 [`../business-architecture/03-value-flows.csv`](../business-architecture/03-value-flows.csv) +- 依赖 [`../business-architecture/04-user-journeys.csv`](../business-architecture/04-user-journeys.csv) +- 相关领域设计来自 `../domains//` + +## 输出给 +- [`../data-architecture/01-entities.csv`](../data-architecture/01-entities.csv) +- [`../technology-architecture/01-runtime-topology.md`](../technology-architecture/01-runtime-topology.md) +- [`../technology-architecture/01-runtime-components.csv`](../technology-architecture/01-runtime-components.csv) + +## 最小实践要求 +- 至少有 1 张系统上下文图 +- 如需要表达系统整体层次，补 1 页系统级分层架构图 +- 如存在明确代码/逻辑分层，补 1 页模块内技术分层说明 +- 至少列出模块职责、owner、依赖关系 +- 至少列出关键外部集成 +- 正式交付开发前补 `06-codebase-alignment.csv` 与 `07-module-boundary-rules.md` +- 表格型数据使用 CSV，不用 Markdown 表格 diff --git a/design/application-architecture/adr/ADR-000-template.md b/design/application-architecture/adr/ADR-000-template.md new file mode 100644 index 0000000..9f8d9dd --- /dev/null +++ b/design/application-architecture/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 应用架构决策模板 + +- Status: draft +- Date: 2026-03-23 +- Scope: application-architecture +- Deciders: architect, tech-lead + +## Context +本决策涉及哪些系统边界、模块边界、接口协作、代码分层或代码仓库落地问题？ + +## Decision +最终应用架构决策是什么？ + +## Consequences +会影响哪些模块、接口、集成、开发边界或代码目录？ diff --git a/design/business-architecture/01-scope-and-goals.md b/design/business-architecture/01-scope-and-goals.md new file mode 100644 index 0000000..e6687c4 --- /dev/null +++ b/design/business-architecture/01-scope-and-goals.md @@ -0,0 +1,67 @@ +--- +doc_id: DOC-BA-001 +title: 范围与目标 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: [] +downstream: + - ./02-capability-map.csv + - ./03-value-flows.csv + - ./04-user-journeys.csv +updated_at: 2026-03-23 +--- + +# 范围与目标 + +## 项目名称 + +Arch Design Dashboard + +## 核心问题 + +管理架构设计过程中： +1. 看不清设计进度——不知道设计到哪一步了，哪些做完了哪些没做 +2. 理不清关系——设计文档之间的依赖关系不清晰，改了一个不知道影响哪些 + +## 用户 + +单人使用（林然）。设计产出给 AI agent 用于写代码。 + +## 核心功能 + +1. **多项目管理**：支持多个项目切换 +2. **可下钻的多层关系图**： + - 全景层：四大架构 + 跨架构的设计部件依赖链（capability → module → entity → runtime component） + - 架构层：展开某个架构看内部设计文档和关系 + - 对象层：展开某个设计对象看详情 + - 代码层：关联到实际代码结构 + 实现进度 +3. **设计进度追踪**：每个文档/节点有完成状态，在图上以颜色体现 +4. **实现进度追踪**：自动扫描代码目录结构 + LLM 辅助评估模块完成度 + 手动覆盖 +5. **影响分析**：改一个文档时，能看到哪些下游需要同步更新 +6. **在线编辑**：直接在 dashboard 里编辑 CSV 和 Markdown + +## 关键约束 + +- 完全围绕 `minimal-design-template` 目录结构工作 +- 如果发现模板不足，先改模板再改工具 +- Web 界面（浏览器访问） +- 服务器部署，Docker 支持 +- 单人使用，无需多用户认证 + +## 目标（Goals） + +1. 让架构设计的进度一眼可见，不需要翻文件夹猜 +2. 让设计部件之间的关系可视化、可下钻，从全景到代码 +3. 让实现进度和设计进度对应起来，知道设计了但没实现的是什么 +4. 让修改一处设计时，影响范围立即可见 +5. 支持在浏览器中直接编辑设计文件 + +## 非目标（Non-Goals） + +1. 不做协作功能（多用户同时编辑、权限管理） +2. 不做设计内容的自动生成（那是 arch-design-agent skill 的事） +3. 不做代码生成或代码审查 +4. 不做版本控制（Git 已经在做这件事） +5. 不做通知/提醒系统 diff --git a/design/business-architecture/02-capability-map.csv b/design/business-architecture/02-capability-map.csv new file mode 100644 index 0000000..944acca --- /dev/null +++ b/design/business-architecture/02-capability-map.csv @@ -0,0 +1,11 @@ +capability_id,capability_name,description,priority,phase,related_value_flows +CAP-PROJ-REG,项目注册与切换,注册新项目路径并在多个项目间切换,must,MVP,VF-01 +CAP-SCAN,设计扫描解析,扫描设计目录解析所有 CSV/MD/YAML 文件为结构化数据,must,MVP,VF-02 +CAP-GAP,完成度检测,检测设计文件状态（missing/sparse/placeholder/template-residue/ok）,must,MVP,VF-02 +CAP-GRAPH-PANORAMA,全景关系图,跨架构的部件依赖链分组可视化（capability→module→entity→runtime component）,must,MVP,VF-03 +CAP-GRAPH-DRILL,关系图下钻,点击节点展开下一层细节（架构层→对象层→代码层）,must,MVP,VF-03 +CAP-PROGRESS-DESIGN,设计进度追踪,每个文档/节点的完成状态在图上以颜色体现,must,MVP,VF-02 VF-03 +CAP-GRAPH-IMPACT,影响分析,选中一个节点高亮所有受影响的下游文档和对象,should,Phase2,VF-04 +CAP-PROGRESS-IMPL,实现进度追踪,扫描代码目录结构 + LLM 辅助评估模块完成度 + 手动覆盖,should,Phase2,VF-05 +CAP-EDIT-CSV,CSV 表格编辑,在 dashboard 中直接编辑 CSV 格式的设计文件,should,Phase2,VF-06 +CAP-EDIT-MD,Markdown 编辑,在 dashboard 中直接编辑 Markdown 格式的设计文件,should,Phase2,VF-06 diff --git a/design/business-architecture/03-value-flows.csv b/design/business-architecture/03-value-flows.csv new file mode 100644 index 0000000..2b519f6 --- /dev/null +++ b/design/business-architecture/03-value-flows.csv @@ -0,0 +1,7 @@ +value_flow_id,value_flow_name,trigger,actor,steps,outcome,phase,related_capabilities +VF-01,注册项目,用户有新项目要管理,林然,输入项目路径→系统检测 design/ 目录→注册成功,项目可在 dashboard 中使用,MVP,CAP-PROJ-REG +VF-02,查看设计进度,用户想知道设计做到哪了,林然,选择项目→系统扫描 design/→显示全景图+各节点完成状态,一眼看到设计进度全貌,MVP,CAP-SCAN CAP-GAP CAP-PROGRESS-DESIGN +VF-03,探索关系,用户想理清某个部件的关系,林然,在全景图点击节点→下钻看细节→看到上下游依赖链,理清设计部件间的依赖关系,MVP,CAP-GRAPH-PANORAMA CAP-GRAPH-DRILL +VF-04,分析影响,用户准备改某个设计,林然,选中文档→系统高亮所有受影响的下游,改设计前知道影响范围,Phase2,CAP-GRAPH-IMPACT +VF-05,追踪实现进度,用户想知道代码做到哪了,林然,系统扫描代码目录+LLM评估→在模块图上显示完成百分比,知道设计了但没实现的是什么,Phase2,CAP-PROGRESS-IMPL +VF-06,在线编辑,用户在图上看到某个文档需要改,林然,点击编辑→CSV/MD编辑器→保存,直接在 dashboard 里修改设计文件,Phase2,CAP-EDIT-CSV CAP-EDIT-MD diff --git a/design/business-architecture/04-user-journeys.csv b/design/business-architecture/04-user-journeys.csv new file mode 100644 index 0000000..342c64c --- /dev/null +++ b/design/business-architecture/04-user-journeys.csv @@ -0,0 +1,5 @@ +journey_id,journey_name,actor,precondition,steps,postcondition,phase,related_value_flows +UJ-01,首次使用——从零到看到全景图,林然,dashboard 已部署运行,"1.打开dashboard→2.点击添加项目→3.输入项目名称和路径→4.系统自动扫描design/→5.跳转全景关系图→6.看到四大架构分组+部件节点+依赖连线→7.节点颜色显示完成状态→8.点击节点下钻看模块列表和依赖→9.继续点击看关联的capability/entity/代码目录",用户对设计进度和关系有全局了解,MVP,VF-01 VF-02 VF-03 +UJ-02,日常查看——打开已有项目看进度,林然,项目已注册,"1.打开dashboard→2.选择已有项目→3.系统重新扫描design/→4.全景图刷新→5.查看各节点最新状态→6.发现某节点变红→7.点击查看具体问题",及时发现设计中的问题和进度变化,MVP,VF-02 VF-03 +UJ-03,影响分析——改设计前看影响范围,林然,项目已注册且有设计内容,"1.在全景图中找到要修改的文档→2.选中该节点→3.系统高亮所有下游受影响节点→4.评估影响范围→5.决定是否继续修改",改设计前知道会影响什么,Phase2,VF-04 +UJ-04,在线编辑——直接修改设计文件,林然,项目已注册且有设计内容,"1.在图上点击某个文档节点→2.点击编辑→3.打开CSV表格编辑器或Markdown编辑器→4.修改内容→5.保存→6.系统重新扫描并刷新图",不需要切换到其他编辑器就能修改设计,Phase2,VF-06 diff --git a/design/business-architecture/README.md b/design/business-architecture/README.md new file mode 100644 index 0000000..bbe1127 --- /dev/null +++ b/design/business-architecture/README.md @@ -0,0 +1,29 @@ +# Business Architecture + +回答的问题： +- 为什么做这个项目？ +- 本期做什么，不做什么？ +- 核心业务能力是什么？ +- 核心流程如何流转？ +- 关键用户路径是什么？ +- 哪些业务决策需要 ADR？ + +## 本目录产出 +- [01-scope-and-goals.md](./01-scope-and-goals.md) +- [02-capability-map.csv](./02-capability-map.csv) +- [03-value-flows.csv](./03-value-flows.csv) +- [04-user-journeys.csv](./04-user-journeys.csv) +- [adr/ADR-000-template.md](./adr/ADR-000-template.md) + +## 依赖与输出 +- 先完成 `01-scope-and-goals.md` +- `02-capability-map.csv` 输出给 [`../application-architecture/02-modules.csv`](../application-architecture/02-modules.csv) +- `03-value-flows.csv` 输出给 [`../application-architecture/03-integrations.csv`](../application-architecture/03-integrations.csv) +- `04-user-journeys.csv` 输出给 [`../application-architecture/04-api-contracts.openapi.yaml`](../application-architecture/04-api-contracts.openapi.yaml) +- 全局业务决策可放 `../adr/`，业务层局部 ADR 放 `./adr/` + +## 最小实践要求 +- 只保留 1~2 条主流程 +- 能力地图做到一级/二级即可 +- 只保留核心角色的旅程 +- 表格型数据使用 CSV，不用 Markdown 表格 diff --git a/design/business-architecture/adr/ADR-000-template.md b/design/business-architecture/adr/ADR-000-template.md new file mode 100644 index 0000000..68ac5db --- /dev/null +++ b/design/business-architecture/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 业务架构决策模板 + +- Status: draft +- Date: 2026-03-23 +- Scope: business-architecture +- Deciders: business-owner, architect + +## Context +本业务决策要解决什么范围、角色、流程或能力问题？ + +## Decision +最终业务边界或业务规则决策是什么？ + +## Consequences +会影响哪些能力、旅程、价值流？ diff --git a/design/change-log.csv b/design/change-log.csv new file mode 100644 index 0000000..101e229 --- /dev/null +++ b/design/change-log.csv @@ -0,0 +1,4 @@ +change_id,date,author,scope,description,affected_files,related_adr +CHG-001,2026-03-23,林然,全部,初始设计——按新流程逐步讨论确认,所有文件, +CHG-002,2026-03-23,林然,application-architecture,新增 MOD-DESIGN 模块——将设计领域实体和业务规则从 MOD-SCANNER 分离,02-modules.csv 03-integrations.csv 02a-layered-architecture.md 06-codebase-alignment.csv 07-module-boundary-rules.md, +CHG-003,2026-03-23,林然,data-architecture,实体扩展至 39 个——覆盖 minimal-design-template 所有设计文件类型,01-entities.csv, diff --git a/design/change-request-template.md b/design/change-request-template.md new file mode 100644 index 0000000..dd41d71 --- /dev/null +++ b/design/change-request-template.md @@ -0,0 +1,37 @@ +# Change Request Template + +## 1. 基本信息 +- 变更标题： +- 提出人： +- 日期： +- 紧急程度：高 / 中 / 低 + +## 2. 变更内容 +- 要改什么： +- 为什么改： +- 不改的风险： + +## 3. 初步影响范围 +- 业务架构： +- 领域目录： +- 应用架构： +- 数据架构： +- 技术架构： +- 代码仓库结构： + +## 4. 需要更新的文档（示例） +- `design/business-architecture/` +- `design/domains//` +- `design/application-architecture/` +- `design/data-architecture/` +- `design/technology-architecture/` +- `design/traceability.csv` +- `design/change-log.csv` +- 相关 ADR 目录 + +## 5. 处理建议 +1. 先用 `traceability.csv` 做影响分析 +2. 判断是否涉及新的 domain / module / entity / runtime component +3. 必要时补对应层级的 ADR +4. 更新结构化 CSV 文件与说明性 Markdown +5. 更新 `change-log.csv` diff --git a/design/data-architecture/01-entities.csv b/design/data-architecture/01-entities.csv new file mode 100644 index 0000000..9c00db3 --- /dev/null +++ b/design/data-architecture/01-entities.csv @@ -0,0 +1,40 @@ +entity_id,entity_name,domain,owner_module,description,phase,source_file +ENT-SCOPE-AND-GOALS,范围与目标,business,MOD-DESIGN,项目范围边界和目标定义,MVP,business-architecture/01-scope-and-goals.md +ENT-CAPABILITY,能力,business,MOD-DESIGN,业务能力项（ID/名称/优先级/关联价值流）,MVP,business-architecture/02-capability-map.csv +ENT-VALUE-FLOW,价值流,business,MOD-DESIGN,用户价值实现链路（触发→步骤→结果）,MVP,business-architecture/03-value-flows.csv +ENT-USER-JOURNEY,用户旅程,business,MOD-DESIGN,用户完整操作路径,MVP,business-architecture/04-user-journeys.csv +ENT-SYSTEM-CONTEXT,系统上下文,application,MOD-DESIGN,系统边界和外部交互描述,MVP,application-architecture/01-system-context.md +ENT-EXTERNAL-SYSTEM,外部系统,application,MOD-DESIGN,与系统交互的外部系统,MVP,application-architecture/01-external-systems.csv +ENT-SOLUTION-LAYER,逻辑分层,application,MOD-DESIGN,系统级逻辑分层定义,MVP,application-architecture/02b-solution-layering.md +ENT-MODULE,功能模块,application,MOD-DESIGN,系统功能模块（ID/名称/层/依赖/能力）,MVP,application-architecture/02-modules.csv +ENT-INTEGRATION,集成关系,application,MOD-DESIGN,模块间和模块与外部的集成,MVP,application-architecture/03-integrations.csv +ENT-API-CONTRACT,API 契约,application,MOD-DESIGN,REST API 接口定义,MVP,application-architecture/04-api-contracts.openapi.yaml +ENT-CODEBASE-ALIGNMENT,代码映射,application,MOD-DESIGN,模块到代码目录的映射,MVP,application-architecture/06-codebase-alignment.csv +ENT-MODULE-BOUNDARY-RULE,边界规则,application,MOD-DESIGN,模块间依赖和通信规则,MVP,application-architecture/07-module-boundary-rules.md +ENT-ENTITY,数据实体,data,MOD-DESIGN,系统数据实体定义（ID/名称/owner）,MVP,data-architecture/01-entities.csv +ENT-DATA-FLOW,数据流,data,MOD-DESIGN,数据在系统中的流动路径,MVP,data-architecture/02-data-flows.csv +ENT-DATA-SECURITY,数据安全,data,MOD-DESIGN,数据敏感度分级和保护策略,MVP,data-architecture/03-data-security.csv +ENT-TECH-SELECTION,技术选型,technology,MOD-DESIGN,技术栈选择及理由,MVP,technology-architecture/00-technology-selection.csv +ENT-RUNTIME-TOPOLOGY,运行拓扑,technology,MOD-DESIGN,系统运行时部署拓扑,MVP,technology-architecture/01-runtime-topology.md +ENT-RUNTIME-COMPONENT,运行组件,technology,MOD-DESIGN,运行时组件定义,MVP,technology-architecture/01-runtime-components.csv +ENT-ENVIRONMENT,环境,technology,MOD-DESIGN,部署环境定义,MVP,technology-architecture/02-environments.csv +ENT-OPERATIONAL-BASELINE,运维基线,technology,MOD-DESIGN,运维监控和告警基线,MVP,technology-architecture/03-operational-baseline.md +ENT-RELEASE-PLAN,发布计划,technology,MOD-DESIGN,发布和回滚策略,MVP,technology-architecture/04-release-and-rollback.md +ENT-TRACEABILITY-LINK,追溯关系,cross-layer,MOD-DESIGN,capability→module→entity 追溯链,MVP,traceability.csv +ENT-CHANGE-LOG-ENTRY,变更记录,cross-layer,MOD-DESIGN,设计变更历史,MVP,change-log.csv +ENT-ADR,架构决策,cross-layer,MOD-DESIGN,架构决策记录,MVP,adr/ +ENT-DESIGN-DOC,设计文档元数据,cross-layer,MOD-DESIGN,非结构化 MD 文件的 frontmatter 元数据,MVP,各 .md 文件 +ENT-SHARED-TERM,共享术语,domain,MOD-DESIGN,跨领域共享术语定义,MVP,domains/_shared/01-shared-terminology.csv +ENT-DOMAIN,领域,domain,MOD-DESIGN,业务领域定义,MVP,domains//01-domain-overview.md +ENT-UBIQUITOUS-TERM,领域术语,domain,MOD-DESIGN,领域内统一语言术语,MVP,domains//02-ubiquitous-language.csv +ENT-SCENARIO,场景与流程,domain,MOD-DESIGN,领域场景和业务流程,MVP,domains//03-scenarios-and-flows.csv +ENT-DOMAIN-MODULE,领域模块,domain,MOD-DESIGN,领域内模块划分,MVP,domains//04-domain-modules.csv +ENT-DOMAIN-ENTITY,领域实体,domain,MOD-DESIGN,领域内实体定义,MVP,domains//05-domain-entities.csv +ENT-PROJECT,项目,dashboard,MOD-PROJECT,Dashboard 管理的项目（ID/名称/路径/创建时间）,MVP,~/.arch-design-dashboard/projects.json +ENT-GRAPH-NODE,图节点,dashboard,MOD-GRAPH,关系图中的节点（类型/ID/标签/状态/分组）,MVP,运行时构建 +ENT-GRAPH-EDGE,图边,dashboard,MOD-GRAPH,关系图中的边（source/target/关系类型）,MVP,运行时构建 +ENT-GRAPH-VIEW,图视图,dashboard,MOD-GRAPH,完整图视图（nodes+edges+groups）,MVP,运行时构建 +ENT-SCAN-RESULT,扫描结果,dashboard,MOD-SCANNER,一次扫描的完整输出,MVP,运行时构建 +ENT-IMPL-PROGRESS,实现进度,dashboard,MOD-IMPL-TRACKER,模块实现完成百分比（auto/llm/manual）,Phase2,运行时构建 +ENT-EDITABLE-FILE,可编辑文件,dashboard,MOD-EDITOR,可编辑的设计文件（路径/格式/内容）,Phase2,运行时构建 +ENT-IMPACT-RESULT,影响分析结果,dashboard,MOD-EDITOR,修改一个文件后的下游影响列表,Phase2,运行时构建 diff --git a/design/data-architecture/02-data-flows.csv b/design/data-architecture/02-data-flows.csv new file mode 100644 index 0000000..0e52b25 --- /dev/null +++ b/design/data-architecture/02-data-flows.csv @@ -0,0 +1,9 @@ +data_flow_id,source,target,data_content,trigger,protocol,phase,description +DF-01,EXT-FS-DESIGN,MOD-SCANNER → MOD-DESIGN,设计文件原始内容,用户触发扫描或打开项目,file I/O + function call,MVP,读取 design/ 下所有文件并解析为 28 种 Design 实体 + 约束校验 +DF-02,MOD-DESIGN 实体,MOD-GRAPH,Capability/Module/Entity/TraceabilityLink 等,扫描完成后,function call,MVP,将 Design 实体转换为 GraphNode/GraphEdge/GraphGroup 构建 GraphView +DF-03,MOD-GRAPH,MOD-FE-GRAPH,GraphView（nodes+edges+groups JSON）,前端请求关系图,REST API,MVP,前端获取关系图数据用于渲染 +DF-04,MOD-SCANNER,MOD-FE-GRAPH,ScanResult（文件列表+完成度+结构化数据 JSON）,前端请求扫描结果,REST API,MVP,前端获取扫描结果用于状态展示 +DF-05,MOD-FE-PROJECT,MOD-PROJECT → EXT-FS-REGISTRY,Project（名称/路径）,用户注册新项目,REST API + JSON write,MVP,项目信息持久化到 projects.json +DF-06,MOD-FE-EDITOR → MOD-EDITOR,EXT-FS-DESIGN → MOD-SCANNER → MOD-GRAPH,文件修改内容,用户保存编辑,REST API + file I/O + function call,Phase2,写文件→重新扫描→重建图 +DF-07,MOD-EDITOR,MOD-FE-GRAPH,ImpactResult（受影响文件列表+原因链）,用户请求影响分析,REST API,Phase2,读取 upstream/downstream + TraceabilityLink 计算影响范围 +DF-08,EXT-FS-CODE + EXT-LLM,MOD-IMPL-TRACKER,代码目录结构 + LLM 评估结果,用户触发实现进度评估,file I/O + HTTP API,Phase2,扫描代码目录对照 Design 的 Module/CodebaseAlignment + LLM 评估得出 ImplProgress diff --git a/design/data-architecture/03-data-security.csv b/design/data-architecture/03-data-security.csv new file mode 100644 index 0000000..582ac3c --- /dev/null +++ b/design/data-architecture/03-data-security.csv @@ -0,0 +1,6 @@ +security_id,data_category,sensitivity,entities,protection_strategy,notes +SEC-01,设计文件内容,低,ENT-CAPABILITY ENT-MODULE ENT-ENTITY ENT-VALUE-FLOW ENT-USER-JOURNEY ENT-INTEGRATION ENT-DATA-FLOW ENT-DESIGN-DOC ENT-TRACEABILITY-LINK ENT-CHANGE-LOG-ENTRY ENT-ADR ENT-SHARED-TERM ENT-DOMAIN ENT-UBIQUITOUS-TERM ENT-SCENARIO ENT-DOMAIN-MODULE ENT-DOMAIN-ENTITY ENT-SCOPE-AND-GOALS ENT-SYSTEM-CONTEXT ENT-SOLUTION-LAYER ENT-API-CONTRACT ENT-CODEBASE-ALIGNMENT ENT-MODULE-BOUNDARY-RULE ENT-DATA-SECURITY ENT-TECH-SELECTION ENT-RUNTIME-TOPOLOGY ENT-RUNTIME-COMPONENT ENT-ENVIRONMENT ENT-OPERATIONAL-BASELINE ENT-RELEASE-PLAN ENT-EXTERNAL-SYSTEM,无特殊保护（本身是给 AI agent 和团队看的公开设计文档）,通过网络隔离保护 +SEC-02,关系图和扫描结果,低,ENT-GRAPH-NODE ENT-GRAPH-EDGE ENT-GRAPH-VIEW ENT-SCAN-RESULT,无特殊保护（运行时派生数据）,从设计文件实时计算无需持久化保护 +SEC-03,项目注册信息,中,ENT-PROJECT,文件路径不暴露在前端 URL 中（前端用项目 ID 后端查路径）,包含本地文件路径泄露可能暴露服务器目录结构 +SEC-04,代码仓库路径,中,ENT-IMPL-PROGRESS ENT-EDITABLE-FILE,同 SEC-03（路径不暴露到前端）,Phase2 +SEC-05,LLM API 密钥,高,,存服务器环境变量不通过 API 返回不写入设计文件,Phase2 diff --git a/design/data-architecture/README.md b/design/data-architecture/README.md new file mode 100644 index 0000000..65013ba --- /dev/null +++ b/design/data-architecture/README.md @@ -0,0 +1,29 @@ +# Data Architecture + +回答的问题： +- 核心数据对象是什么？ +- 谁负责写入和维护？ +- 数据如何在模块之间流动？ +- 哪些数据敏感，需要特别保护？ +- 哪些数据决策需要 ADR？ + +## 本目录产出 +- [01-entities.csv](./01-entities.csv) +- [02-data-flows.csv](./02-data-flows.csv) +- [03-data-security.csv](./03-data-security.csv) +- [adr/ADR-000-template.md](./adr/ADR-000-template.md) + +## 依赖 +- 依赖 [`../business-architecture/02-capability-map.csv`](../business-architecture/02-capability-map.csv) +- 依赖 [`../application-architecture/02-modules.csv`](../application-architecture/02-modules.csv) +- 依赖 [`../application-architecture/03-integrations.csv`](../application-architecture/03-integrations.csv) +- 领域内实体可同步维护在 `../domains//05-domain-entities.csv` + +## 输出给 +- [`../technology-architecture/03-operational-baseline.md`](../technology-architecture/03-operational-baseline.md) + +## 最小实践要求 +- 至少列出核心实体与 owner +- 至少列出关键状态字段 +- 至少列出敏感数据级别 +- 表格型数据使用 CSV，不用 Markdown 表格 diff --git a/design/data-architecture/adr/ADR-000-template.md b/design/data-architecture/adr/ADR-000-template.md new file mode 100644 index 0000000..b38519c --- /dev/null +++ b/design/data-architecture/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 数据架构决策模板 + +- Status: draft +- Date: 2026-03-23 +- Scope: data-architecture +- Deciders: data-owner, architect + +## Context +本决策涉及哪些实体、数据流、一致性或安全约束？ + +## Decision +最终数据架构决策是什么？ + +## Consequences +会影响哪些实体 owner、接口或运行控制？ diff --git a/design/domains/README.md b/design/domains/README.md new file mode 100644 index 0000000..6d2859c --- /dev/null +++ b/design/domains/README.md @@ -0,0 +1,20 @@ +# 领域目录 + +## 领域列表 + +| 领域 | 目录 | 核心模块 | Phase | +|------|------|----------|-------| +| 架构设计 | `design/` | MOD-DESIGN | MVP | +| 扫描 | `scanning/` | MOD-SCANNER | MVP | +| 关系图 | `graph/` | MOD-GRAPH | MVP | +| 项目管理 | `project/` | MOD-PROJECT | MVP | +| 编辑 | `editing/` | MOD-EDITOR | Phase 2 | +| 实现追踪 | `impl-tracking/` | MOD-IMPL-TRACKER | Phase 2 | + +## 共享 + +- `_shared/01-shared-terminology.csv` — 跨领域共享术语（待填充） + +## 模板 + +- `_template/` — 新领域目录的模板 diff --git a/design/domains/_shared/01-shared-terminology.csv b/design/domains/_shared/01-shared-terminology.csv new file mode 100644 index 0000000..e74137e --- /dev/null +++ b/design/domains/_shared/01-shared-terminology.csv @@ -0,0 +1,13 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-S-001,设计文件,Design File,DesignFile,cross-domain,minimal-design-template 目录下的 CSV/MD/YAML/OpenAPI 文件,设计文档(指文件时),,MOD-DESIGN MOD-SCANNER MOD-EDITOR,ENT-DESIGN-DOC ENT-EDITABLE-FILE,与"设计实体"区分：文件是物理载体 实体是解析后的结构化对象 +TERM-S-002,设计实体,Design Entity,DesignEntity,cross-domain,从设计文件解析出的结构化对象（Capability/Module/Entity 等）,,设计文件(指实体而非文件时),MOD-DESIGN MOD-SCANNER MOD-GRAPH,所有 ENT-* 实体, +TERM-S-003,文件状态,File Status,FileStatus,cross-domain,设计文件的完成度评估结果：ok/sparse/missing/template-residue/placeholder-heavy,完成状态,文件质量,MOD-DESIGN MOD-SCANNER,ENT-SCAN-RESULT, +TERM-S-004,架构层,Architecture Layer,ArchitectureLayer,cross-domain,四大架构分类之一：业务(business)/应用(application)/数据(data)/技术(technology),,架构类型,MOD-DESIGN MOD-GRAPH,ENT-GRAPH-GROUP, +TERM-S-005,模块层,Module Layer,ModuleLayer,cross-domain,代码分层：domain/application/infrastructure/interfaces,,代码层,MOD-DESIGN,ENT-CODEBASE-ALIGNMENT, +TERM-S-006,扫描,Scan,,cross-domain,遍历 design/ 目录、解析所有设计文件、产出 ScanResult 的完整过程,全量扫描,检查(泛指时),MOD-SCANNER MOD-FE-GRAPH,ENT-SCAN-RESULT, +TERM-S-007,追溯链,Traceability Link,TraceabilityLink,cross-domain,capability→module→entity 的端到端关联关系,追溯关系,依赖关系(不同概念),MOD-DESIGN MOD-GRAPH,ENT-TRACEABILITY-LINK, +TERM-S-008,模板残留,Template Residue,,cross-domain,从模板复制但未适配为项目特定内容的数据（比空文件更严重）,残留数据,示例数据(当指残留时),MOD-DESIGN MOD-SCANNER,, +TERM-S-009,下钻,Drill-down,,cross-domain,在关系图中点击节点展开下一层细节的交互,展开|深入,,MOD-GRAPH MOD-FE-GRAPH,ENT-GRAPH-NODE, +TERM-S-010,项目,Project,Project,cross-domain,Dashboard 管理的一个架构设计项目（名称+设计目录路径+可选代码目录路径）,设计项目,,MOD-PROJECT MOD-FE-PROJECT,ENT-PROJECT, +TERM-S-011,影响分析,Impact Analysis,ImpactResult,cross-domain,修改一个设计文件后计算所有下游受影响文件的分析过程（Phase 2）,影响范围,依赖分析(不同概念),MOD-EDITOR MOD-FE-GRAPH,ENT-IMPACT-RESULT, +TERM-S-012,实现进度,Implementation Progress,ImplProgress,cross-domain,一个模块的代码实现完成百分比及其评估来源（auto/llm/manual）（Phase 2）,完成度|实现状态,设计进度(不同概念),MOD-IMPL-TRACKER,ENT-IMPL-PROGRESS, diff --git a/design/domains/_template/01-domain-overview.md b/design/domains/_template/01-domain-overview.md new file mode 100644 index 0000000..6523ef6 --- /dev/null +++ b/design/domains/_template/01-domain-overview.md @@ -0,0 +1,27 @@ +--- +doc_id: DOC-DOM-001 +title: 领域概览 +version: 0.1.0 +status: draft +owners: + - domain-owner +updated_at: 2026-03-23 +--- + +# 领域概览 + +## 1. 领域名称 +- 领域名： +- 一句话职责： + +## 2. In scope / Out of scope +- In scope： +- Out of scope： + +## 3. 核心角色 +- 角色 1： +- 角色 2： + +## 4. 核心痛点 / 约束 +- 痛点 1： +- 约束 1： diff --git a/design/domains/_template/02-ubiquitous-language.csv b/design/domains/_template/02-ubiquitous-language.csv new file mode 100644 index 0000000..6653cc6 --- /dev/null +++ b/design/domains/_template/02-ubiquitous-language.csv @@ -0,0 +1,2 @@ +term_id,term,english_term,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,code_symbol,notes +TERM-001,,, ,,,, ,,, diff --git a/design/domains/_template/03-scenarios-and-flows.csv b/design/domains/_template/03-scenarios-and-flows.csv new file mode 100644 index 0000000..1a6c23b --- /dev/null +++ b/design/domains/_template/03-scenarios-and-flows.csv @@ -0,0 +1,2 @@ +scenario_id,scenario_name,trigger,primary_actor,steps,outcome,exceptions,cross_domain_handoffs,related_modules +SCN-001,,,,,,,, diff --git a/design/domains/_template/04-domain-modules.csv b/design/domains/_template/04-domain-modules.csv new file mode 100644 index 0000000..6178d28 --- /dev/null +++ b/design/domains/_template/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,module_type,owner,responsibilities,depends_on,related_entities,public_interfaces,notes +MOD-001,,,,,,,, diff --git a/design/domains/_template/05-domain-entities.csv b/design/domains/_template/05-domain-entities.csv new file mode 100644 index 0000000..20367cf --- /dev/null +++ b/design/domains/_template/05-domain-entities.csv @@ -0,0 +1,2 @@ +entity_id,entity_name,owner_module,description,key_fields,lifecycle_states,sensitive_level,notes +ENT-001,,,,,,, diff --git a/design/domains/_template/06-domain-decisions.md b/design/domains/_template/06-domain-decisions.md new file mode 100644 index 0000000..4f0d8ba --- /dev/null +++ b/design/domains/_template/06-domain-decisions.md @@ -0,0 +1,16 @@ +--- +doc_id: DOC-DOM-006 +title: 领域局部决策 +version: 0.1.0 +status: draft +owners: + - domain-owner +updated_at: 2026-03-23 +--- + +# 领域局部决策 + +- 决策 1： +- 原因： +- 影响： +- 是否需要升级为 ADR： diff --git a/design/domains/_template/07-codebase-mapping.csv b/design/domains/_template/07-codebase-mapping.csv new file mode 100644 index 0000000..c3ec237 --- /dev/null +++ b/design/domains/_template/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,module_name,repo_root,code_path,package_or_namespace,deployable_unit,notes +MOD-001,,,,,, diff --git a/design/domains/_template/adr/ADR-000-template.md b/design/domains/_template/adr/ADR-000-template.md new file mode 100644 index 0000000..bb2b5ad --- /dev/null +++ b/design/domains/_template/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 领域决策模板 + +- Status: draft +- Date: 2026-03-23 +- Scope: domain +- Deciders: domain-owner, architect + +## Context +本决策涉及哪些术语、领域边界、场景或领域模块问题？ + +## Decision +最终领域决策是什么？ + +## Consequences +会影响哪些领域对象、模块、集成或代码落位？ diff --git a/design/domains/design/01-domain-overview.md b/design/domains/design/01-domain-overview.md new file mode 100644 index 0000000..6d6802e --- /dev/null +++ b/design/domains/design/01-domain-overview.md @@ -0,0 +1,25 @@ +# 架构设计领域（Design） + +## 职责 + +定义 `minimal-design-template` 中所有设计文件对应的实体模型、值对象、约束规则。是整个系统的核心领域，被其他所有业务模块依赖。 + +## 核心概念 + +- 28 种设计实体（Capability、Module、Entity、ValueFlow、UserJourney、Integration、DataFlow、TraceabilityLink、DesignDocument、ExternalSystem、RuntimeComponent、TechnologySelection、Environment、ScopeAndGoals、SystemContext、SolutionLayer、ApiContract、CodebaseAlignment、ModuleBoundaryRule、DataSecurity、RuntimeTopology、OperationalBaseline、ReleasePlan、ChangeLogEntry、ADR、SharedTerm、Domain、UbiquitousTerm、Scenario、DomainModule、DomainEntity） +- FileStatus 值对象（ok / sparse / missing / template-residue / placeholder-heavy） +- ArchitectureLayer 值对象（business / application / data / technology） +- ModuleLayer 值对象（domain / application / infrastructure / interfaces） + +## 约束规则 + +- 每个 Capability 至少关联一个 Module +- 每个 Entity 必须有一个 owner Module +- TraceabilityLink 中引用的 ID 必须在对应实体列表中存在 +- DesignDocument 的 upstream/downstream 引用的文件必须存在 + +## 边界 + +- 只定义模型和规则，不负责文件 I/O +- 不负责图结构 +- 纯 Python，零框架依赖 diff --git a/design/domains/design/02-ubiquitous-language.csv b/design/domains/design/02-ubiquitous-language.csv new file mode 100644 index 0000000..601ee3a --- /dev/null +++ b/design/domains/design/02-ubiquitous-language.csv @@ -0,0 +1,7 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-D-001,设计实体,Design Entity,DesignEntity,design,minimal-design-template 中一个设计文件解析出的结构化对象,,设计文件(指实体而非文件时),MOD-DESIGN MOD-SCANNER,所有 ENT-* 实体, +TERM-D-002,文件状态,File Status,FileStatus,design,一个设计文件的完成度评估结果（ok/sparse/missing/template-residue/placeholder-heavy）,完成状态,文件质量,MOD-DESIGN MOD-SCANNER,ENT-SCAN-RESULT, +TERM-D-003,架构层,Architecture Layer,ArchitectureLayer,design,四大架构分类之一：业务/应用/数据/技术,,架构类型,MOD-DESIGN MOD-GRAPH,ENT-GRAPH-GROUP, +TERM-D-004,模板残留,Template Residue,,design,从模板复制但未适配为项目特定内容的数据,残留数据,示例数据(当指残留时),MOD-DESIGN MOD-SCANNER,,比空文件更严重 +TERM-D-005,追溯链,Traceability Link,TraceabilityLink,design,capability→module→entity 的端到端关联关系,追溯关系,依赖关系(不同概念),MOD-DESIGN MOD-GRAPH,ENT-TRACEABILITY-LINK, +TERM-D-006,约束规则,Constraint Rule,,design,设计领域的业务不变量（如 entity 必须有 owner）,校验规则|业务规则,验证(指技术层校验时),MOD-DESIGN,, diff --git a/design/domains/design/03-scenarios-and-flows.csv b/design/domains/design/03-scenarios-and-flows.csv new file mode 100644 index 0000000..c081977 --- /dev/null +++ b/design/domains/design/03-scenarios-and-flows.csv @@ -0,0 +1,4 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-D-001,加载设计实体,Scanner 解析完文件后调用 Design 模块,MOD-SCANNER,Scanner 传入原始解析数据→Design 模块构造实体→返回强类型实体,所有设计文件被映射为 Design 领域实体,CAP-SCAN +SC-D-002,校验约束规则,扫描完成或编辑保存后,MOD-SCANNER MOD-EDITOR,收集所有实体→逐条执行约束规则→返回违规列表,发现不一致的设计（如无 owner 的 entity）,CAP-GAP +SC-D-003,判定文件状态,Scanner 对每个文件调用 Design 的 FileStatus 逻辑,MOD-SCANNER,读取文件内容特征（行数/占位符/残留标记）→判定 FileStatus,每个文件得到一个完成度状态,CAP-GAP CAP-PROGRESS-DESIGN diff --git a/design/domains/design/04-domain-modules.csv b/design/domains/design/04-domain-modules.csv new file mode 100644 index 0000000..c5d1509 --- /dev/null +++ b/design/domains/design/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-DESIGN,架构设计领域,design,定义所有设计文件的领域实体+值对象+约束规则,modules/design/domain/ diff --git a/design/domains/design/05-domain-entities.csv b/design/domains/design/05-domain-entities.csv new file mode 100644 index 0000000..7cfec73 --- /dev/null +++ b/design/domains/design/05-domain-entities.csv @@ -0,0 +1,35 @@ +entity_id,entity_name,type,description,key_attributes +ENT-CAPABILITY,能力,entity,"业务能力项","capability_id, name, priority, related_value_flows" +ENT-MODULE,功能模块,entity,"系统功能模块","module_id, name, layer, depends_on, capabilities" +ENT-ENTITY,数据实体,entity,"系统数据实体","entity_id, name, domain, owner_module" +ENT-VALUE-FLOW,价值流,entity,"用户价值链路","value_flow_id, trigger, steps, outcome" +ENT-USER-JOURNEY,用户旅程,entity,"用户操作路径","journey_id, precondition, steps, postcondition" +ENT-INTEGRATION,集成关系,entity,"模块间/外部集成","integration_id, source, target, protocol, direction" +ENT-DATA-FLOW,数据流,entity,"数据流动路径","data_flow_id, source, target, data_content, trigger" +ENT-TRACEABILITY-LINK,追溯关系,entity,"capability→module→entity 链","trace_id, capability_id, module_id, entity_ids" +ENT-DESIGN-DOC,设计文档元数据,entity,"MD 文件 frontmatter","doc_id, title, status, upstream, downstream" +ENT-EXTERNAL-SYSTEM,外部系统,entity,"外部系统","system_id, name, type, protocol" +ENT-RUNTIME-COMPONENT,运行组件,entity,"运行时组件","component_id, name, type, technology, port" +ENT-TECH-SELECTION,技术选型,entity,"技术选择项","category, technology, version, purpose, rationale" +ENT-ENVIRONMENT,环境,entity,"部署环境","env_id, name, purpose, infra" +ENT-SCOPE-AND-GOALS,范围与目标,entity,"项目范围和目标","title, core_problem, users, constraints" +ENT-SYSTEM-CONTEXT,系统上下文,entity,"系统边界描述","doc_id, boundary, external_interactions" +ENT-SOLUTION-LAYER,逻辑分层,entity,"系统级逻辑分层","layer_name, responsibilities, communication" +ENT-API-CONTRACT,API 契约,entity,"REST API 定义","path, method, operationId, request, response" +ENT-CODEBASE-ALIGNMENT,代码映射,entity,"模块到代码目录映射","module_id, repo_root, code_root, package_name" +ENT-MODULE-BOUNDARY-RULE,边界规则,entity,"模块间约束规则","allowed_deps, forbidden_deps, anti_patterns" +ENT-DATA-SECURITY,数据安全,entity,"数据安全分级","security_id, sensitivity, entities, protection" +ENT-RUNTIME-TOPOLOGY,运行拓扑,entity,"部署拓扑图","topology_diagram, components, connections" +ENT-OPERATIONAL-BASELINE,运维基线,entity,"运维策略","healthcheck, logging, backup, monitoring" +ENT-RELEASE-PLAN,发布计划,entity,"发布回滚策略","release_steps, rollback_steps, verification" +ENT-CHANGE-LOG-ENTRY,变更记录,entity,"设计变更历史","change_id, date, scope, description" +ENT-ADR,架构决策,entity,"架构决策记录","adr_id, title, status, context, decision" +ENT-SHARED-TERM,共享术语,entity,"跨领域术语","term_id, term, definition, aliases" +ENT-DOMAIN,领域,entity,"业务领域","domain_name, overview, modules, entities" +ENT-UBIQUITOUS-TERM,领域术语,entity,"领域统一语言","term_id, term, code_symbol, definition" +ENT-SCENARIO,场景与流程,entity,"业务场景","scenario_id, trigger, steps, outcome" +ENT-DOMAIN-MODULE,领域模块,entity,"领域内模块","module_id, domain, description" +ENT-DOMAIN-ENTITY,领域实体,entity,"领域内实体","entity_id, domain, key_attributes" +FILE-STATUS,文件状态,value_object,"设计文件完成度","ok|sparse|missing|template-residue|placeholder-heavy" +ARCHITECTURE-LAYER,架构层,value_object,"四大架构分类","business|application|data|technology" +MODULE-LAYER,模块层,value_object,"代码分层","domain|application|infrastructure|interfaces" diff --git a/design/domains/design/06-domain-decisions.md b/design/domains/design/06-domain-decisions.md new file mode 100644 index 0000000..40457c0 --- /dev/null +++ b/design/domains/design/06-domain-decisions.md @@ -0,0 +1,13 @@ +# Design 领域决策 + +## 决策 1：Design 模块作为独立核心领域 + +所有设计文件的实体模型集中在 MOD-DESIGN，而非散落在各使用方模块中。这样 Scanner、Graph、Editor 共用同一套实体定义，避免重复和不一致。 + +## 决策 2：约束规则放在 Design 的 domain services + +"capability 必须关联 module" 这类规则是设计领域的业务不变量，不是 Scanner 的文件解析逻辑，所以放在 Design 模块的 domain/services 中。 + +## 决策 3：Design 模块零外部依赖 + +Design 模块不依赖任何其他业务模块，只被依赖。这保证了核心领域的稳定性。 diff --git a/design/domains/design/07-codebase-mapping.csv b/design/domains/design/07-codebase-mapping.csv new file mode 100644 index 0000000..4a7b405 --- /dev/null +++ b/design/domains/design/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-DESIGN,design,[TODO]/modules/design/,design,纯 domain 层为主——domain/entities/ domain/services/ domain/value_objects/ diff --git a/design/domains/design/adr/ADR-000-template.md b/design/domains/design/adr/ADR-000-template.md new file mode 100644 index 0000000..6c2b0f3 --- /dev/null +++ b/design/domains/design/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Design 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/domains/editing/01-domain-overview.md b/design/domains/editing/01-domain-overview.md new file mode 100644 index 0000000..ad7f151 --- /dev/null +++ b/design/domains/editing/01-domain-overview.md @@ -0,0 +1,17 @@ +# 编辑领域（Editing）— Phase 2 + +## 职责 + +设计文件的读写编辑 + 影响分析。让用户在 Dashboard 中直接修改 CSV 和 Markdown 格式的设计文件。 + +## 核心概念 + +- EditableFile：可编辑的设计文件（路径、格式、内容） +- ImpactResult：修改一个文件后的下游影响分析结果 + +## 边界 + +- 依赖 Design（编辑时校验约束规则） +- 依赖 Scanner（保存后触发重新扫描） +- 依赖 Graph（计算影响范围） +- infrastructure 层负责文件读写 I/O diff --git a/design/domains/editing/02-ubiquitous-language.csv b/design/domains/editing/02-ubiquitous-language.csv new file mode 100644 index 0000000..e6145c5 --- /dev/null +++ b/design/domains/editing/02-ubiquitous-language.csv @@ -0,0 +1,3 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-E-001,可编辑文件,Editable File,EditableFile,editing,一个可以在 Dashboard 中直接编辑的设计文件,,设计文件(泛指时),MOD-EDITOR MOD-FE-EDITOR,ENT-EDITABLE-FILE,Phase 2 +TERM-E-002,影响分析,Impact Analysis,ImpactResult,editing,修改一个文件后计算所有下游受影响文件的分析过程,影响范围,依赖分析(不同概念),MOD-EDITOR,ENT-IMPACT-RESULT,Phase 2 diff --git a/design/domains/editing/03-scenarios-and-flows.csv b/design/domains/editing/03-scenarios-and-flows.csv new file mode 100644 index 0000000..4ff65c2 --- /dev/null +++ b/design/domains/editing/03-scenarios-and-flows.csv @@ -0,0 +1,4 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-E-001,编辑 CSV 文件,用户在图上点击某个 CSV 文件节点并选择编辑,林然,加载文件内容→显示表格编辑器→用户修改→校验约束→保存→触发重新扫描→刷新图,设计文件被更新且图反映最新状态,CAP-EDIT-CSV +SC-E-002,编辑 Markdown 文件,用户点击某个 MD 文件节点并选择编辑,林然,加载文件内容→显示 Markdown 编辑器→用户修改→保存→触发重新扫描→刷新图,设计文件被更新,CAP-EDIT-MD +SC-E-003,影响分析,用户选中某个文件查看影响范围,林然,读取文件的 upstream/downstream→沿 TraceabilityLink 遍历→返回所有受影响文件列表,用户看到修改该文件会影响哪些下游,CAP-GRAPH-IMPACT diff --git a/design/domains/editing/04-domain-modules.csv b/design/domains/editing/04-domain-modules.csv new file mode 100644 index 0000000..643e23e --- /dev/null +++ b/design/domains/editing/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-EDITOR,文件编辑器,editing,设计文件读写编辑+影响分析（Phase 2）,modules/editor/ diff --git a/design/domains/editing/05-domain-entities.csv b/design/domains/editing/05-domain-entities.csv new file mode 100644 index 0000000..38d898e --- /dev/null +++ b/design/domains/editing/05-domain-entities.csv @@ -0,0 +1,3 @@ +entity_id,entity_name,type,description,key_attributes +ENT-EDITABLE-FILE,可编辑文件,entity,"可在 Dashboard 中编辑的设计文件","file_path, format(csv|md), content, last_modified" +ENT-IMPACT-RESULT,影响分析结果,value_object,"修改一个文件后的下游影响","source_file, affected_files[], reason_chain[]" diff --git a/design/domains/editing/06-domain-decisions.md b/design/domains/editing/06-domain-decisions.md new file mode 100644 index 0000000..f533e6c --- /dev/null +++ b/design/domains/editing/06-domain-decisions.md @@ -0,0 +1,9 @@ +# Editing 领域决策 + +## 决策 1：保存后强制重新扫描 + +编辑保存文件后必须触发 Scanner 重新扫描，保证图数据和完成度状态与文件内容一致。不允许文件内容和 Dashboard 显示不同步。 + +## 决策 2：编辑时校验约束 + +保存前调用 Design 模块的约束规则预校验，如果违反约束给出警告（但不阻止保存——用户可能是中间状态）。 diff --git a/design/domains/editing/07-codebase-mapping.csv b/design/domains/editing/07-codebase-mapping.csv new file mode 100644 index 0000000..c320e89 --- /dev/null +++ b/design/domains/editing/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-EDITOR,editing,[TODO]/modules/editor/,editor,Phase 2 diff --git a/design/domains/editing/adr/ADR-000-template.md b/design/domains/editing/adr/ADR-000-template.md new file mode 100644 index 0000000..0b43d2c --- /dev/null +++ b/design/domains/editing/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Editing 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/domains/graph/01-domain-overview.md b/design/domains/graph/01-domain-overview.md new file mode 100644 index 0000000..bbd27b1 --- /dev/null +++ b/design/domains/graph/01-domain-overview.md @@ -0,0 +1,19 @@ +# 关系图领域（Graph） + +## 职责 + +将 Design 实体转换为可视化的图结构（节点+边+分组），支持全景视图、分组、下钻查询、邻居查询。 + +## 核心概念 + +- GraphNode：图节点（类型、ID、标签、状态、所属分组） +- GraphEdge：图边（source、target、关系类型） +- GraphGroup：分组（按架构层级） +- GraphView：完整图视图，支持按层级过滤 + +## 边界 + +- 依赖 Design 领域获取源数据（Capability、Module、Entity、TraceabilityLink 等） +- 不直接读文件系统 +- 图结构是展示层概念，不是设计领域概念 +- 不负责图的前端渲染（那是 MOD-FE-GRAPH 的事） diff --git a/design/domains/graph/02-ubiquitous-language.csv b/design/domains/graph/02-ubiquitous-language.csv new file mode 100644 index 0000000..c521c85 --- /dev/null +++ b/design/domains/graph/02-ubiquitous-language.csv @@ -0,0 +1,6 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-G-001,图节点,Graph Node,GraphNode,graph,关系图中的一个节点——对应一个设计实体或设计文件,节点,,MOD-GRAPH MOD-FE-GRAPH,ENT-GRAPH-NODE, +TERM-G-002,图边,Graph Edge,GraphEdge,graph,两个节点之间的关系连线,边|连线,依赖(不同层面),MOD-GRAPH MOD-FE-GRAPH,ENT-GRAPH-EDGE, +TERM-G-003,分组,Graph Group,GraphGroup,graph,按架构层级对节点进行的视觉分组,组,,MOD-GRAPH MOD-FE-GRAPH,, +TERM-G-004,图视图,Graph View,GraphView,graph,一个完整的可渲染图结构（nodes+edges+groups）,,图数据,MOD-GRAPH MOD-FE-GRAPH,ENT-GRAPH-VIEW, +TERM-G-005,下钻,Drill-down,,graph,点击一个节点展开其下一层细节的交互,展开|深入,,MOD-GRAPH MOD-FE-GRAPH,, diff --git a/design/domains/graph/03-scenarios-and-flows.csv b/design/domains/graph/03-scenarios-and-flows.csv new file mode 100644 index 0000000..94edc18 --- /dev/null +++ b/design/domains/graph/03-scenarios-and-flows.csv @@ -0,0 +1,4 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-G-001,构建全景图,扫描完成后前端请求图数据,MOD-FE-GRAPH,从 ScanResult 提取所有 Design 实体→按架构层分组→为每个实体创建 GraphNode→根据 TraceabilityLink/upstream/downstream 创建 GraphEdge→组装 GraphView,完整的全景关系图数据,CAP-GRAPH-PANORAMA +SC-G-002,下钻查询,用户点击某个节点,MOD-FE-GRAPH,接收节点 ID→查找该节点的所有邻居→按关系类型分组→返回子图,该节点的详细关联信息,CAP-GRAPH-DRILL +SC-G-003,影响高亮,用户选中某个节点查看影响,MOD-FE-GRAPH,接收节点 ID→沿 downstream 方向遍历所有可达节点→标记为受影响→返回受影响节点列表,所有下游受影响节点被高亮,CAP-GRAPH-IMPACT diff --git a/design/domains/graph/04-domain-modules.csv b/design/domains/graph/04-domain-modules.csv new file mode 100644 index 0000000..4dacbdd --- /dev/null +++ b/design/domains/graph/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-GRAPH,关系图引擎,graph,从 Design 实体构建关系图支持分组/下钻/邻居查询,modules/graph/ diff --git a/design/domains/graph/05-domain-entities.csv b/design/domains/graph/05-domain-entities.csv new file mode 100644 index 0000000..1c7621b --- /dev/null +++ b/design/domains/graph/05-domain-entities.csv @@ -0,0 +1,4 @@ +entity_id,entity_name,type,description,key_attributes +ENT-GRAPH-NODE,图节点,entity,"关系图中的节点","node_id, node_type, label, status, group_id" +ENT-GRAPH-EDGE,图边,entity,"关系图中的边","source_id, target_id, relation_type" +ENT-GRAPH-VIEW,图视图,aggregate,"完整图视图","nodes, edges, groups, filter_level" diff --git a/design/domains/graph/06-domain-decisions.md b/design/domains/graph/06-domain-decisions.md new file mode 100644 index 0000000..1722d96 --- /dev/null +++ b/design/domains/graph/06-domain-decisions.md @@ -0,0 +1,9 @@ +# Graph 领域决策 + +## 决策 1：图结构与设计实体分离 + +GraphNode/GraphEdge 是展示层概念，不等同于 Design 实体本身。Graph 模块负责"Design 实体 → 图结构"的转换。 + +## 决策 2：Graph 不直接读文件 + +Graph 从 Design 实体构建图，不自己读取文件系统。这保证了关注点分离。 diff --git a/design/domains/graph/07-codebase-mapping.csv b/design/domains/graph/07-codebase-mapping.csv new file mode 100644 index 0000000..3afcad4 --- /dev/null +++ b/design/domains/graph/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-GRAPH,graph,[TODO]/modules/graph/,graph,domain 层定义图结构；application 层编排构建逻辑 diff --git a/design/domains/graph/adr/ADR-000-template.md b/design/domains/graph/adr/ADR-000-template.md new file mode 100644 index 0000000..1b193d1 --- /dev/null +++ b/design/domains/graph/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Graph 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/domains/impl-tracking/01-domain-overview.md b/design/domains/impl-tracking/01-domain-overview.md new file mode 100644 index 0000000..42b17d8 --- /dev/null +++ b/design/domains/impl-tracking/01-domain-overview.md @@ -0,0 +1,17 @@ +# 实现追踪领域（Impl-Tracking）— Phase 2 + +## 职责 + +扫描代码目录结构 + 调用 LLM 评估模块实现完成度 + 支持手动覆盖，产出每个模块的实现进度。 + +## 核心概念 + +- ImplProgress：模块实现进度（模块 ID、百分比、来源：auto/llm/manual） +- CodeStructure：代码目录结构扫描结果 + +## 边界 + +- 依赖 Design（Module 和 CodebaseAlignment 定义） +- 依赖 Scanner（最新扫描数据） +- infrastructure 层负责代码目录 I/O 和 LLM API 调用 +- 代码仓库只读（不修改代码） diff --git a/design/domains/impl-tracking/02-ubiquitous-language.csv b/design/domains/impl-tracking/02-ubiquitous-language.csv new file mode 100644 index 0000000..e4b5774 --- /dev/null +++ b/design/domains/impl-tracking/02-ubiquitous-language.csv @@ -0,0 +1,4 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-IT-001,实现进度,Implementation Progress,ImplProgress,impl-tracking,一个模块的代码实现完成百分比及其评估来源,完成度|实现状态,设计进度(不同概念),MOD-IMPL-TRACKER,ENT-IMPL-PROGRESS,Phase 2 +TERM-IT-002,代码结构,Code Structure,CodeStructure,impl-tracking,项目代码仓库的目录结构扫描结果,,文件结构(指设计文件时),MOD-IMPL-TRACKER,,Phase 2 +TERM-IT-003,评估来源,Progress Source,,impl-tracking,"进度百分比的来源：auto（目录扫描推断）、llm（LLM 评估）、manual（手动标记）",来源,,MOD-IMPL-TRACKER,ENT-IMPL-PROGRESS,Phase 2 diff --git a/design/domains/impl-tracking/03-scenarios-and-flows.csv b/design/domains/impl-tracking/03-scenarios-and-flows.csv new file mode 100644 index 0000000..d17cfff --- /dev/null +++ b/design/domains/impl-tracking/03-scenarios-and-flows.csv @@ -0,0 +1,4 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-IT-001,自动扫描实现进度,用户触发实现进度评估,林然,读取 CodebaseAlignment 中的目录映射→扫描代码仓库对应目录→检查文件/目录是否存在→推断初始百分比,每个模块有一个基于目录结构的初始进度,CAP-PROGRESS-IMPL +SC-IT-002,LLM 辅助评估,自动扫描后需要更精确评估,MOD-IMPL-TRACKER,将模块设计文档+代码内容发送给 LLM→LLM 返回功能覆盖评估→更新百分比,每个模块有 LLM 评估的进度百分比,CAP-PROGRESS-IMPL +SC-IT-003,手动覆盖进度,用户认为自动/LLM 评估不准确,林然,在 Dashboard 上选择模块→手动输入百分比→标记来源为 manual→保存,用户的手动判断覆盖自动评估,CAP-PROGRESS-IMPL diff --git a/design/domains/impl-tracking/04-domain-modules.csv b/design/domains/impl-tracking/04-domain-modules.csv new file mode 100644 index 0000000..04d27f4 --- /dev/null +++ b/design/domains/impl-tracking/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-IMPL-TRACKER,实现进度追踪,impl-tracking,扫描代码目录+LLM 评估+手动覆盖（Phase 2）,modules/impl_tracker/ diff --git a/design/domains/impl-tracking/05-domain-entities.csv b/design/domains/impl-tracking/05-domain-entities.csv new file mode 100644 index 0000000..3926f6f --- /dev/null +++ b/design/domains/impl-tracking/05-domain-entities.csv @@ -0,0 +1,3 @@ +entity_id,entity_name,type,description,key_attributes +ENT-IMPL-PROGRESS,实现进度,entity,"模块实现完成百分比","module_id, percentage, source(auto|llm|manual), evaluated_at" +CODE-STRUCTURE,代码结构,value_object,"代码目录扫描结果","root_path, directories[], files[], matched_modules[]" diff --git a/design/domains/impl-tracking/06-domain-decisions.md b/design/domains/impl-tracking/06-domain-decisions.md new file mode 100644 index 0000000..2c3127f --- /dev/null +++ b/design/domains/impl-tracking/06-domain-decisions.md @@ -0,0 +1,13 @@ +# Impl-Tracking 领域决策 + +## 决策 1：三层评估策略 + +进度评估分三层：auto（目录结构推断）→ llm（LLM 精确评估）→ manual（人工覆盖）。后者优先级高于前者。 + +## 决策 2：代码只读 + +Dashboard 不修改代码仓库，只读取目录结构和文件内容用于评估。 + +## 决策 3：LLM 调用可选 + +如果没有配置 LLM API，auto + manual 仍然可用。LLM 是增强功能，不是必须。 diff --git a/design/domains/impl-tracking/07-codebase-mapping.csv b/design/domains/impl-tracking/07-codebase-mapping.csv new file mode 100644 index 0000000..d028e9f --- /dev/null +++ b/design/domains/impl-tracking/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-IMPL-TRACKER,impl-tracking,[TODO]/modules/impl_tracker/,impl_tracker,Phase 2; infrastructure 层放代码扫描和 LLM 调用 diff --git a/design/domains/impl-tracking/adr/ADR-000-template.md b/design/domains/impl-tracking/adr/ADR-000-template.md new file mode 100644 index 0000000..f3e1fff --- /dev/null +++ b/design/domains/impl-tracking/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Impl-Tracking 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/domains/project/01-domain-overview.md b/design/domains/project/01-domain-overview.md new file mode 100644 index 0000000..1a0a707 --- /dev/null +++ b/design/domains/project/01-domain-overview.md @@ -0,0 +1,16 @@ +# 项目管理领域（Project） + +## 职责 + +项目注册、切换、元数据管理。管理用户在 Dashboard 中跟踪的多个设计项目。 + +## 核心概念 + +- Project：一个被 Dashboard 管理的项目（名称、设计目录路径、代码目录路径、创建时间） +- ProjectRepository：项目持久化抽象接口 + +## 边界 + +- 独立领域，不依赖其他业务模块 +- infrastructure 层实现 JSON 文件持久化（projects.json） +- 不涉及设计文件的解析或图构建 diff --git a/design/domains/project/02-ubiquitous-language.csv b/design/domains/project/02-ubiquitous-language.csv new file mode 100644 index 0000000..32d8afb --- /dev/null +++ b/design/domains/project/02-ubiquitous-language.csv @@ -0,0 +1,3 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-P-001,项目,Project,Project,project,一个被 Dashboard 管理的架构设计项目,设计项目,,MOD-PROJECT MOD-FE-PROJECT,ENT-PROJECT, +TERM-P-002,项目注册表,Project Registry,,project,存储所有已注册项目信息的 JSON 文件,注册表|项目列表,数据库,MOD-PROJECT,ENT-PROJECT,~/.arch-design-dashboard/projects.json diff --git a/design/domains/project/03-scenarios-and-flows.csv b/design/domains/project/03-scenarios-and-flows.csv new file mode 100644 index 0000000..935f6a2 --- /dev/null +++ b/design/domains/project/03-scenarios-and-flows.csv @@ -0,0 +1,4 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-P-001,注册新项目,用户在前端填写项目信息,林然,输入名称+设计目录路径+(可选)代码目录路径→后端验证路径存在→保存到 projects.json→返回项目 ID,项目可在 Dashboard 中使用,CAP-PROJ-REG +SC-P-002,切换项目,用户在项目列表点击另一个项目,林然,选择目标项目→前端更新当前项目状态→触发重新扫描,Dashboard 显示目标项目的设计数据,CAP-PROJ-REG +SC-P-003,列出所有项目,用户打开 Dashboard,林然,读取 projects.json→返回项目列表,用户看到所有已注册项目,CAP-PROJ-REG diff --git a/design/domains/project/04-domain-modules.csv b/design/domains/project/04-domain-modules.csv new file mode 100644 index 0000000..915ab74 --- /dev/null +++ b/design/domains/project/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-PROJECT,项目管理,project,项目注册/切换/配置发现,modules/project/ diff --git a/design/domains/project/05-domain-entities.csv b/design/domains/project/05-domain-entities.csv new file mode 100644 index 0000000..1994068 --- /dev/null +++ b/design/domains/project/05-domain-entities.csv @@ -0,0 +1,2 @@ +entity_id,entity_name,type,description,key_attributes +ENT-PROJECT,项目,aggregate,"Dashboard 管理的项目","project_id, name, design_dir, code_dir, created_at" diff --git a/design/domains/project/06-domain-decisions.md b/design/domains/project/06-domain-decisions.md new file mode 100644 index 0000000..d5d5dcf --- /dev/null +++ b/design/domains/project/06-domain-decisions.md @@ -0,0 +1,9 @@ +# Project 领域决策 + +## 决策 1：JSON 文件持久化 + +不使用数据库。项目元数据量小（预计 < 50 个项目），JSON 文件足够。projects.json 放在 Docker named volume 中。 + +## 决策 2：Project 领域独立 + +Project 不依赖 Design/Scanner/Graph 等模块。它只管理项目的元数据（路径、名称），不涉及设计内容。 diff --git a/design/domains/project/07-codebase-mapping.csv b/design/domains/project/07-codebase-mapping.csv new file mode 100644 index 0000000..5f0cb7d --- /dev/null +++ b/design/domains/project/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-PROJECT,project,[TODO]/modules/project/,project,infrastructure/repositories/ 实现 JSON 文件持久化 diff --git a/design/domains/project/adr/ADR-000-template.md b/design/domains/project/adr/ADR-000-template.md new file mode 100644 index 0000000..55ae141 --- /dev/null +++ b/design/domains/project/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Project 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/domains/scanning/01-domain-overview.md b/design/domains/scanning/01-domain-overview.md new file mode 100644 index 0000000..c41712d --- /dev/null +++ b/design/domains/scanning/01-domain-overview.md @@ -0,0 +1,18 @@ +# 扫描领域（Scanning） + +## 职责 + +文件发现（遍历 design/ 目录）+ 文件解析（CSV/MD/YAML/OpenAPI → Design 实体）+ 完成度检测。 + +## 核心概念 + +- ScanResult：一次扫描的完整输出，包含所有解析出的 Design 实体和文件状态列表 +- ScanPolicy：扫描策略（哪些文件类型要解析、忽略规则） +- Parser：各类文件格式的解析器（infrastructure 层实现） + +## 边界 + +- 依赖 Design 领域的实体定义和约束规则 +- 文件 I/O 在 infrastructure 层（parsers/） +- 不负责图结构构建 +- 不负责文件编辑 diff --git a/design/domains/scanning/02-ubiquitous-language.csv b/design/domains/scanning/02-ubiquitous-language.csv new file mode 100644 index 0000000..7c85cb9 --- /dev/null +++ b/design/domains/scanning/02-ubiquitous-language.csv @@ -0,0 +1,4 @@ +term_id,term,english_term,code_symbol,domain,definition,aliases,forbidden_synonyms,used_by_modules,related_entities,notes +TERM-S-001,扫描结果,Scan Result,ScanResult,scanning,一次扫描 design/ 目录后的完整输出（所有实体+文件状态）,,检查结果,MOD-SCANNER,ENT-SCAN-RESULT, +TERM-S-002,扫描策略,Scan Policy,ScanPolicy,scanning,定义哪些文件要解析、哪些忽略的配置,扫描配置,,MOD-SCANNER,, +TERM-S-003,解析器,Parser,,scanning,将特定格式的文件内容转换为 Design 实体的组件,文件解析器,转换器(不同语义),MOD-SCANNER,,infrastructure 层实现 diff --git a/design/domains/scanning/03-scenarios-and-flows.csv b/design/domains/scanning/03-scenarios-and-flows.csv new file mode 100644 index 0000000..ad00aa3 --- /dev/null +++ b/design/domains/scanning/03-scenarios-and-flows.csv @@ -0,0 +1,3 @@ +scenario_id,scenario_name,trigger,actors,steps,outcome,related_capabilities +SC-S-001,全量扫描,用户打开项目或手动刷新,MOD-FE-GRAPH,遍历 design/ 目录→按文件类型选择 Parser→解析为 Design 实体→调用约束规则检测→汇总为 ScanResult,完整的扫描结果包含所有实体和文件状态,CAP-SCAN CAP-GAP +SC-S-002,完成度检测,全量扫描的一部分,MOD-SCANNER,对每个文件→检查行数/占位符/残留标记→调用 Design 的 FileStatus 逻辑→标记状态,每个文件获得一个 FileStatus,CAP-GAP CAP-PROGRESS-DESIGN diff --git a/design/domains/scanning/04-domain-modules.csv b/design/domains/scanning/04-domain-modules.csv new file mode 100644 index 0000000..d86576e --- /dev/null +++ b/design/domains/scanning/04-domain-modules.csv @@ -0,0 +1,2 @@ +module_id,module_name,domain,description,layer_in_code +MOD-SCANNER,设计扫描与解析,scanning,文件发现+解析+完成度检测,modules/scanner/ diff --git a/design/domains/scanning/05-domain-entities.csv b/design/domains/scanning/05-domain-entities.csv new file mode 100644 index 0000000..6d73355 --- /dev/null +++ b/design/domains/scanning/05-domain-entities.csv @@ -0,0 +1,3 @@ +entity_id,entity_name,type,description,key_attributes +ENT-SCAN-RESULT,扫描结果,entity,"一次扫描的完整输出","design_entities, file_statuses, scan_time" +SCAN-POLICY,扫描策略,value_object,"扫描配置","included_extensions, ignored_patterns" diff --git a/design/domains/scanning/06-domain-decisions.md b/design/domains/scanning/06-domain-decisions.md new file mode 100644 index 0000000..e38d648 --- /dev/null +++ b/design/domains/scanning/06-domain-decisions.md @@ -0,0 +1,9 @@ +# Scanning 领域决策 + +## 决策 1：Scanner 不包含业务规则 + +文件状态判定规则（如"entity 必须有 owner"）属于 Design 领域。Scanner 只负责调用 Design 的规则，不自己实现。 + +## 决策 2：Parser 放在 infrastructure 层 + +CSV/MD/YAML/OpenAPI 的解析是技术实现细节，放在 Scanner 的 infrastructure/parsers/ 中。domain 层只定义"需要什么输出"。 diff --git a/design/domains/scanning/07-codebase-mapping.csv b/design/domains/scanning/07-codebase-mapping.csv new file mode 100644 index 0000000..89a05f4 --- /dev/null +++ b/design/domains/scanning/07-codebase-mapping.csv @@ -0,0 +1,2 @@ +module_id,domain,code_path,package,notes +MOD-SCANNER,scanning,[TODO]/modules/scanner/,scanner,infrastructure/parsers/ 放各类文件解析器 diff --git a/design/domains/scanning/adr/ADR-000-template.md b/design/domains/scanning/adr/ADR-000-template.md new file mode 100644 index 0000000..68f236e --- /dev/null +++ b/design/domains/scanning/adr/ADR-000-template.md @@ -0,0 +1,3 @@ +# ADR 模板（Scanning 领域） + +参见 `../../adr/ADR-000-template.md` diff --git a/design/technology-architecture/00-technology-selection.csv b/design/technology-architecture/00-technology-selection.csv new file mode 100644 index 0000000..bad6621 --- /dev/null +++ b/design/technology-architecture/00-technology-selection.csv @@ -0,0 +1,13 @@ +category,technology,version,purpose,rationale,alternatives_considered,phase +language,Python,3.12+,后端开发语言,团队熟悉+生态丰富+文件处理能力强,Go/Node.js,MVP +framework,FastAPI,latest,后端 Web 框架,异步支持+自动 OpenAPI 文档+类型安全,Flask/Django,MVP +package-manager,uv,latest,Python 依赖管理,速度快+lockfile 支持+替代 pip+venv,poetry/pip,MVP +language,TypeScript,5.x,前端开发语言,类型安全+Vue 3 原生支持,JavaScript,MVP +framework,Vue 3,3.x,前端框架,组合式 API+轻量+生态成熟,React/Svelte,MVP +bundler,Vite,latest,前端构建工具,开发热更新快+Vue 官方推荐,Webpack,MVP +state,Pinia,latest,前端状态管理,Vue 3 官方推荐+TypeScript 友好,Vuex,MVP +visualization,D3.js,7.x,关系图渲染,灵活度最高+适合高度定制的可下钻分组图,ECharts/Cytoscape.js,MVP +container,Docker,latest,容器化部署,标准化部署+环境一致性,直接部署,MVP +orchestration,Docker Compose,latest,多容器编排,前后端两个容器+volume 挂载,K8s(过重),MVP +web-server,Nginx,latest,前端静态文件服务+反向代理,轻量+性能好+反代 /api → backend,Caddy,MVP +asgi-server,Uvicorn,latest,ASGI 服务器,FastAPI 官方推荐+异步性能好,Gunicorn+Uvicorn workers,MVP diff --git a/design/technology-architecture/00-technology-selection.md b/design/technology-architecture/00-technology-selection.md new file mode 100644 index 0000000..c9fd052 --- /dev/null +++ b/design/technology-architecture/00-technology-selection.md @@ -0,0 +1,45 @@ +--- +doc_id: DOC-TA-000 +title: 技术选型说明 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ../business-architecture/01-scope-and-goals.md +downstream: + - ./01-runtime-topology.md + - ./01-runtime-components.csv +updated_at: 2026-03-23 +--- + +# 技术选型说明 + +详细选型清单见 `./00-technology-selection.csv`。 + +## 核心决策 + +### 后端：Python 3.12 + FastAPI + uv +- 文件解析（CSV/MD/YAML/OpenAPI）是核心功能，Python 生态在这方面最成熟 +- FastAPI 提供异步支持和自动 OpenAPI 文档 +- uv 替代 pip+venv，依赖管理更快更可靠 + +### 前端：Vue 3 + TypeScript + Vite + Pinia +- 组合式 API 适合模块化的组件结构 +- TypeScript 提供类型安全 +- Pinia 作为 Vue 3 官方推荐的状态管理方案 + +### 关系图：D3.js +- 需要高度定制的可下钻分组图 +- D3.js 灵活度最高，可以精确控制节点布局、分组、交互 +- 学习曲线较陡，但这个项目的图交互是核心功能，值得投入 + +### 部署：Docker Compose +- 两个容器：Nginx（前端+反代）+ Python（后端） +- 无数据库容器 +- Volume 挂载设计文件目录和代码仓库目录 + +### 不使用数据库 +- 设计文件本身就是 single source of truth +- 项目注册用 JSON 文件 +- 关系图和扫描结果是运行时计算，不需要持久化 diff --git a/design/technology-architecture/01-runtime-components.csv b/design/technology-architecture/01-runtime-components.csv new file mode 100644 index 0000000..30d2afb --- /dev/null +++ b/design/technology-architecture/01-runtime-components.csv @@ -0,0 +1,6 @@ +component_id,component_name,type,technology,port,description,phase +CMP-NGINX,Nginx 前端容器,container,Nginx,80,Serve 前端静态文件 + 反向代理 /api → backend,MVP +CMP-BACKEND,Python 后端容器,container,FastAPI + Uvicorn,8900,REST API 服务,MVP +CMP-DESIGN-VOL,设计文件 Volume,volume mount,filesystem,N/A,挂载宿主机设计文件目录(rw),MVP +CMP-REGISTRY-VOL,注册表 Volume,docker volume,filesystem,N/A,存储 projects.json,MVP +CMP-CODE-VOL,代码仓库 Volume,volume mount,filesystem,N/A,挂载宿主机代码目录(ro),Phase2 diff --git a/design/technology-architecture/01-runtime-topology.md b/design/technology-architecture/01-runtime-topology.md new file mode 100644 index 0000000..3d7efb2 --- /dev/null +++ b/design/technology-architecture/01-runtime-topology.md @@ -0,0 +1,58 @@ +--- +doc_id: DOC-TA-001 +title: 运行时拓扑 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./00-technology-selection.md +downstream: + - ./01-runtime-components.csv + - ./02-environments.csv +updated_at: 2026-03-23 +--- + +# 运行时拓扑 + +## 部署架构 + +```mermaid +flowchart LR + Browser["浏览器
(林然)"] -->|HTTP :80| Nginx["Nginx 容器
静态文件 + 反代"] + Nginx -->|/api/* → :8900| Backend["Python 容器
FastAPI + Uvicorn"] + Backend -->|File I/O| DesignVol["/mnt/designs
(volume mount)"] + Backend -->|File I/O| CodeVol["/mnt/code
(volume mount, Phase 2)"] + Backend -->|JSON R/W| Registry["/data/projects.json
(volume mount)"] +``` + +## Docker Compose 结构 + +```yaml +services: + frontend: + build: ./frontend + ports: ["80:80"] + # Nginx serve 静态文件 + 反代 /api → backend:8900 + + backend: + build: ./backend + expose: ["8900"] + volumes: + - ${DESIGN_DIRS}:/mnt/designs:rw + - ${CODE_DIRS}:/mnt/code:ro # Phase 2 + - dashboard-data:/data + environment: + - REGISTRY_PATH=/data/projects.json + +volumes: + dashboard-data: +``` + +## 关键说明 + +- 前端容器只负责 Nginx，不运行 Node.js +- 后端容器通过 volume 访问宿主机的设计文件和代码目录 +- 设计文件 volume 是 rw（编辑功能需要写），代码 volume 是 ro +- projects.json 放在 named volume 中，容器重建不丢失 +- 无数据库容器 diff --git a/design/technology-architecture/02-environments.csv b/design/technology-architecture/02-environments.csv new file mode 100644 index 0000000..04ad63a --- /dev/null +++ b/design/technology-architecture/02-environments.csv @@ -0,0 +1,3 @@ +env_id,env_name,purpose,infra,url,notes +ENV-DEV,开发环境,本地开发调试,uvicorn + vite dev（无 Docker）,http://localhost:5173 + http://localhost:8900,前后端分别直接运行 +ENV-PROD,生产环境,服务器部署,Docker Compose（Nginx + Python 容器）,http://:80,通过 docker compose up 部署 diff --git a/design/technology-architecture/03-operational-baseline.md b/design/technology-architecture/03-operational-baseline.md new file mode 100644 index 0000000..83622c5 --- /dev/null +++ b/design/technology-architecture/03-operational-baseline.md @@ -0,0 +1,47 @@ +--- +doc_id: DOC-TA-003 +title: 运维基线 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./01-runtime-topology.md +downstream: + - ./04-release-and-rollback.md +updated_at: 2026-03-23 +--- + +# 运维基线 + +## 概述 + +单人使用的工具型应用，运维策略从简。 + +## 健康检查 + +- 后端：`GET /api/health` 返回 `{"status": "ok"}` +- Docker healthcheck：定期探测 `/api/health` +- 前端：Nginx 默认返回静态文件即可视为健康 + +## 日志 + +- 后端日志输出到 stdout/stderr +- Docker 自带日志收集（`docker compose logs`） +- 不需要 ELK/Loki 等日志系统 + +## 备份 + +- 不需要专门备份——设计文件在 Git 仓库中 +- projects.json 丢失后重新注册即可，代价极低 + +## 监控 + +- 不需要专门的监控系统 +- Docker 基础资源监控（`docker stats`）足够 +- 如果未来需要，可以加 Prometheus + Grafana，但当前不需要 + +## 重启策略 + +- Docker Compose: `restart: unless-stopped` +- 后端进程崩溃后 Docker 自动重启 diff --git a/design/technology-architecture/04-release-and-rollback.md b/design/technology-architecture/04-release-and-rollback.md new file mode 100644 index 0000000..d6d7a83 --- /dev/null +++ b/design/technology-architecture/04-release-and-rollback.md @@ -0,0 +1,56 @@ +--- +doc_id: DOC-TA-004 +title: 发布与回滚 +version: 0.1.0 +status: reviewed +owners: + - 林然 +upstream: + - ./03-operational-baseline.md +downstream: [] +updated_at: 2026-03-23 +--- + +# 发布与回滚 + +## 发布流程 + +```bash +# 1. 拉取最新代码 +git pull + +# 2. 构建并部署 +docker compose build +docker compose up -d + +# 3. 验证 +curl http://localhost/api/health # 期望 {"status": "ok"} +# 浏览器打开首页确认可访问 +``` + +## 回滚流程 + +```bash +# 1. 停止当前版本 +docker compose down + +# 2. 回退到上一个版本 +git checkout <上个版本的 commit/tag> + +# 3. 重新构建部署 +docker compose build +docker compose up -d + +# 4. 验证 +curl http://localhost/api/health +``` + +## 验证标准 + +- `/api/health` 返回 HTTP 200 + `{"status": "ok"}` +- 前端首页可访问 +- 已注册项目列表正常加载 + +## 零停机 + +不需要。单人使用，发布期间短暂不可用（通常 < 30 秒）可以接受。 diff --git a/design/technology-architecture/README.md b/design/technology-architecture/README.md new file mode 100644 index 0000000..619de6e --- /dev/null +++ b/design/technology-architecture/README.md @@ -0,0 +1,33 @@ +# Technology Architecture + +回答的问题： +- 整体技术栈和关键技术选型是什么？ +- 系统如何部署和运行？ +- 环境如何划分？ +- 如何发布与回滚？ +- 出问题怎么看、怎么恢复？ +- 最低限度的安全基线是什么？ +- 哪些技术决策需要 ADR？ + +## 本目录产出 +- [00-technology-selection.md](./00-technology-selection.md) +- [00-technology-selection.csv](./00-technology-selection.csv) +- [01-runtime-topology.md](./01-runtime-topology.md) +- [01-runtime-components.csv](./01-runtime-components.csv) +- [02-environments.csv](./02-environments.csv) +- [03-operational-baseline.md](./03-operational-baseline.md) +- [04-release-and-rollback.md](./04-release-and-rollback.md) +- [adr/ADR-000-template.md](./adr/ADR-000-template.md) + +## 依赖 +- 依赖 [`../application-architecture/02b-solution-layering.md`](../application-architecture/02b-solution-layering.md) +- 依赖 [`../application-architecture/02-modules.csv`](../application-architecture/02-modules.csv) +- 依赖 [`../application-architecture/06-codebase-alignment.csv`](../application-architecture/06-codebase-alignment.csv) +- 依赖 [`../data-architecture/03-data-security.csv`](../data-architecture/03-data-security.csv) + +## 最小实践要求 +- 至少说明关键技术选型及原因 +- 至少说明生产系统由哪些组件组成 +- 至少说明环境划分和配置来源 +- 至少说明如何发布、如何回滚、如何看日志 +- 表格型数据使用 CSV，不用 Markdown 表格 diff --git a/design/technology-architecture/adr/ADR-000-template.md b/design/technology-architecture/adr/ADR-000-template.md new file mode 100644 index 0000000..6f4f144 --- /dev/null +++ b/design/technology-architecture/adr/ADR-000-template.md @@ -0,0 +1,15 @@ +# ADR-000: 技术架构决策模板 + +- Status: draft +- Date: 2026-03-23 +- Scope: technology-architecture +- Deciders: tech-lead, sre, architect + +## Context +本决策涉及哪些技术选型、运行拓扑、环境、运维或发布问题？ + +## Decision +最终技术架构决策是什么？ + +## Consequences +会影响哪些系统组件、成本、风险和运维策略？ diff --git a/design/traceability.csv b/design/traceability.csv new file mode 100644 index 0000000..87f46ef --- /dev/null +++ b/design/traceability.csv @@ -0,0 +1,20 @@ +trace_id,capability_id,module_id,entity_ids,value_flow_ids,notes +TR-01,CAP-PROJ-REG,MOD-PROJECT,ENT-PROJECT,VF-01,项目注册与切换 +TR-02,CAP-PROJ-REG,MOD-FE-PROJECT,ENT-PROJECT,VF-01,项目管理前端 +TR-03,CAP-SCAN,MOD-SCANNER,ENT-SCAN-RESULT ENT-DESIGN-DOC,VF-02,扫描设计目录解析为结构化数据 +TR-04,CAP-SCAN,MOD-DESIGN,ENT-CAPABILITY ENT-MODULE ENT-ENTITY ENT-VALUE-FLOW ENT-USER-JOURNEY ENT-INTEGRATION ENT-DATA-FLOW ENT-TRACEABILITY-LINK ENT-EXTERNAL-SYSTEM ENT-RUNTIME-COMPONENT ENT-TECH-SELECTION ENT-ENVIRONMENT ENT-SCOPE-AND-GOALS ENT-SYSTEM-CONTEXT ENT-SOLUTION-LAYER ENT-API-CONTRACT ENT-CODEBASE-ALIGNMENT ENT-MODULE-BOUNDARY-RULE ENT-DATA-SECURITY ENT-RUNTIME-TOPOLOGY ENT-OPERATIONAL-BASELINE ENT-RELEASE-PLAN ENT-CHANGE-LOG-ENTRY ENT-ADR ENT-SHARED-TERM ENT-DOMAIN ENT-UBIQUITOUS-TERM ENT-SCENARIO ENT-DOMAIN-MODULE ENT-DOMAIN-ENTITY,VF-02,Scanner 产出 Design 模块定义的所有领域实体 +TR-05,CAP-GAP,MOD-SCANNER,ENT-SCAN-RESULT,VF-02,完成度检测 +TR-06,CAP-GAP,MOD-DESIGN,,VF-02,Design 模块提供 FileStatus 值对象和约束规则 +TR-07,CAP-GRAPH-PANORAMA,MOD-GRAPH,ENT-GRAPH-NODE ENT-GRAPH-EDGE ENT-GRAPH-VIEW,VF-03,全景关系图构建 +TR-08,CAP-GRAPH-PANORAMA,MOD-FE-GRAPH,ENT-GRAPH-VIEW,VF-03,全景关系图渲染 +TR-09,CAP-GRAPH-DRILL,MOD-GRAPH,ENT-GRAPH-NODE ENT-GRAPH-EDGE,VF-03,下钻查询 +TR-10,CAP-GRAPH-DRILL,MOD-FE-GRAPH,ENT-GRAPH-NODE,VF-03,下钻交互 +TR-11,CAP-PROGRESS-DESIGN,MOD-SCANNER,ENT-SCAN-RESULT,VF-02,设计进度基于扫描结果的完成状态 +TR-12,CAP-PROGRESS-DESIGN,MOD-FE-GRAPH,ENT-GRAPH-NODE,VF-02 VF-03,节点颜色体现设计进度 +TR-13,CAP-GRAPH-IMPACT,MOD-EDITOR,ENT-IMPACT-RESULT ENT-DESIGN-DOC ENT-TRACEABILITY-LINK,VF-04,影响分析（Phase 2） +TR-14,CAP-GRAPH-IMPACT,MOD-FE-GRAPH,ENT-IMPACT-RESULT,VF-04,影响高亮（Phase 2） +TR-15,CAP-PROGRESS-IMPL,MOD-IMPL-TRACKER,ENT-IMPL-PROGRESS ENT-CODEBASE-ALIGNMENT ENT-MODULE,VF-05,实现进度追踪（Phase 2） +TR-16,CAP-EDIT-CSV,MOD-EDITOR,ENT-EDITABLE-FILE,VF-06,CSV 编辑（Phase 2） +TR-17,CAP-EDIT-CSV,MOD-FE-EDITOR,ENT-EDITABLE-FILE,VF-06,CSV 编辑器前端（Phase 2） +TR-18,CAP-EDIT-MD,MOD-EDITOR,ENT-EDITABLE-FILE,VF-06,Markdown 编辑（Phase 2） +TR-19,CAP-EDIT-MD,MOD-FE-EDITOR,ENT-EDITABLE-FILE,VF-06,Markdown 编辑器前端（Phase 2） diff --git a/frontend/src/App.vue b/frontend/src/App.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/main.ts b/frontend/src/main.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/editor/api/index.ts b/frontend/src/modules/editor/api/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/editor/components/CsvEditor.vue b/frontend/src/modules/editor/components/CsvEditor.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/editor/components/MdEditor.vue b/frontend/src/modules/editor/components/MdEditor.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/editor/composables/useEditor.ts b/frontend/src/modules/editor/composables/useEditor.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/editor/types/index.ts b/frontend/src/modules/editor/types/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/graph/api/index.ts b/frontend/src/modules/graph/api/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/graph/components/GraphDetail.vue b/frontend/src/modules/graph/components/GraphDetail.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/graph/components/GraphPanorama.vue b/frontend/src/modules/graph/components/GraphPanorama.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/graph/composables/useGraph.ts b/frontend/src/modules/graph/composables/useGraph.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/graph/types/index.ts b/frontend/src/modules/graph/types/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/project/api/index.ts b/frontend/src/modules/project/api/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/project/components/ProjectList.vue b/frontend/src/modules/project/components/ProjectList.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/project/components/ProjectOverview.vue b/frontend/src/modules/project/components/ProjectOverview.vue new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/project/composables/useProject.ts b/frontend/src/modules/project/composables/useProject.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/modules/project/types/index.ts b/frontend/src/modules/project/types/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/shared/api.ts b/frontend/src/shared/api.ts new file mode 100644 index 0000000..e69de29 diff --git a/frontend/src/shared/types/api.ts b/frontend/src/shared/types/api.ts new file mode 100644 index 0000000..e69de29