# OPS 系统路由和中间件配置文档

## 概览

本文档描述了OPS系统的路由架构和中间件配置，这些配置已经在2026-03-31完成更新。

## 路由架构

### 1. 路由层次结构

```
/api                     # 兼容性API层（保持原有接口）
  ├─ /users              # 用户认证和管理（兼容现有前端）
  ├─ /files              # 文件上传和管理
  ├─ /purchase           # 采购订单管理
  └─ /static             # 静态文件服务

/api/v1                  # RESTful API v1（新架构）
  ├─ /users              # 用户API（新架构）
  ├─ /files              # 文件API（新架构）
  └─ /purchase           # 采购API（新架构）

/                        # 前端静态文件
```

### 2. 主路由配置文件

```
backend/
├── api/
│   ├── main.go          # 主路由配置入口
│   └── v1/
│       └── routes.go    # v1 API路由定义
├── cmd/ops-server/
│   └── main.go          # 应用程序主入口
└── routers/             # 兼容性路由（旧架构）
```

## 中间件配置

### 1. 中间件加载顺序

```go
// 在 cmd/ops-server/main.go 中
r := gin.New()

// 1. CORS中间件
r.Use(middleware.CORS())

// 2. 日志中间件（环境相关）
if isDevelopment {
    r.Use(middleware.SimpleLogger())  // 开发环境：简易日志
} else {
    r.Use(middleware.Logger(logger))   // 生产环境：详细日志
}

// 3. 恢复中间件
r.Use(middleware.Recovery(logger))
```

### 2. 可用的中间件

#### `middleware.CORS()`
- 支持完整的CORS头配置
- 允许跨域请求，支持凭证
- 兼容现有前端系统

#### `middleware.Logger()`
- 详细的HTTP请求日志
- 包含请求ID、响应时间、客户端IP等信息
- 敏感信息过滤（如密码）

#### `middleware.SimpleLogger()`
- 开发环境使用的简易日志
- 控制台输出格式化的日志信息
- 便于开发和调试

#### `middleware.Recovery()`
- Panic恢复中间件
- 捕获并记录Panic信息
- 返回适当的500错误响应

#### `middleware.AuthToken()`
- 认证令牌中间件
- 支持多种认证方式：
  1. `Authorization: Bearer <token>`
  2. POST数据中的 `userCookieValue` 字段
  3. Cookie头中的 `userCookieValue`
  4. URL查询参数中的 `userCookieValue`

#### `middleware.AuthRequired()`
- 需要认证的中间件
- 如果用户未认证，返回401错误
- 调用 `AuthToken()` 中间件并检查结果

## API路由配置

### 兼容性路由（/api/*）

```go
// 在 routers/ 中的原有路由文件
- apiUsers.go       # 用户认证和管理
- apiFiles.go       # 文件上传和管理
- apiPurchase.go    # 采购订单管理
- apiStatic.go      # 静态文件服务
```

### RESTful API v1（/api/v1/*）

```go
// 在 api/v1/routes.go 中
func RegisterRoutes(r *gin.RouterGroup) {
    // 用户认证路由
    userGroup := r.Group("/users")
    {
        userGroup.POST("/login", authHandler.UserLogin)
        userGroup.POST("/register", authHandler.UserRegister)
        userGroup.POST("/logout", middleware.AuthRequired(), authHandler.UserLogout)
    }
    
    // 文件管理路由
    fileGroup := r.Group("/files")
    {
        fileGroup.POST("/upload", middleware.AuthRequired(), fileHandler.UploadFile)
        fileGroup.GET("/list", middleware.AuthRequired(), fileHandler.GetFileList)
    }
    
    // 采购订单路由
    purchaseGroup := r.Group("/purchase")
    {
        purchaseGroup.GET("/orders", middleware.AuthRequired(), purchaseHandler.GetOrders)
        purchaseGroup.POST("/orders", middleware.AuthRequired(), purchaseHandler.CreateOrder)
    }
}
```

## 静态文件服务

### 静态文件处理策略

1. **API请求优先**：所有以 `/api` 开头的请求由API路由处理
2. **静态文件服务**：其他请求尝试从 `./dist` 目录提供静态文件
3. **SPA支持**：对于Vue Router的history模式，没有匹配的文件时会返回 `index.html`

### 配置位置

```go
// 在 api/main.go 中的 NoRoute 处理
r.NoRoute(func(c *gin.Context) {
    if strings.HasPrefix(path, "/api") {
        // API 404错误
        c.JSON(404, ...)
    } else {
        // 静态文件服务
        fs.ServeHTTP(c.Writer, c.Request)
    }
})
```

## 开发和生产环境配置

### 开发环境
- 调试模式日志
- 简易的日志输出
- 本地主机（127.0.0.1:8080）

### 生产环境
- 生产模式日志
- 详细的JSON日志
- 优化的服务器配置
- TLS支持（如果配置）

## 关键配置文件

### `backend/data/config.yaml`
```yaml
web:
  host: "127.0.0.1"
  port: "8080"
  tls: false
  certPrivatePath: ""
  certPublicPath: ""

database:
  type: "sqlite"
  path: "data/database.db"

user:
  cookieTimeout: 604800
  passHashType: "md5"

file:
  maxSize: 52428800
  paths:
    avatar: "data/static/avatar/"
    image: "data/upload/image/"
    # ... 其他配置
```

## 快速启动

### 开发环境
```bash
# Windows
run-dev.bat

# 手动运行
set CGO_ENABLED=1
go run ./cmd/ops-server/main.go
```

### 生产构建
```bash
# Linux/macOS（需要CGO）
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o ops-server ./cmd/ops-server

# Windows（需要CGO）
set CGO_ENABLED=1
go build -o ops-server.exe ./cmd/ops-server
```

## 升级和迁移说明

1. 新架构完全兼容现有前端API
2. 新增 `/api/v1` RESTful API用于新功能开发
3. 中间件系统已统一，支持环境感知配置
4. 静态文件服务更智能，支持SPA应用

## 故障排除

### 常见问题

1. **SQLite需要CGO**：设置 `CGO_ENABLED=1` 环境变量
2. **端口占用**：检查端口8080是否被占用，可在config.yaml中修改
3. **静态文件404**：确保前端已构建，文件位于 `./dist` 目录
4. **数据库连接失败**：检查SQLite文件路径和权限

### 日志级别

- **开发环境**：控制台输出，易于阅读
- **生产环境**：JSON格式，便于日志收集和分析

---

**最后更新**：2026-03-31
**更新内容**：重构路由和中间件系统，引入分层架构和兼容性支持