|
|
@@ -0,0 +1,180 @@
|
|
|
+# 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 |
|
|
|
+
|
|
|
+## 目录结构
|
|
|
+
|
|
|
+```text
|
|
|
+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 作为包管理器。
|
|
|
+
|
|
|
+```bash
|
|
|
+bun install
|
|
|
+```
|
|
|
+
|
|
|
+启动开发环境：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run dev
|
|
|
+```
|
|
|
+
|
|
|
+生产构建：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run build
|
|
|
+```
|
|
|
+
|
|
|
+类型检查：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run typecheck
|
|
|
+```
|
|
|
+
|
|
|
+代码检查：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run lint
|
|
|
+```
|
|
|
+
|
|
|
+格式化：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run format
|
|
|
+```
|
|
|
+
|
|
|
+同步国际化资源：
|
|
|
+
|
|
|
+```bash
|
|
|
+bun run i18n:sync
|
|
|
+```
|
|
|
+
|
|
|
+预览生产构建：
|
|
|
+
|
|
|
+```bash
|
|
|
+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`：理解构建入口、路径别名、代理和生产构建配置。
|
韩洋