ops/AGENTS.md

# AGENTS.md

## 基本要求

- 交流使用中文。
- 代码整洁、高效、易读，优先遵循现有目录结构和命名风格。
- 不使用 Linux 指令；需要命令示例时统一使用 Windows PowerShell。
- 修改前先阅读相关文档和现有代码，避免凭空新增不一致的结构。
- 不回滚或覆盖用户已有改动，除非用户明确要求。

## 项目定位

OPS 是“开发运维一体化平台”。首期交付重点是可验证的后端、前端和验收证据，而不是只停留在模板或文档层面。

统一命名：

- 项目名称统一使用 `OPS`。
- 旧称 `DOIP` 不再使用；新增文档、代码包名、页面文案、配置示例和注释不要再引入 `DOIP`。
- `OPS-001` 至 `OPS-033` 是需求编号，必须保留。

优先参考资料：

- `README.md`：项目一句话说明。
- `TODOS.md`：当前交付任务优先级。
- `docs/首期验收矩阵.md`：OPS 需求到演示路径、数据准备、通过标准和证据的映射。
- `docs/首期数据模型与状态机.md`：第 1 阶段核心模型、状态机和存储分工。
- `docs/首期UI状态覆盖.md`：第 1 阶段页面状态覆盖要求。
- `docs/P1故障救援策略.md`：采集、解析、通知、派单失败的救援策略。
- `docs/P1测试计划.md`：第 1 阶段后端、前端和端到端测试计划。
- `docs/国产时序数据库选型验证.md`：TDengine 开源版选型结论和适配层要求。

当前决策：

- P0 和 P1 文档任务已完成，后续重点应转向可运行的 `server/`、`web/` 和验收证据。
- 时序数据库采用 TDengine 开源版。正式部署前仍需验证 AGPL 合规、麒麟兼容性、备份恢复和是否需要企业版支持。
- 第 1 阶段优先打通资源纳管、采集、原始事件、告警、通知、工单、报表/大屏和审计闭环。
- H3C/华三为首批网络设备适配重点，但具体型号、SNMP 版本、Trap/Syslog 样例和账号权限必须由现场确认，不能凭空编写。
- 3D 机房前端已外包，OPS 侧只提供后端接口、样例数据、权限控制和告警状态。

## 目录职责

- `docs/`：项目需求、架构、验收和计划文档。默认可读可改；改动需保持内容严谨，不做无关润色。
- `templates/front_sample/standard`：前端模板，基于 Arco Design Pro Vue 3、Vite、Pinia、TypeScript。默认只读。
- `templates/server_sample/`：后端模板，基于 Go、Gin、GORM、BSM-SDK Core。默认只读。
- `web/`：实际前端工程目录。不存在时，按任务需要从 `templates/front_sample/standard` 初始化后再开发。
- `server/`：实际后端工程目录。不存在时，按任务需要从 `templates/server_sample/` 初始化后再开发。
- `deploy/`：部署、迁移、发布脚本目录。不存在时按 TODO 创建。

## 边界规则

- 未经用户明确要求，绝不直接修改 `templates/front_sample/standard`。
- 未经用户明确要求，绝不直接修改 `templates/server_sample/`。
- 不把模板目录当作最终交付目录；实际业务代码应落在 `web/`、`server/`、`deploy/` 等交付目录。
- 不提交真实密钥、Token、数据库密码、私有仓库凭据或带凭据的 remote URL。
- 配置文件提供 `.example` 示例，真实本地配置不应纳入版本控制。
- 不引入与当前技术栈无关的大型框架或重构，除非任务明确要求。

## 常用 Windows PowerShell 命令

查看目录：

```powershell
Get-ChildItem -Force
```

查看文件：

```powershell
Get-Content -LiteralPath .\README.md -Encoding UTF8
```

复制模板初始化实际工程：

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

后端常用命令：

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

前端常用命令：

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

Git 状态检查：

```powershell
git status --short
git diff -- .\AGENTS.md
```

检查旧项目名残留：

```powershell
Select-String -Path .\README.md,.\TODOS.md,.\AGENTS.md,.\docs\*.md,.\deploy\README.md -Encoding UTF8 -Pattern 'DOIP','doip'
```

## 后端规范

