# ddtable-tools

**Repository Path**: tangshitai/ddtable-tools

## Basic Information

- **Project Name**: ddtable-tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-27
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ddtable-tools 项目说明（全量源码深读版）

本仓库是一个“动态逻辑表管理工具集”，由后端 Spring Boot Starter、前端 Vue 组件模块与 Demo 工程组成。  
本说明文档基于本次全量源码深读产出，并与 `docs/需求说明.md` 保持同步。

## 1. 项目结构

- `backend/dynamic-table-spring-boot-starter`：**可交付**后端核心（Spring Boot Starter，Controller/Service/DAO/MyBatis XML/Schema）
- `frontend/dynamic-table-module`：**可交付**前端组件（分类管理、数据管理、字段输入组件）
- `demo/backend-demo`：本地联调用后端宿主（H2、演示种子、`/api/demo/*`），**不纳入**根 `pom.xml` 的 `<modules>`，不参与业务系统打包
- `demo/frontend-demo`：本地联调用前端壳子（路由 + 侧栏演示初始化图标），依赖 `file:../../frontend/dynamic-table-module`
- `docs`：需求与使用文档

**Maven 约定**：仓库根目录 `pom.xml` **只聚合** `backend/dynamic-table-spring-boot-starter`。发布或安装 Starter 时在根目录执行 `mvn install` 即可；构建/运行演示后端前需保证本机已 `mvn install` 过父工程与 Starter（否则 `demo/backend-demo` 解析不到依赖）。

## 2. 技术与约束

- 后端：JDK 1.8、Spring Boot 2.7.13、MyBatis（SQL 仅在 XML）
- 前端：Vue 3 + Vite
- 默认演示数据库：H2（内存）
- 模块启用：宿主通过 `@EnableDynamicTableModule` 显式启用（不依赖 `spring.factories`）

## 3. 关键能力（当前实现）

- 分类/逻辑表/字段/关系/约束/索引管理
- 多数据库 DDL 预览（MySQL/PostgreSQL/Oracle）
- 数据分页查询、树查询、关系查询（含一对一/一对多/多对多）
- 批量删除、逻辑删除与恢复
- 长文本类型：
  - `RICH_TEXT`（富文本）
  - `CODE`（代码文本，支持语言配置 `code_lang`）
  - `MD_TEXT`（Markdown 文本）
- 二进制类型：
  - `FILE`（文件）
  - `IMAGE`（图片）
  - 二进制实体存储于 `dt_record_file_blob`，`dt_record_value` 存储元数据 JSON
- 图片预览支持：缩放、旋转、翻转、拖拽平移、ESC 关闭（列表/详情/编辑三处统一）

## 4. 本地启动

### 4.1 构建可交付后端（Starter）

在仓库根目录执行（仅编译打包 **Starter**，不包含 `demo/backend-demo`）：

```bash
mvn -DskipTests install
```

或只构建该模块：

```bash
mvn -pl backend/dynamic-table-spring-boot-starter -am -DskipTests install
```

### 4.2 启动 Demo 后端

需已按 **4.1** 将 Starter 安装到本地仓库。

```bash
cd demo/backend-demo
mvn spring-boot:run
```

默认地址：`http://localhost:18080`

### 4.3 启动前端模块与 Demo 前端

```bash
cd frontend/dynamic-table-module
npm install
npm run dev
```

```bash
cd demo/frontend-demo
npm install
npm run dev
```

默认地址：`http://localhost:15173`

说明：建议 Node 18+。侧栏顶部两个图标分别为 **演示初始化**（`POST /api/demo/init`）、**极限测试初始化**（`POST /api/demo/stress-init`）；成功后当前路由页会重挂载以刷新列表。

### 4.4 业务系统集成（摘要）

- **后端**：依赖 `dynamic-table-spring-boot-starter` 工件，勿依赖 `demo/backend-demo`。
- **前端**：发布或拷贝 `frontend/dynamic-table-module`，勿将 `demo/frontend-demo` 打入业务产物。

## 5. 接口风格（摘要）

- 以 `POST` 接口为主，业务入参使用 JSON body
- 文件上传接口使用 `multipart/form-data`
- 文件/图片下载返回二进制流
- 统一业务响应结构建议为：`code/message/data/requestId`

详细接口与字段约束见：`docs/需求说明.md`

## 6. 回归脚本

（需已启动 Demo 后端，且本机已 `mvn install` 过 Starter。）

- 冒烟脚本：`demo/scripts/smoke-test.ps1`
- FILE 最小回归：`demo/backend-demo/scripts/file-regression.ps1`

建议执行：

```powershell
powershell -ExecutionPolicy Bypass -File "demo/scripts/smoke-test.ps1"
powershell -ExecutionPolicy Bypass -File "demo/backend-demo/scripts/file-regression.ps1"
```

## 7. 全量源码深读结论（摘要）

本次已按“文本源码/配置/文档”进行全量逐文件阅读并形成专项报告，重点结论：

- 存在少量高优先级一致性风险（如记录值唯一约束与写入字段匹配、删除恢复归属校验）
- 存在中期性能风险（复杂关系查询、大数据列表渲染、大字段传输）
- 前端可维护性需继续优化（超大组件拆分、状态流简化）
- Demo 脚本与文档覆盖说明需继续收敛（覆盖边界、错误码断言、统计口径）

详见：`docs/guide/项目源码深度分析报告.md`

## 8. 文档索引

- 需求主文档：`docs/需求说明.md`
- 深度分析报告：`docs/guide/项目源码深度分析报告.md`
- Demo FILE 回归指南：`docs/guide/demo-FILE最小回归验证.md`
- 约束索引（及扩展）验证：`docs/guide/demo-约束索引视图验证.md`