@love-sqjm/magic 2026.4.15

package/doc/architecture.md

@@ -0,0 +1,322 @@
+# Magic 框架技术架构
+
+## 1. 系统概述
+
+Magic 是一个基于 Bun.js 的全栈 Web 开发框架，采用命令行工具 + 编译器的架构设计。框架核心是一个自定义的 `.m` 文件编译器，将声明式的组件文件编译为标准 JavaScript 和 CSS。
+
+## 2. 整体架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        CLI 层                               │
+│                   (index.js / commander.js)                  │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                      核心业务层                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
+│  │ create-project│  │ build-project │  │  run-project │     │
+│  └──────────────┘  └──────────────┘  └──────────────┘     │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                     编译器层                                 │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                   Compiler Pipeline                    │  │
+│  │  Step1 → Step2 → Step3 → Step4 → Step5 → Step6 → End │  │
+│  └──────────────────────────────────────────────────────┘  │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────────────┐
+│                     运行时层                                 │
+│              (runtime.js / runtime.css)                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 3. 目录结构
+
+```
+magic/
+├── index.js                 # CLI 入口
+├── app.js                   # 全局配置
+├── package.json             # 依赖配置
+│
+├── script/                  # 核心业务逻辑
+│   ├── global/              # 全局工具
+│   │   ├── printf.js        # 日志系统
+│   │   ├── project-build-config.js  # 配置校验
+│   │   └── support-platform.js      # 平台列表
+│   │
+│   ├── module/              # 功能模块
+│   │   └── compiler/         # 编译器
+│   │       ├── start.js     # 编译入口
+│   │       ├── global.js    # 编译状态
+│   │       ├── macro.js     # 宏定义
+│   │       ├── macro-replace.js   # 宏替换
+│   │       ├── index-dom.js # HTML 生成
+│   │       ├── id-generate.js    # ID 生成
+│   │       └── step/        # 编译步骤
+│   │           ├── 1.js     # 配置解析
+│   │           ├── 2.js      # 文件扫描
+│   │           ├── 3.js     # 目录初始化
+│   │           ├── 4.js     # 文件分类
+│   │           ├── 5.js     # 核心编译
+│   │           ├── 6.js     # 代码生成
+│   │           └── end.js   # 压缩输出
+│   │
+│   ├── util/                # 工具函数
+│   │   ├── task.js          # 任务包装
+│   │   ├── logging.js       # 日志类
+│   │   ├── file-util.js     # 文件操作
+│   │   ├── filtration-file.js   # 文件过滤
+│   │   ├── copy-dir.js      # 目录复制
+│   │   ├── traversal.js     # 对象遍历
+│   │   └── ...
+│   │
+│   ├── build-project.js     # 构建逻辑
+│   ├── create-project.js    # 创建逻辑
+│   ├── run-project.js       # 运行逻辑
+│   └── config.js            # 运行配置
+│
+├── template/                # 项目模板
+│   ├── platform-config/     # 平台配置
+│   │   ├── web
+│   │   └── node-webkit
+│   ├── project-base/        # 项目基础
+│   │   ├── build.toml
+│   │   ├── build.module.toml
+│   │   └── app.xml
+│   └── runtime/             # 运行时文件
+│       ├── runtime.js
+│       └── runtime.css
+│
+└── doc/                     # 文档
+```
+
+## 4. 核心模块详解
+
+### 4.1 CLI 入口 (index.js)
+
+负责命令行参数解析和命令分发。
+
+```javascript
+// 可用命令
+magic init [name] --web          // 创建 Web 项目
+magic init [name] --node-webkit  // 创建桌面项目
+magic init [name] --module       // 创建模块项目
+magic build                      // 构建项目
+magic run                        // 运行项目
+magic build-run                  // 构建并运行
+magic create-m [filename]         // 创建组件文件 (.m)
+```
+
+### 4.2 项目创建 (create-project.js)
+
+- 读取平台配置模板
+- 创建项目目录结构
+- 生成 `build.toml` 和 `app.xml`
+
+### 4.3 项目构建 (build-project.js)
+
+调用编译器流水线处理源码。
+
+### 4.4 编译器流水线
+
+#### Step 1: 配置解析 (step/1.js)
+
+```javascript
+examine_BuildConfig()   // 校验 build.toml
+examine_AppConfig()    // 解析 app.xml
+```
+
+#### Step 2: 文件扫描 (step/2.js)
+
+```javascript
+source_file = {
+    ".m": [source, source, ...],
+    ".css": [source, ...],
+    ".js": [...],
+    "*it": () => [...]  // 迭代所有文件
+}
+```
+
+#### Step 3: 目录初始化 (step/3.js)
+
+- 清空并创建输出目录
+- 复制 runtime 文件
+
+#### Step 4: 文件分类 (step/4.js)
+
+- `.m` 文件收集到数组待处理
+- 其他文件直接复制到输出目录
+
+#### Step 5: 核心编译 (step/5.js)
+
+`.m` 文件解析的关键处理：
+
+| 标签 | 处理内容 |
+|------|----------|
+| `<import>` | 模块导入解析 |
+| `<template>` | DOM 模板解析 |
+| `<script>` | 脚本分类编译 |
+| `<css>` | CSS 作用域处理 |
+| `<expose-event>` | 事件暴露定义 |
+
+#### Step 6: 代码生成 (step/6.js)
+
+- 生成独立的 `.js` 和 `.css` 文件
+- 处理模块导入
+- Debug/Release 模式分别处理
+
+#### End: 压缩输出 (step/end.js)
+
+- HTML/JS/CSS 压缩
+- CSS Autoprefixer 处理
+- 生成最终 `index.html`
+
+### 4.5 项目运行 (run-project.js)
+
+| 平台 | 处理方式 |
+|------|----------|
+| web (server) | 启动 HTTP 服务器 + WebSocket 热更新 |
+| web (browser) | 直接打开浏览器 |
+| node-webkit | 调用 NW.js 启动 |
+
+## 5. 数据流
+
+```
+源码 (.m)
+    │
+    ▼
+┌─────────┐
+│ Step 1 │ ← build.toml / app.xml
+└────┬────┘
+     ▼
+┌─────────┐
+│ Step 2 │ ← 文件扫描过滤
+└────┬────┘
+     ▼
+┌─────────┐
+│ Step 3 │ ← 初始化输出目录
+└────┬────┘
+     ▼
+┌─────────┐
+│ Step 4 │ ← 分离 .m 文件
+└────┬────┘
+     ▼
+┌─────────┐
+│ Step 5 │ ← AST 解析 + 宏处理 + 代码转换
+└────┬────┘
+     ▼
+┌─────────┐
+│ Step 6 │ ← 生成 .js / .css
+└────┬────┘
+     ▼
+┌─────────┐
+│  End    │ ← 压缩 + 输出 index.html
+└────┬────┘
+     ▼
+  输出目录
+```
+
+## 6. 关键技术点
+
+### 6.1 Babel AST 转换
+
+编译器使用 Babel 生态进行 JavaScript 代码转换：
+
+- `@babel/parser` - 解析源码为 AST
+- `@babel/traverse` - 遍历和修改 AST
+- `@babel/generator` - 将 AST 转换回代码
+- `@babel/types` - 构建和操作 AST 节点
+
+### 6.2 CSS 作用域
+
+Magic 使用特有的 `#id:xx` 选择器实现样式作用域：
+
+```css
+/* 源码 */
+<css scope="#id:myComponent">
+div { color: red; }
+</css>
+
+/* 编译后 */
+.m-css-scope-abc123 div { color: red; }
+```
+
+### 6.3 宏系统
+
+编译时宏在 Step 5 中通过 Babel 插件处理：
+
+| 宏 | 功能 |
+|----|------|
+| `magic_define_include` | 文件内容替换 |
+| `magic_define_ui_data` | 创建 UiData 对象 |
+| `magic_dynamic_value_bind` | 动态值绑定 |
+
+### 6.4 模块导入
+
+模块通过 `importM()` 函数在运行时加载：
+
+```javascript
+// 定义模块 (编译后)
+window["__MAGIC__"]["M"]["uisharengcsettingdialog"] = function(...) {...}
+
+// 导入模块 (运行时)
+const dialog = magic.importM("ui/share/ngc-setting-dialog");
+```
+
+## 7. 配置校验机制
+
+使用 `Type` 类定义配置项约束：
+
+```javascript
+const Type = class {
+    constructor(type, key = true, scope)
+    getScope()   // 获取枚举范围
+    getType()    // 获取类型
+    isKey()      // 是否必需
+}
+```
+
+`ProjectBuildConfigContrast()` 对比校验配置合法性。
+
+## 8. 扩展性设计
+
+### 8.1 平台扩展
+
+在 `template/platform-config/` 添加新平台配置即可扩展。
+
+### 8.2 编译器扩展
+
+在 `step/` 目录添加新的编译步骤文件。
+
+### 8.3 宏扩展
+
+在 `step/5.js` 的 `pretreatmentMagicMacro()` 中添加新的宏处理逻辑。
+
+## 9. 性能考虑
+
+- Step 5 中多个 `.m` 文件并行处理
+- CSS/JS 代码分块输出 (默认 1MB/块)
+- 文件变化通过 WebSocket 轮询检测
+
+## 10. 依赖关系图
+
+```
+index.js
+├── commander
+├── app.js
+├── build-project.js → compiler/*
+├── create-project.js → app.js
+└── run-project.js → app.js, ws
+
+compiler/*
+├── step/1.js → app.js, babel/parser
+├── step/2.js → app.js, fast-glob
+├── step/3.js → app.js
+├── step/4.js
+├── step/5.js → babel/*, postcss, node-html-parser
+├── step/6.js → app.js, terser
+└── end.js → terser, html-minifier, postcss, autoprefixer
+```