reglow-library 后端基础库

reglow-library 是 Reglow 的后端基础库，同一套架构与 API 契约，提供 Python / Node.js / Java / Rust 四种语言实现，全部已发布到对应生态的包仓库，开箱即用。

当前版本：0.14.3（Python；Node.js / Java / Rust 为 0.14.2）。详见 更新日志。

核心设计理念：

• 一套契约，四处实现：四种语言对外暴露一致的 REST API、统一响应格式与数据权限模型
• 基础库 + 业务分离：通用能力全部在库内，业务工程只保留自己的 app/ / modules/ 代码
• 两端分离：管理端（admin）与用户端（client）API 独立分层
• 三维权限：菜单权限 + 按钮权限 + 数据权限（部门 / 本人 / 自定义范围）

四语言实现

Java 版父 POM 为 tech.huoli.reglow:reglow，业务依赖 reglow-core / reglow-common / reglow-modules（reglow-server 为应用入口，不发布）。

统一响应契约

{
  "code": 0,
  "success": true,
  "msg": "操作成功",
  "data": {}
}

• 成功：code: 0，success: true
• 失败：code: 非 0，success: false，data: null
• 分页：data: { "items": [], "total": 100, "page": 1, "size": 10 }

依赖 code==1 判断成功的老版本前端需升级（配合 @reglow/design v0.2.0+）。

通用模块（34 个，四语言 L2 同构）

核心能力：

• RBAC + 数据权限：菜单 / 按钮 / 数据三级权限，支持部门及以下 / 本人 / 自定义范围
• 多端会话：基于 Redis 的有状态会话，多端登录互斥、可强制下线
• 存储抽象：本地 / S3 / 对象存储自动切换
• 多服务商集成：短信（阿里 / 腾讯 / 华为 / Mock）、AI 大模型（DeepSeek / 阿里 / 火山 / 腾讯 / 智谱 / Kimi）、支付（微信 / 支付宝 / 银联）
• 智能客服：内置可嵌入的 sdk_template（悬浮窗 / SSE 流式 / WebSocket / 图片上传 / 满意度评价）；转人工支持坐席并发容量（默认 5）、FIFO 派单、排队位次推送与 GET /cs/queue-status 轮询
• 多租户双轨：DEPLOY_MODE=single_tenant|saas_multi_tenant，JWT claim → X-Tenant-Id 优先级解析、fail-closed、startupGuard
• AI 用量与计量：六种计价模式、峰谷档位、价格快照、XLSX/CSV 导入导出、官方价格同步
• 流程审批：workflow 提供 JSON DSL（start / approve / end 节点、条件求值、串行推进、任务审批）
• 可观测性：结构化日志、健康检查、指标

快速开始

Python（FastAPI）

pip install reglow

from reglow.server import create_app

app = create_app()   # 自动加载基础模块路由

Node.js（Fastify）

npm install @reglow/reglow

import {
  knex,
  getDb,
  settings,
  logger,
  ApiResponse,
  PageData,
  discoverRouters,
  discoverClientRouters,
  autoInitDatabase,
} from "@reglow/reglow";
// 应用侧用 Fastify 组装实例 + 自动发现路由，参考 reglow-tsproject-starter

Java（Spring Boot）

<parent>
  <groupId>tech.huoli.reglow</groupId>
  <artifactId>reglow</artifactId>
  <version>0.14.2</version>
  <relativePath/>
</parent>

Rust（axum）

[dependencies]
reglow = "0.14"

use reglow::server::build_app;

// db: sea_orm::DatabaseConnection（由应用初始化）
let app = build_app(db);

跨语言契约

跨语言必须一致的内容集中在仓库 contract/ 目录，新增或修改需与代码同 PR：

「四语言完全对齐」的判据是基础发行包 reglow：对齐粒度 = 模块清单 + API 契约 + 数据模型 + 行为语义，不等于代码逐行一致。AI-Native 生成能力（Schema DSL / 生成引擎 / Agent 运行时 / 评测集）自 0.6.0 起迁出为同仓库独立发行包 reglow-agent（Python-only），它是库的消费者，不是 Python 的对齐例外。

生态

• 前端基座库：@reglow/design、@reglow/reui
• 快速开发模板：reglow-pyproject-starter / reglow-tsproject-starter / reglow-jvproject-starter / reglow-rsproject-starter
• 管理端参考实现：reglow-admin-python / reglow-admin-nodejs / reglow-admin-java / reglow-admin-rust

源码：gitee.com/reglow-ai/reglow-library