thread-master/docs/product/opportunity-inbox/tasks/T800-radar-inbox-contract-goctl.md

T800 — radar inbox contract goctl

Status: done Milestone: M0 Est. change: ~180 lines

Goal

完成後系統有 ReviewState、DemandMap、CostPreview、列表排序與 Sweep funnel 的 goctl API 契約，且未實作能力會明確回 not-ready。

Depends on

• —

Inputs

• apps/backend/generate/api/radar.api
• Spec §7.1–§7.3、§7.6
• 既有 brand-product-radar API 與 demand-radar envelope／pagination 契約

Outputs

程式變更（預期路徑）

路徑	動作	說明
apps/backend/generate/api/radar.api	edit	增加 review state、DemandMap、CostPreview、排序與 sweep 欄位
apps/backend/internal/handler/**	generated	由 make gen-api 產生，不手寫
apps/backend/internal/types/**	generated/edit	對齊新 request／response

行為變更

• 新契約保留舊 today、accept、dismiss 路徑與舊 sort 相容映射。

API / 契約（若有）

• 列表維持 page/pageSize → pagination/list；時間為 UTC unix ns；成功碼維持 102000。

Out of scope

• 不寫 ReviewState repository、worker、DemandMap 業務。
• 不手改 generated handler／routes。

Acceptance

• radar.api 可被 goctl 解析，欄位 optional 語意正確。
• 未實作 endpoint 的 logic 不回 102000 空資料。
• 指令：

cd apps/backend && make gen-api && go test ./internal/types/... ./internal/handler/... -count=1

Notes

先從現有 API 合併欄位，避免建立第二個 Opportunity response。