docs: 新增项目文档并更新开发规则

- 新增品牌命名、商业化策略、SDK视觉噪音处理、可视化库设计和系统架构文档 - 更新开发规则，明确禁止主动修改项目源代码文件 - 所有文档均为中文编写，用于记录项目设计讨论和决策
2026-02-18 00:18:35 +08:00
parent 4929ca496b
commit a9eaaa6023
6 changed files with 352 additions and 1 deletions
--- a/.trae/documents/system-architecture.md
+++ b/.trae/documents/system-architecture.md
@@ -0,0 +1,109 @@
+# 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` (如果全栈)