- 使用 Go、Gin、GORM，延续 `templates/server_sample/` 的分层：`cmd/`、`internal/config/`、`internal/impl/`、`internal/logic/`、`internal/models/`、`internal/routers/`。
- API 需要统一响应结构、统一错误码和 `traceId`。
- 数据库设计优先面向 PostgreSQL，不继续扩散 MySQL 风格类型。
- 时序数据进入 TDengine 开源版；业务代码必须通过时序库适配层访问，不直接在业务逻辑中散落 TDengine 专有 SQL。
- 危险操作必须有审计日志、人工确认或可恢复方案。
- 配置通过 `etc/*.example.yaml` 描述结构，不把本地真实配置提交进仓库。
- 业务逻辑应写在 `internal/logic/`，模型和持久化写在 `internal/models/`，路由注册写在 `internal/routers/`。
- 首期核心模型优先落地资源、指标定义、采集任务、原始事件、告警、通知、工单、审计。
- 采集失败、Trap/Syslog 解析失败、通知失败、派单失败必须有错误码、重试或降级、用户提示、日志和审计。
- 告警、事件、工单状态机必须在后端集中定义和校验，前端不能自行拼接非法状态。

## 前端规范

- 使用 Vue 3、TypeScript、Pinia、Vue Router、Arco Design Vue，延续模板现有风格。
- 页面优先实现真实可用流程，不新增纯展示型占位页。
- API 定义按业务域放入 `src/api/`，页面放入 `src/views/`，复用组件放入 `src/components/`。
- 状态需要覆盖 loading、empty、error、success、partial、forbidden、stale、operating、operation_failed。
- 开发期 mock 只能用于前端独立调试；验收和联调必须连接真实后端 API。
- 文案和菜单要按模板 i18n 方式维护，不在组件中散落重复字符串。
- 首页、大屏、报表不能使用静态假数据作为验收依据；暂未接通真实接口时要明确显示空态、错误或数据过期。
- 错误状态必须显示 `traceId`，便于从页面追到后端日志。

## 测试规范

- 禁止 mock 数据库；后端测试必须使用真实 SQLite 内存库或任务指定的真实测试数据库。
- 新增核心业务逻辑时补充对应单元测试或接口测试。
- 状态机、统一响应、错误救援、权限边界和审计记录属于必须测试范围。
- TDengine 适配层至少要覆盖批量写入、时间范围查询、聚合查询、保留策略校验和不可用降级。
- 后端改动至少运行：

```powershell
go test ./...
go vet ./...
```

- 前端改动至少运行：

```powershell
pnpm type:check
pnpm lint
pnpm build
```

- 如果因私有依赖、网络、凭据或环境限制无法运行测试，需要在交付说明中明确写出原因和风险。

## 文档规范

- 文档使用中文，标题层级清晰，避免空泛描述。
- 修改需求、架构或验收相关内容时，同步检查 `TODOS.md` 和 `docs/首期验收矩阵.md` 是否需要更新。
- 新增命令示例必须使用 Windows PowerShell，不写 Bash、`cp`、`rm -rf`、`export` 等 Linux 写法。
- 文档中的路径使用项目相对路径，例如 `server/etc/app.example.yaml`。
- 涉及部署 Linux/麒麟时，可以写执行步骤、配置项和检查点，但命令示例仍保持 Windows PowerShell。
- 现场未知信息必须标为“待现场确认”，不要伪造设备型号、账号、OID、Trap/Syslog 样例、短信平台参数或生产地址。
- 修改 OPS 命名、时序数据库选型、H3C 接入、验收矩阵相关内容时，要同步检查 README、TODOS、首期验收矩阵和相关 P1 文档。



## 已知坑

- `templates/front_sample/standard` 和 `templates/server_sample/` 是模板目录，不是最终交付目录。
- 测试不能用 mock 数据库替代真实数据库行为。
- 当前仓库存在私有 Go 依赖，执行 `go mod tidy`、`go test` 可能需要私有仓库访问权限。
- 处理中文文档时使用 UTF-8 读取和写入，避免产生乱码。
- TDengine 开源版无时间使用限制，但 AGPL-3.0 合规和麒麟目标版本支持需要正式确认。
- 旧项目名 `DOIP` 已替换为 `OPS`，后续新增内容不要重新引入旧称。