DevFlow/docs/02-架构设计/专项设计/工程系统设计-2026-06-29.md

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

创建: 2026-06-29 | 状态: ✅ Batch 9-13 已落地(工程表+文件浏览器+Git 状态/变更/提交历史) 关联: 项目知识图谱与任务队列系统-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 迁移)

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) 返回结构

{
  "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

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

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

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

5.2 UI 结构(当前)

项目详情页 → 文件 Tab
┌─────────────────────────┬──────────────────────────────────────┐
│ [📁] [📝 3] 视图切换    │ 文件内容预览                          │
│ ─────────────────────── │                                      │
│ 📁 文件树/变更列表      │ 行号 │ 代码(语法高亮 + 行号)          │
│   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 · 📝 查看变更       │
└─────────────────────────┴──────────────────────────────────────┘

视图切换: 左侧栏顶部两个图标按钮:

• 📁 文件树视图(默认)
• 📝 变更视图(带变更数量角标)

变更视图:

• 变更文件列表(按状态分组:已修改/已新增/已删除/未跟踪)
• 文件按目录深度缩进(src/components/Foo.vue → 缩进 2 层)
• 点击文件 → 右侧预览区显示 git diff(红删绿增)
• 顶部 Tab 切换至"历史":展示提交历史(每条显示 hash+主题+时间)
  • 初始 50 条,支持"加载更多"分页
  • 点击提交行 → 展开该提交的变更文件列表
  • 点击变更文件 → 展示该文件的 diff

内容预览增强:

• 行号列 + highlight.js 语法高亮(按文件后缀自动选语言)
• 按后缀彩色图标(rs/ts/js/vue/css/html/json/md/sh/sql 等)
• Diff 切换按钮(Git 状态不为空时在头部右侧显示 📝)
• 滚动条在预览区域内部,不溢出页面层

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)
Batch 13	文件浏览器增强(行号/图标/Diff/变更面板/窗口分离)

Batch 13 新增功能

功能	说明
行号显示	文件预览左侧显示行号列
后缀图标	rs/ts/js/vue/css/html 等 20+ 类型彩色 SVG 图标
Diff 视图	有 Git 变更的文件可切换内容/Diff 红绿视图
Git 变更面板	文件树侧栏可切换至变更视图,显示变更文件列表(按目录缩进分组)
提交历史分页	展示最近 50 条提交,支持加载更多(分页)
提交详情	点击提交行展开变更文件列表,点文件查看 Diff
提交时间显示	相对时间(刚刚/N分钟前)+超过30天显示具体日期
窗口分离	文件浏览器可弹出独立 Tauri 窗口
中文编码修复	git 命令注入 LANG/LC_ALL UTF-8 环境变量
多工程管理 UI	工具栏添加工程按钮 + 弹窗表单(名称/路径/Git地址)
文件变更自动刷新	write_file/patch_file 触发 df-data-changed 事件推送