# 架构升级与 OpenAPI 文档接入详细实施规范

## 1. 架构调整设计 (Architecture Upgrade)

### 1.1 目录结构变更 (Directory Structure)

我们将把扁平的 Handler 层改造为按业务域（Domain）物理隔离的结构。

**变更前**:
```text
internal/handler/
├── account.go
├── role.go
└── ...
```

**变更后**:
```text
internal/handler/
├── admin/          # 后台管理/PC代理端 (Admin Domain)
│   ├── account.go
│   ├── role.go
│   └── ...         # 现有业务逻辑全部移到这里
├── agent/          # 手机/H5代理端 (Agent Domain) - 预留
│   └── (空)
├── app/            # C端用户 (App Domain) - 预留
│   └── (空)
└── health.go       # 全局健康检查 (保持在根目录)
```

### 1.2 路由注册层改造 (Routing Layer)

路由层将不再是一个巨大的 `routes.go`，而是拆分为“总线 + 分支”结构。

**文件: `internal/routes/routes.go` (总入口)**
```go
package routes

import (
    "github.com/gofiber/fiber/v2"
    "junhong_cmp_fiber/internal/handler" // 引用 health
    "junhong_cmp_fiber/internal/middleware"
    // 引入各个域的路由包 (因循环引用问题，建议直接在此文件定义 Register 函数，或拆分包)
    // 最佳实践：在此文件保留 SetupRoutes，调用同包下的 RegisterAdminRoutes 等
)

func SetupRoutes(app *fiber.App, deps *bootstrap.Dependencies) {
    // 1. 全局路由
    app.Get("/health", handler.HealthCheck)

    // 2. 注册各个域的路由组
    // Admin 域 (挂载在 /api/admin)
    adminGroup := app.Group("/api/admin")
    // 可以在这里挂载 Admin 专属中间件 (Token验证, RBAC等)
    RegisterAdminRoutes(adminGroup, deps)

    // App 域 (挂载在 /api/app)
    appGroup := app.Group("/api/app")
    RegisterAppRoutes(appGroup, deps)

    // Agent 域 (挂载在 /api/agent)
    agentGroup := app.Group("/api/agent")
    RegisterAgentRoutes(agentGroup, deps)
}
```

**文件: `internal/routes/admin.go` (Admin 域详情)**
```go
package routes

import (
    "github.com/gofiber/fiber/v2"
    "junhong_cmp_fiber/internal/handler/admin" // 引用新的 handler 包
)

func RegisterAdminRoutes(router fiber.Router, deps *bootstrap.Dependencies) {
    // 账号管理
    account := router.Group("/accounts")
    account.Post("/", admin.CreateAccount(deps.AccountService))
    account.Get("/", admin.ListAccounts(deps.AccountService))
    
    // ... 其他原有的路由逻辑，全部迁移到这里
}
```

---

## 2. OpenAPI 接入设计 (OpenAPI Integration)

我们将引入 `swaggest/openapi-go`，通过“影子路由”技术实现文档自动化。

### 2.1 基础设施: 文档生成器 (`pkg/openapi/generator.go`)

这是一个通用的工具类，用于封装 `Reflector`。

```go
package openapi

import (
    "github.com/swaggest/openapi-go/openapi3"
)

type Generator struct {
    Reflector *openapi3.Reflector
}

func NewGenerator(title, version string) *Generator {
    reflector := openapi3.Reflector{}
    reflector.Spec = &openapi3.Spec{
        Openapi: "3.0.3",
        Info: openapi3.Info{
            Title:   title,
            Version: version,
        },
    }
    return &Generator{Reflector: &reflector}
}

// 核心方法：向文档中添加一个操作
func (g *Generator) AddOperation(method, path, summary string, input interface{}, output interface{}, tags ...string) {
    op := openapi3.Operation{
        Summary: summary,
        Tags:    tags,
    }
    // ... 反射 input/output 并添加到 Spec 中 ...
    // ... 错误处理 ...
    g.Reflector.Spec.AddOperation(method, path, op)
}

// 导出 YAML
func (g *Generator) Save(filepath string) error { ... }
```

### 2.2 核心机制: 影子注册器 (`internal/routes/registry.go`)

这是一个 Helper 函数，连接 Fiber 路由和 OpenAPI 生成器。

