85 lines
4.2 KiB
Markdown
85 lines
4.2 KiB
Markdown
# 架构文档 - 主模块
|
||
|
||
## 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 约定，与它们测试的代码一起放置。
|