midway-fatcms 0.0.3 → 0.0.5

package/README.md

@@ -1,407 +1,447 @@
-# 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
-
-## 作者
-
-企业级低代码开发团队
+# Midway FatCMS
+
+<p align="center">
+  <strong>🚀 Enterprise-Grade Low-Code / Zero-Code Development Platform</strong>
+</p>
+
+<p align="center">
+  Build production-ready enterprise applications in minutes, not months.
+</p>
+
+---
+
+## ✨ Why Midway FatCMS?
+
+Stop writing repetitive CRUD boilerplate. Stop struggling with API versioning. Stop worrying about multi-tenant data isolation.
+
+**Midway FatCMS** is a battle-tested, enterprise-grade low-code platform that transforms weeks of development into hours of configuration. Built on top of the robust Midway.js framework, it empowers teams to ship faster without sacrificing security, scalability, or control.
+
+### The Problem We Solve
+
+| Traditional Development | With Midway FatCMS |
+|------------------------|-------------------|
+| 2 weeks to build a CRUD module | 15 minutes of configuration |
+| Manual API documentation | Auto-generated, always in sync |
+| Complex multi-tenant logic | Built-in tenant isolation |
+| Reinventing the wheel | Production-ready building blocks |
+
+---
+
+## 🎯 What You Get
+
+### 🏗️ CRUD-Pro Engine — Zero-Code Data Operations
+
+Transform database tables into fully functional REST APIs with zero code.
+
+**Features:**
+- ⚡ **Instant CRUD** — Auto-generated Create, Read, Update, Delete endpoints
+- 🔍 **Advanced Querying** — Pagination, sorting, filtering, and joins out of the box
+- 🔐 **Field-Level Security** — Granular control over visibility, read-only, and mandatory fields
+- ✅ **Built-in Validation** — 20+ validators (email, phone, date, regex, etc.)
+- 🔗 **Smart Relations** — Automatic handling of one-to-one, one-to-many, many-to-many
+- 🗑️ **Soft Delete** — Logical deletion with recovery support
+- 📊 **Audit Trail** — Automatic tracking of creators, modifiers, and timestamps
+- 🌐 **Multi-Database** — MySQL, PostgreSQL, SQL Server support
+
+**Perfect for:**
+- Admin dashboards and back-office systems
+- Data management platforms
+- Reporting and analytics systems
+- Business configuration centers
+
+---
+
+### 🌟 Any API — Three Ways to Build APIs
+
+Whether you need a simple query or complex business logic, we've got you covered.
+
+#### 1. SQL Query API
+Write SQL, get REST. It's that simple.
+- Native SQL with automatic parameter binding
+- SQL injection protection built-in
+- Ideal for complex reports and data analytics
+
+#### 2. Sandbox Script API
+Safe, sandboxed Node.js execution.
+- Isolated VM environment for secure code execution
+- Pre-loaded utilities (axios, lodash, moment)
+- Direct access to database, Redis, and OSS
+
+#### 3. Custom Code API
+Full control when you need it.
+- Serverless-like function deployment
+- Hot-reload without service restart
+- Complete business logic freedom
+
+**Enterprise Security:**
+- JWT authentication & role-based access control
+- Token bucket rate limiting
+- Circuit breaker & timeout protection
+- IP whitelist/blacklist
+
+**Perfect for:**
+- Rapid API prototyping
+- Data aggregation services
+- Third-party integrations
+- Microservice orchestration
+
+---
+
+### 🚪 API Gateway & Proxy — Enterprise-Grade Traffic Management
+
+A full-featured API gateway that handles the complexity so you don't have to.
+
+#### Load Balancing Strategies
+- Round Robin
+- Weighted Round Robin
+- Random & Weighted Random
+- IP Hash (sticky sessions by IP)
+- User Hash (sticky sessions by user)
+- Session Hash (sticky sessions by session)
+
+#### Traffic Control
+- Request rate limiting
+- Configurable timeouts
+- Automatic retry mechanisms
+- Circuit breaker & fallback
+
+#### Security & Context
+- Real IP forwarding through proxies
+- User context propagation
+- Customizable headers (Host, Origin)
+- Request/response header manipulation
+
+**Perfect for:**
+- Microservices gateway
+- Canary deployments
+- A/B testing
+- Traffic splitting & aggregation
+
+---
+
+### 🏢 Multi-Tenant Architecture — True SaaS-Ready
+
+Deploy once, serve unlimited customers. Complete tenant isolation without the complexity.
+
+**Tenant Isolation:**
+- **Domain Recognition** — Automatic tenant detection by domain
+- **Data Separation** — Complete data isolation between tenants
+- **Permission Boundaries** — Independent user, role, and permission management
+- **Resource Isolation** — Files, configurations, and apps are tenant-scoped
+
+**Flexible Configuration:**
+- Primary domain + 2 backup domains per tenant
+- Wildcard domain support
+- Tenant templates for rapid onboarding
+- Customizable tenant branding
+
+**Perfect for:**
+- SaaS platforms
+- Multi-brand operations
+- Enterprise groups
+- White-label products
+
+---
+
+### 🔄 Workflow Engine — Automate Business Processes
+
+Streamline approvals and business flows with a flexible workflow engine.
+
+- Visual process definition
+- Process instance tracking
+- Task assignment and approval workflows
+- Real-time status monitoring
+- Historical flow records
+
+**Perfect for:**
+- Approval workflows (expenses, leaves, purchases)
+- Business process automation
+- State machine management
+
+---
+
+### 📚 Document Management System — Enterprise Knowledge Base
+
+A complete document management solution with version control and analytics.
+
+- **Document Libraries** — Multiple document repositories
+- **Hierarchical Structure** — Tree-based organization
+- **Version Control** — Full document versioning
+- **Analytics** — PV/UV tracking with IP deduplication
+- **Access Control** — Document-level permissions
+
+**Perfect for:**
+- API documentation
+- Product documentation
+- Internal knowledge bases
+- Help centers
+
+---
+
+### 📁 File Service — Complete File Management
+
+Enterprise file handling with cloud storage integration.
+
+- **Upload & Download** — Single and batch file uploads
+- **Cloud Storage** — Alibaba Cloud OSS integration (public & private buckets)
+- **File Preview** — Images, PDFs, Office documents
+- **Access Control** — Time-limited secure URLs
+- **Organization** — Categories and tags
+
+---
+
+### ⚙️ System Management — Everything You Need
+
+**User & Permissions:**
+- User account management
+- Role-based access control
+- Feature-level permissions
+- Permission allocation workflows
+
+**Application Management:**
+- Application registry
+- Page management
+- Menu configuration
+- Low-code templates
+
+**System Configuration:**
+- Data dictionaries
+- System parameters
+- Enumeration management
+- Scheduled tasks
+
+**Monitoring & Operations:**
+- Access statistics
+- Operation logs
+- System health info
+- Deployment management
+
+---
+
+## 🛡️ Security First
+
+We take security seriously. Built-in protection at every layer:
+
+### Access Control
+- JWT Token authentication
+- Session management with Redis
+- Super admin mechanism
+- Granular permission control
+
+### Attack Prevention
+- SQL injection protection
+- XSS protection
+- CSRF token validation
+- Path traversal prevention
+- User-Agent blacklisting (scanner detection)
+- IP-based rate limiting
+
+### Data Protection
+- AES-128-CBC encryption
+- Asymmetric encryption support
+- Sensitive field encryption
+- Salted password hashing
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 10
+- MySQL >= 5.7 / PostgreSQL >= 8 / SQL Server >= 11
+- Redis >= 3.0
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd midway-fatcms
+
+# Install dependencies
+npm install
+```
+
+### Configuration
+
+1. Configure database connection in `src/config/config.default.ts`
+2. Set up Redis connection
+3. Configure OSS (optional)
+4. Configure workbench information
+
+### Database Setup
+
+```sql
+-- Run initialization SQL
+source ddl/2025-12-20.sql
+```
+
+### Start Development
+
+```bash
+# Development mode with hot reload
+npm run dev
+
+# Build for production
+npm run build
+
+# Start production server
+npm start
+```
+
+### Code Quality
+
+```bash
+# Check code style
+npm run lint
+
+# Auto-fix issues
+npm run lint:fix
+```
+
+### Testing
+
+```bash
+# Run tests
+npm test
+
+# Generate coverage report
+npm run cov
+```
+
+---
+
+## 🏛️ Architecture
+
+### Technology Stack
+
+| Layer | Technology |
+|-------|-----------|
+| **Framework** | Midway.js 3.x (Enterprise Node.js) |
+| **Web Server** | Koa |
+| **Language** | TypeScript |
+| **Database** | MySQL / PostgreSQL / SQL Server |
+| **Cache** | Redis |
+| **File Storage** | Alibaba Cloud OSS / S3-compatible |
+
+### Core Middleware
+
+**Global Middleware:**
+- User session management
+- Multi-tenant isolation
+- Transaction management
+- Request-level logging
+- Unified response formatting
+- Real IP extraction
+
+**Security Middleware:**
+- Login verification (`checkLogin`)
+- Role verification (`checkRole`)
+- Permission verification (`checkPermission`)
+- Path blacklist (`Forbidden`)
+- Distributed locking (`RedisLock`)
+- Response caching (`RedisCache`)
+
+---
+
+## 📁 Project Structure
+
+```
+midway-fatcms/
+├── src/
+│   ├── config/              # Configuration files
+│   ├── controller/          # Controllers
+│   │   ├── base/           # Base controllers
+│   │   ├── gateway/        # Gateway APIs
+│   │   ├── manage/         # Management APIs
+│   │   ├── myinfo/         # Personal info APIs
+│   │   └── render/         # Rendering APIs
+│   ├── filter/             # Exception filters
+│   ├── libs/               # Core libraries
+│   │   ├── crud-pro/       # CRUD-Pro engine
+│   │   ├── global-config/  # Global configuration
+│   │   └── utils/          # Utilities
+│   ├── middleware/         # Middleware
+│   ├── models/             # Data models
+│   ├── schedule/           # Scheduled tasks
+│   ├── service/            # Business services
+│   │   ├── anyapi/         # Dynamic API
+│   │   ├── asyncTask/      # Async tasks
+│   │   ├── base/           # Base services
+│   │   ├── crudstd/        # Standard CRUD
+│   │   ├── curd/           # CRUD services
+│   │   ├── flow/           # Workflow
+│   │   └── proxyapi/       # Proxy API
+│   └── views/              # View templates
+├── ddl/                    # Database scripts
+├── scripts/                # Utility scripts
+└── package.json            # Project configuration
+```
+
+---
+
+## 🎯 Use Cases
+
+### Enterprise Back-Office Systems
+- Rapid admin dashboard creation
+- Business system configuration hubs
+- Internal tool platforms
+
+### SaaS Platforms
+- Multi-tenant applications
+- White-label products
+- Industry-specific solutions
+
+### API Platforms
+- API management & gateways
+- Data open platforms
+- Microservice aggregation
+
+### Low-Code Development
+- Rapid business system development
+- Form-driven applications
+- Data analysis platforms
+
+### Content Management
+- Document repositories
+- Knowledge bases
+- Content publishing platforms
+
+---
+
+## 🛠️ Utility Endpoints
+
+### Encryption Helper
+
+```
+http://127.0.0.1:7002/ns/api/helpers/cryptoAes128CBC?input=123
+```
+
+---
+
+## 📌 Version
+
+Current Version: `0.0.1-beta.82`
+
+---
+
+## 📄 License
+
+MIT License — Use it freely, contribute often.
+
+---
+
+## 👥 Contributing
+
+We welcome contributions! Whether it's bug reports, feature requests, or pull requests, your input helps make Midway FatCMS better for everyone.
+
+---
+
+<p align="center">
+  <strong>Built with ❤️ by the Enterprise Low-Code Development Team</strong>
+</p>
+
+<p align="center">
+  Ready to ship faster? Let's build something amazing together.
+</p>