Repository Wiki
ChanIok/SpinningMomo

核心层：RPC 传输、访问控制、环境与任务

核心层（src/core/）是 SpinningMomo 前端应用的公共基础设施层，承载异步执行、命令注册、数据库访问、事件分发与对话框服务等横切能力，并为上层的 RPC 传输、访问控制、环境变量与任务执行提供统一的支撑环境。本页给出该层已验证的模块组成、分层架构与各子系统的职责边界。

⚠️ 证据限制声明：在本页的源码探索预算（6 次源码工具调用）耗尽时，仅完成了目录结构与文件清单的验证，未能读取任何文件正文。因此本页对"RPC 传输、访问控制、环境变量、任务"这四项运行时行为的描述仅停留在模块命名与分层推断层面；文中所有基于文件名/目录结构的结论均以"结构推断"标注，未经过代码级验证。本页不包含任何代码示例——按照文档规范，无法从真实源码中提取的示例一律不虚构。

Purpose and Scope（目的与范围）

本页覆盖以下内容：

  • src/core/ 目录下已验证存在的五个子系统模块（async、commands、database、dialog_service、events）的组成与职责划分（基于文件清单）。
  • src/app.cpp / src/app.hpp 应用入口与核心层的关系。
  • 核心层构建常量（build_config.hpp、version.hpp）的作用。
  • 与目录标题中"RPC 传输、访问控制、环境与任务"相关的能力归属推断，以及尚待代码验证的空白点。

本页不覆盖（留给兄弟页面）：

  • 数据库层（database/）的数据映射与持久化细节 → 属于数据库/持久化专题页。
  • 命令系统的内置命令清单与命令处理流程 → 属于命令系统专题页。
  • 事件总线的事件清单与订阅模式 → 属于事件系统专题页。
  • UI 组件与前端渲染逻辑 → 属于 UI 层专题页。

Overview（概述）

SpinningMomo 的 src/core/ 目录采用按子系统分文件夹的组织方式，每个子系统内部遵循统一的文件分工模式：

模块目录已验证文件结构推断的职责
src/core/async/async.cpp、async.hpp、state.hpp、ui_awaitable.hpp异步执行基础设施，含 UI 线程可等待对象（awaitable）与异步状态管理
src/core/commands/builtin.cpp、registry.cpp、registry.hpp、state.hpp、types.hpp命令注册中心（registry）、内置命令（builtin）、命令类型与状态
src/core/database/data_mapper.hpp、database.cpp、database.hpp、state.hpp、types.hpp数据库连接/访问与数据映射（mapper）
src/core/dialog_service/dialog_service.cpp、dialog_service.hpp、state.hpp对话框服务，统一封装弹窗/提示交互
src/core/events/events.cpp、events.hpp、registrar.cpp事件定义与事件注册器
src/core/（根）build_config.hpp、version.hpp构建期常量与版本信息

值得注意的是，每个子系统普遍包含一个 state.hpp，这表明核心层采用集中式状态声明 + 分离实现（.cpp/.hpp）+ 类型契约（types.hpp）的一致化设计模式；events/registrar.cpp 与 commands/registry.cpp 的命名则暗示核心层通过注册器模式将分散的能力聚合到统一入口。

Architecture（架构）

下图基于已验证的目录清单绘制，箭头表示结构推断的依赖方向（应用入口依赖核心层各子系统；各子系统共享构建常量与事件机制）：

Loading diagram...

设计意图解读（结构推断）：

  • 入口单一化：app.cpp/app.hpp 是唯一直接面向核心层的应用侧编排点，避免核心层被多处零散引用。
  • 注册器模式：commands/registry 与 events/registrar 的命名表明核心层把"可扩展能力点"集中到注册中心，新增能力通过注册而非修改入口完成，符合开闭原则。
  • 状态外置：各子系统的 state.hpp 把可变状态从算法实现中抽离，便于跨子系统共享与测试。
  • 类型契约前置：commands/types.hpp 与 database/types.hpp 定义了跨文件共享的数据契约，降低编译耦合。

目录标题四要素的归属说明（未验证项）

目录标题提到的"RPC 传输、访问控制、环境与任务"四项能力，在本次已验证的文件清单中未发现对应的独立目录（src/core/rpc/、access/、env/、task*/ 均为空结果，模式搜索亦返回空）。可能的解释包括：

  1. 这些能力可能内嵌在 app.cpp、commands/ 或 database/ 的实现文件中，未单独成目录；
  2. 相关代码可能位于 src/core/ 之外（如 src/ 根下的其他目录），本次预算内未能定位；
  3. 相关代码可能尚未提交到 main 分支。

由于未读取任何正文，本页不提供这四项能力的 API 签名、配置项、失败模式或代码示例，避免虚构。后续如需补全，应优先阅读 app.cpp、commands/builtin.cpp 与 database/database.cpp 三个最可能的落点。

文件分工模式（已验证的通用约定）

从文件命名可以稳定归纳出核心层每个子系统遵循的四类文件角色，这一约定本身就是核心层最重要的可维护性资产：

文件角色命名模式作用（结构推断）
接口头*.hpp（如 registry.hpp、database.hpp）对外暴露的类型、函数签名与注册入口
实现*.cpp（如 registry.cpp、builtin.cpp、registrar.cpp）具体实现与聚合注册逻辑
状态state.hpp子系统可变状态的定义与初始化
类型契约types.hpp跨文件共享的 DTO / 枚举 / 常量

Usage Examples（用法示例）

No code example available —— 本页生成时源码读取预算已耗尽，未能读取任何文件正文，因此无法提供经过验证的代码摘录。按照"不虚构代码"的硬性要求，本节留空，待后续预算可用时从上述文件中提取真实示例并附行号锚点。

Configuration Options（配置项）

No verified configuration options available。src/core/build_config.hpp 与 src/core/version.hpp 从命名看是构建期常量定义，但其键名、类型与默认值未经验证，不在此列出以免误导。

API Reference（API 参考）

No verified API signatures available。原因同上：未读取任何头文件正文，无法给出任何函数签名、参数或返回值。

Professional Notes（专业说明）

  • 并发与异步：async/ui_awaitable.hpp 的命名暗示存在面向 UI 线程的可等待（awaitable）抽象，通常与协程或异步消息泵配套；具体语义未验证。
  • 扩展点：commands/registry 与 events/registrar 是核心层最明确的两个扩展点——新增命令或事件应通过注册器接入，而非改动应用入口。
  • 测试建议：由于各子系统均有独立的 state.hpp 与 types.hpp，单元测试应以这些类型契约 + 注册器行为为主要切入点。
  • 文档补全路线：本页后续维护者应优先消耗读取预算在（1）src/app.cpp 应用装配流程；（2）commands/registry.hpp 注册契约；（3）database/database.hpp 连接生命周期，这三处能最快补齐"RPC 传输 / 访问控制 / 环境 / 任务"的真实落点。