midway-fatcms 0.0.4 → 0.0.6

package/README.md

@@ -1,407 +1,690 @@
 # 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. 内容管理系统
-- 文档管理
-- 知识库
-- 内容发布平台
-
-## 快速开始
-
-### 环境要求
+<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>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> · <a href="#-core-engines">Core Engines</a> · <a href="#-architecture">Architecture</a> · <a href="#-api-reference">API Reference</a>
+</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 |
+| Hand-coded sharding & pagination | Cross-shard queries out of the box |
+| Reinventing the wheel | Production-ready building blocks |
+
+---
+
+## Core Engines
+
+### CRUD-Pro Engine — Zero-Code Data Operations
+
+Transform database tables into fully functional REST APIs with zero code. CRUD-Pro is the heart of Midway FatCMS, providing configuration-driven SQL execution with built-in validation, security, and multi-database support.
+
+**Features:**
+
+- **Instant CRUD** — Auto-generated Create, Read, Update, Delete endpoints via `sqlSimpleName`
+- **Advanced Querying** — Pagination, sorting, filtering, joins, and MongoDB-style query operators
+- **Field-Level Security** — Granular control over visibility (`allowCfg`), read-only, and rejected fields (`rejectCfg`)
+- **Built-in Validation** — 20+ validators (email, phone, date, regex, length, range, enum, etc.)
+- **Smart Relations** — Automatic data enrichment via `columnsRelation` (dict, sysConfig, account, workbench, custom)
+- **Soft Delete** — Logical deletion with recovery support (`enableSoftDelete`)
+- **Audit Trail** — Automatic tracking of creators, modifiers, and timestamps (`enableStandardUpdateCfg`)
+- **Data Type Conversion** — Auto-convert JS arrays to PostgreSQL array literals, JSON strings parsed automatically
+- **Multi-Database** — MySQL, PostgreSQL, SQL Server support with dialect-aware SQL generation
+- **Custom SQL** — Template-based SQL with `@@placeholder` syntax for complex queries
+- **Transaction Support** — Built-in transaction management with configurable isolation levels
+- **Configuration Cache** — Database-stored configurations with TTL-based caching
+
+**10-Step Execution Pipeline:**
+
+```
+1. Receive Request (RequestModel)
+   ↓
+2. Load Configuration (RequestCfgModel)
+   ↓
+3. Field Filtering (filterDataByTableMeta)       — Remove non-existent columns based on table schema
+   ↓
+4. Data Type Conversion (convertDataTypeByTableMeta) — Auto-convert based on column types (e.g. PG ARRAY)
+   ↓
+5. Data Validation (validateByAllow/rejectCfg/validateCfg)
+   ↓
+6. Permission Check (validateByAuthCfg)
+   ↓
+7. Default Value Setting (updateByCfg)
+   ↓
+8. Generate SQL (generateSQLList)
+   ↓
+9. Execute SQL (executeSQLList)
+   ↓
+10. Return Result (ExecuteContext)
+```
+
+**Quick Example:**
+
+```typescript
+const cfgJson: IRequestCfgModel = {
+  method: 'article.list',
+  sqlTable: 'article',
+  sqlSimpleName: KeysOfSimpleSQL.SIMPLE_QUERY_PAGE,
+};
+
+const reqJson: IRequestModel = {
+  columns: 'id,title,content,author_id,created_at',
+  condition: {
+    status: 1,
+    category_id: { $in: [1, 2, 3] },
+    created_at: { $gte: '2024-01-01' },
+  },
+  pageNo: 1,
+  pageSize: 20,
+  orderBy: 'created_at-',
+};
+
+const ctx = await crudPro.executeCrudByCfg(reqJson, cfgJson);
+const { rows, total_count } = ctx.getResModelForQueryPage();
+```
+
+> Full CRUD-Pro documentation: [src/libs/crud-pro/README.md](src/libs/crud-pro/README.md) · Built-in Functions: [src/libs/crud-pro/README_FUNC.md](src/libs/crud-pro/README_FUNC.md)
+
+---
+
+### Sharding Engine — Scalable Table Partitioning
+
+Built on top of CRUD-Pro, the Sharding Engine provides transparent table partitioning with automatic routing, cross-shard pagination, and smart result merging — zero code changes required.
+
+**Sharding Strategies:**
+
+| Strategy | Enum | Suffix Example | Best For |
+|----------|------|----------------|----------|
+| By Year | `ShardingType.YEAR` | `_2024`, `_2025` | Annual reports, yearly archives |
+| By Month | `ShardingType.MONTH` | `_202401`, `_202402` | Order systems, log tables |
+| By Day | `ShardingType.DAY` | `_20240101` | High-volume daily logs |
+| By Range | `ShardingType.RANGE` | `_0` ~ `_99` | Numeric ID-based partitioning |
+| By Hash | `ShardingType.HASH` | `_01` ~ `_16` | Even distribution, user-based |
+| Custom | `ShardingType.CUSTOM` | User-defined | Tenant-based, business-specific |
+
+**Key Features:**
+
+- **Automatic Routing** — Insert/update/delete routed to the correct shard based on data fields
+- **Cross-Shard Pagination** — Transparent `queryPage()` across multiple shards with direct-offset optimization
+- **Smart Batch Insert** — `batchInsert()` auto-groups data by shard, parallel writes across tables
+- **COUNT Query Cache** — LRU + TTL cache for historical shard COUNT queries, real-time for current period
+- **Table Existence Filtering** — Non-existent shards silently skipped in queries, error on insert
+- **Multi-Sort Support** — Primary time-based sort + secondary field sorts within each shard
+
+**Quick Example:**
+
+```typescript
+const sharding = curdProService.getShardingCrud('mydb', SqlDbType.mysql, {
+  type: ShardingType.MONTH,
+  baseTable: 't_order',
+  timeColumn: 'created_at',
+  autoCreateTable: true,
+  countCache: { ttlSeconds: 300, maxSize: 1000 },
+});
+
+// Insert — auto-routes to t_order_202403
+await sharding.insert({
+  data: { order_id: '001', amount: 100, created_at: '2024-03-15' }
+});
+
+// Cross-shard pagination — automatic merging
+const page = await sharding.queryPage({
+  condition: { status: 'paid' },
+  pageNo: 1,
+  pageSize: 10,
+  orderBy: 'created_at DESC',
+});
+```
+
+> Full Sharding documentation: [src/libs/crud-sharding/ROUTING_LOGIC.md](src/libs/crud-sharding/ROUTING_LOGIC.md)
+
+---
+
+### 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
+
+---
+
+### 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
+
+---
+
+### 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
+
+---
+
+### 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
+
+---
+
+### 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
+
+---
+
+### 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 (`authType: free | login | byRoleCode | byFuncCode`)
+
+### Attack Prevention
+- SQL injection protection (parameterized queries)
+- 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
+
+---
+
+## 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 (CRUD, AnyAPI, Proxy, etc.)
+│   │   ├── manage/         # Management APIs
+│   │   ├── myinfo/         # Personal info & Auth APIs
+│   │   └── render/         # Rendering APIs
+│   ├── filter/             # Exception filters
+│   ├── libs/               # Core libraries
+│   │   ├── crud-pro/       # CRUD-Pro engine (SQL generation, validation, execution)
+│   │   ├── crud-sharding/  # Sharding engine (routing, merging, caching)
+│   │   ├── global-config/  # Global configuration
+│   │   └── utils/          # Shared utilities
+│   ├── middleware/         # Middleware (auth, permission, tx, cache, lock)
+│   ├── models/             # Data models & type definitions
+│   ├── schedule/           # Scheduled tasks
+│   ├── service/            # Business services
+│   │   ├── anyapi/         # Dynamic API (SQL, Sandbox, Custom Code)
+│   │   ├── asyncTask/      # Async task runner
+│   │   ├── base/           # Base services (cache, rate limiter)
+│   │   ├── crudstd/        # Standard CRUD (gateway-level)
+│   │   ├── curd/           # CRUD service layer (context injection, soft delete, relations)
+│   │   ├── flow/           # Workflow engine
+│   │   └── proxyapi/       # Proxy API gateway
+│   └── views/              # View templates
+├── ddl/                    # Database initialization scripts
+├── scripts/                # Utility scripts
+└── package.json            # Project configuration
+```
+
+### Service Layer Architecture
+
+```
+Business Code
+  │
+  ├── CurdMixService (orchestrator: CRUD + relation enrichment)
+  │     ├── CurdMixByDictService         → relatedType: 'dict'
+  │     ├── CurdMixBySysConfigService    → relatedType: 'sysCfgEnum'
+  │     ├── CurdMixByAccountService      → relatedType: 'accountBasic'
+  │     ├── CurdMixByWorkbenchService    → relatedType: 'workbenchBasic'
+  │     └── CurdMixByLinkToCustomService → relatedType: 'linkToCustom'
+  │
+  └── CurdProService (core service layer)
+        ├── CrudProQuick      → Quick CRUD (fluent API)
+        ├── ShardingCrudPro   → Sharded CRUD
+        ├── fixCfgModel()     → Standard field auto-fill
+        └── fixSoftDelete()   → Soft delete handling
+```
+
+> Full service layer documentation: [src/service/curd/README.md](src/service/curd/README.md)
+
+---
+
+## API Reference
+
+### CrudProQuick — Fluent CRUD API
+
+The quickest way to perform database operations. All methods automatically inherit context (visitor, transaction, soft delete, standard fields).
+
+```typescript
+const quick = curdProService.getQuickCrud('mydb', SqlDbType.mysql, 't_user');
+
+// Query methods
+const users = await quick.getList({ condition: { status: 'active' } });
+const page = await quick.getListPage({ condition: { status: 'active' }, pageNo: 1, pageSize: 20 });
+const user = await quick.getUniqueOne({ condition: { email: 'user@example.com' } });
+const exists = await quick.isExist({ condition: { phone: '13800138000' } });
+const count = await quick.getTotalCount({ condition: { status: 'active' } });
+
+// Write methods
+const result = await quick.insertObject({ data: { name: 'Alice', email: 'a@b.com' } });
+const batch = await quick.batchInsert({ data: [{ name: 'A' }, { name: 'B' }] });
+const updated = await quick.updateObject({ condition: { id: 1 }, data: { name: 'Bob' } });
+const deleted = await quick.deleteObject({ condition: { id: 1 } });
+const upserted = await quick.insertOnDuplicate({ data: { id: 1, name: 'A' } }, ['id']);
+
+// Raw SQL
+const rows = await quick.executeSQL('SELECT * FROM t_user WHERE status = ?', ['active']);
+```
+
+### Query Condition Operators
+
+MongoDB-style operators for powerful queries:
+
+```typescript
+const condition = {
+  status: 1,                             // Equal
+  age: { $gt: 18, $lt: 60 },            // Greater than / Less than
+  id: { $in: [1, 2, 3] },               // IN
+  code: { $nin: ['a', 'b'] },            // NOT IN
+  amount: { $between: [100, 500] },      // BETWEEN
+  name: { $like: '张' },                 // Prefix match
+  title: { $likeInclude: '文章' },        // Contains match
+  deleted_at: { $isNull: true },          // IS NULL
+  updated_at: { $isNotNull: true },       // IS NOT NULL
+  $or: [{ name: { $like: '张' } }, { name: { $like: '李' } }],  // OR
+};
+```
+
+### Sorting Syntax
+
+```typescript
+// Standard SQL format
+orderBy: 'created_at DESC, amount ASC'
+
+// Shorthand format (+ ascending, - descending)
+orderBy: 'created_at-, amount+'
+
+// Array format (mixed strings & objects)
+orderBy: ['order_id', { fieldName: 'created_at', orderType: 'desc' }, 'amount+']
+```
+
+### ShardingCrudPro API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `insert(reqJson)` | `ExecuteContext` | Insert single record (auto-route) |
+| `batchInsert(reqJson)` | `IShardingSmartBatchInsertResult` | Batch insert (cross-shard, parallel) |
+| `update(reqJson)` | `ExecuteContext` | Update data |
+| `delete(reqJson)` | `ExecuteContext` | Delete data |
+| `insertOrUpdate(reqJson)` | `ExecuteContext` | Insert or update |
+| `insertOnDuplicateUpdate(reqJson)` | `ExecuteContext` | Native upsert |
+| `queryOne(reqJson)` | `any \| null` | Query single record |
+| `query(reqJson)` | `any[]` | List query (auto-merge shards) |
+| `queryPage(reqJson)` | `IShardingPageQueryResult` | Cross-shard pagination |
+| `queryCount(reqJson)` | `number` | Count across shards |
+| `isExist(reqJson)` | `boolean` | Existence check across shards |
+
+### Built-in Functions
+
+CrudPro provides 30+ built-in functions for `updateCfg`, `validateCfg`, `executeWhen`, and `validate`:
+
+**DateTime:** `getCurrentTimeStampMs`, `getCurrentTimeStampSecond`, `getCurrentTimeString`, `getCurrentDateFormat`, `getYesterdayDateFormat`
+
+**Compare:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`
+
+**Utility:** `isNil`, `isNotNil`, `isEmpty`, `isNotEmpty`, `equals`, `equalsIgnoreCase`, `startsWith`, `isValidFieldName`, `selectNotEmpty`, `hasAny`, `parseValueByType`, `sleepMs`, `uuid`, `generateSnowflakeId`
+
+**Type Check:** `isBasicType`, `isBoolean`, `isString`, `isInteger`, `isNumber`, `isNumeric`, `isValidName`, `isChinesePhone`, `isEmailStrValid`, `pickNumber`
+
+> Full function reference: [src/libs/crud-pro/README_FUNC.md](src/libs/crud-pro/README_FUNC.md)
+
+### Soft Delete
+
+When `enableSoftDelete: true`, operations are automatically rewritten:
+
+| Operation | Original | With Soft Delete |
+|-----------|----------|-----------------|
+| INSERT | Normal insert | Auto-set `data.deleted_at = 0` |
+| DELETE | Physical DELETE | UPDATE: `deleted_at = timestamp`, `deleted_by = userId` |
+| QUERY | Normal query | Auto-append `condition.deleted_at = 0` |
+
+### Standard Field Auto-Fill
+
+When `enableStandardUpdateCfg: true`, standard fields are automatically populated:
+
+| Operation | Auto-Filled Fields |
+|-----------|--------------------|
+| INSERT | `created_by`, `created_avatar`, `created_nickname`, `created_account_type` |
+| UPDATE | `modified_by`, `modified_avatar`, `modified_nickname`, `modified_account_type` |
+| DELETE | — (condition auto-includes `created_by` for ownership check) |
+
+### Data Type Auto-Conversion
+
+CrudPro automatically converts data types based on table schema before INSERT/UPDATE:
+
+**PostgreSQL ARRAY** — JS arrays are automatically converted to PG array literal format:
+
+| Input | Converted | Description |
+|-------|-----------|-------------|
+| `["a","b","c"]` | `{"a","b","c"}` | String arrays: double-quoted |
+| `[1,2,3]` | `{1,2,3}` | Number arrays: no quotes |
+| `[true,false]` | `{t,f}` | Boolean arrays: t/f notation |
+| `[1,null,3]` | `{1,NULL,3}` | Null handling |
+| `[]` | `{}` | Empty arrays |
+| `['he"llo']` | `{"he\"llo"}` | Special character escaping |
+
+> Only applies to PostgreSQL; MySQL and SQL Server drivers handle type conversion natively.
+
+---
+
+## 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. 配置数据库连接（`src/config/config.default.ts`）
-2. 配置 Redis 连接
-3. 配置 OSS（可选）
-4. 配置工作台信息
+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
--- 执行初始化 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
 ```
 
-## 工具接口
+---
+
+## 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
+
+### High-Volume Data Systems
+- Sharded order management (millions of records per month)
+- Time-series log storage with auto-routing
+- Real-time analytics across partitioned tables
+
+### 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
 ```
 
