# 工程系统设计 — 项目多工程 + Git 状态 + 文件浏览

> 创建: 2026-06-29 | 状态: 实施中(Batch 9)
> 关联: [项目知识图谱与任务队列系统-2026-06-26.md](./项目知识图谱与任务队列系统-2026-06-26.md) / ARCHITECTURE.md

---

## 一、背景

DevFlow 的项目(Project)当前只能绑定一个目录(projects.path)。现实中的项目经常包含多个工程(Module):Monorepo 多仓库、微服务多服务、前后端分离等。每个工程是独立的代码仓库(各自的 .git),有自己的 Git 远程地址和技术栈。

引入工程(Module)概念,使 AI 和用户都能以工程为粒度操作代码仓库。

---

## 二、两级结构

```
项目(Project)           ← 业务实体("支付平台")
├── 工程(Module)        ← 代码仓库("后端 API" / "前端 Web")
│   ├── 工程目录(path)
│   ├── Git 地址(git_url)
│   ├── 技术栈(stack)
│   └── Git 状态(实时派生,不存表)
├── 工程(Module)
└── 工程(Module)
```

单仓库项目 = 项目下只有一个工程(退化场景,UI 不显式展示工程层级)。

---

## 三、数据模型

### 3.1 project_modules 表(V34 迁移)

```sql
CREATE TABLE project_modules (
    id            TEXT PRIMARY KEY,
    project_id    TEXT NOT NULL REFERENCES projects(id),
    name          TEXT NOT NULL,             -- "后端 API"
    path          TEXT NOT NULL,             -- 工程目录(绝对路径)
    git_url       TEXT,                      -- Git 远程地址(可选)
    stack         TEXT,                      -- 技术栈 JSON(["rust","tokio","postgresql"])
    auto_detected BOOLEAN NOT NULL DEFAULT FALSE,  -- 自动探测创建(重新探测时覆盖,用户编辑后不回写)
    sort_order    INTEGER NOT NULL DEFAULT 0,
    created_at    TEXT NOT NULL,
    updated_at    TEXT NOT NULL
);

CREATE INDEX idx_project_modules_project ON project_modules(project_id);
```

### 3.2 设计原则

| 字段 | 来源 | 说明 |
|---|---|---|
| name | 用户/探测 | 工程名称 |
| path | 用户 | 工程目录(必填,等于 .git 所在目录) |
| git_url | 用户 | Git 远程地址(可选,单机可不填) |
| stack | 探测+用户可改 | 技术栈 JSON(探测 Cargo.toml/package.json 填充默认,用户可覆盖) |
| auto_detected | 系统 | true=自动探测创建;重新探测时只覆盖 auto_detected=true 的行 |
| sort_order | 系统 | 列表排序 |

**Git 状态实时派生(不存表)**:分支/改动文件/最近提交 → 查询时跑 git 命令返回。

---

## 四、Git 状态查询

### 4.1 get_module_git_status(module_id) 返回结构

```json
{
  "branch": "main",
  "remote": "origin",
  "changes": {
    "modified": 3,
    "added": 1,
    "untracked": 2,
    "total": 6
  },
  "files": [
    { "path": "src/main.rs", "status": "M" },
    { "path": "Cargo.toml", "status": "M" },
    { "path": "README.md", "status": "??" }
  ],
  "last_commit": {
    "hash": "abc1234",
    "message": "feat: add login",
    "author": "lxy",
    "date": "2026-06-29T10:00:00"
  }
}
```

### 4.2 实现方式

在工程目录(module.path)执行:
- `git branch --show-current` → 当前分支
- `git remote get-url origin` → 远程地址(与 module.git_url 互补)
- `git status --porcelain` → 改动文件列表(解析为结构化)
- `git log -1 --format=...` → 最近提交

所有 git 命令包 10s timeout。无 .git 目录返回空状态。

---

## 五、文件浏览器(IPC + UI)

### 5.1 get_module_file_tree IPC

```rust
get_module_file_tree(module_id, sub_path?, depth?) → FileTreeResponse
```

返回文件列表 + Git 状态合并(一次查询)。文件树懒加载:默认展开 2 层,点击展开加载子目录。

噪音过滤:跳过 node_modules / target / .git / __pycache__ / dist / .vite。

### 5.2 UI 结构

```
项目详情页 → 文件 Tab
┌──────────────┬──────────────────────────────────┐
│ 文件树       │ 文件内容预览                      │
│              │                                  │
│ 📁 src/      │  1  use std::...;                 │
│   main.rs  M │  2  fn main() {                  │
│   config.rs  │  3      println!("hello");       │
│ 📁 tests/    │  4  }                            │
│ Cargo.toml A │                                  │
│              │  main.rs · 2.1 KB · 已修改        │
└──────────────┴──────────────────────────────────┘
```

Git 状态标记:M(橙色=已修改) / A(绿色=已新增) / ??(灰色=未跟踪)。

### 5.3 单工程退化

项目只有 1 个工程时不显工程选择器,直接展示文件浏览器。

---

## 六、创建项目适配

create_project 时自动建一个工程:
- name = 项目名
- path = 绑定目录
- stack = 探测结果(复用现有 detect_stack)
- git_url = 探测(git remote get-url origin,失败为 None)
- auto_detected = true

用户后续可添加更多工程(多工程场景)。

---

## 七、AI 工具

### 7.1 只读工具(Batch 9 随数据层一起注册)

| 工具 | 功能 | 风险 |
|---|---|---|
| list_project_modules | 列出项目工程列表 | Low |
| get_module_git_status | 查询工程 Git 状态 | Low |

### 7.2 Git 工具(后续批次)

| 工具 | 功能 | 风险 |
|---|---|---|
| git_status | 工作区状态(结构化) | Low |
| git_diff | 未提交改动详情 | Low |
| git_log | 提交历史 | Low |
| git_commit | 提交改动 | Medium |
| git_branch | 分支管理 | Medium |
| git_merge | 合并分支 | High |

安全边界:禁止 push / force / reset --hard。

---

## 八、实施批次

| 批次 | 内容 |
|---|---|
| Batch 9 | 工程表 + CRUD IPC + Git 状态查询 + 创建项目适配 + AI 工具注册 |
| Batch 10 | 文件浏览器 UI(工程选择 + 文件树 + Git 状态标记 + 内容预览) |
| Batch 11 | Git 只读 AI 工具(status/diff/log) |
| Batch 12 | Git 写 AI 工具(commit/branch/merge) |