Go-Web-Template/AGENTS.md

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 常用命令

后端

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

新后台前端

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 文档

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

根目录构建

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。