-## 项目结构
+---
 
-```
-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            # 项目配置
-```
+## Documentation Index
+
+| Document | Description |
+|----------|-------------|
+| [CRUD-Pro Guide](src/libs/crud-pro/README.md) | Configuration-driven CRUD operations, validation, permissions |
+| [Built-in Functions](src/libs/crud-pro/README_FUNC.md) | 30+ functions: date, compare, utility, type check |
+| [Service Layer Guide](src/service/curd/README.md) | Context injection, soft delete, quick CRUD, sharding, relations |
+| [Sharding Routing Logic](src/libs/crud-sharding/ROUTING_LOGIC.md) | Shard strategies, cross-shard pagination, COUNT cache |
+
+---
+
+## Version
+
+Current Version: `0.0.1-beta.82`
+
+---
+
+## License
+
+MIT License — Use it freely, contribute often.
 
-## 版本
+---
 
-当前版本：`0.0.1-beta.82`
+## Contributing
 
-## 许可证
+We welcome contributions! Whether it's bug reports, feature requests, or pull requests, your input helps make Midway FatCMS better for everyone.
 
-MIT License
+---
 
-## 作者
+<p align="center">
+  <strong>Built with care by the Enterprise Low-Code Development Team</strong>
+</p>
 
-企业级低代码开发团队
+<p align="center">
+  Ready to ship faster? Let's build something amazing together.
+</p>