# Structrail 系统架构设计与技术选型

本文档总结了 Structrail 平台的技术架构决策，包括 Monorepo 策略、服务拆分原则以及前后端架构方案的对比分析。

## 1. 总体架构策略：Monorepo (单体仓库)

考虑到 Structrail 项目涉及多语言 SDK、统一的协议定义、前端可视化组件以及后端执行服务，我们决定采用 **Monorepo** 架构。

### 核心收益
1.  **单一事实来源 (Single Source of Truth)**：协议定义 (`@structrail/protocol`) 作为核心资产，被前端、后端、SDK 共同引用。协议变更时，所有依赖方均可即时感知（类型检查报错），避免版本割裂。
2.  **原子化提交 (Atomic Commits)**：由于协议变更往往涉及多端修改（如 ArrayTracer 新增指令 -> 前端渲染逻辑更新 -> SDK 实现更新），Monorepo 允许在一个 Commit 中完成所有相关修改，保证系统一致性。
3.  **统一版本管理**：便于统一管理多语言 SDK 的版本发布节奏。
4.  **开发体验**：利用 `pnpm workspace` 和 `Turborepo` 等工具，实现高效的依赖管理和增量构建。

## 2. 服务架构设计

Structrail 的业务特性决定了其架构必须采用 **动静分离** 的策略，将轻量级的业务逻辑与重量级的代码执行隔离。

### 2.1 核心服务拆分

| 服务模块 | 职责描述 | 技术特征 |
| :--- | :--- | :--- |
| **Web (业务层)** | 用户界面、题目管理、社区互动、鉴权 | I/O 密集型，重交互，适合快速开发 |
| **API (接口层)** | 业务逻辑处理、数据转发、RPC 服务 | 高并发，低延迟，连接 Web 与 Runner |
| **Runner (执行层)** | 代码编译、沙箱运行、Trace 数据生成 | CPU 密集型，高风险，需独立部署与资源隔离 |
| **Protocol (共享层)** | 核心协议定义、类型声明、常量 | 纯代码库，无运行时依赖 |

### 2.2 架构方案对比

针对 Web 与 API 的实现，我们探讨了两种主流方案。两种方案均可行，且在 Monorepo 下都能实现 **100% 的端到端类型安全**。

#### 方案 A：Next.js 全栈架构 (SSR 优先)
*   **架构描述**：Web 与 API 合二为一，直接在 Next.js 的 Server Actions / Route Handlers 中处理业务逻辑，并调用 Runner 服务。
*   **优势**：
    *   **开发效率极致**：无 API 胶水层，前后端代码在同一文件中，调用后端函数像调用本地函数一样自然。
    *   **SSR 支持**：对 SEO 友好，首屏加载快（适合题目详情页、文档页）。
    *   **生态丰富**：Vercel/Next.js 生态拥有大量现成组件。
*   **劣势**：
    *   **部署绑定**：较强依赖 Node.js Runtime 或 Vercel 平台。
    *   **边界模糊**：Server Actions 可能导致前后端代码耦合，心智负担较重。

#### 方案 B：React (SPA) + Hono (API) 前后端分离 (CSR + Edge 优先)
*   **架构描述**：
    *   **Web**: 纯 React SPA，通过 CDN 分发。
    *   **API**: 独立 Hono 服务，提供 RPC 接口。
    *   **通信**: 通过 `hono/client` 实现类型安全的 RPC 调用。
*   **优势**：
    *   **物理边界清晰**：前端关注 UI 交互，后端关注数据处理，职责分明。
    *   **部署极其灵活**：前端可部署至任何静态托管（OSS/Netlify），后端可部署至 Edge（Cloudflare Workers/Deno）或容器。
    *   **高性能**：Hono 基于 Web Standards，冷启动快，资源占用极低。
    *   **类型安全**：通过 Monorepo 导出 API 类型 (`AppType`)，前端直接引用，实现与 tRPC 类似的开发体验。
*   **劣势**：
    *   **SEO 略弱**：纯 SPA 对 SEO 不如 SSR 友好（虽然可以通过预渲染解决）。
    *   **初期搭建成本**：需配置两个独立应用及通信链路。

### 2.3 结论与推荐

**推荐采用 Monorepo 架构，并根据团队偏好选择方案 A 或 B。**

*   如果更看重 **SEO** 和 **快速验证原型**，推荐 **方案 A (Next.js)**。
*   如果更看重 **架构清晰度**、**部署灵活性 (Edge)** 和 **前后端解耦**，推荐 **方案 B (React + Hono)**。
    *   *注：考虑到 Structrail 的编辑器交互极其复杂（重客户端逻辑），且 Runner 服务天然适合独立部署，**方案 B** 在长期维护和扩展性上可能更具优势。*

## 3. 建议的项目目录结构

无论选择哪种方案，Monorepo 的基础结构应保持一致：

```text
structrail/
├── apps/                          # 应用程序（业务层）
│   ├── web/                       # [React/Next.js] 平台前端
│   │   └── ... (Visualizer 组件调用)
│   ├── api/                       # [Hono/Node] 业务后端 (如果是方案 B)
│   ├── runner/                    # [Go/Rust] 代码执行沙箱服务
│   └── docs/                      # [VitePress] 文档站点
│
├── packages/                      # 共享库（核心资产）
│   ├── protocol/                  # 核心协议定义 (JSON Schema, TS Interfaces)
│   │   ├── index.ts               # 导出 Tracer 类型、指令定义
│   │   └── schema.json            # 用于校验 Trace 数据的 Schema
│   ├── sdk-ts/                    # TypeScript SDK 实现
│   ├── ui/                        # 通用 UI 组件库 (可选)
│   └── eslint-config/             # 统一的代码规范配置
│
├── sdks/                          # 多语言 SDK (非 JS/TS 生态)
│   ├── c/                         # C 语言 SDK (Makefile)
│   ├── python/                    # Python SDK (Poetry)
│   ├── java/                      # Java SDK (Maven/Gradle)
│   └── ...
│
├── tools/                         # 工程化脚本
│   └── scripts/                   # 批量发布、协议生成脚本
│
├── package.json                   # Root package.json
├── pnpm-workspace.yaml            # pnpm workspace 配置
└── turbo.json                     # Turborepo 构建编排配置
```

## 4. 关键技术栈建议

*   **包管理器与运行时**: `Bun` (All-in-One 工具链，提供极致的安装速度和高性能运行时)
    *   作为包管理器替代 `npm/pnpm`
    *   作为脚本执行器替代 `ts-node`
    *   作为测试运行器替代 `Jest/Vitest`
*   **构建系统**: `Turborepo` (任务编排、远程缓存)
*   **前端框架**: `React` (配合 Vite)
*   **后端框架**: `Hono` (完美适配 Bun 运行时，性能卓越)
*   **Runner 语言**: `Go` 或 `Rust` (高性能、并发强、安全性好)
*   **API 通信**: `Hono RPC` (如果分离) 或 `Server Actions` (如果全栈)