midway-fatcms 0.0.1-beta.82 → 0.0.2

package/README.md

@@ -1,8 +1,407 @@
-#midway-fatcms
+# Midway FatCMS
 
+**企业级低代码/零代码开发平台**
 
+基于 Midway.js 框架的多租户 SaaS 低代码平台，提供 API 网关、CRUD-Pro 引擎、工作流、文档管理等企业级功能。
 
-* 加密字段：
+## 项目简介
+
+Midway FatCMS 是一个功能完整的企业级低代码开发平台，旨在通过配置化的方式快速构建企业应用系统。系统核心特性包括：
+
+- **零代码 CRUD 开发**：通过配置自动生成 CRUD 接口
+- **动态 API 管理**：支持 SQL 查询、沙箱脚本、自定义代码三种 API 类型
+- **API 网关与代理**：反向代理、负载均衡、流量控制
+- **多租户架构**：基于域名的租户隔离，支持 SaaS 部署
+- **工作流引擎**：灵活的业务流程管理
+- **文档管理系统**：支持文档库、版本控制、权限管理
+- **文件服务**：OSS 对接、上传下载、预览管理
+
+## 核心功能
+
+### 1. CRUD-Pro 引擎
+
+**智能 CRUD 生成引擎**，提供配置化的数据库操作能力：
+
+- **标准化 CRUD**：基于表配置自动生成增删改查接口
+- **复杂查询支持**：分页、排序、筛选、关联查询
+- **字段级权限**：支持字段可见性、只读、必填等控制
+- **数据验证**：内置 20+ 种验证器（邮箱、手机号、日期等）
+- **关联关系**：自动处理一对一、一对多、多对多关系
+- **软删除**：支持逻辑删除和物理删除
+- **审计日志**：自动记录创建人、修改人、时间戳
+- **多数据库支持**：MySQL、PostgreSQL、SQL Server
+
+**应用场景**：
+- 快速搭建后台管理系统
+- 数据管理平台
+- 报表查询系统
+- 业务配置中心
+
+### 2. 动态 API 管理（Any API）
+
+**三种 API 创建方式**，满足不同复杂度需求：
+
+#### 2.1 SQL 查询 API
+- 直接编写 SQL，自动转换为 REST API
+- 支持参数化查询、防 SQL 注入
+- 适用于复杂报表、数据分析
+
+#### 2.2 沙箱脚本 API
+- 使用 Node.js VM 沙箱执行自定义代码
+- 提供安全的运行环境
+- 内置工具库（axios、lodash、moment 等）
+- 访问数据库、Redis、OSS 等资源
+
+#### 2.3 自定义代码 API
+- 完全自定义的业务逻辑
+- 类似 Serverless Function
+- 热更新，无需重启服务
+
+**安全控制**：
+- 权限验证（登录、角色、功能点）
+- 限流控制（令牌桶算法）
+- 服务降级开关
+- 超时控制
+- IP 黑白名单
+
+**应用场景**：
+- 快速开发业务接口
+- 数据聚合 API
+- 第三方集成
+- 微服务编排
+
+### 3. API 网关与代理
+
+**企业级 API 网关**，提供完整的代理转发能力：
+
+#### 负载均衡策略
+- 轮询（Round Robin）
+- 加权轮询（Weighted Round Robin）
+- 随机（Random）
+- 加权随机（Weighted Random）
+- IP Hash（同一 IP 固定路由）
+- 用户 Hash（同一用户固定路由）
+- 会话 Hash（同一会话固定路由）
+
+#### 流量控制
+- 请求限流
+- 超时控制
+- 重试机制
+- 熔断降级
+
+#### 安全特性
+- 真实 IP 透传
+- 用户上下文传递
+- Host/Origin 修改
+- 请求/响应头控制
+
+**应用场景**：
+- 微服务网关
+- 灰度发布
+- A/B 测试
+- 流量分发
+- 服务聚合
+
+### 4. 多租户架构
+
+**工作台（Workbench）系统**，实现完整的多租户隔离：
+
+#### 租户隔离机制
+- **域名识别**：根据请求域名自动识别租户
+- **数据隔离**：租户数据完全隔离
+- **权限隔离**：用户、角色、权限独立管理
+- **资源隔离**：文件、配置、应用独立
+
+#### 灵活配置
+- 支持主域名 + 2 个备用域名
+- 通配符域名支持
+- 租户模板机制
+- 个性化配置
+
+**应用场景**：
+- SaaS 平台
+- 多品牌运营
+- 集团企业
+- 白标产品
+
+### 5. 工作流引擎
+
+**灵活的业务流程管理**：
+
+- 流程定义与配置
+- 流程实例管理
+- 任务分配与审批
+- 流程状态跟踪
+- 流转记录查询
+
+**应用场景**：
+- 审批流程
+- 业务流转
+- 状态机管理
+
+### 6. 文档管理系统
+
+**企业级文档管理**：
+
+- **文档库管理**：支持多个文档库
+- **目录结构**：树形目录组织
+- **版本控制**：文档版本管理
+- **访问统计**：PV/UV 统计（IP 去重）
+- **权限控制**：文档级权限管理
+
+**应用场景**：
+- API 文档
+- 产品文档
+- 知识库
+- 帮助中心
+
+### 7. 文件服务
+
+**完整的文件管理能力**：
+
+- **上传下载**：支持单文件、多文件上传
+- **存储管理**：OSS 对接（公有桶、私有桶）
+- **文件预览**：图片、PDF、Office 文档
+- **访问控制**：临时链接、权限验证
+- **分类管理**：文件分类、标签
+
+### 8. 系统管理
+
+#### 用户权限管理
+- 用户账号管理
+- 角色管理
+- 功能点管理
+- 权限分配
+
+#### 应用管理
+- 应用列表
+- 应用页面管理
+- 菜单管理
+- 低代码模板
+
+#### 系统配置
+- 数据字典
+- 系统参数
+- 枚举管理
+- 定时任务
+
+#### 监控运维
+- 访问统计
+- 操作日志
+- 系统信息
+- 部署管理
+
+## 技术架构
+
+### 技术栈
+
+**后端框架**
+- Midway.js 3.x（企业级 Node.js 框架）
+- Koa（Web 框架）
+- TypeScript（类型安全）
+
+**数据存储**
+- MySQL 2（主数据库）
+- PostgreSQL 8（可选）
+- SQL Server 11（可选）
+- Redis（缓存、锁、会话）
+
+**文件存储**
+- 阿里云 OSS
+- 兼容 S3 协议的对象存储
+
+**工具库**
+- Lodash（工具函数）
+- Moment（日期处理）
+- Axios（HTTP 客户端）
+- EJS（模板引擎）
+- Nodemailer（邮件发送）
+- LRU Cache（内存缓存）
+
+### 核心中间件
+
+#### 全局中间件
+- **用户会话管理**：登录状态、权限信息
+- **多租户隔离**：域名识别、数据隔离
+- **事务管理**：自动事务控制
+- **日志追踪**：请求级日志
+- **响应格式化**：统一响应格式
+- **调试信息注入**：开发环境调试
+- **真实 IP 获取**：代理环境下获取真实 IP
+
+#### 权限中间件
+- **登录检查**（checkLogin）
+- **角色检查**（checkRole）
+- **权限检查**（checkPermission）
+
+#### 安全中间件
+- **黑名单拦截**（Forbidden）：防止路径遍历、敏感文件访问
+- **Redis 分布式锁**（RedisLock）：防止并发冲突
+- **Redis 缓存**（RedisCache）：接口级缓存
+
+#### 事务中间件
+- **自动事务**（Transaction）：开启、提交、回滚
+
+### 安全特性
+
+#### 访问控制
+- JWT Token 认证
+- 会话管理
+- 超级管理员机制
+- 细粒度权限控制
+
+#### 攻击防护
+- SQL 注入防护
+- XSS 防护
+- CSRF Token
+- 路径遍历防护
+- User-Agent 黑名单（扫描工具检测）
+- IP 限流
+
+#### 数据安全
+- AES-128-CBC 加密
+- 非对称加密支持
+- 敏感字段加密存储
+- 密码加盐存储
+
+## 应用场景
+
+### 1. 企业后台系统
+- 快速搭建管理后台
+- 业务系统配置中心
+- 内部工具平台
+
+### 2. SaaS 平台
+- 多租户应用
+- 白标产品
+- 行业解决方案
+
+### 3. API 平台
+- API 管理与网关
+- 数据开放平台
+- 微服务聚合
+
+### 4. 低代码平台
+- 业务系统快速开发
+- 表单驱动应用
+- 数据分析平台
+
+### 5. 内容管理系统
+- 文档管理
+- 知识库
+- 内容发布平台
+
+## 快速开始
+
+### 环境要求
+
+- Node.js >= 10
+- MySQL >= 5.7 / PostgreSQL >= 8 / SQL Server >= 11
+- Redis >= 3.0
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 配置
+
+1. 配置数据库连接（`src/config/config.default.ts`）
+2. 配置 Redis 连接
+3. 配置 OSS（可选）
+4. 配置工作台信息
+
+### 数据库初始化
+
+```sql
+-- 执行初始化 SQL
+source ddl/2025-12-20.sql
+```
+
+### 启动服务
+
+```bash
+# 开发模式
+npm run dev
+
+# 生产构建
+npm run build
+
+# 生产运行
+npm start
+```
+
+### 代码检查
+
+```bash
+# 检查代码规范
+npm run lint
+
+# 自动修复
+npm run lint:fix
+```
+
+### 测试
+
+```bash
+# 运行测试
+npm test
+
+# 测试覆盖率
+npm run cov
+```
+
+## 工具接口
+
+### 加密工具
+
+```
 http://127.0.0.1:7002/ns/api/helpers/cryptoAes128CBC?input=123
+```
+
+## 项目结构
+
+```
+midway-fatcms/
+├── src/
+│   ├── config/              # 配置文件
+│   ├── controller/          # 控制器
+│   │   ├── base/           # 基础控制器
+│   │   ├── gateway/        # 网关接口
+│   │   ├── manage/         # 管理接口
+│   │   ├── myinfo/         # 个人信息
+│   │   └── render/         # 渲染接口
+│   ├── filter/             # 异常过滤器
+│   ├── libs/               # 核心库
+│   │   ├── crud-pro/       # CRUD-Pro 引擎
+│   │   ├── global-config/  # 全局配置
+│   │   └── utils/          # 工具函数
+│   ├── middleware/         # 中间件
+│   ├── models/             # 数据模型
+│   ├── schedule/           # 定时任务
+│   ├── service/            # 业务服务
+│   │   ├── anyapi/         # 动态 API
+│   │   ├── asyncTask/      # 异步任务
+│   │   ├── base/           # 基础服务
+│   │   ├── crudstd/        # CRUD 标准
+│   │   ├── curd/           # CRUD 服务
+│   │   ├── flow/           # 工作流
+│   │   └── proxyapi/       # 代理 API
+│   └── views/              # 视图模板
+├── ddl/                    # 数据库脚本
+├── scripts/                # 脚本工具
+└── package.json            # 项目配置
+```
+
+## 版本
+
+当前版本：`0.0.1-beta.82`
+
+## 许可证
+
+MIT License
 
