# OPS 本地开发与验收部署说明

## 1. 文档目标

本文区分本地开发、联调验收和 Linux/麒麟部署三类场景，避免把模板 README 直接作为交付部署手册。

当前仓库尚未初始化 `server/` 和 `web/`。后续实际工程创建后，应在对应目录补充更细的运行说明。

## 2. 场景边界

| 场景 | 目标 | 主要使用者 | 命令口径 |
| --- | --- | --- | --- |
| 本地开发 | 开发、调试、单元测试、接口联调 | 开发工程师 | Windows PowerShell |
| 联调验收 | 连接真实后端 API，准备演示数据和证据 | 交付工程师、测试人员 | Windows PowerShell 为主 |
| 生产或验收部署 | 在 Linux/麒麟内网环境部署服务 | 部署工程师 | 本文只写步骤和检查项，不写 Linux 命令示例 |

## 3. 本地开发目录

| 目录 | 职责 | 状态 |
| --- | --- | --- |
| `server/` | 实际后端工程，基于 `templates/server_sample/` 初始化 | 尚未创建 |
| `web/` | 实际前端工程，基于 `templates/front_sample/standard` 初始化 | 尚未创建 |
| `deploy/` | 部署、迁移、回滚、烟测说明和配置示例 | 已规划 |
| `docs/` | 需求、架构、验收和测试文档 | 已存在 |

模板目录默认只读，不作为最终交付目录。

## 4. 初始化实际工程

后端初始化：

```powershell
Copy-Item -LiteralPath .\templates\server_sample -Destination .\server -Recurse
```

前端初始化：

```powershell
Copy-Item -LiteralPath .\templates\front_sample\standard -Destination .\web -Recurse
```

初始化后需要检查：

| 检查项 | 要求 |
| --- | --- |
| 配置示例 | 只提交 `etc/*.example.yaml` 或 `.env.example`，不提交真实密码。 |
| 目录结构 | 后端延续 `cmd/`、`internal/config/`、`internal/logic/`、`internal/models/`、`internal/routers/`。 |
| 前端结构 | API 放入 `src/api/`，页面放入 `src/views/`，状态放入 Pinia。 |
| 模板引用 | 业务代码不直接写回 `templates/`。 |

## 5. 本地后端开发

常用命令：

```powershell
Set-Location .\server
go mod tidy
go test ./...
go vet ./...
gofmt -w .
go run .\cmd\main\main.go
```

迁移命令按实际 CLI 保留：

```powershell
Set-Location .\server
go run .\cmd\cli\main.go migrate
```

后端本地配置要求：

| 配置 | 要求 |
| --- | --- |
| PostgreSQL | 本地可使用开发库；测试不能用 mock 数据库。 |
| SQLite 内存库 | 仅用于后端测试，验证真实 SQL 行为。 |
| 时序数据库 | 使用 TDengine 开源版；本地和验收环境均通过适配层配置连接信息，不在代码中写死地址或凭据。 |
| 通知渠道 | 本地使用测试账号或受控沙箱，不能提交真实凭据。 |
| traceId | 所有接口和任务日志必须可关联。 |

## 6. 本地前端开发

常用命令：

```powershell
Set-Location .\web
pnpm install
pnpm dev
pnpm type:check
pnpm lint
pnpm build
```

前端联调要求：

| 项目 | 要求 |
| --- | --- |
| API 地址 | 通过本地配置读取，不写死到组件中。 |
| 状态覆盖 | 页面按 `docs/首期UI状态覆盖.md` 实现。 |
| mock 数据 | 只用于独立调试，验收必须连接真实后端 API。 |
| 文案 | 按模板 i18n 方式维护，不在组件中散落重复字符串。 |

## 7. Linux/麒麟验收部署检查项

部署说明放入 `deploy/README.md`。验收前必须确认：

| 检查项 | 要求 |
| --- | --- |
| 操作系统 | 明确 Linux 或麒麟版本、CPU 架构、补丁状态。 |
| 运行用户 | 后端、前端静态服务、数据库、时序库使用独立低权限账号。 |
| 网络策略 | 明确 Web 端口、API 端口、数据库端口、Trap/Syslog 接收端口和防火墙策略。 |
| 数据库 | PostgreSQL 版本、初始化库、备份路径、恢复演练方式。 |
| 时序库 | 选定产品版本、部署形态、保留策略、备份恢复方式。 |
| 配置 | 只使用现场配置文件，不把真实凭据提交进仓库。 |
| 日志 | 应用日志、审计日志、采集日志、通知日志有保存周期。 |
| 回滚 | 后端二进制、前端静态包、数据库迁移均有回滚方案。 |
| 烟测 | 登录、资源列表、告警列表、通知记录、工单流转、报表查询可验证。 |

## 8. 验收材料目录

```text
验收证据/
  01-首页总览/
  02-资源监控/
  03-H3C网络设备/
  04-告警闭环/
  05-通知记录/
  06-工单闭环/
  07-报表大屏/
  08-权限审计/
  09-3D机房接口/
  10-部署与烟测/
```

证据目录不要求当前仓库立即创建。正式验收时应保存截图、录像、接口响应、日志和数据库查询结果。