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 命令

查看目录：

Get-ChildItem -Force

查看文件：

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

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

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

后端常用命令：

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

前端常用命令：

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

Git 状态检查：

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

检查旧项目名残留：

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 适配层至少要覆盖批量写入、时间范围查询、聚合查询、保留策略校验和不可用降级。
• 后端改动至少运行：

go test ./...
go vet ./...

• 前端改动至少运行：

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，后续新增内容不要重新引入旧称。