Metadata-Version: 2.5
Name: faker-plus
Version: 2.0.0
Summary: AI-powered test data generation agent for relational databases — TUI, auto FK inference, transactional write-back
Project-URL: Homepage, https://gitee.com/unigood/faker-plus
Project-URL: Repository, https://gitee.com/unigood/faker-plus
Author-email: unigood <unigood@gitee.com>
License: MIT
Keywords: database,faker,mock-data,sqlalchemy,test-data,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: litellm>=1.40
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pymysql>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: textual>=0.80
Provides-Extra: code
Requires-Dist: tree-sitter-java>=0.21; extra == 'code'
Requires-Dist: tree-sitter-languages>=1.10; extra == 'code'
Requires-Dist: tree-sitter-python>=0.21; extra == 'code'
Requires-Dist: tree-sitter>=0.22; extra == 'code'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: testcontainers[mysql]>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <p>
    <a align="center" href="https://gitee.com/unigood/faker-plus" target="_blank">
      <img width="100%" src=".images/splash.png">
    </a>
  </p>
  <h1>Faker-Plus 2.0 — 测试数据生成智能体</h1>
  <p><b>连接数据库 → 智能推断表关联 → 可视化确认 → 生成精准匹配的测试数据 → 事务写回</b></p>
  <p>Python 3.11 · Textual TUI · SQLAlchemy · 零 GUI 依赖</p>
</div>

---

开源的**测试数据生成智能体工具**:连接数据库 → 选中若干表 → 自动读取项目源代码推断表关联关系 →
展示完整关联图并确认生成范围 → 生成与库中已有数据格式/分布精确匹配的测试数据 → 事务写回。

## 版本演进

### v1.0.0 — Faker-Plus(Web 图形界面版)

第一代产品,基于 **Spring Boot 2.x + Vue2/ElementUI** 的数据库测试数据批量生成工具:

- **Web 双端**:浏览器操作,连接管理、表树浏览、逐列配置生成规则
- **生成类型 40+**:三级级联选择(通用 / 中文 / 英文)——自增、UUID、姓名、手机号、身份证(MOD 11-2 校验)、银行卡(Luhn 校验)、车牌号等
- **AI 智能数据**:字段配置提示词按批次请求大模型,程序校验 + 失败回退规则生成
- **异步任务**:大批量自动转异步,taskId + 进度轮询
- **多表外键关联**:全局变量 + 短板法则对齐

v1 验证了「规则库 + AI 兜底」的数据生成内核,但也暴露了 Web 形态的天花板:**表关联要靠人工逐列配置**,
无法理解项目源码;部署重(JDK + Maven + Node + MySQL 元数据库),个人开发者用起来门槛高。

### v2.0.0 — Faker-Plus(全面重构,智能体化)
推倒重来,以「智能体」思路重构为开箱即用的终端工具(Python + Textual TUI):

| | v1.0.0 Faker-Plus(Web 版) | v2.0.0 Faker-Plus(TUI 版) |
|---|---|---|
| 形态 | Spring Boot + Vue Web 应用 | 单一 Python TUI,`faker` 一条命令即用 |
| 表关联 | 人工逐列配置 | **自动推断**:DB 外键 + 项目源码 AST/正则分析(MyBatis XML、JPA 注解、ORM 模型),置信度标注 |
| 关系可视化 | 无 | 关联图面板,上游/下游一目了然,`[DB-FK]` / `[Code-FK 0.8]` 标注 |
| 数据匹配 | 靠规则类型人工挑选 | **采样驱动**:读取库中真实数据分布,生成值与已有数据格式/风格精确匹配(含中文、枚举、唯一列去重、BLOB 二进制) |
| 写入方式 | 分批独立事务(中断留半截数据) | **拓扑序 + 单事务写回**,FK 依赖自动排序,失败整体回滚零残留 |
| 部署 | JDK + Maven + Node + MySQL | `uv sync` 一条命令 |

## 截图

**关联确认**——自动推断的表关联图(`[DB-FK]` 数据库外键 / `[Code-FK 0.8]` 源码推断),
空格裁剪表、设定每表行数:

