mm_os 4.3.7 → 5.0.0

package/README_EN.md

@@ -1,505 +0,0 @@
-# MM_OS Server Architecture
-
-[![npm version](https://badge.fury.io/js/mm_os.svg)](https://badge.fury.io/js/mm_os)
-[![npm downloads](https://img.shields.io/npm/dm/mm_os.svg)](https://www.npmjs.com/package/mm_os)
-[![License](https://img.shields.io/npm/l/mm_os.svg)](https://gitee.com/qiuwenwu91/mm_os/blob/master/LICENSE)
-
-## Project Introduction
-
-MM_OS is a lightweight server architecture that provides a complete server development framework, including support for multiple communication protocols such as Web, WebSocket, MQTT, Socket, as well as rich components and modules.
-
-**Use Cases:**
-- **Website Development**: Quickly build enterprise websites, e-commerce platforms, content management systems
-- **Mini Programs**: Backend services for WeChat Mini Programs, Alipay Mini Programs, etc.
-- **AI Applications**: AI API services, intelligent assistants, machine learning inference services
-- **IoT/AIoT**: IoT device management, sensor data collection, smart hardware control
-- **Game Servers**: Small-to-medium game servers, real-time battle games, game backend management
-
-Supports **AI, GAME, IOT, AIOT, Games, Internet of Things, Mini Programs, Website Development** and other application scenarios.
-
-## Core Features
-
-- **Multi-protocol support**: Web, WebSocket, MQTT, Socket
-- **Modular design**: Application, Module, Middleware, Notifier, Sender, Pusher
-- **Infrastructure**: Database, Cache, Log, File Management
-- **Event-driven**: Asynchronous processing based on event bus
-- **Plugin system**: Support for function extension
-
-## Design Philosophy: Configuration and Logic Separation
-
-The core design principle of MM_OS framework is **separation of configuration and logic**. Both `core` modules and `com` components follow a unified structure:
-
-### Module Composition
-
-Each module consists of the following files:
-
-| File Type | File Name | Purpose |
-|-----------|-----------|---------|
-| **Configuration** | `config.tpl.json` / `com.json` | Declarative definition of module configuration and metadata |
-| **Logic** | `index.js` / `script.tpl.js` | Implementation of business logic and functionality |
-| **Driver** | `drive.js` (optional) | Protocol driver and adapter logic |
-
-### Design Advantages
-
-**1. Declarative Configuration**
-- JSON files define module metadata and configuration declaratively
-- Module registration and parameter configuration can be completed without writing code
-- Easy to manage and configure through visual tools
-
-**2. Logic and Configuration Decoupling**
-- Configuration changes do not require code modification, reducing maintenance costs
-- The same business logic can be reused with different configurations
-- Configuration files can be independently version-managed and deployed
-
-**3. Automation Capabilities**
-- Framework can automatically scan JSON configurations for module registration
-- Automatically generate documentation and configuration forms
-- Automatically perform parameter validation, reducing repetitive code
-
-**4. Hot Update Support**
-- Configuration files can be hot-updated without restarting the service
-- Supports dynamic addition/modification of module configurations
-
-**5. Team Collaboration Optimization**
-- Configuration personnel and developers can work in parallel
-- Non-developers can also participate in module configuration
-- Unified configuration format reduces communication costs
-
-### Module Types
-
-**core modules**: Framework base modules including app, controller, model, logic, plugin, service, view, middleware, etc.
-
-**com components**: Reusable common components including sql, cache, api, event, task, static, template, MQTT, Socket, etc.
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install mm_os
-```
-
-### Basic Usage
-
-```javascript
-const { MM_os } = require('mm_os');
-
-// Set runtime path
-$.run_path = __dirname;
-
-// Create server instance
-const server = new MM_os({
-  web: {
-    host: '0.0.0.0',
-    port: 8000,
-    socket: true
-  },
-  mysql: {
-    host: '127.0.0.1',
-    port: 3306,
-    user: 'root',
-    password: '123456',
-    database: 'test'
-  },
-  cache: {
-    way: 'memory'
-  }
-});
-
-// Start server
-async function startServer() {
-  await server.init();
-  await server.start();
-  console.log('服务启动成功');
-}
-
-startServer();
-```
-
-## Project Directory Structure
-
-Projects developed with MM_OS framework follow a standardized directory structure:
-
-```
-├── app/                    # Application directory containing multiple apps
-│   ├── app_name/           # Application name
-│   │   ├── event_api/      # Event API directory
-│   │   │   ├── web/        # Web route handling
-│   │   │   │   ├── event.json    # Event configuration
-│   │   │   │   └── main.js       # Entry file
-│   │   │   ├── api/        # API route
-│   │   │   ├── client/     # Client API route
-│   │   │   └── manage/     # Management backend route
-│   │   ├── plugin/         # Plugin directory
-│   │   │   ├── main/       # Main plugins (business logic)
-│   │   │   │   └── api_{app}_{channel}/{api_name}/
-│   │   │   │       ├── api.json   # API configuration
-│   │   │   │       ├── param.json # Parameter validation config
-│   │   │   │       └── index.js   # API implementation
-│   │   │   └── server/     # Server plugins (data management)
-│   │   ├── pendant/        # Pendant component directory
-│   │   ├── static/         # Static resources
-│   │   ├── app.json        # Application configuration
-│   │   └── index.js        # Application entry
-├── cache/                  # Cache configuration directory
-├── com/                    # Common components directory
-├── config/                 # Global configuration directory
-│   ├── local.json          # Local configuration
-│   ├── development.json    # Development configuration
-│   └── production.json     # Production configuration
-├── db/                     # Database files directory (SQLite, etc.)
-├── static/                 # Global static resources
-├── index.js                # Project entry
-└── config.json             # Main configuration file
-```
-
-## Application Development
-
-### Create Application
-
-Each application contains independent business logic. Application configuration file `app.json`:
-
-```json
-{
-  "name": "user",
-  "version": "1.0",
-  "title": "User",
-  "description": "User authentication service",
-  "author": "developer",
-  "scope": "server",
-  "main": "./index.js",
-  "func_name": "main",
-  "sort": 10,
-  "state": 1,
-  "sql": {
-    "way": "mysql",
-    "mysql": {
-      "host": "127.0.0.1",
-      "port": 3306,
-      "user": "root",
-      "password": "password",
-      "database": "example"
-    }
-  },
-  "cache": {
-    "way": "redis"
-  }
-}
-```
-
-### Event Route Configuration (event.json)
-
-Define application routing rules:
-
-```json
-{
-  "/api/user/list": {
-    "method": "GET",
-    "title": "Get User List",
-    "auth": false
-  },
-  "/api/user/create": {
-    "method": "POST",
-    "title": "Create User",
-    "auth": true
-  },
-  "/user/*": {
-    "method": "ALL",
-    "title": "User Page Routes",
-    "auth": false
-  }
-}
-```
-
-### Create API Interface
-
-API is the core component of MM_OS framework. Each API consists of three files:
-
-#### 1. api.json - API Configuration
-
-```json
-{
-  "name": "user_sign_in",
-  "title": "User Login",
-  "description": "User login interface, supports username/password, phone/code, and social login",
-  "path": "/api/user/sign_in",
-  "type": "api",
-  "method": "ALL",
-  "cache": 0,
-  "param_path": "./param.json",
-  "check_param": true,
-  "sort": 1
-}
-```
-
-**api.json Field Description:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| name | string | Yes | Unique API identifier |
-| title | string | Yes | Display name |
-| description | string | No | Description |
-| path | string | Yes | Access path |
-| type | string | Yes | Type, fixed as "api" |
-| method | string | Yes | HTTP method: GET, POST, ALL |
-| cache | number | No | Cache time in seconds, 0 means no cache |
-| param_path | string | No | Parameter validation config path |
-| check_param | boolean | No | Whether to validate parameters |
-| sort | number | No | Sort order |
-
-#### 2. param.json - Parameter Validation Configuration
-
-```json
-{
-  "title": "User Login Validation Model",
-  "name": "user_sign_in",
-  "filter": true,
-  "get": {
-    "query": ["account", "password", "code"],
-    "query_required": ["account"]
-  },
-  "post": {
-    "body": ["account", "password", "code", "phone"],
-    "body_required": ["account"]
-  },
-  "list": [
-    {
-      "name": "account",
-      "title": "Account",
-      "type": "string",
-      "string": {
-        "min": 5,
-        "max": 16,
-        "format": "username"
-      }
-    },
-    {
-      "name": "password",
-      "title": "Password",
-      "type": "string",
-      "string": {
-        "min": 32,
-        "max": 32,
-        "format": "password"
-      }
-    },
-    {
-      "name": "phone",
-      "title": "Phone Number",
-      "type": "string",
-      "string": {
-        "format": "phone",
-        "range": [11, 11]
-      }
-    },
-    {
-      "name": "code",
-      "title": "Verification Code",
-      "type": "string"
-    }
-  ]
-}
-```
-
-**param.json Field Description:**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| title | string | Validation model name |
-| name | string | Model identifier |
-| filter | boolean | Whether to enable filtering |
-| get.query | array | Acceptable query parameters for GET |
-| get.query_required | array | Required parameters for GET |
-| post.body | array | Acceptable body parameters for POST |
-| post.body_required | array | Required parameters for POST |
-| list | array | Parameter validation rules |
-
-**Supported Parameter Types:**
-- `string`: String type, supports format (phone, email, username, password), min, max, range
-- `number`: Number type, supports min, max, range
-- `boolean`: Boolean type
-- `array`: Array type
-- `object`: Object type
-
-#### 3. index.js - API Implementation
-
-```javascript
-/**
- * User Login API
- * @param {Object} ctx HTTP context
- * @param {Object} db Data manager
- * @return {Object} Execution result
- */
-async function main(ctx, db) {
-  // Get request parameters
-  var params = ctx.method === "POST" ? ctx.request.body : ctx.request.query;
-  
-  // Validate parameters
-  var account = params['account'];
-  var password = params['password'];
-  
-  if (!account) {
-    return { code: 30001, message: 'Account cannot be empty' };
-  }
-  if (!password) {
-    return { code: 30002, message: 'Password cannot be empty' };
-  }
-  
-  // Query user
-  db.table = "user_account";
-  db.key = "user_id";
-  var users = await db.get({ username: account });
-  
-  if (users.length === 0) {
-    return { code: 60001, message: 'User does not exist' };
-  }
-  
-  var user = users[0];
-  
-  // Validate password
-  var pass = (password + user.salt).md5();
-  if (pass !== user.password) {
-    return { code: 30003, message: 'Incorrect password' };
-  }
-  
-  // Set login state
-  ctx.session.user = user;
-  
-  // Return result
-  return { 
-    code: 200, 
-    message: 'Login successful',
-    data: {
-      user_id: user.user_id,
-      username: user.username,
-      nickname: user.nickname
-    }
-  };
-}
-
-exports.main = main;
-```
-
-### Event Handler Entry (main.js)
-
-```javascript
-// Use API manager
-var api = $.admin.api('user_web', 'Website - User Management');
-api.call('update');
-
-/**
- * @description Main handler function
- * @param {Object} ctx HTTP context
- * @param {Object} db Data manager
- * @return {Object} Execution result
- */
-async function main(ctx, db) {
-  // Set database connection
-  $.push(db, $.admin.sql('sys').db(), true);
-  
-  // Use template engine
-  db.tpl = new $.Tpl();
-  var bag = db.tpl.viewBag;
-  bag.path = ctx.path;
-  bag.query = ctx.query;
-  
-  // Execute API routing
-  return await api.run(ctx, db);
-}
-
-exports.main = main;
-```
-
-## Configuration
-
-MM_OS supports multiple configuration options:
-
-- **web**: Web server configuration
-- **mysql**: MySQL database configuration
-- **sqlite**: SQLite database configuration
-- **cache**: Cache configuration (`way` specifies type: `memory`, `redis`, `mongodb`)
-- **redis**: Redis cache configuration
-- **mongodb**: MongoDB configuration
-- **mqtt**: MQTT server configuration
-- **socket**: Socket server configuration
-
-### Configuration File Example
-
-```json
-{
-  "name": "mm_os",
-  "title": "Server System",
-  "log": {
-    "level": "debug",
-    "file": true
-  },
-  "web": {
-    "state": true,
-    "host": "0.0.0.0",
-    "port": 8000,
-    "socket": false,
-    "cos": {
-      "status": true,
-      "origin": "*"
-    },
-    "static": {
-      "state": 1,
-      "root": "./static"
-    }
-  },
-  "mysql": {
-    "host": "127.0.0.1",
-    "port": 3306,
-    "user": "root",
-    "password": "password",
-    "database": "example"
-  },
-  "cache": {
-    "way": "redis"
-  },
-  "redis": {
-    "host": "localhost",
-    "port": 6379,
-    "password": "",
-    "database": 0
-  }
-}
-```
-
-## Global Objects
-
-MM_OS provides rich global objects for development:
-
-### `$` Object
-
-| Property | Description |
-|----------|-------------|
-| `$.sql` | Database operation object |
-| `$.cache` | Cache operation object |
-| `$.log` | Log object |
-| `$.admin` | Admin object |
-| `$.eventer` | Event bus |
-| `$.config` | Configuration manager |
-| `$.Tpl` | Template engine class |
-| `$.ret` | Response utility |
-| `$.run_path` | Current runtime path |
-
-### `$.ret` Response Utility
-
-```javascript
-// Success response
-return $.ret.body(data);  // { code: 200, message: 'success', data: data }
-
-// Error response
-return $.ret.error(code, message);  // { code: code, message: message }
-```
-
-## Development Guide
-
-1. **Install dependencies**: `npm install`
-2. **Development and debugging**: `npm run dev`
-3. **Run tests**: `npm run test`
-
-## License
-
-ISC