155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
# CODEBUDDY.md
|
||
|
||
本文件为 CodeBuddy Code 在此仓库中工作提供指引。
|
||
|
||
## 项目概述
|
||
|
||
`smartserve-client` 是一个基于 [Wails v2](https://wails.io/) 构建的桌面应用程序。Wails 是一个将 **Go 后端**与 **React + TypeScript 前端**结合并打包为原生桌面应用的框架。Go 代码负责处理应用逻辑，并通过自动生成的 JavaScript 绑定暴露给前端。
|
||
|
||
## 命令
|
||
|
||
### 完整应用
|
||
|
||
```bash
|
||
# 开发模式（前端热重载，保存时自动重新编译 Go）
|
||
wails dev
|
||
|
||
# 生产构建（输出二进制文件至 build/bin/）
|
||
wails build
|
||
```
|
||
|
||
### 仅前端（在 `frontend/` 目录下执行）
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 开发服务器（浏览器预览地址 http://localhost:5173，无 Go 后端）
|
||
pnpm run dev
|
||
|
||
# 类型检查 + 生产构建
|
||
pnpm run build
|
||
|
||
# 代码检查
|
||
pnpm run lint
|
||
```
|
||
|
||
### Go 后端
|
||
|
||
```bash
|
||
# 运行所有 Go 测试
|
||
go test ./...
|
||
|
||
# 运行单个测试
|
||
go test -run TestName ./...
|
||
```
|
||
|
||
## 架构
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
smartserve-client/
|
||
├── main.go # Wails 应用入口
|
||
├── app.go # App 结构体，暴露给前端的 Go 方法
|
||
├── go.mod / go.sum
|
||
├── wails.json # Wails 项目配置
|
||
└── frontend/
|
||
└── src/
|
||
├── App.tsx # 根组件（antd 配置、401 处理器）
|
||
├── main.tsx # React 入口（MSW 启动）
|
||
├── api/ # HTTP 请求函数（user、knowledgeCards）
|
||
├── pages/ # 页面组件（小驼峰命名）
|
||
├── layouts/ # 布局组件（大驼峰命名）
|
||
├── router/ # 路由配置与实例
|
||
├── store/ # Zustand 状态管理
|
||
├── mock/ # MSW 模拟 API（开发专用）
|
||
├── types/ # TypeScript 全局类型
|
||
└── utils/ # 工具函数（request.ts HTTP 客户端）
|
||
```
|
||
|
||
### Go ↔ 前端桥接（Wails 绑定）
|
||
|
||
- 在 `main.go` 的 `Bind: []interface{}{app}` 中注册的结构体方法会自动暴露给前端。
|
||
- Wails 会在 `frontend/wailsjs/go/main/App.d.ts` 和 `App.js` 中生成 TypeScript 绑定——**不要手动编辑这些文件**，它们会在 `wails dev`/`wails build` 时自动重新生成。
|
||
- 在 React 中调用 Go 函数：`import { Greet } from '../wailsjs/go/main/App'`——所有调用均返回 `Promise`。
|
||
- 运行时工具（窗口管理、事件、对话框等）位于 `frontend/wailsjs/runtime/`。
|
||
|
||
### 关键文件
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `main.go` | 入口点；配置 Wails 应用（窗口尺寸、标题、资源服务器、绑定结构体） |
|
||
| `app.go` | `App` 结构体，包含暴露给前端的方法；新增 Go→JS 方法在此添加 |
|
||
| `frontend/src/App.tsx` | 根 React 组件 |
|
||
| `frontend/src/main.tsx` | React 入口点 |
|
||
| `frontend/src/utils/request.ts` | HTTP 客户端（Token 注入、401 拦截、超时） |
|
||
| `wails.json` | 项目配置（前端构建命令、输出文件名、作者信息） |
|
||
|
||
### 前端技术栈
|
||
|
||
- **React 19** + **TypeScript**（严格模式）
|
||
- **Ant Design 6**（`antd@6.x` + `@ant-design/icons@6.x`）用于 UI 组件——**编写页面时优先使用 antd 组件**
|
||
- **react-router-dom v7** 用于路由管理
|
||
- **Zustand v5** 用于状态管理
|
||
- **MSW v2** 用于开发模式 API 模拟
|
||
- **Vite 8** 用于打包
|
||
- **pnpm** 作为包管理器（不要使用 npm/yarn）
|
||
|
||
### Ant Design 文档
|
||
|
||
编写或修改 UI 组件时，可通过以下地址查询 antd 最新用法：
|
||
|
||
- 索引：`https://ant.design/llms.txt`
|
||
- 完整文档（中文）：`https://ant.design/llms-full-cn.txt`
|
||
- 语义文档（中文）：`https://ant.design/llms-semantic-cn.md`
|
||
|
||
### 前端目录命名规范
|
||
|
||
- **功能分类目录**（`pages/`、`layouts/`、`router/`、`components/` 等）：小写
|
||
- **页面目录**（`pages/` 下的子目录）：小驼峰，如 `pages/home`、`pages/notFound`
|
||
- **自定义组件目录**（`layouts/`、`components/` 下的子目录）：大驼峰，如 `layouts/BasicLayout`、`components/SideMenu`
|
||
|
||
### 前端路由结构
|
||
|
||
路由相关文件位于 `frontend/src/router/`：
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `frontend/src/router/routes.tsx` | 路由配置数据，导出 `RouteConfig` 接口和 `routes` 数组；菜单组件从这里取数据 |
|
||
| `frontend/src/router/index.tsx` | 基于 `routes` 创建并导出 `router` 实例（`createBrowserRouter`） |
|
||
| `frontend/src/router/AuthGuard.tsx` | 路由守卫（`AuthGuard` 要求登录，`GuestGuard` 要求未登录） |
|
||
|
||
`RouteConfig` 包含 `path`、`label`、`icon`、`element`、`hideInMenu`、`children` 字段，菜单组件过滤 `hideInMenu: true` 的条目即可渲染菜单。
|
||
|
||
页面访问流程：
|
||
```
|
||
未登录访问任意页 → AuthGuard 重定向至 /login
|
||
登录成功 → GuestGuard 重定向至 /
|
||
```
|
||
|
||
### 状态管理（Zustand）
|
||
|
||
| Store | 文件 | 内容 |
|
||
|-------|------|------|
|
||
| `useUserStore` | `store/user.ts` | 用户信息、登录/登出、Token（持久化至 `localStorage` key: `access_token`） |
|
||
| `useAppStore` | `store/app.ts` | 侧边栏折叠状态 |
|
||
|
||
401 响应由 `utils/request.ts` 全局拦截，调用 `App.tsx` 注册的 `setUnauthorizedHandler`，自动执行 `logout()` 并跳转 `/login`。
|
||
|
||
### API 层
|
||
|
||
- 请求函数位于 `frontend/src/api/`，调用 `utils/request.ts` 封装的 HTTP 客户端。
|
||
- 统一响应格式（`types/global.d.ts`）：`API.Response<T>` 含 `code`、`msg`、`ok`、`data`、`time` 字段。
|
||
- 开发模式下，`mock/handlers/` 中的 MSW 处理器拦截请求并返回模拟数据；生产构建不包含 MSW。
|
||
|
||
### 添加新的 Go 方法
|
||
|
||
1. 在 `app.go` 的 `App` 结构体中添加方法（必须是导出/公开的）。
|
||
2. 运行 `wails dev`——`frontend/wailsjs/go/main/` 中的绑定会自动重新生成。
|
||
3. 在 React 中使用生成的 TypeScript 类型导入并调用。
|
||
|
||
### 前端资源
|
||
|
||
前端的 `dist/` 目录在构建时通过 `main.go` 中的 `//go:embed all:frontend/dist` 嵌入到 Go 二进制文件中。开发模式下，Wails 会代理到 Vite 开发服务器。
|