Proto Schema

Argus 用 protobuf 描述所有 message / service。proto 是單一事實來源：

• backend Go：backend/generated-go/（由 buf generate 產出）
• frontend TS：frontend/src/types/proto-es/（由 buf generate 產出）
• API 文件：proto/gen/grpc-doc/（由 buf generate 產出）

套件

套件	路徑	穩定性	用途
argus.v1	proto/v1/v1/*.proto	stable	對外 API（HTTP / gRPC / connectrpc）
argus.store	proto/store/store/*.proto	internal	JSONB 儲存格式（metastore 內部）
argus.internal.v1	proto/internal/v1/*.proto	internal	公司內部模組（risk-rule 等）

自動產生文件

內容	路徑（docs-site）
argus.v1 services / messages / enums	api-v1
argus.store JSONB payloads	proto-store
OpenAPI 3.1 spec	openapi.yaml

來源：proto/gen/grpc-doc/。更新由 docs-site/scripts/sync-api-docs.sh 從 source 同步。

命名規範

• 服務 <Resource>Service（IssueService、PlanService）
• RPC 動詞：Get / List / Search / Create / Update / Delete / Batch* / 自訂動詞（如 ApproveIssue）
• 列舉值：HELLO 不是 TYPE_HELLO（依 AIP）
• Resource name 模式：projects/{project}/issues/{issue} 之類，由 google.api.resource_definition 宣告

開發者工具

# 1. 編輯 .proto
$EDITOR proto/v1/v1/issue_service.proto

# 2. 格式化 + lint
buf format -w proto
buf lint proto

# 3. 生成
cd proto && buf generate

# 4. 同步到 docs-site
docs-site/scripts/sync-api-docs.sh

CI 也會跑 buf breaking 比對 main，破壞性變更會被擋。

穩定性承諾

argus.v1 規則

• ✅ 新增 RPC / message / 欄位 — 允許
• ✅ 標 deprecated — 允許，至少保留一個 release
• ❌ 直接刪除（未先 deprecate） — 禁止
• ❌ 改欄位語意（同名欄位含義變了） — 禁止；改名字
• ❌ 改欄位編號 — 禁止（protobuf wire 不相容）

argus.store 規則

• 視同 internal；任何變更可能在 minor release 發生
• 由 server 端自動 migration 處理欄位演進（reserved field number / 預設值轉換）
• 不要讓外部系統直接讀 argus.store JSONB；走 argus.v1 對外端點

argus.internal.v1 規則

• 同 argus.store，視同 internal
• 設計上只給 Argus server 自己 + 公司內部 module（如 risk-rule）用

在哪裡讀完整定義

1. 直接讀 proto 檔（最新 source of truth）：proto/v1/v1/*.proto
2. 讀自動產生 reference：api-v1 / proto-store
3. 從 OpenAPI 3.1 出發：openapi.yaml

相關

• REST / gRPC API
• Settings
• 錯誤碼