项目总览

相关源文件

本页面内容基于以下源文件生成：

• README.md
• package.json
• vite.config.ts
• back/index.ts

本项目是一个基于 Vite 构建的单体全栈脚手架，旨在提供一套精简且类型安全的开发模板。项目采用前后端一体化架构，后端基于 Fastify 驱动，集成 tRPC 实现端到端类型安全，数据层使用 MongoDB 与 Redis；前端采用 React 19 配合 TailwindCSS 4，并利用 Vite 的多页面能力支持多端入口（如 PC 端与管理后台）。该架构特别适合需要快速迭代、强类型约束以及前后端共享代码逻辑的中小型全栈项目。

技术栈与核心依赖

项目技术栈选型遵循“现代、精简、全栈一体化”的原则，核心依赖如下表所示：

证据来源：项目整体介绍见 README.md:1-4；完整依赖列表见 package.json:12-48。

端口分配与网络配置

项目采用多进程隔离策略，严格规划了本地开发环境的端口占用，以避免冲突并模拟微服务部署环境。

• 后端 API 服务：监听 0.0.0.0:5550，负责处理 tRPC 请求与业务逻辑 (back/index.ts:96-98)。
• 前端开发服务器：监听 0.0.0.0:5551，由 Vite 提供资源服务与热更新 (vite.config.ts:39-42)。
• 数据层服务：
  • MongoDB：localhost:5552
  • Redis：localhost:5553
  • 注：需预留 4-5 个端口用于扩展服务 (README.md:7-13)。

核心架构设计

1. 系统架构图

下图展示了项目从前端多入口到后端服务的整体架构流向与模块依赖关系。

正在加载图表渲染器...

架构说明：

1. 多入口前端：Vite 配置了 admin 与 pc 两个构建入口，通过中间件重写 URL 规则（/admin -> admin.html）实现路由隔离 (vite.config.ts:14-28)。
2. 类型安全通信：前后端通过 tRPC 协议通信，后端使用 fastifyTRPCPlugin 将 tRPC 路由挂载至 /rpc 前缀 (back/index.ts:17-21)。
3. 文档与调试：开发环境下，系统利用 trpc-to-openapi 自动生成 OpenAPI 文档，并通过 Scalar 渲染在 /doc 路径 (back/index.ts:63-94)。
4. 数据层集成：Fastify 通过插件机制注册 MongoDB 和 Redis，服务启动时自动执行数据库迁移 (migrate) 和定时任务 (runProcedures) (back/index.ts:99-102)。

2. 核心请求处理流

下图详细描述了从客户端发起请求到后端处理并返回的完整生命周期，重点展示了 tRPC 的上下文创建与认证逻辑。

正在加载图表渲染器...

流程关键点解析：

1. 上下文创建策略：每个请求进入 tRPC 时，都会调用 createContext。系统首先检查请求路径是否在 whiteList 中，若在则直接放行 (back/index.ts:28-32)。
2. 认证降级：对于非白名单请求，系统会尝试解析 Authorization 头。如果 Token 等于环境变量 DEFAULT_USER_ID，直接赋予管理员权限；否则返回空用户对象（即未登录态），实现了开发环境的灵活降级 (back/index.ts:33-55)。
3. 错误处理：tRPC 配置了全局错误钩子 onError，捕获并打印路径与错误信息，便于开发调试 (back/index.ts:57-59)。

开发与部署流程

开发环境启动

项目利用 tsx 直接运行 TypeScript 代码，无需繁琐的构建步骤。

• 前端启动：执行 pnpm dev，启动 Vite 开发服务器，默认监听 5551 端口 (package.json:7)。
• 后端启动：执行 pnpm back，使用 tsx watch 监听文件变化，加载 .env.development 环境变量，并启动 Fastify 服务 (package.json:9)。
• 接口文档：后端启动后，访问 http://localhost:5550/doc 查看自动生成的 API 文档 (README.md:25)。

生产环境部署

生产环境部署通过 Jenkins 调用 deploy.sh 脚本执行。项目设计上不区分 devDependencies，所有依赖均打包进容器，利用云厂商的容器镜像服务进行部署 (README.md:17-18)。HTTPS、HTTP/2 及 Gzip 压缩等性能优化配置建议在 CDN 层面处理，而非应用层 (README.md:15)。

目录结构概览

基于源文件分析，项目的核心目录结构推断如下：

text
1monoproject/
2├── back/                 # 后端源码目录
3│   ├── index.ts          # 后端入口：Fastify 初始化、tRPC 注册、迁移启动
4│   ├── init.ts           # (推断) Fastify App 实例初始化
5│   ├── router.ts         # (推断) tRPC 路由定义
6│   ├── procedures/       # (推断) 后台任务或定时过程
7│   ├── migrate.ts        # (推断) 数据库迁移脚本
8│   └── whiteList.json    # tRPC 白名单配置
9├── src/                  # 前端源码目录
10│   └── shared/           # 前后端共享代码 (别名 ~)
11├── admin.html            # 管理后台入口
12├── pc.html               # PC 客户端入口
13├── vite.config.ts        # Vite 配置：多页面、代理、别名
14├── package.json          # 项目依赖与脚本
15└── tsconfig.back.json    # 后端 TypeScript 配置

核心特性总结

1. 端到端类型安全：基于 tRPC，前后端共享 TypeScript 类型定义，消除接口不一致导致的运行时错误。
2. 多应用架构：通过 Vite 多页面配置，在单一仓库中维护 PC 端与管理后台，共享业务逻辑与 UI 组件。
3. 零配置类型运行：后端使用 tsx 直接运行 TS 代码，配合 watch 模式实现极速开发反馈。
4. 自动化 API 文档：开发环境自动生成 OpenAPI 文档，并通过 Scalar 提供美观的交互界面。
5. 灵活的认证策略：内置白名单机制与开发环境硬编码 Token，方便本地调试与接口测试。
6. 全栈一体化：不区分开发与生产依赖，简化依赖管理，适配容器化部署流程。