架构概览 / Architecture

目录结构 / Directory Structure

NeurolingsCE/
├── src/app/ # Qt 应用层(14 个 .cc 源文件)
├── src/platform/Platform/ # 平台抽象层(Windows/Linux/macOS)
├── include/shijima-qt/ # 公共头文件(与 src/app/ 一一对应)
├── libshijima/ # [子模块] 核心看板娘模拟引擎
├── libshimejifinder/ # [子模块] 资源包导入解压
├── cpp-httplib/ # [子模块] HTTP 服务器(header-only)
├── miniz/ # 轻量级 ZIP 库(用于 SimpleZipImporter)
├── cmake/ # CMake 辅助脚本
├── translations/ # i18n 翻译文件
├── src/assets/ # 内置默认看板娘精灵图 + XML
├── src/packaging/ # 桌面入口、图标、.app 骨架
├── src/tools/ # Shell 辅助脚本
├── src/docs/ # HTTP API 文档
├── src/resources/ # Windows 资源文件(.rc)+ Qt 资源(.qrc)
├── licenses/ # 第三方许可证文本(构建时嵌入)
├── dev-docker/ # Fedora Docker 镜像(Windows 交叉编译)
└── .github/workflows/ # CI 工作流

核心类图 / Core Class Diagram

┌─────────────────────────────────────────────────────────────────┐
│ main.cc │
│ QApplication → 单实例检查 → ShijimaManager::defaultManager() │
└────────────────────────────┬────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ ShijimaManager │
│ (PlatformWidget<QMainWindow> 单例) │
│ │
│ 职责 / Responsibilities: │
│ ├── 管理看板娘生命周期(生成、销毁、tick 循环) │
│ ├── 管理已加载的看板娘资源包 (MascotData) │
│ ├── 同步多屏幕环境信息 (environment) │
│ ├── 处理拖放导入 │
│ ├── 语言切换 │
│ └── 协调 HTTP API 和窗口观察器 │
│ │
│ 关键成员 / Key Members: │
│ ├── m_mascots: list<ShijimaWidget*> ← 活跃的看板娘实例 │
│ ├── m_loadedMascots: QMap<名称, MascotData*> │
│ ├── m_httpApi: ShijimaHttpApi ← HTTP REST API │
│ ├── m_windowObserver: ActiveWindowObserver ← 窗口追踪 │
│ ├── m_factory: shijima::mascot::factory ← 看板娘工厂 │
│ └── m_env: QMap<QScreen*, environment> ← 每屏幕环境 │
└──────┬──────────┬──────────┬──────────┬────────────────────────┘
 │ │ │ │
 ▼ ▼ ▼ ▼
┌────────────┐ ┌────────┐ ┌──────────┐ ┌────────────────────┐
│ShijimaWidget│ │MascotData│ │ShijimaHttpApi│ │ActiveWindowObserver│
│(看板娘窗口) │ │(资源数据) │ │(HTTP API) │ │(窗口追踪) │
└────────────┘ └────────┘ └──────────┘ └────────────────────┘

核心组件详解 / Core Components

1. ShijimaManager(看板娘管理器)

2. ShijimaWidget(看板娘窗口)

3. MascotData(看板娘数据)

4. AssetLoader(资源加载器)

5. Asset(精灵图资源)

6. ShijimaHttpApi(HTTP API)

7. ShijimaContextMenu(右键菜单)

8. SimpleZipImporter(ZIP 导入器)

9. SoundEffectManager(音效管理器)

10. PlatformWidget(平台窗口模板)

// 用法
class ShijimaManager : public PlatformWidget<QMainWindow> { ... };
class ShijimaWidget : public PlatformWidget<QWidget> { ... };

数据流 / Data Flow

启动流程 / Startup Flow

main()
 │
 ├── argc > 1? → shijimaRunCli() // CLI 模式
 │
 ├── Platform::initialize() // 平台初始化
 ├── QApplication 创建
 │
 ├── HTTP ping 127.0.0.1:32456 // 单实例检查
 │ ├── 响应成功 → 报错退出
 │ └── 无响应 → 继续
 │
 ├── ShijimaManager::defaultManager()->show()
 │ ├── 加载默认看板娘 (DefaultMascot.cc)
 │ ├── 扫描 mascots/ 目录加载已有资源包
 │ ├── 启动 HTTP API 服务器
 │ ├── 启动窗口观察器定时器
 │ └── 启动 tick 定时器 (25 FPS)
 │
 └── app.exec() // Qt 事件循环

Tick 循环 / Tick Loop

timerEvent() (每 40ms = 25 FPS)
 │
 ├── updateEnvironment() // 更新屏幕/窗口信息
 │ └── m_windowObserver.tick() // 轮询前台窗口
 │
 ├── for each ShijimaWidget:
 │ └── widget->tick()
 │ ├── m_mascot->tick() // libshijima 状态推进
 │ ├── updateOffsets() // 计算绘制位置
 │ └── repaint() // 触发 paintEvent
 │
 └── 处理 tickCallbacks // HTTP API 的线程安全回调
 └── m_tickCallbackCompletion.notify_all()

资源包导入流程 / Mascot Import Flow

用户拖拽 .zip → dropEvent()
 │
 ├── SimpleZipImporter::import() // 或 libshimejifinder
 │ ├── 解压 ZIP
 │ ├── 识别资源包布局
 │ └── 复制到 mascots/<name>/
 │
 ├── loadData(MascotData*) // 解析 XML 注册到工厂
 │ └── m_factory.load_template() // libshijima 加载模板
 │
 └── refreshListWidget() // 刷新 UI 列表

子模块关系 / Submodule Relations

NeurolingsCE (Qt App)
 │
 ├── libshijima (只读依赖 / Read-only)
 │ ├── 看板娘行为模拟引擎
 │ ├── XML 解析 (rapidxml)
 │ ├── JavaScript 脚本 (duktape)
 │ └── shijima::mascot::manager / factory / environment
 │
 ├── libshimejifinder (只读依赖 / Read-only)
 │ ├── 资源包归档解压
 │ └── 依赖 libunarr + libarchive
 │
 └── cpp-httplib (只读依赖 / Read-only)
 └── HTTP 服务器/客户端 (header-only)

条件编译 / Conditional Compilation

相关页面 / Related Pages