@love-sqjm/magic 2026.4.15

package/doc/workflow.md

@@ -0,0 +1,548 @@
+# Magic 业务流程文档
+
+## 概述
+
+本文档描述 Magic 框架的核心业务流程，包括项目创建、编译构建、开发运行等关键环节。
+
+---
+
+## 1. 项目创建流程
+
+### 1.1 流程图
+
+```
+用户执行
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    magic init [name] --web                    │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                   createProject(name, "web")                  │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ 1. 获取平台配置模板 (template/platform-config/web)      │  │
+│  │ 2. 读取项目基础模板 (template/project-base/build.toml)  │  │
+│  │ 3. 替换模板变量 ($name, $target, $config)              │  │
+│  │ 4. 创建目录结构 (name/app/)                             │  │
+│  │ 5. 写入 build.toml 和 app/app.xml                      │  │
+│  │ 6. 创建 app/index.m 入口文件                            │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+                    项目创建完成
+```
+
+### 1.2 详细步骤
+
+| 步骤 | 函数 | 说明 |
+|------|------|------|
+| 1 | `createProject(name, platform)` | 入口函数 |
+| 2 | `app.templateDir.platformConfig.get(platform)` | 获取平台配置 |
+| 3 | `app.templateDir.projectBase.get("build.toml")` | 获取项目模板 |
+| 4 | 替换 `$name`, `$target`, `$config` | 填充配置 |
+| 5 | `fs.mkdirSync()` | 创建目录 |
+| 6 | `fs.writeFileSync()` | 写入配置文件 |
+| 7 | 创建 `app/index.m` | 创建入口组件文件 |
+
+---
+
+## 2. 项目构建流程
+
+### 2.1 完整编译流水线
+
+```
+magic build
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      BuildProject()                           │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 1: 配置解析                          │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ examine_BuildConfig()                                   │  │
+│  │ 1. 加载 build.toml                                    │  │
+│  │ 2. 校验配置项类型和范围                                 │  │
+│  │ 3. 解析 app.xml                                        │  │
+│  │ 4. 解析 import 标签                                     │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 2: 文件扫描                          │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ _2(build_config, app_config)                           │  │
+│  │ 1. 添加默认排除项 (app.xml, magic/)                     │  │
+│  │ 2. filtrationFile() 扫描所有源文件                      │  │
+│  │ 3. 按扩展名分组创建 source 对象                         │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 3: 目录初始化                         │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ _3()                                                   │  │
+│  │ 1. fs.rmSync() 清空输出目录                            │  │
+│  │ 2. fs.mkdirSync() 创建输出目录                          │  │
+│  │ 3. 复制 runtime.js 和 runtime.css                      │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 4: 文件分类                           │
+│  ┌────────────────────────────────────────────────────────┘  │
+│  │ _4()                                                   │  │
+│  │ 1. 遍历所有源文件                                       │  │
+│  │ 2. .m 文件收集到数组待处理                              │  │
+│  │ 3. 其他文件直接复制到输出目录                           │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 5: 核心编译                           │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ _5(m source[])                                         │  │
+│  │ 1. 解析 import 标签                                     │  │
+│  │ 2. 解析 template DOM 树                                 │  │
+│  │ 3. 分类处理 script 标签                                │  │
+│  │ 4. 处理 css 标签和作用域                                │  │
+│  │ 5. 处理 expose-event                                   │  │
+│  │ 6. Babel AST 宏替换                                     │  │
+│  │ 7. 生成 mData 对象数组                                  │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Step 6: 代码生成                          │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ _6(mDatas, CSS_VAR)                                    │  │
+│  │ 1. 处理模块导入                                         │  │
+│  │ 2. 创建 M*.js 和 M*.css 文件                           │  │
+│  │ 3. 更新 index_dom                                       │  │
+│  │ 4. debug/release 模式分别处理                           │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    End: 压缩输出                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ _end(paths)                                            │  │
+│  │ 1. 生成 index.html                                     │  │
+│  │ 2. HTML/JS/CSS 压缩                                     │  │
+│  │ 3. PostCSS Autoprefixer 处理                           │  │
+│  │ 4. 输出到 build/ 目录                                   │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+                      构建完成
+```
+
+---
+
+## 3. Step 5 核心编译详解
+
+### 3.1 .m 文件解析流程
+
+```
+.m 文件内容
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    parse() 解析 DOM                           │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                   各标签并行处理                               │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
+│  │ <import> │  │<template>│  │ <script> │  │   <css>   │     │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘     │
+└───────┼─────────────┼─────────────┼─────────────┼────────────┘
+        │             │             │             │
+        ▼             ▼             ▼             ▼
+┌──────────────────────────────────────────────────────────────┐
+│                    Babel AST 处理                             │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ 1. magic_define_include 宏替换                        │  │
+│  │ 2. magic_define_ui_data 转换                          │  │
+│  │ 3. magic_dynamic_value_bind 标记                       │  │
+│  │ 4. 提取事件/接口/监听函数                              │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+                    mData 对象
+```
+
+### 3.2 脚本分类处理
+
+| code 属性 | 处理方式 | 存储位置 |
+|-----------|----------|----------|
+| 无 / `default` | 直接拼接 | `data.script` |
+| `before` | 拼接后处理宏 | `data.before` |
+| `global` | 拼接后处理宏 | `data.global` |
+| `event` | 提取函数名，生成事件代码 | `data.event` |
+| `listen` | 提取函数名，生成监听代码 | `data.listen` |
+| `interface` | 提取函数名，生成接口代码 | `data.interface` |
+
+### 3.3 CSS 处理流程
+
+```
+<css scope="#id:button" default-theme>
+& {
+    background-color: #c6c6c6;
+}
+</css>
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 1. scope 属性解析                                            │
+│    → 确定作用域选择器                                        │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 2. 编译作用域选择器                                          │
+│    → 生成唯一类名 .m-css-scope-abc123                       │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 3. default-theme 处理 (可选)                                 │
+│    → 将 CSS 值转换为 CSS 变量                                │
+│    → 添加到 CSS_VAR 字符串                                  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 4. 输出                                                    │
+│    CSS: .m-css-scope-abc123 { background-color: ... }      │
+│    VAR: --button-m-css-scope-abc123-background-color: ...  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. 项目运行流程
+
+### 4.1 Web 平台运行
+
+```
+magic run
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│                      RunProject()                            │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 1. 加载 build.toml                                          │
+│ 2. examine_BuildConfig() 校验配置                            │
+│ 3. 根据 platform.target 分发                                │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                   platform["web"](config)                     │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ 判断运行模式:                                           │  │
+│  │ • browser: 启动浏览器                                  │  │
+│  │ • server: 启动 HTTP 服务器 + WebSocket                 │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│              HTTP 服务器 + WebSocket 热更新                    │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │ 1. http.createServer() 创建 HTTP 服务器                 │  │
+│  │ 2. ws.Server() 创建 WebSocket 服务器                   │  │
+│  │ 3. 处理静态文件请求                                     │  │
+│  │ 4. 广播刷新消息                                        │  │
+│  │ 5. 客户端自动刷新页面                                   │  │
+│  └────────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 4.2 热更新机制
+
+```
+┌─────────────┐         ┌─────────────┐         ┌─────────────┐
+│   客户端    │         │   服务器    │         │   文件系统   │
+└──────┬──────┘         └──────┬──────┘         └──────┬──────┘
+       │                       │                       │
+       │   WebSocket 连接       │                       │
+       │───────────────────────>│                       │
+       │                       │                       │
+       │                       │   每 500ms 轮询检查    │
+       │                       │───────────────────────>│
+       │                       │                       │
+       │                       │   文件变化检测         │
+       │                       │<───────────────────────│
+       │                       │                       │
+       │   发送刷新指令          │                       │
+       │<───────────────────────│                       │
+       │                       │                       │
+       │   location.reload()   │                       │
+       │   页面刷新             │                       │
+       │                       │                       │
+```
+
+---
+
+## 5. 模块导入流程
+
+### 5.1 导入解析
+
+```
+<import root="magic-ui/ui">
+    <module:control>
+        <list-view/>
+    </module:control>
+</import>
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 解析 namespace                                               │
+│   "control" → namespace: "control"                           │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 解析模块路径                                                  │
+│   module:list-view → magic-ui/ui/control/list-view          │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 生成导入映射                                                  │
+│ {                                                           │
+│   "control": {                                              │
+│     "list-view": "magic-ui/ui/control/list-view"            │
+│   }                                                         │
+│ }                                                           │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 运行时加载
+
+```
+magic.importM("list-view")
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 1. 名称标准化                                                │
+│    name = "list-view".replace(/[^a-zA-Z]/g, '').toLowerCase()│
+│    → "listview"                                             │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 2. 查找模块构造函数                                          │
+│    window["__MAGIC__"]["M"]["listview"]                     │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 3. 实例化                                                    │
+│    new window["__MAGIC__"]["M"]["listview"](args, listen)   │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+                    返回模块元素
+```
+
+---
+
+## 6. 事件系统流程
+
+### 6.1 事件定义与触发
+
+```
+【定义端】
+<script code="event">
+clickHandler = (event) => {
+    emit_event("click", { data: "test" });
+}
+</script>
+    │
+    ▼
+编译生成
+    │
+    ▼
+this.__magic_event = {
+    clickHandler: function(event) {...}
+};
+this.__magic_template.bind_event = () => {
+    magic.dom.event(element, "click", this, "clickHandler");
+};
+    │
+    ▼
+emit_event = magic.emit.event(_listen);
+    │
+    ▼
+emit_event("click", { data: "test" });
+```
+
+### 6.2 事件监听流程
+
+```
+【模板定义】
+<child-component #listen:select="onSelect"/>
+
+【编译后】
+magic.importM("child-component", {}, {
+    select: (data) => this.__magic_listen_onSelect(data)
+});
+
+【监听函数】
+<script code="listen">
+onSelect = (data) => {
+    console.log("Selected:", data);
+}
+</script>
+
+【触发流程】
+子模块 emit_event("select", { value: "A" })
+    │
+    ▼
+调用 _listen["select"]({ value: "A" })
+    │
+    ▼
+执行 onSelect({ value: "A" })
+```
+
+---
+
+## 7. 响应式数据流
+
+### 7.1 UiData 创建
+
+```
+const UiData = magic_define_ui_data({
+    text: "Hello",
+    count: 0
+});
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 编译时转换                                                   │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+const UiData = magic.createUiData({
+    text: "Hello",
+    count: 0
+}, _args);
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ createUiData() 返回深拷贝代理                                │
+│ • 支持类型转换                                               │
+│ • 支持嵌套对象                                               │
+│ • 返回响应式代理                                             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 7.2 动态值绑定
+
+```
+magic_dynamic_value_bind($textElement)
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 编译时转换                                                   │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+magic.DynamicValueBind($textElement, UiData);
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 运行时处理                                                   │
+│ 1. replaceMagicComments() 替换 ${} 为注释节点               │
+│ 2. UiData.__DynamicValueBind() 绑定                         │
+│ 3. 当 UiData 属性变化时自动更新文本节点                       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 8. 编译错误处理流程
+
+### 8.1 配置错误
+
+```
+examine_BuildConfig() 校验失败
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ ProjectBuildConfigContrast()                                │
+│ 发现类型不匹配或范围错误                                      │
+└──────────────────────────┬───────────────────────────────────┘
+                           │
+                           ▼
+抛出错误: "目标 [key = value] 类型应该为 type"
+```
+
+### 8.2 编译时错误
+
+```
+step/5.js Babel 解析失败
+    │
+    ▼
+┌──────────────────────────────────────────────────────────────┐
+│ 抛出错误信息                                                  │
+│ code: <错误码>                                               │
+│ 错误原因: <reasonCode>                                       │
+│ 行 <line>, 列 <column>                                      │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. 构建产物结构
+
+### 9.1 Debug 模式
+
+```
+build/
+├── index.html                    # 主页面
+├── magic/
+│   ├── runtime.js               # 运行时
+│   ├── runtime.css              # 运行时样式
+│   ├── default-theme-var.css   # 主题变量
+│   ├── 模块1.js                  # 每个模块独立文件
+│   ├── 模块1.css
+│   ├── 模块2.js
+│   └── 模块2.css
+├── 其他资源文件...
+```
+
+### 9.2 Release 模式
+
+```
+build/
+├── index.html                    # 压缩后的主页面
+├── magic/
+│   ├── runtime.js               # 可能压缩
+│   ├── runtime.css
+│   ├── default-theme-var.css
+│   ├── m.js                      # 合并的 JS（可能分块）
+│   └── m-1.js                    # 超过 1MB 的分块
+│       └── m-2.css               # CSS 分块
+├── 其他资源文件...
+```