```go
package routes

import (
    "github.com/gofiber/fiber/v2"
    "junhong_cmp_fiber/pkg/openapi"
)

// RouteSpec 定义接口文档元数据
type RouteSpec struct {
    Summary string
    Input   interface{} // 请求参数结构体 (Query/Path/Body)
    Output  interface{} // 响应参数结构体
    Tags    []string
    Auth    bool        // 是否需要认证图标
}

// Register 封装后的注册函数
// router: Fiber 路由组
// doc: 文档生成器
// method, path: HTTP 方法和路径
// handler: Fiber Handler
// spec: 文档元数据
func Register(router fiber.Router, doc *openapi.Generator, method, path string, handler fiber.Handler, spec RouteSpec) {
    // 1. 注册实际的 Fiber 路由
    router.Add(method, path, handler)

    // 2. 注册文档 (如果 doc 不为空 - 也就是在生成文档模式下)
    if doc != nil {
        doc.AddOperation(method, path, spec.Summary, spec.Input, spec.Output, spec.Tags...)
    }
}
```

### 2.3 业务代码改造示例

**Step 1: 改造路由文件 (`internal/routes/admin.go`)**

```go
// 引入文档生成器
func RegisterAdminRoutes(router fiber.Router, deps *bootstrap.Dependencies, doc *openapi.Generator) {
    
    // 使用 Register 替代 router.Post
    registry.Register(router, doc, "POST", "/accounts", 
        admin.CreateAccount(deps.AccountService), 
        registry.RouteSpec{
            Summary: "创建管理员账号",
            Tags:    []string{"Account"},
            Input:   new(model.CreateAccountReq),  // 必须是结构体指针
            Output:  new(model.AccountResp),       // 必须是结构体指针
        },
    )
}
```

**Step 2: 规范化 Model (`internal/model/account_dto.go`)**

必须确保 Input/Output 结构体有正确的 Tag。

```go
type CreateAccountReq struct {
    // Body 参数
    Username string `json:"username" required:"true" minLength:"4" description:"用户名"`
    Password string `json:"password" required:"true" description:"初始密码"`
    RoleID   uint   `json:"role_id" description:"角色ID"`
}

type AccountResp struct {
    ID       uint   `json:"id"`
    Username string `json:"username"`
    // ...
}
```

### 2.4 文档生成入口 (`cmd/gendocs/main.go`)

这是一个独立的 main 函数，用于生成文档文件。

```go
package main

import (
    "junhong_cmp_fiber/internal/routes"
    "junhong_cmp_fiber/pkg/openapi"
    "github.com/gofiber/fiber/v2"
)

func main() {
    // 1. 创建生成器
    adminDoc := openapi.NewGenerator("Admin API", "1.0")

    // 2. 模拟 Fiber App (不需要 Start)
    app := fiber.New()
    
    // 3. 调用注册函数，传入 doc
    // 注意：这里 deps 传 nil 即可，因为我们只跑路由注册逻辑，不跑实际 Handler
    routes.RegisterAdminRoutes(app, nil, adminDoc)

    // 4. 保存文件
    adminDoc.Save("./docs/admin-openapi.yaml")
}
```

---

## 3. 详细实施步骤 (Execution Plan)

### 第一阶段：路由与目录重构 (无文档)
1.  **创建目录**: `internal/handler/{admin,agent,app}`。
2.  **移动文件**: 将 `account.go`, `role.go` 等移入 `internal/handler/admin`。
3.  **修改包名**: 将移动后的文件 `package handler` 改为 `package admin`。
4.  **修复引用**: 使用 IDE 或 grep 查找所有引用了 `internal/handler` 的地方（主要是 `routes` 和 `bootstrap`），改为引用 `internal/handler/admin`。
5.  **重构路由**:
    *   在 `internal/routes` 下新建 `admin.go`，把 `routes.go` 里关于 admin 的代码剪切过去，封装成 `RegisterAdminRoutes` 函数。
    *   在 `routes.go` 中调用 `RegisterAdminRoutes`，并挂载到 `/api/admin`（注意：**路径变更**，需通知前端或暂时保持原路径）。*建议先保持原路径 `/api/v1` 以减少破坏性，等文档上齐了一起改。或者直接痛快点改成 `/api/admin`。你选择了"路由分离"，我就按 `/api/admin` 改。*

### 第二阶段：文档基础设施
1.  **添加依赖**: `swaggest/openapi-go`。
2.  **编写工具**: 实现 `pkg/openapi/generator.go`。
3.  **编写注册器**: 实现 `internal/routes/registry.go`。

### 第三阶段：文档接入 (以 Account 模块为例)
1.  **DTO 检查**: 检查 `internal/model/account_dto.go`，确保字段 Tag 完善。
2.  **路由改造**: 修改 `internal/routes/admin.go`，引入 `doc` 参数，用 `registry.Register` 替换原生路由。
3.  **生成测试**: 编写 `cmd/gendocs`，运行生成 YAML，验证内容是否正确。

### 第四阶段：全面铺开
1.  对所有模块重复第三阶段的工作。
2.  在 Makefile 中添加 `make docs`。
