# 架构文档 - 主模块

## 1. 执行摘要

猪场控制器是一个使用 Go 语言开发的后端应用程序，它利用 Echo Web 框架和 GORM ORM。它提供了一套全面的 API，用于管理猪场的各个方面，包括用户管理、设备控制、计划执行、猪群批次管理和数据监控。该应用程序被设计为一个分层、以 API 为中心的后端服务。

## 2. 技术栈

| 类别        | 技术          | 版本    |
| :---------- | :------------ | :------ |
| 语言        | Go            | 1.25    |
| Web 框架    | Echo          | v4.13.4 |
| ORM         | GORM          | v1.30.5 |
| 数据库驱动  | PostgreSQL    |         |
| 数据库驱动  | SQLite        |         |
| 日志        | Zap           | v1.27.0 |
| 文档        | Swaggo        | v1.16.6 |
| JWT         | golang-jwt/jwt | v5.3.0  |
| UUID        | google/uuid   | v1.6.0  |
| 并发        | Ants          | v2.11.3 |
| 调度        | Cron          | v3.0.1  |
| 测试        | Testify       | v1.11.1 |
| 串口        | tarm/serial   |         |
| 加密        | golang.org/x/crypto | v0.43.0 |
| Protobuf    | google/protobuf | v1.36.9 |
| YAML        | gopkg.in/yaml.v2 | v2.4.0  |

## 3. 架构模式

该应用程序遵循**分层/以 API 为中心的后端服务**架构。它公开了一个 RESTful API，用于与各种功能进行交互。核心逻辑被组织成应用层、领域层和基础设施层，促进了关注点分离和可维护性。

## 4. 数据架构

该应用程序使用 PostgreSQL 数据库，支持 TimescaleDB 用于时序数据。GORM 用作对象关系映射器。数据库模式包含 33 个表，涵盖了用户、设备、计划、猪群批次、农场资产（猪舍、猪圈）、传感器数据、药物和通知等实体。主要表包括：

*   `User` (用户)
*   `Device` (设备)
*   `Plan` (计划)
*   `PigBatch` (猪群批次)
*   `PigHouse` (猪舍)
*   `Pen` (猪圈)
*   `SensorData` (传感器数据)
*   `Medication` (药物)
*   `Notification` (通知)

有关数据模型的完整列表，请参阅 [数据模型 - 主模块](./data-models-main-zh.md)。

## 5. API 设计

API 被设计为 RESTful 接口，主要使用 JSON 作为请求和响应体。它包括公共和认证端点。认证通过 JWT 处理。API 涵盖了广泛的功能，包括：

*   用户认证和管理。
*   设备、设备模板、区域控制器、计划、猪舍和猪圈的 CRUD 操作。
*   全面的猪群批次管理，包括转栏、销售、采购和健康记录。
*   各种日志和传感器数据的监控端点。

有关 API 端点的详细列表，请参阅 [API 契约 - 主模块](./api-contracts-main-zh.md)。

## 6. 组件概述

应用程序由几个关键组件组成：

*   **应用层 (`internal/app`)**: 处理 API 路由、控制器、DTO、中间件和应用程序特定服务。
*   **核心层 (`internal/core`)**: 包含核心应用程序设置和初始化逻辑。
*   **领域层 (`internal/domain`)**: 封装了审计、设备、猪只、调度器等各种模块的业务逻辑和领域实体。
*   **基础设施层 (`internal/infra`)**: 管理外部关注点，如数据库交互、日志记录、配置和外部通信（例如，LoRaWAN ChirpStack 集成）。

## 7. 源代码树

有关项目目录结构和每个关键文件夹用途的详细说明，请参阅 [源代码树分析 - 主模块](./source-tree-analysis-zh.md)。

## 8. 开发工作流

开发工作流涉及标准的 Go 实践，包括使用 `go mod` 进行依赖管理，使用 `go build`（或 `make`）进行构建，以及使用 `go test` 进行测试。配置通过 `config.yml` 外部化。

有关详细的开发说明，请参阅 [开发指南 - 主模块](./development-guide-main-zh.md)。

## 9. 部署架构

虽然没有找到明确的 Dockerfile 或 CI/CD 配置，但该应用程序是一个自包含的 Go 二进制文件。部署通常涉及编译应用程序，为目标环境配置 `config.yml`，然后运行可执行文件。它旨在与外部 PostgreSQL 数据库和 ChirpStack LoRaWAN 服务器进行交互。

## 10. 测试策略

测试主要使用 Go 的内置测试框架进行，并使用 `github.com/stretchr/testify` 进行断言。测试通常遵循 Go 约定，与它们测试的代码一起放置。