From 3c261c4f6468b0490939d7c6dd513e9d5254b477 Mon Sep 17 00:00:00 2001
From: xie2can <384968446@qq.com>
Date: Thu, 28 May 2026 11:42:47 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E7=9B=AE=E5=BD=95=E7=BB=93=E6=9E=84=E4=B8=8E=E6=8A=80=E6=9C=AF?=
 =?UTF-8?q?=E6=A0=88=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index e60251c..4425cb7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,6 +46,28 @@ 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}` 中注册的结构体方法会自动暴露给前端。
@@ -61,6 +83,7 @@ go test -run TestName ./...
 | `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` | 项目配置（前端构建命令、输出文件名、作者信息） |
 
 ### 前端技术栈
@@ -68,6 +91,8 @@ go test -run TestName ./...
 - **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）
 
@@ -93,9 +118,31 @@ go test -run TestName ./...
 |------|------|
 | `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` 结构体中添加方法（必须是导出/公开的）。