mm_ai 1.0.0

package/example/project/MMServer/doc//346/236/266/346/236/204/350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -0,0 +1,1258 @@
+# MM服务端架构设计文档
+
+> **项目名称**：MMServer
+> **文档版本**：v2.0（基于mm框架）
+> **编写人**：Node.js系统架构师
+> **编写日期**：2025年
+
+---
+
+## 目录
+
+1. [项目概述](#1-项目概述)
+2. [mm框架分析](#2-mm框架分析)
+3. [技术选型建议](#3-技术选型建议)
+4. [系统架构设计](#4-系统架构设计)
+5. [模块划分](#5-模块划分)
+6. [项目目录结构](#6-项目目录结构)
+7. [API设计规范](#7-api设计规范)
+8. [数据库设计初步方案](#8-数据库设计初步方案)
+9. [部署架构建议](#9-部署架构建议)
+10. [mm框架集成方案](#10-mm框架集成方案)
+11. [后续规划](#11-后续规划)
+
+---
+
+## 1. 项目概述
+
+### 1.1 项目背景
+
+MMServer 是一个基于 **mm服务端框架** 构建的Node.js服务端项目。mm框架是一套完整的插件化Node.js模块系统，提供了模块化加载、配置管理、缓存、日志、数据库、HTTP请求等全方位的服务端能力。
+
+### 1.2 设计目标
+
+| 目标 | 说明 |
+|------|------|
+| **插件化架构** | 充分利用mm框架的插件化机制，实现模块热插拔 |
+| **高性能** | 基于mm框架的事件驱动+异步IO，支撑高并发 |
+| **可扩展性** | 模块化设计，支持业务功能快速扩展 |
+| **高可用性** | 无状态设计+mm框架热更新，支持水平扩展 |
+| **可维护性** | 统一的模块加载、配置、日志体系 |
+
+### 1.3 设计原则
+
+- **插件化**：一切皆模块，基于mm_machine的插件机制
+- **约定优于配置**：遵循mm框架的目录和命名约定
+- **渐进增强**：从核心模块开始，逐步扩展业务模块
+
+---
+
+## 2. mm框架分析
+
+### 2.1 框架概述
+
+mm框架是一套完整的Node.js模块化服务端框架，以 **mm_machine**（插件化引擎）为核心，配合 **mm_expand**（工具库）和一系列功能模块，提供统一的服务端开发体验。
+
+### 2.2 核心模块体系
+
+| 模块 | 功能 | 在本项目中的角色 |
+|------|------|----------------|
+| **mm_machine** | 插件化引擎，动态加载/管理/执行模块 | **核心引擎**，服务端主骨架 |
+| **mm_expand** | 工具库：原型扩展、对象操作、事件系统、文件操作 | **基础工具**，全局可用 `$` |
+| **mm_config** | 配置文件管理，自动同步保存 | **配置中心**，管理所有配置 |
+| **mm_logs** | 多级别日志，文件轮转，控制台输出 | **日志系统** |
+| **mm_cache** | 统一缓存接口（Redis/Memory/File） | **缓存层** |
+| **mm_ret** | JSON-RPC 2.0 响应生成器 | **响应格式**标准 |
+| **mm_https** | HTTP请求客户端，Cookie管理，代理支持 | **HTTP客户端** |
+| **mm_sql** | 通用SQL帮助类（MySQL/SQLite） | **数据库操作** |
+| **mm_mysql** | MySQL数据库驱动 | **MySQL支持** |
+| **mm_sqlite** | SQLite数据库驱动 | **SQLite支持** |
+| **mm_redis** | Redis缓存驱动 | **Redis支持** |
+| **mm_mongodb** | MongoDB缓存驱动 | **MongoDB支持** |
+| **mm_session** | 会话管理 | **会话管理** |
+| **mm_queue** | 消息队列 | **异步任务** |
+| **mm_tpl** | 模板引擎 | **模板渲染** |
+| **mm_html** | HTML解析 | **HTML处理** |
+| **mm_hot_reload** | 热重载支持 | **开发效率** |
+
+### 2.3 mm_machine 核心机制
+
+#### 2.3.1 插件化加载机制
+
+```
+mm_machine (Engine)
+    │
+    ├── loads()           → 扫描目录，加载所有模块
+    ├── get(name)         → 获取指定模块
+    ├── exec(method)      → 执行所有模块的指定方法
+    ├── reload(name)      → 重载指定模块（热更新）
+    ├── unload(name)      → 卸载模块
+    ├── watch()           → 监听文件变化（热更新模式）
+    └── list              → 已加载模块列表
+```
+
+#### 2.3.2 模块生命周期
+
+```
+加载 (loads) → 初始化 (init) → 执行 (exec) → 重载 (reload) → 卸载 (unload)
+                                     │
+                              ┌──────┴──────┐
+                              ▼             ▼
+                        main_before()    main()
+                              │             │
+                              └──────┬──────┘
+                                     ▼
+                                main_after()
+```
+
+#### 2.3.3 模块结构约定
+
+每个模块遵循统一的目录结构：
+
+```
+app/module_name/
+├── config_{type}.json    # 模块配置文件（命名规则：config_{engine.type}.json）
+└── index.js              # 模块实现（或 main.js）
+```
+
+配置文件示例：
+```json
+{
+  "name": "module_name",
+  "title": "模块标题",
+  "description": "模块描述",
+  "sort": 10,
+  "state": 1,
+  "show": 1,
+  "options": {}
+}
+```
+
+### 2.4 mm_expand 工具库
+
+mm_expand 提供全局 `$` 对象，是框架的基础工具：
+
+```javascript
+const $ = require('mm_expand');
+
+// 日志
+$.log.debug/info/success/warn/error/fatal
+
+// 对象操作
+$.copy/deepMerge/equals
+
+// 事件系统
+$.eventer.on/emit/off
+
+// 文件操作
+$.file.read/write/copy/delete
+
+// 原型扩展（String/Array/Number/Date等）
+'hello'.toDate() / [1,2,3].copy() / (3.14).toRound(1)
+```
+
+### 2.5 mm_ret 响应规范
+
+mm框架采用 **JSON-RPC 2.0** 风格的响应格式：
+
+```javascript
+const { Ret, Req } = require('mm_ret');
+
+// 成功响应
+Ret.body({ data: 'xxx' });       // → {"result": {"data": "xxx"}}
+Ret.list([...], count);          // → {"result": {"list": [...], "count": N}}
+Ret.obj({...});                  // → {"result": {...}}
+Ret.bl(true, '操作成功');        // → {"result": true, "tip": "操作成功"}
+
+// 错误响应
+Ret.error(code, message);        // → {"error": {"code": N, "message": "..."}}
+```
+
+---
+
+## 3. 技术选型建议
+
+### 3.1 技术栈总览
+
+| 层级 | 技术选型 | 版本 | 说明 |
+|------|---------|------|------|
+| **运行环境** | Node.js | 20 LTS+ | 高性能事件驱动I/O |
+| **核心框架** | **mm_machine** | latest | 插件化引擎，服务端骨架 |
+| **工具库** | **mm_expand** | latest | 全局工具库 `$` |
+| **配置管理** | **mm_config** | latest | 配置热更新 |
+| **日志系统** | **mm_logs** | latest | 多级别日志 |
+| **缓存** | **mm_cache** + Redis | latest | 统一缓存接口 |
+| **数据库** | **mm_sql** + **mm_mysql** | latest | 通用SQL操作 |
+| **HTTP客户端** | **mm_https** | latest | HTTP请求 |
+| **响应格式** | **mm_ret** | latest | JSON-RPC标准 |
+| **实时通信** | Socket.IO / ws | latest | WebSocket |
+| **会话管理** | **mm_session** | latest | 会话管理 |
+| **消息队列** | **mm_queue** / RabbitMQ | latest | 异步任务 |
+| **部署** | Docker + Docker Compose | latest | 容器化部署 |
+
+### 3.2 技术选型说明
+
+#### 3.2.1 为什么选择mm框架
+
+- **完整的模块体系**：从配置、日志、缓存到数据库，一站式解决方案
+- **插件化架构**：支持热更新、动态加载/卸载，适合服务端长期运行
+- **约定优于配置**：统一的模块结构和命名规范，降低团队沟通成本
+- **轻量高效**：无过度封装，保留Node.js原生性能
+- **渐进式**：可以从核心模块开始，逐步引入更多mm模块
+
+#### 3.2.2 补充技术
+
+| 技术 | 用途 | 与mm框架的关系 |
+|------|------|---------------|
+| **Express/Koa** | HTTP路由 | mm框架不包含HTTP路由，需搭配使用 |
+| **Socket.IO** | WebSocket实时通信 | 作为独立模块集成 |
+| **Redis** | 高性能缓存 | 通过mm_cache统一接口操作 |
+| **PostgreSQL/MySQL** | 关系型数据库 | 通过mm_sql统一接口操作 |
+
+### 3.3 推荐的npm包
+
+```json
+{
+  "dependencies": {
+    "mm_machine": "^1.x",
+    "mm_expand": "^1.x",
+    "mm_config": "^1.x",
+    "mm_logs": "^1.x",
+    "mm_cache": "^1.x",
+    "mm_sql": "^1.x",
+    "mm_mysql": "^2.x",
+    "mm_ret": "^1.x",
+    "mm_https": "^1.x",
+    "mm_session": "^1.x",
+    "mm_queue": "^1.x",
+    "express": "^4.x",
+    "socket.io": "^4.x",
+    "redis": "^4.x",
+    "jsonwebtoken": "^9.x",
+    "bcryptjs": "^2.x"
+  }
+}
+```
+
+---
+
+## 4. 系统架构设计
+
+### 4.1 分层架构图
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                        客户端层 (Client)                            │
+│    Web浏览器  │  移动端App  │  桌面客户端  │  第三方服务             │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  │ HTTP / WebSocket
+┌─────────────────────────────────▼───────────────────────────────────┐
+│                       接入层 (Gateway)                              │
+│    Nginx反向代理  │  SSL终止  │  负载均衡  │  限流熔断              │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  │
+┌─────────────────────────────────▼───────────────────────────────────┐
+│                    应用服务层 (基于mm框架)                           │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │              mm_machine (插件化引擎)                         │  │
+│  │    loads() → get() → exec() → reload() → watch()            │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                  │                                   │
+│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────┐  │
+│  │ 核心模块    │ │ 业务模块   │ │ 工具模块   │ │  网关/路由模块     │  │
+│  │ (Core)     │ │ (Biz)     │ │ (Utils)   │ │  (Express路由)    │  │
+│  └───────────┘ └───────────┘ └───────────┘ └───────────────────┘  │
+│                                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │              mm_expand ($) 全局工具库                        │  │
+│  │   日志 │ 事件系统 │ 对象操作 │ 文件操作 │ 原型扩展             │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  │
+┌─────────────────────────────────▼───────────────────────────────────┐
+│                      中间件层 (Middleware)                          │
+│                                                                     │
+│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐   │
+│  │  mm_cache     │ │  mm_queue    │ │   mm_logs (日志系统)      │   │
+│  │  统一缓存接口  │ │  消息队列    │ │   控制台+文件输出         │   │
+│  │  Redis/Memory │ │  异步任务    │ │   日志轮转               │   │
+│  └──────────────┘ └──────────────┘ └──────────────────────────┘   │
+│                                                                     │
+│  ┌──────────────┐ ┌──────────────┐                                │
+│  │  mm_config    │ │  mm_ret      │                                │
+│  │  配置管理     │ │  响应格式    │                                │
+│  └──────────────┘ └──────────────┘                                │
+└─────────────────────────────────┬───────────────────────────────────┘
+                                  │
+┌─────────────────────────────────▼───────────────────────────────────┐
+│                       数据持久化层 (Storage)                        │
+│                                                                     │
+│  ┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐  │
+│  │  mm_sql         │ │  Redis         │ │   对象存储 (OSS/S3)    │  │
+│  │  MySQL/SQLite   │ │  缓存/会话    │ │   文件/图片/视频       │  │
+│  │  统一SQL接口    │ │                │ │                       │  │
+│  └────────────────┘ └────────────────┘ └────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 架构核心：mm_machine 引擎
+
+mm_machine 是整个服务端的核心骨架，负责：
+
+```
+启动流程：
+1. 创建 Engine 实例
+2. 配置 searchPath（模块搜索路径）
+3. 调用 loads() 加载所有模块
+4. 调用 exec('main') 执行所有模块的main方法
+5. 启动 HTTP 服务（Express）
+6. 开启热更新监听（watch）
+
+模块交互：
+- 模块间通过 engine.get('module_name') 获取其他模块
+- 通过 mm_expand 的事件系统进行事件通信
+- 通过 mm_cache 共享缓存数据
+- 通过 mm_queue 进行异步任务通信
+```
+
+### 4.3 数据流设计
+
+#### 4.3.1 HTTP请求流
+```
+客户端 → Nginx → Express Router → Auth中间件 → Controller模块
+                                                      │
+                                                 mm_sql/mm_cache
+                                                      │
+                                                 mm_ret 格式化响应
+                                                      │
+                                                 返回客户端
+```
+
+#### 4.3.2 模块内部通信流
+```
+模块A (main方法)
+    │
+    ├── engine.get('模块B') → 调用模块B的方法
+    ├── $.eventer.emit('event_name', data) → 触发事件
+    ├── cache.set('key', value) → 写入缓存
+    └── sql.run('SELECT ...') → 查询数据库
+
+其他模块通过事件监听或engine.get获取模块A的服务
+```
+
+### 4.4 热更新机制
+
+利用mm_machine的watch模式，实现开发和生产环境的热更新：
+
+```javascript
+const engine = new Machine();
+engine.mode = 2;          // 热更新模式
+await engine.loads();     // 加载模块
+engine.watch();           // 监听文件变化
+
+// 修改模块文件后，自动重载
+// 无需重启服务，业务无中断
+```
+
+---
+
+## 5. 模块划分
+
+### 5.1 模块分类
+
+根据mm框架的插件化机制，将服务端功能划分为以下模块类型：
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| **核心模块 (Core)** | 框架基础能力 | engine、config、logger |
+| **网关模块 (Gateway)** | 外部接口 | http_server、websocket |
+| **业务模块 (Business)** | 业务逻辑 | auth、user、message、room |
+| **数据模块 (Data)** | 数据访问 | cache、database |
+| **工具模块 (Utils)** | 通用工具 | helper、validator |
+
+### 5.2 核心模块设计
+
+#### 5.2.1 engine（引擎模块）
+- **基于**：mm_machine
+- **职责**：服务端启动入口，加载所有模块
+- **关键代码**：
+```javascript
+const Machine = require('mm_machine');
+const engine = new Machine();
+engine.type = 'mm_server';  // 配置文件前缀：config_mm_server.json
+
+async function start() {
+  await engine.loads();
+  await engine.exec('init');
+  await engine.exec('main');
+  engine.watch();  // 开启热更新
+}
+```
+
+#### 5.2.2 http_server（HTTP服务模块）
+- **基于**：Express + mm_ret
+- **职责**：HTTP路由、中间件、RESTful API
+- **配置文件**：`config_mm_server.json`
+```json
+{
+  "name": "http_server",
+  "title": "HTTP服务",
+  "port": 3000,
+  "cors": true,
+  "body_limit": "10mb"
+}
+```
+
+#### 5.2.3 websocket（WebSocket服务模块）
+- **基于**：Socket.IO
+- **职责**：实时双向通信
+- **功能**：
+  - 连接管理（建立/断开/重连）
+  - 消息路由（点对点/广播/房间）
+  - 心跳检测
+  - 在线状态管理
+
+#### 5.2.4 auth（认证授权模块）
+- **职责**：用户注册、登录、Token管理
+- **使用mm框架组件**：mm_sql（数据库）、mm_cache（Token缓存）、mm_ret（响应）
+- **功能**：
+  - 用户注册/登录
+  - JWT Token签发与验证
+  - 密码加密（bcrypt）
+  - 权限控制
+
+#### 5.2.5 user（用户服务模块）
+- **职责**：用户资料、好友关系、在线状态
+- **使用mm框架组件**：mm_sql、mm_cache
+- **功能**：
+  - 用户资料CRUD
+  - 好友/关注关系
+  - 在线状态管理
+  - 用户搜索
+
+#### 5.2.6 message（消息服务模块）
+- **职责**：消息收发、存储、历史查询
+- **功能**：
+  - 点对点消息
+  - 群组消息广播
+  - 消息存储与历史查询
+  - 离线消息
+
+#### 5.2.7 room（房间管理模块）
+- **职责**：房间/频道/群组管理
+- **功能**：
+  - 房间创建/加入/离开/解散
+  - 成员管理
+  - 房间内消息广播
+
+#### 5.2.8 cache（缓存模块）
+- **基于**：mm_cache
+- **职责**：统一缓存接口
+- **配置**：
+```javascript
+const { Cache } = require('mm_cache');
+const cache = new Cache({
+  way: 'redis',  // 或 'memory' / 'cachebase'
+  redis: {
+    host: '127.0.0.1',
+    port: 6379
+  }
+});
+```
+
+#### 5.2.9 database（数据库模块）
+- **基于**：mm_sql
+- **职责**：数据库操作
+- **配置**：
+```javascript
+const { Sql } = require('mm_sql');
+const sql = new Sql({
+  db_type: 'mysql',
+  host: 'localhost',
+  user: 'root',
+  password: '***',
+  database: 'mm_server'
+});
+```
+
+#### 5.2.10 admin（管理后台模块）
+- **职责**：系统管理、数据统计、运营工具
+- **功能**：
+  - 用户管理（查询/禁用）
+  - 数据统计
+  - 系统配置
+  - 操作日志审计
+
+### 5.3 模块间依赖关系
+
+```
+engine (mm_machine)
+  ├── http_server (Express)
+  │     ├── auth (认证)
+  │     ├── user (用户)
+  │     ├── message (消息)
+  │     ├── room (房间)
+  │     └── admin (管理)
+  ├── websocket (Socket.IO)
+  │     ├── message (消息)
+  │     └── room (房间)
+  ├── cache (mm_cache) ← 被所有模块依赖
+  ├── database (mm_sql) ← 被所有数据模块依赖
+  └── utils (mm_expand) ← 全局可用
+```
+
+### 5.4 模块生命周期钩子
+
+每个模块可以利用mm_machine提供的钩子：
+
+```javascript
+// 模块生命周期
+async function init() { }          // 初始化（加载时执行）
+async function load() { }          // 加载完成
+async function main() { }          // 主方法（启动时执行）
+async function main_before() { }   // main执行前
+async function main_after(res) { } // main执行后
+async function destroy() { }       // 销毁（卸载时执行）
+```
+
+---
+
+## 6. 项目目录结构
+
+### 6.1 整体目录
+
+```
+MMServer/
+├── index.js                    # 启动入口
+├── package.json
+├── config.json                 # 全局配置文件
+│
+├── app/                        # 模块目录（mm_machine 加载）
+│   ├── http_server/            # HTTP服务模块
+│   │   ├── config_mm_server.json   # 模块配置
+│   │   └── index.js               # 模块实现
+│   ├── websocket/              # WebSocket服务模块
+│   │   ├── config_mm_server.json
+│   │   └── index.js
+│   ├── auth/                   # 认证授权模块
+│   │   ├── config_mm_server.json
+│   │   ├── index.js
+│   │   ├── controller.js       # 路由控制器
+│   │   ├── service.js          # 业务逻辑
+│   │   └── middleware.js       # 中间件
+│   ├── user/                   # 用户服务模块
+│   │   ├── config_mm_server.json
+│   │   ├── index.js
+│   │   ├── controller.js
+│   │   └── service.js
+│   ├── message/                # 消息服务模块
+│   │   ├── config_mm_server.json
+│   │   ├── index.js
+│   │   ├── handler.js          # 消息处理器
+│   │   └── store.js            # 消息存储
+│   ├── room/                   # 房间管理模块
+│   │   ├── config_mm_server.json
+│   │   ├── index.js
+│   │   └── manager.js          # 房间管理器
+│   ├── admin/                  # 管理后台模块
+│   │   ├── config_mm_server.json
+│   │   ├── index.js
+│   │   └── stats.js            # 统计服务
+│   ├── cache/                  # 缓存模块
+│   │   ├── config_mm_server.json
+│   │   └── index.js
+│   ├── database/               # 数据库模块
+│   │   ├── config_mm_server.json
+│   │   └── index.js
+│   └── utils/                  # 工具模块
+│       ├── config_mm_server.json
+│       ├── index.js
+│       ├── response.js         # 响应工具（mm_ret封装）
+│       └── validator.js        # 验证工具
+│
+├── config/                     # 配置文件目录
+│   ├── database.json           # 数据库配置
+│   ├── redis.json              # Redis配置
+│   └── app.json                # 应用配置
+│
+├── logs/                       # 日志目录（mm_logs自动生成）
+├── test/                       # 测试
+│   ├── unit/
+│   └── integration/
+├── docker/                     # Docker配置
+│   ├── Dockerfile
+│   └── docker-compose.yml
+├── docs/                       # 文档
+└── scripts/                    # 脚本
+```
+
+### 6.2 启动入口 (index.js)
+
+```javascript
+const $ = require('mm_expand');
+const Machine = require('mm_machine');
+
+// 创建引擎实例
+const engine = new Machine();
+engine.type = 'mm_server';  // 配置文件前缀
+
+// 启动服务
+async function start() {
+  $.log.info('MMServer 启动中...');
+
+  // 加载所有模块
+  await engine.loads();
+  $.log.info(`已加载 ${engine.list.length} 个模块`);
+
+  // 执行所有模块的 main 方法
+  await engine.exec('main');
+  $.log.success('MMServer 启动完成');
+
+  // 开启热更新（开发模式）
+  if (process.env.NODE_ENV === 'development') {
+    engine.mode = 2;
+    engine.watch();
+    $.log.info('热更新模式已开启');
+  }
+}
+
+start().catch(err => {
+  $.log.error('启动失败:', err);
+  process.exit(1);
+});
+```
+
+### 6.3 模块示例 (auth/index.js)
+
+```javascript
+const $ = require('mm_expand');
+const { Ret } = require('mm_ret');
+const jwt = require('jsonwebtoken');
+const bcrypt = require('bcryptjs');
+
+/**
+ * 初始化
+ */
+async function init() {
+  $.log.info('[auth] 认证模块初始化');
+}
+
+/**
+ * 主方法：注册路由
+ */
+async function main() {
+  const httpServer = this.parent.get('http_server');
+  if (!httpServer) return;
+
+  const router = httpServer.router;
+
+  // 注册路由
+  router.post('/api/v1/auth/register', register);
+  router.post('/api/v1/auth/login', login);
+  router.post('/api/v1/auth/refresh', refreshToken);
+}
+
+/**
+ * 用户注册
+ */
+async function register(ctx) {
+  const { username, password, nickname } = ctx.request.body;
+  // 业务逻辑...
+  ctx.body = Ret.body({ userId: 1 });
+}
+
+/**
+ * 用户登录
+ */
+async function login(ctx) {
+  const { username, password } = ctx.request.body;
+  // 业务逻辑...
+  ctx.body = Ret.obj({ token: 'xxx', user: {} });
+}
+
+module.exports = { init, main };
+```
+
+---
+
+## 7. API设计规范
+
+### 7.1 通用规范
+
+#### 7.1.1 基础URL
+```
+# 开发环境
+http://localhost:3000/api/v1
+
+# 生产环境
+https://api.mm-server.com/api/v1
+```
+
+#### 7.1.2 请求格式
+- Content-Type: `application/json`
+- 认证方式：`Authorization: Bearer <token>`
+
+#### 7.1.3 响应格式（基于mm_ret）
+```json
+// 成功响应
+{
+  "result": { ... },
+  "id": "req_xxx"
+}
+
+// 列表响应
+{
+  "result": {
+    "list": [...],
+    "count": 100
+  }
+}
+
+// 错误响应
+{
+  "error": {
+    "code": 10000,
+    "message": "参数错误"
+  }
+}
+```
+
+### 7.2 RESTful API 接口
+
+#### 7.2.1 认证接口
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/auth/register | 用户注册 |
+| POST | /api/v1/auth/login | 用户登录 |
+| POST | /api/v1/auth/refresh | 刷新Token |
+| POST | /api/v1/auth/logout | 退出登录 |
+
+#### 7.2.2 用户接口
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/users/me | 获取当前用户信息 |
+| PUT | /api/v1/users/me | 更新当前用户信息 |
+| GET | /api/v1/users/:id | 获取指定用户信息 |
+| GET | /api/v1/users/search | 搜索用户 |
+| POST | /api/v1/users/friends | 添加好友 |
+| DELETE | /api/v1/users/friends/:id | 删除好友 |
+| GET | /api/v1/users/friends | 好友列表 |
+
+#### 7.2.3 消息接口
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/messages/:userId | 历史消息 |
+| DELETE | /api/v1/messages/:id | 撤回消息 |
+| GET | /api/v1/messages/unread | 未读消息数 |
+
+#### 7.2.4 房间接口
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/rooms | 创建房间 |
+| GET | /api/v1/rooms/:id | 房间信息 |
+| PUT | /api/v1/rooms/:id | 更新房间 |
+| DELETE | /api/v1/rooms/:id | 解散房间 |
+| POST | /api/v1/rooms/:id/join | 加入房间 |
+| POST | /api/v1/rooms/:id/leave | 离开房间 |
+| GET | /api/v1/rooms/:id/members | 成员列表 |
+
+#### 7.2.5 管理接口
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/admin/users | 用户列表 |
+| PUT | /api/v1/admin/users/:id/status | 变更用户状态 |
+| GET | /api/v1/admin/stats | 数据统计 |
+
+### 7.3 WebSocket 消息协议
+
+#### 消息格式
+```json
+{
+  "type": "message_type",
+  "data": {},
+  "seq": 1,
+  "timestamp": 1700000000000
+}
+```
+
+#### 客户端→服务端
+| 消息类型 | 说明 |
+|---------|------|
+| auth | 认证 { token } |
+| ping | 心跳 |
+| message.send | 发送消息 { to, type, content } |
+| room.join | 加入房间 { roomId } |
+| room.leave | 离开房间 { roomId } |
+| room.message | 房间消息 { roomId, content } |
+
+#### 服务端→客户端
+| 消息类型 | 说明 |
+|---------|------|
+| auth.ok/fail | 认证结果 |
+| pong | 心跳回复 |
+| message.new | 新消息 |
+| room.joined/left | 房间加入/离开 |
+| room.member.join/leave | 成员变动通知 |
+| error | 错误通知 |
+
+---
+
+## 8. 数据库设计初步方案
+
+### 8.1 数据库选型
+
+| 数据库 | 用途 | 操作方式 |
+|--------|------|---------|
+| **MySQL** | 核心业务数据 | mm_sql + mm_mysql |
+| **Redis** | 缓存/会话/实时数据 | mm_cache (way: 'redis') |
+| **SQLite** | 开发/测试环境 | mm_sql (db_type: 'sqlite') |
+
+### 8.2 核心表设计
+
+#### 8.2.1 users（用户表）
+```sql
+CREATE TABLE users (
+  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+  username    VARCHAR(50) NOT NULL UNIQUE,
+  password    VARCHAR(255) NOT NULL,
+  nickname    VARCHAR(100),
+  avatar      VARCHAR(255),
+  email       VARCHAR(100),
+  phone       VARCHAR(20),
+  role        VARCHAR(20) DEFAULT 'user',
+  status      TINYINT DEFAULT 1,
+  last_login_at DATETIME,
+  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_username (username),
+  INDEX idx_status (status)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+#### 8.2.2 user_friends（好友表）
+```sql
+CREATE TABLE user_friends (
+  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+  user_id     BIGINT NOT NULL,
+  friend_id   BIGINT NOT NULL,
+  status      TINYINT DEFAULT 0,
+  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_friend (user_id, friend_id),
+  INDEX idx_user_id (user_id),
+  FOREIGN KEY (user_id) REFERENCES users(id),
+  FOREIGN KEY (friend_id) REFERENCES users(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+#### 8.2.3 messages（消息表）
+```sql
+CREATE TABLE messages (
+  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+  from_uid    BIGINT NOT NULL,
+  to_uid      BIGINT NOT NULL,
+  msg_type    VARCHAR(20) DEFAULT 'text',
+  content     TEXT NOT NULL,
+  status      TINYINT DEFAULT 0,
+  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+  INDEX idx_from_to (from_uid, to_uid),
+  INDEX idx_to_status (to_uid, status),
+  INDEX idx_created (created_at),
+  FOREIGN KEY (from_uid) REFERENCES users(id),
+  FOREIGN KEY (to_uid) REFERENCES users(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+#### 8.2.4 rooms（房间表）
+```sql
+CREATE TABLE rooms (
+  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+  name        VARCHAR(100) NOT NULL,
+  owner_id    BIGINT NOT NULL,
+  type        VARCHAR(20) DEFAULT 'public',
+  password    VARCHAR(255),
+  max_members INT DEFAULT 100,
+  status      TINYINT DEFAULT 1,
+  created_at  DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at  DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  INDEX idx_owner (owner_id),
+  FOREIGN KEY (owner_id) REFERENCES users(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+#### 8.2.5 room_members（房间成员表）
+```sql
+CREATE TABLE room_members (
+  id          BIGINT AUTO_INCREMENT PRIMARY KEY,
+  room_id     BIGINT NOT NULL,
+  user_id     BIGINT NOT NULL,
+  role        VARCHAR(20) DEFAULT 'member',
+  joined_at   DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_room_user (room_id, user_id),
+  FOREIGN KEY (room_id) REFERENCES rooms(id),
+  FOREIGN KEY (user_id) REFERENCES users(id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
+```
+
+### 8.3 Redis 数据结构设计（通过mm_cache操作）
+
+| Key模式 | 数据结构 | 用途 | 过期 |
+|---------|---------|------|------|
+| `session:{token}` | String | 用户会话 | 24h |
+| `user:{id}:online` | String | 在线状态 | 随连接 |
+| `user:{id}:info` | String | 用户信息缓存 | 30min |
+| `room:{id}:members` | Set | 房间成员 | - |
+| `room:{id}:info` | String | 房间信息缓存 | 30min |
+
+### 8.4 mm_sql 操作示例
+
+```javascript
+const { Sql } = require('mm_sql');
+
+// 创建连接
+const sql = new Sql({
+  db_type: 'mysql',
+  host: 'localhost',
+  user: 'root',
+  password: '***',
+  database: 'mm_server'
+});
+
+// 查询
+const users = await sql.run('SELECT * FROM users WHERE status = ?', [1]);
+
+// 插入
+const result = await sql.exec(
+  'INSERT INTO users (username, password, nickname) VALUES (?, ?, ?)',
+  ['test', 'hashed_pwd', '测试']
+);
+
+// 更新
+await sql.exec('UPDATE users SET nickname = ? WHERE id = ?', ['新昵称', 1]);
+
+// 关闭
+await sql.close();
+```
+
+### 8.5 mm_cache 操作示例
+
+```javascript
+const { Cache } = require('mm_cache');
+
+// 创建Redis缓存
+const cache = new Cache({
+  way: 'redis',
+  redis: { host: '127.0.0.1', port: 6379 }
+});
+
+// 基本操作
+await cache.set('key', 'value');
+const val = await cache.get('key');
+await cache.del('key');
+const exists = await cache.has('key');
+
+// 设置过期时间
+await cache.set('key', 'value', 3600);  // 1小时过期
+const ttl = await cache.ttl('key');     // 剩余时间
+
+---
+
+## 9. 部署架构建议
+
+### 9.1 开发环境部署
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  mysql:
+    image: mysql:8
+    environment:
+      MYSQL_DATABASE: mm_server
+      MYSQL_USER: mm_user
+      MYSQL_PASSWORD: mm_pass
+      MYSQL_ROOT_PASSWORD: root_pass
+    ports:
+      - "3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+
+  redis:
+    image: redis:7
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+
+  mm-server:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      NODE_ENV: development
+      DB_HOST: mysql
+      REDIS_HOST: redis
+    volumes:
+      - ./:/app
+      - /app/node_modules
+    depends_on:
+      - mysql
+      - redis
+
+volumes:
+  mysql_data:
+  redis_data:
+```
+
+### 9.2 生产环境部署架构
+
+```
+                                  ┌─────────────┐
+                                  │  Nginx/LB   │
+                                  │  负载均衡    │
+                                  └──────┬──────┘
+                                         │
+                    ┌────────────────────┼────────────────────┐
+                    │                    │                    │
+           ┌────────▼──────┐   ┌────────▼──────┐   ┌────────▼──────┐
+           │  MM Server 1  │   │  MM Server 2  │   │  MM Server N  │
+           │  (mm_machine)  │   │  (mm_machine)  │   │  (mm_machine)  │
+           └────────┬──────┘   └────────┬──────┘   └────────┬──────┘
+                    │                    │                    │
+                    └────────────────────┼────────────────────┘
+                                         │
+                    ┌────────────────────┼────────────────────┐
+                    │                    │                    │
+           ┌────────▼──────┐   ┌────────▼──────┐             │
+           │  MySQL主库     │   │  MySQL从库     │             │
+           │  (写)          │──▶│  (读)          │             │
+           └───────────────┘   └───────────────┘             │
+                                                              │
+           ┌───────────────┐   ┌──────────────────────────────┘
+           │  Redis主从     │
+           │  (缓存/会话)   │
+           └───────────────┘
+```
+
+### 9.3 环境要求
+
+| 环境 | Node.js | MySQL | Redis | 内存 | 磁盘 |
+|------|---------|-------|-------|------|------|
+| 开发 | 20 LTS | 8.0+ | 7.x | 4GB+ | 20GB+ |
+| 生产 | 20 LTS | 8.0+ | 7.x | 8GB+ | 50GB+ |
+
+### 9.4 监控与运维
+
+| 监控项 | 工具 | 说明 |
+|-------|------|------|
+| 应用日志 | mm_logs | 自动日志轮转 |
+| 性能监控 | Node.js 内置 + PM2 | CPU/内存/事件循环 |
+| 进程管理 | PM2 | 进程守护、自动重启 |
+| 健康检查 | HTTP /health | 服务状态检测 |
+
+---
+
+## 10. mm框架集成方案
+
+### 10.1 框架安装
+
+```bash
+# 创建项目
+mkdir MMServer && cd MMServer
+npm init -y
+
+# 安装mm框架核心
+npm install mm_machine mm_expand mm_config mm_logs mm_ret
+
+# 安装数据组件（按需选择）
+npm install mm_sql mm_mysql        # MySQL支持
+npm install mm_cache               # 缓存支持
+npm install mm_https               # HTTP客户端
+
+# 安装Web框架
+npm install express socket.io
+
+# 安装工具库
+npm install jsonwebtoken bcryptjs
+npm install --save-dev nodemon
+```
+
+### 10.2 启动流程
+
+```
+1. index.js 启动
+    │
+2. new Machine() → 创建引擎
+    │
+3. engine.loads() → 加载 app/ 下所有模块
+    │
+4. engine.exec('init') → 初始化所有模块
+    │
+5. engine.exec('main') → 启动所有模块
+    │       │
+    │  ┌────┴────┐
+    │  ▼         ▼
+    │  http_server 启动 (端口3000)
+    │  websocket 启动 (端口3001)
+    │  cache 连接Redis
+    │  database 连接MySQL
+    │  auth/user/message/room 注册路由
+    │
+6. engine.watch() → 开启热更新
+    │
+7. 服务就绪，等待请求
+```
+
+### 10.3 模块开发规范
+
+#### 10.3.1 创建新模块步骤
+
+```
+1. 在 app/ 下创建模块目录：mkdir app/my_module
+2. 创建配置文件：config_mm_server.json
+3. 创建模块实现：index.js
+4. 重启服务或等待热更新自动加载
+```
+
+#### 10.3.2 模块配置规范
+
+```json
+{
+  "name": "my_module",
+  "title": "我的模块",
+  "description": "模块功能描述",
+  "sort": 50,
+  "state": 1,
+  "show": 1,
+  "options": {
+    "custom_option": "value"
+  }
+}
+```
+
+| 配置项 | 说明 |
+|--------|------|
+| name | 模块唯一标识，通过 engine.get(name) 获取 |
+| title | 模块显示名称 |
+| sort | 执行顺序，值越小越先执行 |
+| state | 状态：1启用 0禁用 |
+| show | 是否显示在列表中 |
+| options | 自定义配置 |
+
+#### 10.3.3 模块间通信
+
+```javascript
+// 方式1：通过 engine 获取其他模块
+const userModule = this.parent.get('user');
+if (userModule) {
+  const result = await userModule.getUserInfo(userId);
+}
+
+// 方式2：通过事件系统
+const $ = require('mm_expand');
+$.eventer.emit('user:login', { userId: 123 });
+$.eventer.on('user:login', (data) => {
+  $.log.info('用户登录:', data.userId);
+});
+
+// 方式3：通过共享缓存
+const cache = this.parent.get('cache');
+await cache.set('key', value);
+const data = await cache.get('key');
+```
+
+### 10.4 热更新开发体验
+
+```javascript
+// 开发模式下启动
+NODE_ENV=development node index.js
+
+// 修改模块文件后，mm_machine 自动检测并重载
+// 无需手动重启，开发效率大幅提升
+```
+
+### 10.5 错误处理规范
+
+```javascript
+const { Ret } = require('mm_ret');
+
+// 统一错误处理中间件
+async function errorHandler(ctx, next) {
+  try {
+    await next();
+  } catch (err) {
+    $.log.error('请求异常:', err);
+
+    if (err.code) {
+      // 已知业务错误
+      ctx.body = Ret.error(err.code, err.message);
+    } else {
+      // 未知系统错误
+      ctx.body = Ret.error(5000, '服务器内部错误');
+    }
+  }
+}
+```
+
+---
+
+## 11. 后续规划
+
+### 11.1 实施路线图
+
+```
+阶段一：框架搭建（第1周）
+├── 安装mm框架依赖
+├── 创建项目骨架（index.js + app/目录）
+├── 实现 engine 模块（mm_machine启动）
+├── 实现 http_server 模块（Express集成）
+├── 实现 cache 模块（mm_cache）
+├── 实现 database 模块（mm_sql）
+└── 验证模块加载和热更新
+
+阶段二：核心业务（第2周）
+├── 实现 auth 模块（注册/登录/Token）
+├── 实现 user 模块（用户资料/好友）
+├── 数据库表创建
+└── 单元测试
+
+阶段三：实时通信（第3周）
+├── 实现 websocket 模块
+├── 实现 message 模块
+├── 实现 room 模块
+└── 集成测试
+
+阶段四：完善部署（第4周）
+├── 实现 admin 模块
+├── Docker部署配置
+├── 性能测试与优化
+├── 文档完善
+└── 上线部署
+```
+
+### 11.2 待确认事项
+
+| # | 事项 | 影响 |
+|---|------|------|
+| 1 | mm框架各模块的具体版本 | 依赖安装 |
+| 2 | 核心业务场景（游戏/IM/社交？） | 模块优先级 |
+| 3 | 预期用户规模 | 部署架构 |
+| 4 | 数据库选型（MySQL/PostgreSQL） | mm_sql配置 |
+| 5 | 是否使用Express或其他HTTP框架 | 路由模块实现 |
+
+### 11.3 风险与应对
+
+| 风险 | 应对措施 |
+|------|---------|
+| mm框架版本兼容问题 | 锁定版本号，提前验证 |
+| 高并发性能瓶颈 | 利用mm_cache缓存热点数据，水平扩展 |
+| 模块间耦合 | 通过事件系统和缓存解耦 |
+| 热更新导致状态丢失 | 无状态设计，状态存入Redis |
+
+---
+
+> **文档结束**
+>
+> 本文档为MMServer项目基于mm框架的架构设计方案v2.0。
+> 核心思路：以 **mm_machine** 为引擎，**mm_expand** 为工具库，配合 Express + WebSocket 构建完整的服务端体系。
+> 如有任何问题或建议，请与架构师联系。