# wbr_ai_stack

**Repository Path**: ycdtbs/wbr_ai_stack

## Basic Information

- **Project Name**: wbr_ai_stack
- **Description**: 测试啊啊啊啊啊啊啊啊啊
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-15
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数据智能中台

基于本仓库管理后台脚手架构建的 **数据智能中台**：面向业务系统、数据大屏、报表系统与第三方应用的数据解读、图表分析与报告生成服务平台。

## 产品能力（MVP）

| 模块 | 说明 |
|------|------|
| 图表数据解读 | 提交 ECharts Option / 表格 JSON，自动归一化 → 匹配分析规则 → 算子计算 → 大模型解读 |
| 分析规则管理 | 配置图表类型、算子组合与参数、Prompt 模板、输出格式、校验规则（内置折线/柱状/饼图示例规则） |
| 算子计算层 | 12 个内置确定性算子：基础统计、总量占比、同环比、TOP N、趋势、波动、异常点、阈值、排名变化、结构占比、多维交叉、时序趋势 |
| Prompt 模板 | 业务角色 / 分析目标 / 输出结构 / 禁止项可配置，与规则联动 |
| 报告模板 | 章节结构 + dataKey 数据约定 + 规则绑定 + 章节 Prompt，模板化生成报告 |
| 报告生成 | 异步任务，输出 HTML / Word(docx) / Markdown / JSON，支持在线预览与下载 |
| 任务中心 | 解读任务、报告任务、模型调用日志（Token 消耗）、算子执行日志、失败重试 |
| API 服务化 | API Key 应用管理、X-API-Key 鉴权、限流、调用统计与日志，开放 `/api/v1/open/*` 接口 |

后端模块在 `apps/api/src/modules/`（operators / llm / analysis-rules / prompt-templates / chart-analysis / report-templates / reports / task-center / open-api），前端页面在 `apps/web/src/pages/datainsight/`，数据表使用 `di_` 前缀。

### 大模型配置

在 `apps/api/.env` 中配置 OpenAI 兼容接口（Qwen / DeepSeek / 私有化模型均可）：

```env
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_API_KEY=sk-xxx
LLM_MODEL=qwen-plus
```

未配置 `LLM_API_KEY` 时系统自动降级为「算子指标自动整理」模式，全链路仍可运行，便于离线开发与验收算子结果。

### 开放 API 速览（X-API-Key 鉴权）

```text
POST /api/v1/open/analysis/chart        图表数据解读
GET  /api/v1/open/analysis/status/:id   解读任务查询
POST /api/v1/open/report/generate       报告生成（异步）
GET  /api/v1/open/report/status/:id     报告状态查询
GET  /api/v1/open/report/download/:id   报告文件下载
GET  /api/v1/open/rules                 可用分析规则
GET  /api/v1/open/templates             可用报告模板
```

完整请求示例见管理端「API 应用 → 接口文档」。

---

# 数据问答 / NL2SQL 数据建模支撑平台

为 NL2SQL（自然语言转 SQL）提供**静态知识的管理与供给**：表结构语义、字段含义、枚举值、表间关联、业务术语、QA few-shot 样例，并通过 **MCP 服务**对外提供检索接口。意图识别、SQL 生成与执行由外部编排平台（如 Dify）完成。

```text
用户提问 → Dify 智能体 → 调用本平台 MCP 服务（Bearer Token 鉴权）
  ├─ search_few_shots(question)  → Top-N 相似 QA 样例
  ├─ search_tables(question)     → 相关表的 LLM 可读结构描述 + 命中术语
  └─ get_glossary(terms)         → 业务术语定义
→ Dify 将返回内容拼入提示词 → 大模型生成 SQL → add_few_shot 沉淀验证正确的样例
```

## 功能模块（一级菜单「数据问答」，与其他模块一致的两级菜单）

