# AGENTS.md

## 1. 文件作用

本文件定义本仓库的协作约束，供人类开发者和代码代理统一遵循。

目标只有三个：

- 先分清模块边界，再动代码。
- 新功能默认落在 `server` 和 `web-admin`。
- `web` 只作为旧版参考实现，不参与当前交付。

## 2. 项目总览

本仓库是一个前后端分离项目，当前有效开发面如下：

| 目录 | 角色 | 技术栈 | 是否允许修改 |
| --- | --- | --- | --- |
| `server` | 后端服务 | Go 1.24、Gin、Gorm、Viper、Zap | 允许 |
| `web-admin` | 新管理后台前端 | React 19、TypeScript、Vite、Ant Design、Zustand、React Query | 允许 |
| `web` | 原版 Vue 管理后台 | Vue | 不允许 |

当前默认管理后台目录已经在根目录 `Makefile` 中指定为 `WEB_DIR ?= web-admin`，后续构建与打包应以 `web-admin` 为准。

## 3. 工作边界

### 3.1 允许修改的目录

- `server/**`
- `web-admin/**`
- 根目录与部署目录中和当前任务直接相关的文档、脚本、配置文件

### 3.2 禁止修改的目录

- `web/**`

`web` 是旧版 Vue 后台，仅用于界面、接口命名、交互流程和功能覆盖范围参考。不得在该目录内新增、删除或修改任何文件。

### 3.3 修改原则

- 如果 `web-admin` 缺少某个页面或交互，可以参考 `web` 的实现思路，但要用 React 方式重写。
- 如果 `server` 的接口能力不足，应优先补齐后端，再让 `web-admin` 接入。
- 不为了兼容旧实现而把新代码继续写回 `web`。

## 4. 目录说明

### 4.1 `server`

后端采用典型分层结构，开发时按职责落位：

| 目录 | 职责 |
| --- | --- |
| `server/api` | HTTP 接口入口。负责参数接收、调用 service、返回响应。 |
| `server/service` | 业务逻辑层。负责业务编排、事务边界、数据写入策略。 |
| `server/router` | 路由注册。负责把接口暴露给 Gin。 |
| `server/model` | 数据模型、请求结构、响应结构。 |
| `server/middleware` | 中间件。负责鉴权、日志、限流、错误处理等横切逻辑。 |
| `server/initialize` | 初始化流程。负责数据库、Redis、路由、校验器、定时器等装配。 |
| `server/config` | 配置结构定义。与 `config.yaml` / `config.docker.yaml` 对应。 |
| `server/utils` | 通用工具，不承载具体业务语义。 |
| `server/mcp` | MCP 相关能力。新增此类能力时优先放在这里。 |
| `server/docs` | Swagger 产物目录。只有接口变更需要更新文档时才修改。 |

后端变更约束：

- 不要把业务逻辑堆进 `api` 层。
- 不要把页面专属拼装逻辑散落到 `utils`。
- 新接口需要同时检查路由注册、权限、请求结构和返回结构是否完整。
- 涉及配置项变更时，必须同步检查 `server/config.yaml`、`server/config.docker.yaml` 和对应结构体。

### 4.2 `web-admin`

新后台是当前主开发前端，目录组织以功能模块为中心：

| 目录 | 职责 |
| --- | --- |
| `web-admin/src/features` | 业务页面与模块实现。页面优先落在这里。 |
| `web-admin/src/router` | 路由定义与页面装配。 |
| `web-admin/src/lib` | 请求封装、日期、树结构、存储等通用前端基础设施。 |
| `web-admin/src/store` | 全局状态。当前主要用于鉴权与会话信息。 |
| `web-admin/src/types` | 共享类型定义。 |
| `web-admin/public` | 静态资源。 |

前端变更约束：

