# data-sys

**Repository Path**: ecky88/data-sys

## Basic Information

- **Project Name**: data-sys
- **Description**: 简单的数据系统，快速进行表格数据管理
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-10-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# data-sys 智能体过程数据存放与统计分析系统

这是一个本地优先、后续可迁移服务器的动态数据表平台，面向智能体推广过程中的过程数据存放、API 接入、查询和统计分析。

## 当前能力

- 默认无账号模式，便于本地快速使用；可选 MaxKey 登录与多账号资源隔离
- 通过 API 创建真实 PostgreSQL 数据表
- 自动记录表结构元数据
- 动态表数据写入、查询、修改、删除
- 可定制统计分析：趋势、分类对比、直方图、箱线图、散点图及保存分析视图
- 独立数据监控：事件驱动/定时检查、规则试运行、邮件/企业微信/Webhook、持久化投递与失败重试
- API 使用说明页面
- Vue 3 管理页面
- 本地直跑与 Docker Compose 两套启动配置

## 只读表结构

数据表管理每行的“表结构”入口打开右侧抽屉，保留列表位置。字段字典支持按字段、类型和说明搜索；索引与约束、DDL 分页展示。窄屏下字段自动切换为纵向属性列表。

`GET /api/tables/{table_name}/structure` 通过 data-sys 的 SQLAlchemy 会话读取实际数据库结构，只接受已登记的逻辑表名，不修改字段配置、物理结构或业务记录。返回系统字段、物理类型、可空性、主键、数据库默认表达式、索引、唯一/外键/检查约束，并单独附带登记的配置类型。未登记的物理字段、配置登记但物理表缺失的字段及可空性差异会明确标记。

SQLite 的 DDL 来自 `sqlite_master`；PostgreSQL 的 DDL 由实际结构反射生成，界面明确标注它不是原始建表文本。抽屉支持刷新、复制表名与 DDL，关闭或切换表会取消未完成的读取，避免旧响应覆盖新表。

验证：在 `backend` 运行 `.venv/Scripts/python.exe -m unittest discover -s tests -v`，在 `frontend` 运行 `npm run build`。

## 自定义统计分析

统计分析页面可按表选择字段、聚合方式、时间粒度、系列与筛选条件，预览五类图表，并查看统计结果和最多 50 条匹配明细。分析配置支持保存、修改、另存与删除，重新打开可直接重算当前数据。

第一版采用单表探索性分析。预览通过现有 DataSys 会话只读查询；保存配置写入独立的 `sys_analysis_views`，不复制或修改业务记录。空值、时区和完整数据范围有明确口径，大数据分布分析不会偷偷截断样本。原有 `/api/statistics` 接口保留。

接口、统计口径、数据量边界和验证方式见 [统计分析说明](docs/statistical-analysis.md)。

## 数据监控

“数据监控”提供规则、通知渠道和投递记录。每条规则可选择检测方式；记录数/数据停更使用定时检查，记录条件可选事件驱动。通知渠道由 data-sys 独立实现，不依赖 JinFlow，也没有站内通知；第一版不自动修改业务数据。

事件与业务写入同事务提交，专用任务队列不受审计清空影响，后台投递支持重试与重启恢复。敏感渠道配置加密保存，本地密钥文件须与数据库一起备份。配置、事件覆盖边界、部署与 API 见 [数据监控说明](docs/data-monitoring.md)。

## 系统设置与账号对接

“系统设置”提供账号对接、资源归属、认证记录和服务令牌。支持无账号、单账号管理（登录后共享资源）、多账号隔离三种模式。MaxKey 负责登录，DataSys 负责普通账号、管理员、超级管理员的本地权限。

升级和保存草稿不会启用登录，不改变现有业务表与 JinFlow 无认证 API 调用。只有通过当前草稿的超级管理员登录验证并明确启用，才切换模式。隔离模式的历史资源保留在系统空间，由超级管理员显式分配；管理员跨账号访问只读。

首次配置、MaxKey 要求、权限边界、程序接入和备份恢复见 [账号对接说明](docs/account-integration.md)。

## 技术栈

- 后端：FastAPI + SQLAlchemy Core
- 数据库：本地直跑默认 SQLite，Docker 部署默认 PostgreSQL
- 前端：Vue 3 + TypeScript + Element Plus + ECharts
- 部署：Docker Compose

## 运行方式边界

data-sys 当前有两套运行方式，参数不能混用：

| 运行方式 | 用途 | 前端端口 | 后端端口 | 数据库 | 配置来源 |
| --- | --- | ---: | ---: | --- | --- |
| 本地直跑 | JinFlow 本机开发/采样配套 | `6881` | `5955` | SQLite：`var/sqlite/data_sys.db` | 根目录 `.env` / `.env.example` |
| 标准部署 | 独立 data-sys 部署 | `5173` | `8000` | PostgreSQL Docker 命名卷 | `docker-compose.yml` / `DOCKER_*` |