+## 作者
 
+企业级低代码开发团队

package/dist/controller/gateway/DocGatewayController.js

@@ -20,12 +20,14 @@ const global_config_1 = require("../../libs/global-config/global-config");
 const keys_1 = require("../../libs/crud-pro/models/keys");
 const WorkbenchService_1 = require("../../service/WorkbenchService");
 const common_dto_1 = require("../../libs/utils/common-dto");
+const fatcms_request_1 = require("../../libs/utils/fatcms-request");
 function checkIsNumber(value, name) {
-    if (!value) {
-        throw `${name}参数不存在`;
+    if (value === null || value === '' || typeof value === 'undefined') {
+        throw new Error(`${name}参数不存在`);
     }
-    if (!parseInt(value)) {
-        throw `${name}参数不是一个整数`;
+    const num = parseInt(value, 10);
+    if (isNaN(num)) {
+        throw new Error(`${name}参数不是一个整数`);
     }
 }
 /**
@@ -34,7 +36,7 @@ function checkIsNumber(value, name) {
  */
 let DocGatewayController = class DocGatewayController extends BaseApiController_1.BaseApiController {
     async updateDocPV(docId, docLibId, pv) {
-        const ip = this.ctx.headers['x-real-ip'];
+        const ip = (0, fatcms_request_1.getRealIpSafe)(this.ctx);
         const lockKey = `doc_ip_pv_${docId}_${ip}`;
         const EXPIRE_TIME = 5 * 60 * 1000; // 在五分钟内，同一个IP地址重复刷新同一篇文章，认为是一个PV
         const nxRes = await this.redisService.set(lockKey, 1, 'EX', EXPIRE_TIME, 'NX');

package/dist/interface.d.ts

@@ -11,6 +11,7 @@ declare module '@midwayjs/core' {
         workbenchInfo: IWorkbenchEntity;
         workbenchInfoTools: WorkbenchInfoTools;
         contextLogger: ContextLogger;
+        fatcmsRealIp: string;
     }
 }
 export interface ICacheService {

package/dist/libs/crud-pro/models/Transaction.js

@@ -38,7 +38,7 @@ class TransactionConnection {
     }
     async rollback() {
         this.isTxRollback = true;
-        await this.originConnection.commit();
+        await this.originConnection.rollback();
     }
     async release() {
         if (this.isReleased) {

package/dist/libs/crud-pro/models/TransactionMySQL.js

@@ -22,7 +22,7 @@ class MySqlConnectionClient {
         await this.originConnection.commit();
     }
     async rollback() {
-        await this.originConnection.commit();
+        await this.originConnection.rollback();
     }
     async release() {
         try {

package/dist/libs/crud-pro/utils/MixinUtils.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MixinUtils = void 0;
 const exceptions_1 = require("../exceptions");
+//  至少需要2个字符
 const FIELD_NAME_REG_EXP = /^[a-zA-Z][0-9a-zA-Z_]+$/;
 const MixinUtils = {
     isNil(obj) {
@@ -11,22 +12,22 @@ const MixinUtils = {
         return !MixinUtils.isNil(obj);
     },
     isEmpty(obj) {
-        if (typeof obj === 'number') {
-            return false;
+        if (typeof obj === 'number' || typeof obj === 'boolean') {
+            return false; // ✅ 数字和布尔值永远不为空
         }
-        if (obj) {
-            if (typeof obj === 'string') {
-                const str = obj;
-                return str.length === 0;
-            }
-            if (Array.isArray(obj)) {
-                return obj.length === 0;
-            }
-            if (typeof obj === 'object') {
-                return Object.keys(obj).length === 0;
-            }
+        if (obj === null || obj === undefined) {
+            return true;
+        }
+        if (typeof obj === 'string') {
+            return obj.length === 0;
         }
-        return !obj;
+        if (Array.isArray(obj)) {
+            return obj.length === 0;
+        }
+        if (typeof obj === 'object') {
+            return Object.keys(obj).length === 0;
+        }
+        return false;
     },
     isNotEmpty(obj) {
         return !MixinUtils.isEmpty(obj);
@@ -35,12 +36,11 @@ const MixinUtils = {
         return obj1 === obj2;
     },
     equalsIgnoreCase(str1, str2) {
-        if (str1 && str2) {
-            const str1Upper = str1.toUpperCase();
-            const str2Upper = str2.toUpperCase();
-            return str1Upper === str2Upper;
+        // 严格检查类型
+        if (typeof str1 !== 'string' || typeof str2 !== 'string') {
+            return str1 === str2;
         }
-        return !str1 && !str2;
+        return str1.toUpperCase() === str2.toUpperCase();
     },
     startsWith(str1, str2) {
         if (typeof str1 === 'string' && typeof str2 === 'string') {

package/dist/libs/utils/errorToString.d.ts

@@ -1,2 +1,20 @@
+/**
+ * 将错误对象转换为详细的字符串描述
+ *
+ * 支持多种错误类型：
+ * - Error对象（包含堆栈信息）
+ * - 原始值类型（string, number, boolean等）
+ * - 普通对象
+ * - null/undefined
+ *
+ * @param error 任意类型的错误对象
+ * @returns 格式化后的错误描述字符串
+ *
+ * @example
+ * errorToString(new Error('test'))           // 包含堆栈信息
+ * errorToString('error message')             // 'Error: A primitive value was thrown...'
+ * errorToString({ code: 500, msg: 'fail' }) // JSON格式的对象
+ * errorToString(null)                        // 'Error: null was thrown'
+ */
 declare function errorToString(error: any): string;
 export { errorToString };

package/dist/libs/utils/errorToString.js

@@ -1,6 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.errorToString = void 0;
+/**
+ * 将错误对象转换为详细的字符串描述
+ *
+ * 支持多种错误类型：
+ * - Error对象（包含堆栈信息）
+ * - 原始值类型（string, number, boolean等）
+ * - 普通对象
+ * - null/undefined
+ *
+ * @param error 任意类型的错误对象
+ * @returns 格式化后的错误描述字符串
+ *
+ * @example
+ * errorToString(new Error('test'))           // 包含堆栈信息
+ * errorToString('error message')             // 'Error: A primitive value was thrown...'
+ * errorToString({ code: 500, msg: 'fail' }) // JSON格式的对象
+ * errorToString(null)                        // 'Error: null was thrown'
+ */
 function errorToString(error) {
     var _a;
     // 处理非错误对象的情况
@@ -11,11 +29,11 @@ function errorToString(error) {
         return 'Error: null was thrown';
     }
     // 处理原始值类型
-    const primitiveTypes = ['string', 'number', 'boolean', 'symbol'];
+    const primitiveTypes = ['string', 'number', 'boolean', 'symbol', 'bigint'];
     if (primitiveTypes.includes(typeof error)) {
         return `Error: A primitive value was thrown\nValue: ${String(error)}`;
     }
-    // 处理 Error 对象
+    // 处理 Error 对象（必须在处理普通对象之前）
     if (error instanceof Error) {
         const errorDetails = [];
         errorDetails.push(`Error: ${error.name || 'Error'}`);
@@ -24,21 +42,24 @@ function errorToString(error) {
             errorDetails.push('Stack Trace:');
             errorDetails.push(error.stack);
         }
-        const extraProperties = ['code', 'fileName', 'lineNumber', 'columnNumber'];
+        // 常见的错误扩展属性
+        const extraProperties = ['code', 'fileName', 'lineNumber', 'columnNumber', 'statusCode', 'status'];
         extraProperties.forEach(prop => {
             if (error[prop] !== undefined) {
                 errorDetails.push(`${prop}: ${error[prop]}`);
             }
         });
+        // 获取自定义属性
         const customProps = Object.keys(error).filter(key => !['name', 'message', 'stack', ...extraProperties].includes(key));
         if (customProps.length > 0) {
             errorDetails.push('Custom Properties:');
             customProps.forEach(prop => {
                 try {
-                    const value = JSON.stringify(error[prop], null, 2) || String(error[prop]);
+                    const value = JSON.stringify(error[prop], null, 2);
                     errorDetails.push(`  ${prop}: ${value}`);
                 }
                 catch (e) {
+                    // 处理循环引用或不可序列化的对象
                     errorDetails.push(`  ${prop}: [Object cannot be serialized]`);
                 }
             });
@@ -51,6 +72,7 @@ function errorToString(error) {
         return `Error: A plain object was thrown\nObject: ${objectDetails}`;
     }
     catch (e) {
+        // 处理循环引用或不可序列化的对象
         return `Error: An object was thrown but could not be serialized\nType: ${((_a = error.constructor) === null || _a === void 0 ? void 0 : _a.name) || 'Unknown'}`;
     }
 }

package/dist/libs/utils/fatcms-request.d.ts

@@ -28,3 +28,18 @@ export declare function getCsrfToken(ctx: Context): string;
 export declare function getExtLocalLoaderPort(ctx: Context): string;
 export declare function isCsrfTokenValid(ctx: Context): Promise<boolean>;
 export declare function assertCsrfToken(ctx: Context): Promise<void>;
+/**
+ * 安全获取客户端真实IP地址（优先从 userSession 获取）
+ *
+ * 推荐在业务代码中使用此方法，因为：
+ * 1. userSession 中的 IP 在全局中间件初始化时已解析，性能更好
+ * 2. 自动处理 userSession 不存在的边界情况
+ *
+ * @param ctx Koa上下文
+ * @returns 客户端真实IP地址
+ *
+ * @example
+ * // 在 Controller/Service 中推荐使用
+ * const ip = getRealIpSafe(this.ctx);
+ */
+export declare function getRealIpSafe(ctx: Context): string;