182 lines
8.4 KiB
Markdown
182 lines
8.4 KiB
Markdown
# 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`，后续新增内容不要重新引入旧称。
|