标准部署不是本地直跑参数的简单换端口版；它由三套 Docker 服务/镜像组成：`postgres`、`backend`、`frontend`。本地直跑的 `FRONTEND_PORT`、`BACKEND_PORT`、`DB_TYPE=sqlite` 只服务于本机调试，不参与标准 Docker 部署。

## 快速启动

### 本地直跑：SQLite + 6881/5955

本地直跑使用根目录 `.env`，如果 `.env` 不存在，脚本会自动从 `.env.example` 复制一份。

默认配置：

- 前端页面：http://localhost:6881
- 后端 API：http://localhost:5955
- Swagger 文档：http://localhost:5955/docs
- 数据库：SQLite，文件位于 `var/sqlite/data_sys.db`

```powershell
cd data-sys
scripts\start-data-sys-local-env.bat
```

本地直跑需要 Node.js/npm；首次运行会在 `frontend` 下安装前端依赖。启动脚本会分别检查后端与前端健康状态，缺哪个启动哪个；后端/前端后台窗口会隐藏，日志在 `work/logs`。停止本地直跑服务：

```powershell
scripts\stop-data-sys-local-env.bat
```

如需调整本地端口或数据源，只改根目录 `.env`。该文件已被 Git 忽略，不会显示为待提交变更。

### 标准 Docker 部署：三服务/三镜像

确保已安装 Docker Desktop。

```bash
cd data-sys
docker compose up -d --build
```

访问：

- 前端页面：http://localhost:5173
- 后端 API：http://localhost:8000
- Swagger 文档：http://localhost:8000/docs

Docker 部署参数保留在 `docker-compose.yml` 的默认值中，不会被本地 `.env` 的 `FRONTEND_PORT`、`BACKEND_PORT`、`DB_TYPE` 污染。需要覆盖 Docker 部署参数时，使用 `DOCKER_*` 环境变量，例如 `DOCKER_FRONTEND_PORT`、`DOCKER_BACKEND_PORT`、`DOCKER_DB_TYPE`。

标准部署包含三项服务：

- `postgres`：PostgreSQL 数据库，默认使用 `postgres_data` 命名卷。
- `backend`：FastAPI 后端，容器内端口 `8000`。
- `frontend`：Vue 管理前端，容器内端口 `5173`。

## 目录约定

- `backend/migrations/`：可提交的数据库结构脚本和迁移参考。
- `var/sqlite/`：本地直跑生成的 SQLite 数据文件，已被 Git 忽略。
- Docker 数据：PostgreSQL 使用 `postgres_data` 命名卷，SQLite 使用 `sqlite_data` 命名卷。

## 手动本地开发启动

### 后端

```powershell
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 5955
```

### 前端

```powershell
cd frontend
npm install
$env:VITE_API_BASE_URL="http://localhost:5955"
npm run dev -- --host 0.0.0.0 --port 6881 --strictPort
```

## API 示例

下面示例以本地直跑默认后端端口 `5955` 为例；Docker 部署时将端口改为 `8000`。

### 创建数据表

```bash
curl -X POST http://localhost:5955/api/tables ^
  -H "Content-Type: application/json" ^
  -d "{\"table_name\":\"agent_call_logs\",\"display_name\":\"智能体调用记录\",\"columns\":[{\"name\":\"agent_key\",\"type\":\"string\",\"length\":100,\"nullable\":false},{\"name\":\"called_at\",\"type\":\"datetime\",\"nullable\":false},{\"name\":\"duration_ms\",\"type\":\"integer\",\"nullable\":true},{\"name\":\"success\",\"type\":\"boolean\",\"nullable\":false,\"default\":true}]}"
```

### 写入数据

```bash
curl -X POST http://localhost:5955/api/tables/agent_call_logs/records ^
  -H "Content-Type: application/json" ^
  -d "{\"agent_key\":\"data-web-dev-agent\",\"called_at\":\"2026-07-02T15:30:00+08:00\",\"duration_ms\":1200,\"success\":true}"
```

### 批量写入

`POST /api/tables/{table_name}/records/batch` 接收 `records` 数组（1 至 500 条）和可选的 `idempotency_field`。幂等字段必须是已注册的文本或整数字段，每条记录的键值不能为空且必须匹配字段类型。整批使用统一数据库写事务，校验或写入失败时全部回滚，数据变更审计和监控事件同时回滚。

响应包含 `ids`、`accepted_count`、`inserted_count`、`duplicate_count`。重复键返回旧记录 ID，不更新旧记录，也不重复产生通知。指定幂等字段时自动创建普通查询索引，兼容已有表；并发批量请求在 SQLite 写锁 / PostgreSQL 表锁内进行查重和插入。未指定幂等字段时，保留普通插入语义。其他单条写入接口不受此查重约定约束。

批量接口沿用表的读取和写入权限，不绕过 MaxKey 账号隔离或服务令牌的资源授权。

## 设计原则

- 动态数据表统一使用 `data_` 前缀，例如 `agent_call_logs` 实际表名为 `data_agent_call_logs`。
- 外部传入的表名、字段名、字段类型全部做白名单校验。
- 默认无账号模式不适合直接暴露到公网；可显式启用 MaxKey 登录与受资源权限约束的服务令牌。