| 二级菜单 | 说明 |
|------|------|
| 数据问答 | P1 预留占位，本期不开发 |
| 语义建模 | 三栏页面：数据源（测试连接 / 加密存储）→ 数据表（information_schema 勾选添加，自动字段同步）→ 字段建模（业务名 / 语义类型 / 描述 / 枚举值采样 / LLM 可见开关 / 表间关系 / LLM 描述预览） |
| 项目管理 | 项目 = 数据范围 + QA 库 + Token。工作空间 3 个 Sheet：QA 样例（手工 + AI 辅助生成草稿人工采纳）、表信息（建模完成度 / 描述缓存刷新）、Token 管理（创建仅展示一次，列表脱敏） |
| 术语管理 | 业务术语 + 同义词，映射到字段 / 枚举值 / 计算口径，支持全局与项目级 |
| LLM 配置 | OpenAI 兼容接口配置（对话模型 / 嵌入模型分开管理），密钥加密存储，分别连通测试 |

## MCP 服务接入

- 端点：`POST http://<host>:3201/api/v1/mcp`（Streamable HTTP，JSON-RPC 2.0）
- 鉴权：`Authorization: Bearer <token>`，Token 在「项目管理 → Token 管理」创建，数据范围限定为所属项目
- 工具：`search_few_shots` / `search_tables` / `add_few_shot`（写入后停用，需人工审核启用）/ `get_glossary`
- 鉴权失败返回 HTTP 401；每次调用记录审计日志（token、工具、入参摘要、耗时）

```bash
curl -X POST http://localhost:3201/api/v1/mcp \
  -H 'Authorization: Bearer sk-xxx' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_few_shots","arguments":{"question":"上月华东销售额","top_n":3}}}'
```

## 检索与缓存实现

- **QA 相似检索**：优先使用 LLM 配置中的默认嵌入模型调用 `/embeddings` 端点生成 query 向量，再到 Milvus（默认 `192.168.3.53:19530` / database `default` / collection `vibe_admin`）按 `project_id + status=1` 做 TopK 召回；Milvus 不可用时自动降级为 MySQL 中 `nq_qa_example.embedding` 的应用内余弦相似度，再失败则用轻量分词关键词打分。MySQL 仍保存 QA 主数据和 embedding JSON，Milvus 作为向量索引。
- **表描述缓存**：表 LLM 描述文本（统一渲染格式）按「项目 × 表」缓存于 `nq_project_table`；表 / 字段 / 关系建模变更时自动失效，下次读取重建，也可在工作空间手动强制刷新。
- **安全**：数据源密码、LLM api_key 使用 AES-256-GCM 加密存储（密钥 `ENCRYPTION_KEY`，未设置时由 `JWT_SECRET` 派生）；枚举采样与元数据读取的表名 / 字段名经白名单校验后才拼入 SQL，参数一律绑定变量，建议数据源使用只读账号。

后端模块：`apps/api/src/modules/nl2sql/`；前端页面：`apps/web/src/pages/dataqa/`；数据表 `nq_` 前缀（11 张）。

---

# AI Vibe Coding Admin 脚手架

一个开箱即用的全栈管理后台脚手架，为 **AI Vibe Coding（让 AI 工程师快速写业务）** 而生。

项目目标是：AI 工程师拿到仓库后，不需要重新搭基础设施，只配置 MySQL，就可以直接在既有后台能力上开发业务模块。

已删除全部示例业务，只保留最核心、可复用的后台底座：

- 登录认证（JWT）
- 用户管理
- 角色管理（基于 RBAC）
- 菜单管理（页面在线新增菜单，前端动态生成路由）
- API 调用日志
- Prisma + MySQL 数据库访问

数据库结构、配置、初始化全部脚本化：填好数据库信息，一键初始化即可开始开发。

## 技术栈

- 前端：Arco Design Pro React、Vite、TypeScript
- 后端：NestJS、Prisma、MySQL、JWT、Passport
- 工程：npm workspaces、共享类型包、模块化目录

## 目录

```text
apps/api        NestJS 后端服务
apps/web        Arco Design Pro React 前端
packages/shared 前后端共享类型
scripts         初始化脚本
```

## 快速开始：只需要配置 MySQL

```bash
# 1. 安装依赖
npm install

# 2. 一键初始化（交互式输入数据库信息，自动写入 .env 并建表 + 初始化数据）
npm run setup

# 3. 启动前后端
npm run dev
```

默认地址：