- 新页面优先沿用现有 `features/*Page.tsx` 的组织方式。
- 接口请求优先收敛到 `web-admin/src/lib` 或对应 feature 内部的请求层，不要在组件里散写 HTTP 细节。
- 类型优先显式声明，不要用大量 `any`。
- 页面以管理后台场景为前提，优先保证信息密度、操作链路和可维护性。

### 4.3 `web`

该目录只读。允许查看，不允许编辑。

适用场景：

- 查旧版菜单结构
- 查既有接口命名
- 查页面字段和交互流程
- 查某个能力在旧后台中的展示方式

不适用场景：

- 直接在这里修 bug
- 在这里补新功能
- 为了图省事复制构建配置并改回旧目录

## 5. 本地开发

### 5.1 环境基线

| 项目 | 要求 |
| --- | --- |
| Go | 1.24.x |
| Node.js | >= 18.16，建议 20+ |
| 包管理器 | `web-admin` 使用 `npm` |

### 5.2 常用命令

#### 后端

```bash
cd /Users/lee/GolandProjects/Go-Web-Template/server
go run .
```

#### 新后台前端

```bash
cd /Users/lee/GolandProjects/Go-Web-Template/web-admin
npm install
npm run dev
```

默认约定：

- `web-admin` 开发地址：`http://localhost:8081`
- 后端默认代理目标：`http://127.0.0.1:8888`

#### Swagger 文档

```bash
cd /Users/lee/GolandProjects/Go-Web-Template/server
swag init
```

#### 根目录构建

```bash
cd /Users/lee/GolandProjects/Go-Web-Template
make build
```

## 6. 变更落地规则

### 6.1 后端任务

遇到后端需求时，优先按下面顺序检查：

1. 是否已有对应 `model`、`service`、`api`、`router`。
2. 是否需要补权限、菜单、字典、参数或日志记录。
3. 是否影响 Swagger 文档、配置文件或初始化逻辑。
4. 是否需要补测试，至少覆盖纯工具函数和稳定业务逻辑。

### 6.2 前端任务

遇到管理后台需求时，优先按下面顺序处理：

1. 先确认目标页面属于 `web-admin` 哪个 feature。
2. 需要参考旧实现时，只读取 `web`，不在 `web` 动手。
3. 先整理接口契约，再组织页面状态和交互。
4. 提交前至少完成构建或 lint 校验。

### 6.3 跨端联动任务

如果需求同时涉及前后端，推荐顺序如下：

1. 先定义或确认接口契约。
2. 先补 `server`，保证接口可运行。
3. 再接 `web-admin` 页面和交互。
4. 最后联调并确认代理、鉴权、菜单和权限表现一致。

## 7. 验证要求

只要改动了对应模块，至少执行一项最低验证：

| 改动范围 | 最低验证 |
| --- | --- |
| `server` Go 代码 | `go test ./...` 或最小相关包测试 |
| `web-admin` 前端代码 | `npm run build` 或 `npm run lint` |
| 接口定义变更 | 补充或更新 Swagger 文档，并做一次接口联调 |
| 构建脚本或部署配置 | 执行对应构建命令，确认没有明显路径错误 |

如果因为外部依赖无法完成验证，需要明确说明阻塞点，不得省略。

## 8. 代码风格补充

- 文档、注释、提交说明优先使用清晰中文。
- 注释只说明职责、边界、约束和必要语义，不复述代码表面行为。
- 新增后端代码遵循现有分层，不主动引入跨层调用。
- 新增前端代码遵循现有 React + TypeScript + Ant Design 方案，不回退到旧 Vue 写法。
- 非必要不新增大型依赖。新增依赖前先确认当前栈无法直接解决问题。

## 9. 决策优先级

出现冲突时，按下面顺序决策：

1. 不修改 `web`
2. 以 `web-admin` 作为当前管理后台主实现
3. 以 `server` 的真实接口和数据结构为准
4. 参考旧版 `web` 的业务行为，而不是复制其实现细节

## 10. 一句话约束

这个仓库的当前主线是：维护 `server`，建设 `web-admin`，只参考 `web`，绝不修改 `web`。