![关联确认](docs/images/tui-relations.png)

**生成写回**——事务写回结果与数据质量自检报告(FK 完整性 / 枚举合法 / UTF-8 中文 / PK 唯一):

![生成写回](docs/images/tui-writeback.png)

## 快速开始

无需下载源码,直接从 PyPI 安装:

```bash
pip install faker-plus        # 或 uv tool install faker-plus / pipx install faker-plus

faker                         # 在任意目录启动 TUI
```

首次启动三步完成(全部可在界面里配,不用改任何配置文件):

1. **连接页**粘贴数据库连接串(连接串里的密码按原样填即可),回车测试连接
2. 项目源码目录**默认自动检测当前目录**(识别 pom.xml / pyproject.toml / src 等,可留空只用 DB 外键)
3. **LLM 无需配置**:不填 Key 自动用纯规则模式(采样驱动,生成质量已实战验证);想启用 AI 文本生成时,连接页按 `Ctrl+S` 填 OpenAI 兼容端点即可

<details>
<summary>开发者方式(源码运行)</summary>

```bash
git clone https://gitee.com/unigood/faker-plus.git
cd faker-plus
uv sync --extra code --extra dev
uv run faker
```

</details>

界面流转:**连接**(输入连接串,测试连接;`Ctrl+S` 全局设置)→ **选表**(树形多选 + 右侧列/PK/FK/采样摘要,
支持搜索过滤)→ **关联确认**(上游/下游关联图,边标注 `[DB-FK]` / `[Code-FK 0.8]`,
空格裁剪表,设定每表行数)→ **生成**(策略匹配 + 规则/LLM 生成)→ **写回**(拓扑序 + 事务,
附质量核验报告)。

快捷键:方向键移动 · `空格` 勾选/裁剪 · `Ctrl+S` 设置页 · `Ctrl+G` 下一步 · `Esc` 返回 · `Ctrl+Q` 退出。

## 工作原理

1. **内省与采样**:读取 information_schema 获取表/列/PK/显式 FK 元信息,每列采样真实数据学习分布
2. **源码关联分析**(可选):对项目源码做三级检索(SQL JOIN → ORM 注解 → 词法匹配)+
   tree-sitter AST 解析(Java: JPA/MyBatis-Plus/MyBatis XML;Python: SQLAlchemy/Django),
   推断数据库里没有声明的逻辑外键;LLM 单次调用合并残余片段(置信度 ≤ 0.5),无 LLM 配置则跳过,token 消耗为 0
3. **策略匹配**:每列按类型/命名/注释/采样自动选择生成策略——自增 PK、UUID、雪花 ID、外键引用、
   枚举复用、格式列(邮箱/手机/URL/日期/JSON/二进制)、中文文本、数值边界(DECIMAL 按精度)
4. **生成与写回**:按拓扑序生成(环检测 + 自引用回填),单事务写回,任一失败整体回滚
5. **质量核验**:写回后自检 FK 悬挂 / 枚举非法 / UTF-8 乱码 / PK 重复,出报告

置信度:DB 显式外键 `1.0` > 显式注解 `0.95` > SQL JOIN `0.8` > 命名约定 `0.6` > LLM 推断 `0.5`。

## 配置项

| 环境变量(`FAKER_` 前缀) | 默认值 | 说明 |
|---|---|---|
| `FAKER_DATABASE_URL` | `""` | SQLAlchemy 连接串(MySQL/PostgreSQL/SQLite;Oracle/SQL Server 实验性) |
| `FAKER_PROJECT_DIR` | `""` | 待分析的项目源码根目录(可为空,则只做 DB 外键推断) |
| `FAKER_LLM_BASE_URL` / `FAKER_LLM_MODEL` / `FAKER_LLM_API_KEY` | `""` | OpenAI 兼容端点(litellm);留空自动降级为纯规则模式 |
| `FAKER_SAMPLE_ROWS` | `100` | 每列采样行数 |
| `FAKER_MAX_FILES_PER_TABLE` | `50` | 每表参与源码解析的文件数上限 |

