CarlLee1983/archivolt

# 🏛️ Archivolt **Archivolt** 是一款本地可视化与注释工具，旨在帮助遗留项目的开发者理解、记录并导出数据库关系。 在许多遗留系统中，数据库存在大量“隐式关系”——例如名为 `user_id` 的列，但在数据库引擎中并没有实际的外键支持。Archivolt 提供了一个可视化界面来注释这些关系，并将其导出为现代 ORM 格式或 ER 图。 ## ✨ 功能特性 - **可视化数据库浏览器**：基于 [ReactFlow](https://reactflow.dev/) 构建，提供可交互和可缩放的 Schema 可视化。 - **虚拟外键 (vFK)**：在不修改生产数据库 Schema 的情况下，注释表之间的“隐式”关系。 - **智能表分组**：利用现有外键、列命名模式（例如 `_id` 后缀）和表前缀自动对表进行分组，使大型 Schema 易于管理。 - **多格式导出器**： - **Eloquent (PHP)**：生成包含 `$fillable`、`$casts` 和关系方法（`belongsTo`、`hasMany` 等）的 Laravel 模型。 - **Prisma**：生成包含数据源和模型关系的 `schema.prisma` 文件。 - **DBML**：导出为兼容 [dbdiagram.io](https://dbdiagram.io) 的格式。 - **Mermaid**：生成 ER 图语法，以便嵌入 Markdown 文档。 - **查询记录与分块**：运行 TCP 代理以捕获实时数据库查询。根据交互时间和浏览器事件自动将查询分组为逻辑“块”。 - **Chrome 扩展集成**：捕获浏览器事件（点击、fetch、导航），以便与数据库记录同步，实现端到端调试。 - **Archivolt Doctor**：内置诊断工具，用于验证环境健康状况、依赖项和数据完整性，并提供交互式自动修复建议。 - **强大的 CLI**：将带有注释的 Schema 直接导出到文件，或通过 Artisan 与 Laravel 项目集成。 - **实时持久化**：更改会即时保存到本地 `archivolt.json`，该文件作为唯一可信数据源，同时也易于 LLM 读取。 ## 🚀 快速入门 ### 前置条件 - [Bun](https://bun.sh) (v1.0.0 或更高版本) - [dbcli](https://github.com/CarlLee1983/dbcli) (用于将数据库 Schema 提取为 JSON) ### 安装 1. 克隆仓库： git clone https://github.com/intellectronica/archivolt.git cd archivolt 2. 安装依赖： bun install ### 使用方法 1. **导入数据库 Schema**： Archivolt 使用 [dbcli](https://github.com/CarlLee1983/dbcli) 输出的 JSON 数据。 # 使用 dbcli 提取 Schema dbcli schema --format json > my-database.json # 导入到 Archivolt bun run dev --input my-database.json *注意：使用 `--reimport` 可以在保留现有注释的同时更新表/列信息。* 2. **启动可视化界面**： 上述命令会启动 API 服务器。你还需要运行 Web 前端： bun run dev:all 在浏览器中打开 [http://localhost:5173](http://localhost:5173)。 3. **记录数据库查询**： Archivolt 可以充当应用程序与数据库之间的 TCP 代理，实时捕获所有查询，无需数据库凭据 —— 身份验证直接在你的应用与目标数据库之间进行。 # 开始记录 —— 直接指定目标数据库 bun run dev record start --target localhost:3306 # 或者从 .env 文件读取 DB_HOST / DB_PORT bun run dev record start --from-env /path/to/.env --port 13306 然后将应用程序的数据库连接指向 `127.0.0.1:13306`（或你指定的端口）。按 `Ctrl+C` 停止。 # 管理记录会话 bun run dev record status # 检查记录是否处于活动状态 bun run dev record list # 列出所有会话 bun run dev record summary # 查看某个会话的查询统计 4. **通过 CLI 导出**： # 导出到 Laravel Eloquent 模型 bun run dev export eloquent --laravel path/to/laravel-project # 导出到 Mermaid ER 图 bun run dev export mermaid --output ./docs/schema ## 🗺️ 项目结构 - `src/Modules/Schema`: 核心业务逻辑（DDD 优先结构）。 - `Domain`: ER 模型实体和分组策略。 - `Application`: 用于导入、管理 vFK 和导出的服务。 - `Infrastructure`: JSON 持久化、导出器（Eloquent、Prisma 等）和文件写入器。 - `web/`: React + ReactFlow 前端应用。 - `extension/`: 用于捕获浏览器事件的 Chrome 扩展。 - `archivolt.json`: 用于存储注释的本地数据存储。 ### 详细文档 - [概述与技术栈](docs/overview.md) - [架构](docs/architecture.md) — 后端 DDD 模块、前端、Chrome 扩展、数据流 - [命令](docs/commands.md) — 完整 CLI 参考 - [测试](docs/testing.md) — 如何运行和编写测试 - [规范](docs/conventions.md) — 编码标准和模式 - [工作流 (中文)](docs/WORKFLOW.zh-TW.md) ## 📜 许可证 [MIT](LICENSE)

标签：Beacon Object File, DBML, DevOps工具, ER模型生成, Homebrew安装, HTTP工具, Laravel Eloquent, Mermaid, ORM导出, Prisma, ReactFlow, SQL记录, TCP代理, 全栈调试, 数据库可视化, 数据库文档生成, 数据库模式管理, 数据库迁移, 数据库逆向工程, 查询分析, 自动化攻击, 虚拟外键, 遗留系统重构