Linwit-ai-token-platform/default

Linwit Token Web

Linwit Token Web 是一个面向 AI Token 平台的前端单页应用，提供门户展示、用户控制台、模型浏览、渠道管理、API Key 管理、钱包充值、个人资料、Playground 调试以及系统设置等能力。

项目基于 React、TypeScript 与 Rsbuild 构建，采用文件路由、服务端状态管理、统一 API 请求封装和功能模块化目录结构，适合作为 AI 网关、模型分发、Token 计费与平台管理类系统的前端入口。

项目特点

• 基于 React 19 与 TypeScript，使用函数式组件和 Hooks 开发。
• 使用 TanStack Router 文件路由，路由结构清晰，支持认证守卫与嵌套路由布局。
• 使用 TanStack Query 管理服务端状态，统一处理缓存、请求状态与数据刷新。
• 使用 Axios 封装统一 API 请求实例，支持 Cookie 会话、请求去重与错误处理。
• 使用 Zustand 管理本地认证状态和必要的客户端状态。
• 使用 Tailwind CSS、Base UI、Hugeicons、Lucide 等构建现代化界面。
• 支持 i18next 国际化，适合多语言平台扩展。
• 使用 Rsbuild / Rspack 构建，开发体验和生产构建性能较好。

技术栈

分类	技术
基础框架	React 19、TypeScript
构建工具	Rsbuild、Rspack
路由	TanStack Router
服务端状态	TanStack Query
本地状态	Zustand
请求库	Axios
UI 与样式	Tailwind CSS、Base UI、shadcn 风格组件、Hugeicons、Lucide、Sonner
表单与校验	React Hook Form、Zod、@hookform/resolvers
表格与虚拟列表	TanStack Table、TanStack Virtual
国际化	i18next、react-i18next、i18next-browser-languagedetector
图表	VisActor VChart、React VChart、Recharts
Markdown / 代码展示	marked、shiki、CodeMirror、KaTeX
工程质量	oxlint、oxfmt、knip

目录结构

default
├── public                 # 静态资源，如 logo、favicon、支付图标等
├── scripts                # 工程脚本，如格式化、版权、国际化同步
├── src                    # 应用源码
│   ├── components         # 通用组件、布局组件、UI 基础组件
│   ├── context            # 全局 React Context
│   ├── features           # 业务功能模块
│   ├── hooks              # 通用 Hooks
│   ├── i18n               # 国际化配置与语言资源
│   ├── lib                # API、工具函数、通用逻辑
│   ├── routes             # TanStack Router 文件路由
│   ├── stores             # Zustand 状态管理
│   ├── styles             # 全局样式
│   ├── main.tsx           # 应用入口
│   └── routeTree.gen.ts   # 路由树生成文件
├── index.html             # HTML 模板
├── package.json           # 项目依赖与脚本
├── rsbuild.config.ts      # Rsbuild 构建配置
└── tsconfig*.json         # TypeScript 配置

主要模块

• src/routes：应用路由入口，包含公开页面、认证页面和受保护后台页面。
• src/routes/_authenticated：需要登录后访问的后台路由分组。
• src/features/auth：登录、注册、找回密码等认证相关功能。
• src/features/dashboard：控制台与概览相关功能。
• src/features/models：模型展示、模型分组与模型相关页面。
• src/features/channels：渠道管理相关功能。
• src/features/keys：API Key 管理相关功能。
• src/features/pricing：价格展示与计费相关页面。
• src/features/profile：用户资料、账户设置与个人中心。
• src/features/playground：模型调用体验与调试页面。
• src/features/system-settings：系统配置与管理后台相关能力。

应用入口与运行流程

1. 浏览器加载 index.html，通过 #root 挂载 React 应用。
2. src/main.tsx 创建 QueryClient 和 TanStack Router。
3. 路由使用 src/routeTree.gen.ts 中生成的路由树。
4. 应用外层注入 Query、主题、字体方向、路由等全局 Provider。
5. 根路由检查系统初始化状态，未完成初始化时进入 /setup。
6. 受保护路由会检查本地认证状态，并通过 /api/user/self 验证当前会话。

API 请求说明

统一请求封装位于 src/lib/api.ts：

• 默认使用同源接口，baseURL 为空。
• 开启 withCredentials，用于携带 Cookie / Session。
• 对并发 GET 请求进行去重，减少重复接口调用。
• 统一处理业务错误、登录过期、401 状态和 toast 提示。
• 基础接口如获取当前用户、系统状态等也集中在该文件中。

开发环境接口代理在 rsbuild.config.ts 中配置，默认代理路径包括：

• /api
• /mj
• /pg

本地开发后端地址通过 .env 中的 VITE_REACT_APP_SERVER_URL 配置；未配置时默认使用 http://localhost:3000。

常用命令

项目使用 Bun 作为包管理器。

bun install

启动开发环境：

bun run dev

生产构建：

bun run build

类型检查：

bun run typecheck

代码检查：

bun run lint

格式化：

bun run format

同步国际化资源：

bun run i18n:sync

预览生产构建：

bun run preview

开发约定

• 页面路由优先放在 src/routes，具体业务实现放在对应的 src/features/<feature> 中。
• 通用组件放在 src/components，业务组件优先放在所属 feature 内。
• 请求接口优先复用 src/lib/api.ts 中的统一 Axios 实例。
• 服务端数据获取优先使用 TanStack Query。
• 本地全局状态优先使用 Zustand，并按功能拆分 store。
• 面向用户的文案应接入 i18n，避免直接写死在组件中。
• 新增 TypeScript / TSX 代码后应执行类型检查和 lint 检查。
• 不要手动修改 src/routeTree.gen.ts，它由 TanStack Router 插件生成。

构建与部署

• 构建入口：src/main.tsx
• HTML 模板：index.html
• 构建配置：rsbuild.config.ts
• 生产输出目录：dist
• SPA 部署时需要将前端路由回退到 index.html

仓库中已包含 netlify.toml，用于在 Netlify 部署时将所有路径回退到 /index.html。

适合阅读的关键文件

• src/main.tsx：理解应用启动和全局 Provider。
• src/routes/__root.tsx：理解根路由、初始化检查和全局错误边界。
• src/routes/_authenticated/route.tsx：理解登录态校验和后台路由保护。
• src/components/layout/components/authenticated-layout.tsx：理解后台整体布局。
• src/lib/api.ts：理解接口请求、错误处理和会话逻辑。
• src/stores/auth-store.ts：理解认证状态在前端如何保存与恢复。
• rsbuild.config.ts：理解构建入口、路径别名、代理和生产构建配置。