配置文件 `~/.faker-plus/config.yaml` 的键名与上表去掉前缀后一致,可被环境变量覆盖。
**所有配置项都可以在 TUI 界面里修改**:连接页按 `Ctrl+S` 打开设置页(连接串 / 源码目录 /
LLM 端点与 Key / 采样行数 / 文件上限),保存即写入配置文件并即时生效——不记环境变量也能用。

> **不配 LLM Key 能用吗?** 能。LLM 只用于「源码残余片段消解 + 中文文本生成」两个可选环节,
> 留空时自动跳过:关联推断走 DB 外键 + 源码 AST/规则(零 token),文本列走采样驱动的规则生成。
> 实战验收(RuoYi-Vue 28 表三轮)全程未配 Key。

## 架构

```
src/faker_plus/
├── cli/            # Textual TUI(入口),只消费 core 公开接口
│   ├── app.py            # 主应用 + 深色主题 CSS
│   └── screens/          # connect / tables / graph / progress / result 五屏
├── core/           # 纯逻辑,零 UI 依赖(可被未来 server/MCP 复用)
│   ├── introspector.py   # SQLAlchemy 内省:表/列/PK/显式 FK/行数 + 取样
│   ├── sampling.py       # 采样画像:UUID 风格/枚举/长度/中英文占比/自增
│   ├── codeanalyzer/     # 源码关联分析(检索零 token + AST 解析 + 单次 LLM 消解)
│   ├── graph/            # 关系图模型 / 边合并 / Kahn 拓扑 + Tarjan 环检测
│   ├── generator/        # matcher 策略匹配 / rules 规则生成器 / llm 文本生成 / engine
│   ├── writer.py         # 拓扑序事务写回 + 质量核验
│   └── relations.py      # 关联分析编排(内省 + 源码 -> RelGraph)
├── llm/            # litellm 封装(配置/重试/超时)
└── config.py       # pydantic-settings 配置
```

分层红线:`core` 不 import 任何 UI 代码(有测试强制校验)。

## 开发与测试

```bash
uv run ruff check          # 静态检查
uv run pytest -q           # 单元测试(142 个,不依赖真实数据库)
uv run python scripts/e2e_m2.py            # M1+M2 真机集成验证(sqlite 全流程 + 截图)
MYSQL_ROOT_PASSWORD=*** uv run python scripts/e2e_m2.py   # 追加 MySQL 8 真库内省验证
FAKER_MYSQL_URL=... uv run python scripts/e2e_m3.py   # M3 真库生成/写回 E2E(临时库,不碰源库)
```

`scripts/e2e_m2.py` 会:建 sqlite 真文件库 + 内嵌 mini Java 项目 → pilot 驱动 TUI 走通三屏 →
逐项断言关联图与置信度 → 输出截图 `docs/e2e_m2.svg`。MySQL 凭据来自
`FAKER_MYSQL_URL` 或 `MYSQL_HOST/MYSQL_PORT/MYSQL_USER/MYSQL_PASSWORD/MYSQL_DB`,
缺凭据自动跳过。

`scripts/e2e_m3.py` 会:复制 DDL + 种子数据到临时库 `faker_m3_e2e_<ts>` → 走生成 →
拓扑序事务写回 → 核验本次生成行(FK/枚举/中文/PK)→ TUI 结果页截图 `docs/e2e_m3.svg` → 清理临时库。

## 实战验收

以 Gitee 经典开源项目 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue)
(Spring Boot 权限管理系统,28 张表)为实战对象完成三轮真库测试:

- 10 张核心表 × 50 行,生成 0.2s、写回 3.1s
- 8 组逻辑外键关联 **0 悬挂**(含 `sys_dept` 自引用、`sys_dict_data.dict_type` 字符串关联)
- 中文字段 HEX 校验 **0 乱码**,PK **0 重复**
- 注入超长坏值验证:事务整体回滚,库状态零残留

设计文档见 `docs/superpowers/specs/2026-10-19-dataforge-v2-design.md`,
实施计划见 `docs/superpowers/plans/`。

## License

MIT
