xie2can/smartserve-client

Fork 0

Files

xie2can 3c261c4f64 docs: 补充项目目录结构与技术栈文档

2026-05-28 11:42:47 +08:00

6.0 KiB

Raw Permalink Blame History

CODEBUDDY.md

本文件为 CodeBuddy Code 在此仓库中工作提供指引。

项目概述

smartserve-client 是一个基于 Wails v2 构建的桌面应用程序。Wails 是一个将 Go 后端与 React + TypeScript 前端结合并打包为原生桌面应用的框架。Go 代码负责处理应用逻辑，并通过自动生成的 JavaScript 绑定暴露给前端。

命令

完整应用

# 开发模式（前端热重载，保存时自动重新编译 Go）
wails dev

# 生产构建（输出二进制文件至 build/bin/）
wails build

仅前端（在 `frontend/` 目录下执行）

# 安装依赖
pnpm install

# 开发服务器（浏览器预览地址 http://localhost:5173，无 Go 后端）
pnpm run dev

# 类型检查 + 生产构建
pnpm run build

# 代码检查
pnpm run lint

Go 后端

# 运行所有 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 方法

在 app.go 的 App 结构体中添加方法（必须是导出/公开的）。
运行 wails dev——frontend/wailsjs/go/main/ 中的绑定会自动重新生成。
在 React 中使用生成的 TypeScript 类型导入并调用。

前端资源

前端的 dist/ 目录在构建时通过 main.go 中的 //go:embed all:frontend/dist 嵌入到 Go 二进制文件中。开发模式下，Wails 会代理到 Vite 开发服务器。

6.0 KiB Raw Permalink Blame History Unescape Escape