- 前端：http://localhost:5174
- 后端：http://localhost:3201/api/v1
- 健康检查：http://localhost:3201/api/v1/health
- 默认数据库：MySQL，库名 `vibe_admin`

初始管理员：

```text
账号：admin
密码：admin123
```

## 初始化的两种方式

- **交互式（推荐）**：`npm run setup`，按提示输入 MySQL 主机/端口/用户名/密码/库名，脚本会自动写入 `apps/api/.env`、创建数据库、建表并初始化数据。
- **纯 .env 方式**：复制 `.env.example` 为 `apps/api/.env` 并填好 `DATABASE_URL`，然后执行 `npm run db:setup`（= generate + push + seed）。

> `npm run setup -- --yes` 可在已有 `.env` 时跳过交互直接初始化。

## 如何新增一个业务页面（Vibe Coding 流程）

1. 进入「系统管理 → 菜单管理」，点击「新增菜单」：
   - 类型选 `菜单`
   - 填写 **路由地址**（如 `/content/article`）和 **组件路径**（如 `content/article`）
   - 选择图标、设置排序
2. 在前端创建对应页面文件：`apps/web/src/pages/content/article/index.tsx`
3. 为需要看到该菜单的角色在「角色管理」里勾选授权
4. 刷新即可在左侧导航看到新菜单并访问

菜单完全存储在数据库中，前端登录后动态拉取菜单树并生成路由，无需改动路由代码。

## 给 AI 工程师的开发入口

请优先阅读 `AGENTS.md`。它定义了本脚手架的开发边界：

- 默认只使用 MySQL，不新增 SQLite/PostgreSQL/MongoDB 等数据库。
- 后端业务模块放在 `apps/api/src/modules/<module>`。
- 前端业务页面放在 `apps/web/src/pages/<module>/<page>/index.tsx`。
- 菜单和路由由数据库驱动，新增业务页面时先在菜单管理中登记 `path` 和 `component`。
- 共享类型放在 `packages/shared/src`，不要复制粘贴前后端 DTO 类型。

## 常用脚本

| 命令 | 说明 |
|------|------|
| `npm run setup` | 交互式初始化（写 .env + 建库 + 建表 + 种子数据） |
| `npm run dev` | 同时启动前后端 |
| `npm run dev:api` / `npm run dev:web` | 单独启动后端 / 前端 |
| `npm run db:setup` | 已有 .env 时一键 generate + push + seed |
| `npm run db:push` | 同步 Prisma schema 到数据库 |
| `npm run db:seed` | 写入初始角色、菜单、管理员 |
| `npm run typecheck` | 全量类型检查 |
| `npm run build` | 构建 shared + api + web |

## 许可证激活校验（可选）

脚手架默认关闭许可证校验：`LICENSE_ENABLED=false`。

如果你要把系统作为商业交付版本分发，可以开启许可证激活校验。开启后，服务在**每次启动时**会向认证授权服务中心
（`LICENSE_SERVER_URL`）注册当前部署的设备指纹，**校验失败（网络不可达 / 密钥错误 / 未授权）将导致服务拒绝启动**。

- 上报字段：`service_id`、`mac_address`、`ip_address`、`system_username`、`product_info`、`register_time`
- 鉴权：`X-API-Key` + 时间戳 + nonce + HMAC-SHA256 签名
- 实现：透明开源模块 `packages/license`，在 `apps/api/src/main.ts` 启动流程中调用
- 配置：见 `.env.example` 中的 `LICENSE_*`

> 该机制用于授权管理。由于会采集 MAC/IP 等设备信息并上报，请在向使用方分发软件时
> 在许可协议 / 部署说明中明确告知，并按所在地法律要求取得必要的同意。

### 打成独立二进制（可选）

```bash
npm run build:license-bin
```

会在 `apps/api/bin/` 生成原生可执行文件 `license-check`（基于 Node SEA），
可在系统/服务启动前调用，校验失败返回非 0 退出码以中止启动。
若当前环境无法生成原生二进制，会保留单文件包
`packages/license/build/license-check.cjs`（用 `node` 运行）。

## 数据库

仅依赖 MySQL。后端本地运行读取 `apps/api/.env`。