qsc20001102/AquaControlAI
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

11

Browse Source
This commit is contained in:
qsc20001102
2026-07-11 13:15:28 +08:00
parent 129bf28ccf
commit e1b03eb88c
1 changed files with 90 additions and 340 deletions
Download Patch File Download Diff File Expand all files Collapse all files
开发文档/code-standards.md
+90 -340
View File
@@ -8,17 +8,15 @@
## 目录 ## 目录
- [1. 通用原则](#1-通用原则) - [1. 通用原则](#1-通用原则)
- [1.4 优先复用，禁止重复造轮子](#14-优先复用禁止重复造轮子)
- [2. 项目结构与工程规范](#2-项目结构与工程规范) - [2. 项目结构与工程规范](#2-项目结构与工程规范)
- [3. Go 后端规范](#3-go-后端规范) - [3. Go 后端规范](#3-go-后端规范)
- [4. 前端规范](#4-前端规范) - [4. 前端规范](#4-前端规范)
- [5. RESTful API 规范](#5-restful-api-规范) - [5. RESTful API 规范](#5-restful-api-规范)
- [6. 数据库规范](#6-数据库规范) - [6. 数据库规范](#6-数据库规范)
- [6.4 连接配置、初始化与重建](#64-连接配置初始化与重建)
- [7. 日志与错误处理规范](#7-日志与错误处理规范) - [7. 日志与错误处理规范](#7-日志与错误处理规范)
- [8. 安全规范](#8-安全规范) - [8. 安全规范](#8-安全规范)
- [9. 代码审核清单](#9-代码审核清单) - [9. 代码审核清单](#9-代码审核清单)
- [附录 A：模块间关系与命名约定](#附录-a模块间关系与命名约定) - [附录 A：命名约定](#附录-a命名约定)
--- ---
@@ -33,7 +31,6 @@
| **最小惊讶** | 函数的名称和签名应让调用者无需查看实现就能大致猜到行为 | | **最小惊讶** | 函数的名称和签名应让调用者无需查看实现就能大致猜到行为 |
| **防御式编程** | 不信任外部输入，对所有外部输入做校验，但内部调用尽量减少冗余校验 | | **防御式编程** | 不信任外部输入，对所有外部输入做校验，但内部调用尽量减少冗余校验 |
| **模块自治** | 每个模块有清晰的边界，模块间通过 API 通信，不直接访问其他模块的内部数据 | | **模块自治** | 每个模块有清晰的边界，模块间通过 API 通信，不直接访问其他模块的内部数据 |
| **优先复用** | 先复用已有模块、成熟依赖和平台能力；仅在现有方案确实无法满足需求时才自行实现 |
### 1.2 命名风格对照表 ### 1.2 命名风格对照表
@@ -57,14 +54,12 @@
- **FIXME 注释**：必须附带 issue 编号，如 `// FIXME(#123): 此处有并发安全问题` - **FIXME 注释**：必须附带 issue 编号，如 `// FIXME(#123): 此处有并发安全问题`
- **代码删除**：不保留被注释掉的旧代码，直接删除，有需要从 git 历史查找 - **代码删除**：不保留被注释掉的旧代码，直接删除，有需要从 git 历史查找
### 1.4 优先复用，禁止重复造轮子 ### 1.4 复用约束
- **先查后写**：新增功能前，必须先检查项目现有代码、已引入依赖、组件库和已封装的公共能力；优先复用 `internal/pkg/`、`web/src/components/`、`web/src/utils/` 与同类模块的实现。 - 新增功能前，必须优先复用 `internal/pkg/`、`web/src/components/`、`web/src/utils/` 中的现有实现及已引入的依赖
- **优先级**：项目既有能力 → 官方 SDK / 框架内置能力 → 维护活跃、许可证兼容的成熟开源库 → 自研实现。不得因“实现简单”绕过这一顺序。 - 复用优先级：项目既有能力 → 官方 SDK / 框架内置能力 → 维护活跃的开源库 → 自研实现
- **禁止重复实现**：禁止自行实现已有成熟方案已覆盖的通用能力，例如鉴权、参数校验、密码哈希、UUID、数据库迁移、HTTP 客户端重试、日期处理、图表、虚拟列表、CSV 编解码和协议编解码。 - **禁止**：自行实现已有成熟方案已覆盖的通用能力，包括但不限于鉴权、参数校验、密码哈希、UUID、数据库迁移、HTTP 客户端重试、日期处理、图表、CSV 编解码和协议编解码
- **允许自研的条件**：现有方案无法满足性能、可靠性、许可、安全、离线部署或工业协议兼容性要求时，方可自研；提交中必须说明已调研方案、未采用原因、维护边界和测试方案。 - 封装边界：对第三方库的调用应集中在适配层或公共封装中，业务代码不得散落依赖某个供应商的私有 API
- **封装边界**：对第三方库的调用应集中在适配层或公共封装中，业务代码不得散落依赖某个供应商的私有 API；不得为薄封装无理由再造通用组件。
- **审查要求**：PR 必须说明“复用了什么”或“为何不能复用”；无法说明的重复实现不得合入。
--- ---
@@ -138,24 +133,9 @@ water-plant-control/
└── Makefile # 构建脚本 └── Makefile # 构建脚本
``` ```
### 2.2 新增模块的目录规范 ### 2.2 模块目录与命名约束
当新增模块（如未来开发"实时监控""智能控制""系统配置"）时，遵循以下规范： 新增模块时，后端在 `internal/` 下各层同步添加子包，前端在 `web/src/views/` 下添加页面目录。
```
# 后端新增模块，在以下目录各增加一个子包
internal/
├── api/monitoring/ # 实时监控 API
├── service/monitoring/ # 实时监控业务逻辑
├── repository/... # 数据访问
└── model/ # 数据模型
# 前端新增模块，在以下目录增加
web/src/views/
└── monitoring/ # 实时监控页面
```
#### 模块级命名约束
| 模块 | 后端 Go package | 前端目录 | API 路径前缀 | | 模块 | 后端 Go package | 前端目录 | API 路径前缀 |
|------|----------------|----------|-------------| |------|----------------|----------|-------------|
@@ -164,16 +144,13 @@ web/src/views/
| 数据管理-写入点 | `writepoint` | `write-point/` | `/api/v1/write-points` | | 数据管理-写入点 | `writepoint` | `write-point/` | `/api/v1/write-points` |
| 历史数据 | `history` | `history/` | `/api/v1/history` | | 历史数据 | `history` | `history/` | `/api/v1/history` |
> 上表中未列出的模块（实时监控、智能控制、系统配置）在开发时补充至此表。
### 2.3 依赖管理 ### 2.3 依赖管理
- **Go**：使用 `go.mod` 管理依赖，定期执行 `go mod tidy` - **Go**：使用 `go.mod` 管理依赖，定期执行 `go mod tidy`
- **前端**：使用 `package.json` + `pnpm-lock.yaml`（优先 pnpm，其次 npm） - **前端**：使用 `package.json` + `pnpm-lock.yaml`（优先 pnpm，其次 npm）
- **禁止**：直接拷贝第三方库源码到项目中（除非 fork 修改，且需在 README 中注明） - **禁止**：直接拷贝第三方库源码到项目中（除非 fork 修改，且需在 README 中注明）
- **新增依赖准入**：新增依赖前必须检索现有依赖和代码，确认没有等价能力；选择有明确维护状态、兼容许可证、稳定版本与安全更新渠道的库。 - **版本锁定**：提交依赖变更时必须同时提交锁文件；禁止使用不受控的浮动版本
- **版本锁定**：提交依赖变更时必须同时提交锁文件；禁止使用不受控的浮动版本或从未固定提交的 Git 分支安装依赖。 - **最小化引入**：不得为单个小功能引入体积过大或功能重叠的依赖
- **最小化引入**：不得为单个小功能引入体积过大或功能重叠的依赖；优先按需导入，并删除不再使用的依赖。
--- ---
@@ -207,14 +184,13 @@ Repository (数据访问、ORM 查询)
#### 3.2.1 Handler 层规范 #### 3.2.1 Handler 层规范
```go ```go
// ✅ 正确示例 // ✅ 正确：Handler 只做参数校验和响应转换
func (h *DeviceHandler) Create(c *gin.Context) { func (h *DeviceHandler) Create(c *gin.Context) {
var req CreateDeviceRequest var req CreateDeviceRequest
if err := c.ShouldBindJSON(&req); err != nil { if err := c.ShouldBindJSON(&req); err != nil {
response.BadRequest(c, "无效的请求参数", err.Error()) response.BadRequest(c, "无效的请求参数", err.Error())
return return
} }
// Handler 只做参数校验和响应转换
device, err := h.svc.Create(c.Request.Context(), &req) device, err := h.svc.Create(c.Request.Context(), &req)
if err != nil { if err != nil {
response.Error(c, err) response.Error(c, err)
@@ -223,86 +199,32 @@ func (h *DeviceHandler) Create(c *gin.Context) {
response.Success(c, device) response.Success(c, device)
} }
// ✗ 禁止：Handler 中写业务逻辑 // ✗ 禁止：Handler 中写业务逻辑或直接操作数据库
func (h *DeviceHandler) Create(c *gin.Context) {
// ... 校验参数
// ... 自己查数据库判断是否重名 ✗ 应该调用 Service
// ... 自己拼 SQL 插入 ✗ 应该调用 Service
// ... 自己写日志 ✗ 应该由 Service 层处理
}
``` ```
#### 3.2.2 Service 层规范 #### 3.2.2 Service 层规范
```go ```go
// ✅ 正确示例 // ✅ 正确：Service 层专注业务逻辑
func (s *DeviceService) Create(ctx context.Context, req *CreateDeviceRequest) (*Device, error) { func (s *DeviceService) Create(ctx context.Context, req *CreateDeviceRequest) (*Device, error) {
// 1. 参数校验（复杂校验逻辑放在 Service 层） // 复杂校验放 Service 层
if err := s.validateDevice(req); err != nil { if err := s.validate(req); err != nil {
return nil, err return nil, err
} }
// 调用 Repository
// 2. 业务逻辑（如检查 name 唯一性）
existing, err := s.repo.FindByName(ctx, req.Name)
if err != nil {
return nil, fmt.Errorf("查询设备名称失败: %w", err)
}
if existing != nil {
return nil, ErrDeviceNameConflict
}
// 3. 转换为模型
device := &model.Device{
Name: req.Name,
ProtocolType: req.ProtocolType,
Host: req.Host,
Port: req.Port,
// ...
}
// 4. 持久化
if err := s.repo.Create(ctx, device); err != nil { if err := s.repo.Create(ctx, device); err != nil {
return nil, fmt.Errorf("创建设备失败: %w", err) return nil, fmt.Errorf("创建设备失败: %w", err)
} }
return device, nil return device, nil
} }
``` ```
#### 3.2.3 Repository 层规范 #### 3.2.3 Repository 层规范
```go - 使用参数化查询，禁止字符串拼接 SQL
// ✅ 正确示例 - 显式指定查询字段，禁止 `SELECT *`
func (r *DeviceRepo) FindByProtocolType(ctx context.Context, protocolType string) ([]*model.Device, error) { - 复杂查询使用 QueryBuilder，避免字符串拼接
query := `SELECT id, name, protocol_type, host, port, enabled, - 简单 CRUD 操作统一封装 BaseRepo
connect_timeout, reconnect_interval, protocol_config,
created_at, updated_at
FROM devices
WHERE protocol_type = $1 AND deleted = FALSE
ORDER BY name`
rows, err := r.db.QueryContext(ctx, query, protocolType)
if err != nil {
return nil, fmt.Errorf("查询设备列表失败: %w", err)
}
defer rows.Close()
var devices []*model.Device
for rows.Next() {
var d model.Device
if err := rows.Scan(&d.ID, &d.Name, &d.ProtocolType, &d.Host, &d.Port,
&d.Enabled, &d.ConnectTimeout, &d.ReconnectInterval, &d.ProtocolConfig,
&d.CreatedAt, &d.UpdatedAt); err != nil {
return nil, fmt.Errorf("扫描设备记录失败: %w", err)
}
devices = append(devices, &d)
}
return devices, rows.Err()
}
// ✅ 建议：对于简单 CRUD 操作，统一封装 BaseRepo
// ✅ 建议：复杂查询使用 QueryBuilder，避免字符串拼接
```
### 3.3 错误处理 ### 3.3 错误处理
@@ -311,7 +233,6 @@ func (r *DeviceRepo) FindByProtocolType(ctx context.Context, protocolType string
var ( var (
ErrDeviceNotFound = errors.New("设备不存在") ErrDeviceNotFound = errors.New("设备不存在")
ErrDeviceNameConflict = errors.New("设备名称已存在") ErrDeviceNameConflict = errors.New("设备名称已存在")
ErrProtocolNotSupport = errors.New("不支持的协议类型")
) )
// 错误包装：始终携带上下文 // 错误包装：始终携带上下文
@@ -326,22 +247,10 @@ if err != nil {
### 3.4 并发安全 ### 3.4 并发安全
- 采集引擎（运行时）涉及设备连接池、共享内存状态，必须使用 `sync.Mutex` 或 `sync.RWMutex` 保护 - 采集引擎涉及设备连接池、共享内存状态，必须使用 `sync.Mutex` 或 `sync.RWMutex` 保护
- 避免裸 `sync.Map`，优先使用 `map + sync.RWMutex` - 避免裸 `sync.Map`，优先使用 `map + sync.RWMutex`
- 协程启动必须可控：使用 `context.Context` + `sync.WaitGroup` 管理生命周期 - 协程启动必须可控：使用 `context.Context` + `sync.WaitGroup` 管理生命周期
- **禁止无限制启动 goroutine**，必须通过带有缓冲 channel 或协程池限制并发数 - **禁止无限制启动 goroutine**，必须通过缓冲 channel 或协程池限制并发数
```go
// ✅ 正确示例：采集引擎任务管理
type CollectorManager struct {
mu sync.RWMutex
connPool map[string]*Connection // 设备连接池
runners map[string]*PointRunner // 采集点执行器
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
}
```
### 3.5 单元测试 ### 3.5 单元测试
@@ -354,13 +263,13 @@ type CollectorManager struct {
- 测试文件与源码同目录，命名 `*_test.go` - 测试文件与源码同目录，命名 `*_test.go`
- Mock 统一使用 `github.com/stretchr/testify/mock` 或 `go.uber.org/mock` - Mock 统一使用 `github.com/stretchr/testify/mock` 或 `go.uber.org/mock`
- 测试数据使用 t.Helper() + t.Cleanup() 管理 - 测试数据使用 `t.Helper()` + `t.Cleanup()` 管理
--- ---
## 4. 前端规范 ## 4. 前端规范
### 4.1 框架与技术选型（约定） ### 4.1 技术栈约定
| 领域 | 选型 | | 领域 | 选型 |
|------|------| |------|------|
@@ -376,9 +285,8 @@ type CollectorManager struct {
### 4.2 组件设计规范 ### 4.2 组件设计规范
```vue ```vue
<!-- ✅ 正确示例 --> <!-- ✅ props 和 emit 使用类型定义 -->
<script setup lang="ts"> <script setup lang="ts">
// 1. props 和 emit 使用类型定义
interface Props { interface Props {
deviceId: string deviceId: string
loading?: boolean loading?: boolean
@@ -392,7 +300,7 @@ const emit = defineEmits<{
(e: 'delete', id: string): void (e: 'delete', id: string): void
}>() }>()
// 2. 组合式函数提取可复用逻辑 // 组合式函数提取可复用逻辑
const { data, fetchData } = useDeviceDetail(props.deviceId) const { data, fetchData } = useDeviceDetail(props.deviceId)
</script> </script>
@@ -407,30 +315,15 @@ const { data, fetchData } = useDeviceDetail(props.deviceId)
</style> </style>
``` ```
### 4.3 API 调用层 ### 4.3 API 调用层规范
```typescript ```typescript
// src/api/device.ts // src/api/device.ts
import request from '@/utils/request' import request from '@/utils/request'
// ✅ 每个模块一个 API 文件，所有请求集中在 api/ 目录 // 每个模块一个 API 文件，所有请求集中在 api/ 目录
export interface DeviceListParams { export function fetchDeviceList(params: Record<string, unknown>) {
page?: number return request.get('/api/v1/devices', { params })
pageSize?: number
keyword?: string
protocolType?: string
enabled?: boolean
}
export function fetchDeviceList(params: DeviceListParams) {
const { pageSize, ...rest } = params
return request.get('/api/v1/devices', {
params: { ...rest, page_size: pageSize },
})
}
export function createDevice(data: Record<string, unknown>) {
return request.post('/api/v1/devices', data)
} }
// ✗ 禁止：在组件中直接调用 axios // ✗ 禁止：在组件中直接调用 axios
@@ -442,53 +335,12 @@ export function createDevice(data: Record<string, unknown>) {
- 图表组件统一封装在 `src/components/charts/` 目录下 - 图表组件统一封装在 `src/components/charts/` 目录下
- ECharts 的 option 构造使用纯函数，方便测试 - ECharts 的 option 构造使用纯函数，方便测试
- 图表容器使用 `ResizeObserver` 自动适应窗口变化 - 图表容器使用 `ResizeObserver` 自动适应窗口变化
- **曲线模式分段自适应 Y 轴**：实现为可复用的工具函数 `src/utils/axis-mapper.ts`
```typescript ### 4.5 状态管理规范
// ✅ 工具函数封装示例
// src/utils/axis-mapper.ts
interface Segment {
start: number
end: number
heightRatio: number // 占Y轴高度的比例
}
export function buildSegments(dataValues: number[]): Segment[] { - 跨组件共享状态使用 Pinia store 统一管理
// 根据数据分布自动分段 - 每个 Store 文件职责单一，按业务模块拆分
// ... 实现分段自适应Y轴的映射逻辑 - 禁止在组件中直接修改非本组件的状态
}
export function mapValueToPosition(value: number, segments: Segment[]): number {
// 将原始值映射为显示坐标
// ...
}
```
### 4.5 状态与复选框勾选
- **勾选状态**：使用 Pinia store 统一管理，支持曲线/表格模式切换时保持状态
```typescript
// ✅ 正确示例
// src/store/selected-points.ts
export const useSelectedPointsStore = defineStore('selected-points', () => {
const selectedIds = ref<Set<string>>(new Set())
// 最大勾选数 20
const MAX_SELECTION = 20
function toggle(id: string) {
if (selectedIds.value.has(id)) {
selectedIds.value.delete(id)
} else if (selectedIds.value.size < MAX_SELECTION) {
selectedIds.value.add(id)
}
// 超过上限不做操作
}
return { selectedIds, toggle }
})
```
--- ---
@@ -501,7 +353,6 @@ export const useSelectedPointsStore = defineStore('selected-points', () => {
约定： 约定：
- 资源名使用 kebab-case 复数形式（devices, collection-points, write-points） - 资源名使用 kebab-case 复数形式（devices, collection-points, write-points）
- 子资源（如导出/导入）使用 POST 动词 + 路径
- 批量操作使用 POST，非 GET（避免 URL 过长） - 批量操作使用 POST，非 GET（避免 URL 过长）
- 版本号 v1 写在路径中 - 版本号 v1 写在路径中
``` ```
@@ -511,19 +362,11 @@ export const useSelectedPointsStore = defineStore('selected-points', () => {
所有 API 响应使用统一格式： 所有 API 响应使用统一格式：
```json ```json
// ✅ 成功响应
{ {
"code": 0, "code": 0,
"message": "success", "message": "success",
"data": { ... } "data": { ... }
} }
// ✅ 错误响应
{
"code": 40001,
"message": "设备名称已存在",
"data": null
}
``` ```
| 字段 | 必填 | 说明 | | 字段 | 必填 | 说明 |
@@ -575,7 +418,6 @@ export const useSelectedPointsStore = defineStore('selected-points', () => {
``` ```
✅ /api/v1/devices/{id} // 路径参数使用 {param} 风格 ✅ /api/v1/devices/{id} // 路径参数使用 {param} 风格
✅ /api/v1/collection-points/groups // 固定子路径 ✅ /api/v1/collection-points/groups // 固定子路径
✅ /api/v1/write-points/{id}/write // 动作子路径
查询参数命名（与数据库字段一致）： 查询参数命名（与数据库字段一致）：
?page=1&page_size=20&keyword=XXX&enabled=true ?page=1&page_size=20&keyword=XXX&enabled=true
@@ -598,10 +440,6 @@ export const useSelectedPointsStore = defineStore('selected-points', () => {
| 唯一索引 | 逻辑删除的表使用 `WHERE deleted = FALSE` 的条件唯一索引 | | 唯一索引 | 逻辑删除的表使用 `WHERE deleted = FALSE` 的条件唯一索引 |
| 外键 | 显式声明 `REFERENCES`，但不启用级联（业务层处理级联逻辑） | | 外键 | 显式声明 `REFERENCES`，但不启用级联（业务层处理级联逻辑） |
| 迁移 | 使用 golang-migrate 或类似工具管理，禁止手动修改库结构 | | 迁移 | 使用 golang-migrate 或类似工具管理，禁止手动修改库结构 |
| 更新时间 | 通过迁移创建触发器或由仓储层统一维护 `updated_at`，不得依赖调用方遗漏更新 |
- 每次结构变更必须新增可重复执行的迁移文件，并在空库和包含历史数据的库上验证。
- 破坏性变更采用“先兼容、再迁移、后删除”的至少两个发布周期策略；确需一次性变更时，必须附带回滚与数据备份方案。
```sql ```sql
-- ✅ 正确示例 -- ✅ 正确示例
@@ -635,7 +473,6 @@ CREATE UNIQUE INDEX idx_devices_name ON devices(name) WHERE deleted = FALSE;
| 质量戳 | `INT` 类型：`0=good`, `1=bad` | | 质量戳 | `INT` 类型：`0=good`, `1=bad` |
| 值 | 统一使用 `DOUBLE`，BOOL 类型存 0/1 | | 值 | 统一使用 `DOUBLE`，BOOL 类型存 0/1 |
| 标签 | 元数据信息存为 TAGS，不做查询条件的有选择缓存 | | 标签 | 元数据信息存为 TAGS，不做查询条件的有选择缓存 |
| KEEP 参数 | 通过系统配置动态调整，通过 `ALTER DATABASE` 执行 |
### 6.3 SQL 书写规范 ### 6.3 SQL 书写规范
@@ -649,47 +486,18 @@ LIMIT 20 OFFSET 0;
-- ✗ 禁止：SELECT *，必须显式指定字段列表 -- ✗ 禁止：SELECT *，必须显式指定字段列表
-- ✅ INSERT 语句 -- ✅ INSERT 语句：显式指定列名
INSERT INTO devices (name, protocol_type, host, port, protocol_config) INSERT INTO devices (name, protocol_type, host, port, protocol_config)
VALUES ($1, $2, $3, $4, $5) VALUES ($1, $2, $3, $4, $5)
RETURNING id; RETURNING id;
``` ```
### 6.4 连接配置、初始化与重建 ### 6.4 数据库连接规范
数据库连接必须通过环境变量或密钥管理服务注入，应用仅读取配置并在启动时执行连通性检查。数据库名称不是默认值，必须由部署环境显式指定；严禁在代码、示例配置或本文档中写入真实密码。 - 数据库连接参数通过环境变量注入，禁止硬编码在代码中
- 连接 DSN 按 `postgres://USER:PASS@HOST:PORT/DB?sslmode=require` 格式组装
```dotenv - Go 后端使用连接池，并在应用启动时通过带超时的 `PingContext` 校验连接
# .env.example：可提交，仅包含非敏感连接端点与占位符 - 数据库连接配置仅由 `.env.example` 提供占位符模板，`.env` 文件必须加入 `.gitignore`
POSTGRES_HOST=101.35.54.96
POSTGRES_PORT=5432
POSTGRES_USER=qsc20001102
POSTGRES_PASSWORD=qsc102341
POSTGRES_DB=aquacontrolai
TDENGINE_HOST=101.35.54.96
TDENGINE_PORT=6041
TDENGINE_USER=root
TDENGINE_PASSWORD=taosdata
TDENGINE_DB=aquacontrolai
```
- **PostgreSQL DSN**：按 `postgres://{POSTGRES_USER}:{POSTGRES_PASSWORD}@{POSTGRES_HOST}:{POSTGRES_PORT}/{POSTGRES_DB}?sslmode={POSTGRES_SSLMODE}` 组装。Go 后端使用连接池，并在应用启动时通过带超时的 `PingContext` 校验连接；不得记录完整 DSN 或密码。
- **TDengine DSN**：6041 为 taosAdapter 服务端口。Go 后端优先使用 `github.com/taosdata/driver-go/v3` 的 WebSocket 驱动，DSN 格式为 `{TDENGINE_USER}:{TDENGINE_PASSWORD}@ws({TDENGINE_HOST}:{TDENGINE_PORT})/{TDENGINE_DB}`，驱动名为 `taosWS`。必须在 DSN 中指定数据库名，不依赖连接后的 `USE` 语句。
- **网络与权限**：对公网地址必须配置最小网络访问范围；生产环境 PostgreSQL 必须启用证书校验，两个数据库账号均应按环境和最小权限拆分，禁止使用共享管理员账号作为长期应用账号。
- **配置文件**：真实密码只允许位于部署平台密钥、CI Secret 或开发人员本地未提交的 `.env` 文件；`.env.example` 保留占位符，`.env` 必须在 `.gitignore` 中。
#### 6.4.1 开发/测试环境数据库重建
开发或测试环境允许清空并重建 PostgreSQL 与 TDengine 数据库，以确保初始结构一致；此操作会永久删除目标库中的全部数据。
- 仅允许由人工显式执行的初始化/重建脚本触发，**禁止**在应用启动、普通迁移或自动部署中隐式执行 `DROP DATABASE`。
- 脚本必须要求显式确认标记（例如 `RESET_DATABASE=CONFIRM_DROP_AND_RECREATE`），并在执行前打印目标主机、端口、数据库名和环境；任一项缺失则立即失败。
- PostgreSQL 重建顺序：连接维护库 → 断开目标库现有连接 → 删除目标库 → 创建目标库及所需扩展 → 从零执行全部迁移。
- TDengine 重建顺序：删除目标库 → 创建目标库及保留策略 → 从零执行全部时序表/超级表初始化脚本。
- 重建脚本必须只操作 `POSTGRES_DB` 和 `TDENGINE_DB` 指定的目标库，禁止对系统库、未指定库或生产环境执行；生产环境重建须另行书面审批、备份和恢复演练。
- 每次重建完成后必须执行迁移状态检查和最小连通性/读写冒烟测试，并记录执行人、时间、目标环境和结果。
--- ---
@@ -697,27 +505,20 @@ TDENGINE_DB=aquacontrolai
### 7.1 日志级别 ### 7.1 日志级别
| 级别 | 使用场景 | 示例 | | 级别 | 使用场景 |
|------|---------|------| |------|---------|
| DEBUG | 调试信息，仅开发环境 | `DEBUG 采集点曝气池DO_01 采集完成，值=2.35` | | DEBUG | 调试信息，仅开发环境 |
| INFO | 正常运行信息 | `INFO 设备一期曝气柜PLC 连接成功` | | INFO | 正常运行信息 |
| WARN | 可恢复的异常 | `WARN 设备一期曝气柜PLC 重连第3次失败，将在10秒后重试` | | WARN | 可恢复的异常 |
| ERROR | 需要关注的错误 | `ERROR 写入点加药泵频率 写入失败: 回读值不匹配` | | ERROR | 需要关注的错误 |
### 7.2 日志规范 ### 7.2 日志格式规范
```go ```go
// ✅ 正确示例 // ✅ 正确：采用结构化键值对
logger.Info("设备连接成功", logger.Info("设备连接成功",
"device_id", device.ID, "device_id", device.ID,
"device_name", device.Name, "device_name", device.Name,
"protocol", device.ProtocolType,
)
logger.Error("写入操作失败",
"point_id", pointID,
"target_value", targetValue,
"error", err.Error(),
) )
// ✗ 禁止：没有上下文的日志 // ✗ 禁止：没有上下文的日志
@@ -728,18 +529,15 @@ logger.Error("写入操作失败",
### 7.3 关键业务日志埋点 ### 7.3 关键业务日志埋点
以下业务操作必须记录日志（作为审计追溯依据）： | 操作 | 日志级别 |
|------|---------|
| 操作 | 日志级别 | 说明 | | 设备创建/修改/删除 | INFO |
|------|---------|------| | 采集点/写入点创建/修改/删除 | INFO |
| 设备创建/修改/删除 | INFO | 记录操作人和变更内容 | | 写入操作 | INFO |
| 采集点创建/修改/删除 | INFO | 同上 | | 采集引擎启停 | INFO |
| 写入点创建/修改/删除 | INFO | 同上 | | 设备连接/断开 | WARN |
| 写入操作 | INFO | 记录写入值、来源（manual/auto）、操作人、结果 | | 重连失败 | WARN |
| 采集引擎启停 | INFO | 记录启动/停止原因 | | 协议驱动异常 | ERROR |
| 设备连接/断开 | WARN | 记录连接耗时或断开原因 |
| 重连失败 | WARN | 记录失败次数 |
| 协议驱动异常 | ERROR | 记录异常堆栈 |
--- ---
@@ -752,7 +550,6 @@ logger.Error("写入操作失败",
db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name) db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name)
// ✗ 禁止：字符串拼接 SQL // ✗ 禁止：字符串拼接 SQL
// db.QueryContext(ctx, "SELECT * FROM devices WHERE name = '" + name + "'")
``` ```
### 8.2 输入校验 ### 8.2 输入校验
@@ -761,24 +558,22 @@ db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name)
|------|---------| |------|---------|
| IP 地址 | 使用 `net.ParseIP()` 或正则校验合法格式 | | IP 地址 | 使用 `net.ParseIP()` 或正则校验合法格式 |
| 端口号 | 范围 1~65535 | | 端口号 | 范围 1~65535 |
| 时间范围 | 结束时间必须晚于开始时间，最大跨度不超过 31 天（防止 TDengine 扫大量数据） | | 时间范围 | 结束时间必须晚于开始时间，最大跨度不超过 31 天 |
| 分页 | page >= 1, page_size <= 100 | | 分页 | page >= 1, page_size <= 100 |
| 文件名 | 导出的 CSV 文件名不含用户输入（防止路径穿越） | | 文件名 | 导出的 CSV 文件名不含用户输入（防止路径穿越） |
| 布尔值 | 在 Go 中由 JSON 解析器自动校验，前端限制 true/false |
### 8.3 写入安全 ### 8.3 写入安全
- **写入开关校验**：必须在 Service 层校验 `write_enabled=true`，Handler 层只做类型校验 - **写入开关校验**：在 Service 层校验 `write_enabled=true`
- **写入来源校验**：校验 `write_source` 与请求 `source` 的匹配关系（manual/auto/both） - **写入来源校验**：校验 `write_source` 与请求 `source` 的匹配关系
- **回读验证**：写入后必须回读确认，实现位置在 Engine 层，Service 层调用 - **回读验证**：写入后必须执行回读确认
- **写入权限**：人工写入（`source=manual`）需要登录鉴权；程序自动写入（`source=auto`）需要 API Token - **写入权限**：人工写入需登录鉴权；程序自动写入需 API Token
### 8.4 配置安全 ### 8.4 配置安全
- 数据库密码、API Key 等敏感信息通过环境变量或 vault 注入，**禁止硬编码在代码中** - 数据库密码、API Key 等敏感信息通过环境变量注入，**禁止硬编码在代码中**
- `.env` 文件加入 `.gitignore`，仅提供 `.env.example` 模板 - `.env` 文件加入 `.gitignore`，仅提供 `.env.example` 占位符模板
- `protocol_config` 中不存储凭据类信息 - `protocol_config` 中不存储凭据类信息
- 本规范、README、Issue、日志、截图和错误响应中均不得记录真实密码、完整 DSN 或 Token；如发生泄露，立即轮换凭据并按安全事件处理
--- ---
@@ -793,9 +588,8 @@ db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name)
□ 无被注释掉的旧代码 □ 无被注释掉的旧代码
□ 无 console.log / fmt.Println 等调试输出 □ 无 console.log / fmt.Println 等调试输出
□ 无硬编码的敏感信息（密码、token、key） □ 无硬编码的敏感信息（密码、token、key）
□ 新增能力已复用既有实现或成熟依赖；如无法复用，已说明原因并完成评审 □ 新增能力已复用既有实现或成熟依赖
□ 数据库变更已提供迁移，且未在应用启动流程中执行破坏性重建 □ 数据库变更已提供迁移文件
□ 新增 API 已添加至 API 文档
□ 所有 TODO/FIXME 已确认或附带了责任人 □ 所有 TODO/FIXME 已确认或附带了责任人
``` ```
@@ -805,34 +599,27 @@ db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name)
| 检查项 | 说明 | | 检查项 | 说明 |
|--------|------| |--------|------|
| 模块边界是否清晰 | 是否有跨模块的内部依赖（如 Handler 直接调用其他模块的 Repo） | | 模块边界是否清晰 | 是否有 Handler 直接调用其他模块的 Repo |
| 分层是否遵守 | Handler → Service → Repository 单向依赖 | | 分层是否遵守 | Handler → Service → Repository 单向依赖 |
| 是否引入循环依赖 | Package A 依赖 Package B，Package B 不应再依赖 Package A | | 是否引入循环依赖 | 包间依赖不能成环 |
| 扩展点是否留好 | 协议驱动是否遵循 ProtocolDriver 接口而非直接调用具体实现 | | 扩展点是否留好 | 协议驱动是否遵循 ProtocolDriver 接口 |
| 新增模块的目录是否符第 2 节规范 | 按照约定的目录结构添加 |
| 是否重复造轮子 | 是否已经检索并复用项目既有能力、官方 SDK 或成熟依赖；自研是否有充分理由 |
#### 功能层面 #### 功能层面
| 检查项 | 说明 | | 检查项 | 说明 |
|--------|------| |--------|------|
| 业务规则是否覆盖 | 对照 spec 中的业务规则表（R001~R013, H001~H010）逐条确认 | | 边界条件是否处理 | 空列表、分页边界、超长输入、逻辑删除记录等 |
| 边界条件是否处理 | 空列表、分页边界、超长输入、字段缺失、逻辑删除记录等 |
| 并发安全 | 共享状态的读写是否有锁保护 | | 并发安全 | 共享状态的读写是否有锁保护 |
| 事务管理 | 跨表操作的 Service 方法是否使用了数据库事务 | | 事务管理 | 跨表操作的 Service 方法是否使用了数据库事务 |
| CSV 导入导出 | 编码是否为 UTF-8 with BOM，布尔值和 JSON 字段格式是否正确 |
| 写入流程完整性 | 是否执行了写入→回读验证→记录日志的完整流程 |
#### 性能层面 #### 性能层面
| 检查项 | 说明 | | 检查项 | 说明 |
|--------|------| |--------|------|
| N+1 查询 | 列表查询时是否 batch 加载关联数据，而非循环查询 | | N+1 查询 | 列表查询时是否 batch 加载关联数据 |
| 索引 | 新增查询条件是否添加了对应的数据库索引 | | 索引 | 新增查询条件是否添加了对应的数据库索引 |
| 分页 | 列表接口是否都有分页，且 page_size 有上限约束 | | 分页 | 列表接口是否都有分页，且 page_size 有上限约束 |
| 连接池 | 数据库和 PLC 连接是否使用了连接池而非每次新建 | | 连接池 | 数据库连接是否使用了连接池 |
| 迁移安全 | 结构变更是否可追踪、可验证；破坏性变更是否具备备份、回滚和发布兼容方案 |
| 采集周期最小限制 | collect_interval 是否校验 >= 1 秒 |
#### 安全层面 #### 安全层面
@@ -840,54 +627,23 @@ db.QueryContext(ctx, "SELECT id, name FROM devices WHERE name = $1", name)
|--------|------| |--------|------|
| SQL 注入 | 全库搜索字符串拼接的 SQL 语句 | | SQL 注入 | 全库搜索字符串拼接的 SQL 语句 |
| 参数校验 | 所有用户输入是否都通过了校验 | | 参数校验 | 所有用户输入是否都通过了校验 |
| 写入权限校验 | `write_enabled` 和 `write_source` 是否在 Service 层校验 | | 敏感信息泄露 | 错误信息是否直接返回给前端 |
| 敏感信息泄露 | 错误信息是否直接返回给前端（如数据库密码、SQL 错误） | | 路径穿越 | 文件操作的路径是否使用用户输入构造 |
| 路径穿越 | 文件操作的路径是否未使用用户输入构造 |
#### 前端层面 #### 前端层面
| 检查项 | 说明 | | 检查项 | 说明 |
|--------|------| |--------|------|
| API 路径 | 路径是否统一在 `src/api/` 中管理 | | API 路径 | 路径是否统一在 `src/api/` 中管理 |
| 组件拆分 | 是否合理拆分为可复用组件，而非单文件过长 | | 组件拆分 | 是否合理拆分为可复用组件 |
| 状态管理 | 跨组件共享状态是否使用 Pinia | | 状态管理 | 跨组件共享状态是否使用 Pinia |
| 响应式 | 图表容器是否自适应窗口变化 | | 错误处理 | API 调用是否有统一的错误处理 |
| 错误处理 | API 调用是否有统一的错误处理（如失败提示、加载状态） |
| 勾选上限 | 历史数据点位勾选是否有 20 个上限 |
--- ---
## 附录 A：模块间关系与命名约定 ## 附录 A：命名约定
### A.1 模块间依赖关系 ### A.1 Go 模型命名与数据库字段映射
```
数据管理模块（基础层）
├── 提供：设备配置、采集点配置、写入点配置
├── 提供：采集数据写入 TDengine
├── 依赖：PostgreSQL（配置）、TDengine（时序数据）
│
├── 历史数据模块（消费层）依赖数据管理模块
│ ├── 读取：采集点配置、设备配置
│ ├── 读取：TDengine 历史数据
│ └── 提供：历史数据查询、曲线/表格展示
│
├── 实时监控模块（待开发）依赖数据管理模块
│ ├── 读取：采集点配置、设备配置
│ ├── 读取：采集引擎内存中的最新值
│ └── 订阅：MQTT 实时数据通道
│
├── 智能控制模块（待开发）
│ ├── 依赖：数据管理模块（设备信息、写入点）
│ ├── 依赖：历史数据模块（AI 训练数据来源）
│ └── 操作：通过写入点对 PLC 下发控制指令
│
└── 系统配置模块（待开发）
├── 负责：全局参数管理，如历史保留天数、采集引擎参数
└── 被所有模块引用
```
### A.2 Go 模型命名与数据库字段映射
| 数据库表（snake_case） | Go 结构体（PascalCase） | 说明 | | 数据库表（snake_case） | Go 结构体（PascalCase） | 说明 |
|----------------------|-----------------------|------| |----------------------|-----------------------|------|
@@ -904,11 +660,9 @@ type Device struct {
Name string `json:"name" db:"name"` Name string `json:"name" db:"name"`
ProtocolType string `json:"protocol_type" db:"protocol_type"` ProtocolType string `json:"protocol_type" db:"protocol_type"`
Enabled bool `json:"enabled" db:"enabled"` Enabled bool `json:"enabled" db:"enabled"`
Deleted bool `json:"-" db:"deleted"` // 逻辑删除不返回前端 Deleted bool `json:"-" db:"deleted"` // json:"-" 不返回前端
Host string `json:"host" db:"host"` Host string `json:"host" db:"host"`
Port int `json:"port" db:"port"` Port int `json:"port" db:"port"`
ConnectTimeout int `json:"connect_timeout" db:"connect_timeout"`
ReconnectInterval int `json:"reconnect_interval" db:"reconnect_interval"`
ProtocolConfig json.RawMessage `json:"protocol_config" db:"protocol_config"` ProtocolConfig json.RawMessage `json:"protocol_config" db:"protocol_config"`
CreatedAt time.Time `json:"created_at" db:"created_at"` CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"` UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
@@ -920,29 +674,25 @@ type Device struct {
规则： 规则：
- `json:"-"` 标记的字段不返回前端（如 `deleted`） - `json:"-"` 标记的字段不返回前端（如 `deleted`）
- `omitempty` 用于可空字段 - `omitempty` 用于可空字段
- 请求体对应的结构体以 `Request` 结尾（如 `CreateDeviceRequest`） - 请求体结构体以 `Request` 结尾（如 `CreateDeviceRequest`）
- 响应体结构体在 Handler 层组装，不直接暴露模型
### A.3 前端目录与路由命名 ### A.2 前端目录与路由命名
| 页面 | 路由路径 | 目录 | 说明 | | 页面 | 路由路径 | 目录 |
|------|---------|------|------| |------|---------|------|
| 设备管理 | `/data/device` | `views/device/` | 数据管理子模块 | | 设备管理 | `/data/device` | `views/device/` |
| 数据采集 | `/data/collection` | `views/collection/` | 数据管理子模块 | | 数据采集 | `/data/collection` | `views/collection/` |
| 数据写入 | `/data/write-point` | `views/write-point/` | 数据管理子模块 | | 数据写入 | `/data/write-point` | `views/write-point/` |
| 历史数据 | `/history` | `views/history/` | 独立模块 | | 历史数据 | `/history` | `views/history/` |
| 实时监控 | `/monitoring` | `views/monitoring/` | 待开发 |
| 智能控制 | `/control` | `views/control/` | 待开发 |
| 系统配置 | `/settings` | `views/settings/` | 待开发 |
--- ---
> 本文档版本：v1.0 > 本文档版本：v1.1
> 最后更新：2026-07-10 > 最后更新：2026-07-11
> 适用范围：污水厂智能控制系统全部后端（Go）、前端（Vue 3）代码 > 适用范围：污水厂智能控制系统全部后端（Go）、前端（Vue 3）代码
> >
> **使用说明**： > **使用说明**：
> 1. 开发者开发新功能前阅读本文档，确保代码风格一致 > 1. 开发者开发新功能前阅读本文档，确保代码风格一致
> 2. 提交 MR/PR 前依据 [第 9 章 代码审核清单](#9-代码审核清单) 逐条自查 > 2. 提交 MR/PR 前依据 [第 9 章 代码审核清单](#9-代码审核清单) 逐条自查
> 3. Code Review 时以本文档作为审核标准，不符合规范的要求修改后重新提审 > 3. Code Review 时以本文档作为审核标准，不符合规范的要求修改后重新提审
> 4. 本文档随项目推进持续更新，新增模块时补充对应章节 > 4. 本文档随项目推进持续更新，新增模块时补充对应章节