🎨 精简完善系统
This commit is contained in:
215
AGENTS.md
Normal file
215
AGENTS.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# 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`。
|
||||
Reference in New Issue
Block a user