407 lines
14 KiB
Plaintext
407 lines
14 KiB
Plaintext
syntax = "v1"
|
||
|
||
// demand-radar: service profile / radar watches / sweeps / opportunities / replies
|
||
// spec: docs/product/demand-radar/spec.md §5.2
|
||
// 未實作能力一律回 501（radarDomain.ErrNotReady），禁止 102000 空成功。
|
||
|
||
type (
|
||
// ---------- ServiceProfile ----------
|
||
ServiceItem {
|
||
Name string `json:"name"`
|
||
PriceMin float64 `json:"price_min,optional"`
|
||
PriceMax float64 `json:"price_max,optional"`
|
||
Currency string `json:"currency,optional"`
|
||
}
|
||
|
||
ServiceCasePublic {
|
||
Title string `json:"title"`
|
||
Summary string `json:"summary,optional"`
|
||
Link string `json:"link,optional"`
|
||
}
|
||
|
||
FaqItem {
|
||
Question string `json:"question"`
|
||
Answer string `json:"answer"`
|
||
}
|
||
|
||
ServiceProfilePublic {
|
||
Exists bool `json:"exists"`
|
||
Services []ServiceItem `json:"services"`
|
||
Cases []ServiceCasePublic `json:"cases"`
|
||
Forbidden []string `json:"forbidden"`
|
||
Faq []FaqItem `json:"faq"`
|
||
ServiceAreas []string `json:"service_areas"`
|
||
RemoteOk bool `json:"remote_ok"`
|
||
Availability string `json:"availability,optional"`
|
||
ToneNote string `json:"tone_note,optional"`
|
||
UpdatedAt int64 `json:"updated_at,optional"`
|
||
}
|
||
|
||
UpsertServiceProfileReq {
|
||
Services []ServiceItem `json:"services"`
|
||
Cases []ServiceCasePublic `json:"cases,optional"`
|
||
Forbidden []string `json:"forbidden,optional"`
|
||
Faq []FaqItem `json:"faq,optional"`
|
||
ServiceAreas []string `json:"service_areas,optional"`
|
||
RemoteOk bool `json:"remote_ok,optional"`
|
||
Availability string `json:"availability,optional"`
|
||
ToneNote string `json:"tone_note,optional"`
|
||
}
|
||
|
||
// ---------- RadarWatch ----------
|
||
RadarWatchPublic {
|
||
Id string `json:"id"`
|
||
Terms []string `json:"terms"`
|
||
ExcludeTerms []string `json:"exclude_terms"`
|
||
Regions []string `json:"regions"`
|
||
Status string `json:"status"` // active | paused | archived
|
||
LastSweptAt int64 `json:"last_swept_at,optional"`
|
||
CreatedAt int64 `json:"created_at"`
|
||
UpdatedAt int64 `json:"updated_at"`
|
||
// 只在建立當下這是使用者第一組訂閱、且已排入首巡時為 true；不是持久狀態，僅供前端顯示一次性提示。
|
||
FirstSweepTriggered bool `json:"first_sweep_triggered,optional"`
|
||
}
|
||
|
||
ListWatchesReq {
|
||
Page int `form:"page,default=1"`
|
||
PageSize int `form:"pageSize,default=20"`
|
||
Status string `form:"status,optional"`
|
||
}
|
||
|
||
WatchListData {
|
||
List []RadarWatchPublic `json:"list"`
|
||
Pagination Pagination `json:"pagination"`
|
||
ActiveCount int `json:"active_count"`
|
||
MaxActive int `json:"max_active"`
|
||
ProfileExists bool `json:"profile_exists"`
|
||
}
|
||
|
||
CreateWatchReq {
|
||
Terms []string `json:"terms"`
|
||
ExcludeTerms []string `json:"exclude_terms,optional"`
|
||
Regions []string `json:"regions,optional"`
|
||
Enabled bool `json:"enabled,optional"`
|
||
}
|
||
|
||
UpdateWatchReq {
|
||
Id string `path:"id"`
|
||
Terms []string `json:"terms,optional"`
|
||
ExcludeTerms []string `json:"exclude_terms,optional"`
|
||
Regions []string `json:"regions,optional"`
|
||
}
|
||
|
||
WatchIdReq {
|
||
Id string `path:"id"`
|
||
}
|
||
|
||
SuggestWatchTermsReq {
|
||
Limit int `json:"limit,optional"`
|
||
}
|
||
|
||
WatchTermSuggestion {
|
||
Term string `json:"term"`
|
||
Reason string `json:"reason"`
|
||
Usage string `json:"usage"` // include | exclude
|
||
}
|
||
|
||
WatchSuggestData {
|
||
List []WatchTermSuggestion `json:"list"`
|
||
}
|
||
|
||
TriggerSweepData {
|
||
JobId string `json:"job_id"`
|
||
SweepId string `json:"sweep_id,optional"`
|
||
}
|
||
|
||
// ---------- Opportunity ----------
|
||
OpportunityReason {
|
||
Dimension string `json:"dimension"` // authenticity | intent | region | freshness | fit
|
||
Score int `json:"score"`
|
||
Reason string `json:"reason"`
|
||
}
|
||
|
||
OpportunityOverride {
|
||
FromBand string `json:"from_band,optional"`
|
||
ToBand string `json:"to_band,optional"`
|
||
FromStatus string `json:"from_status,optional"`
|
||
ToStatus string `json:"to_status,optional"`
|
||
ActorUid int64 `json:"actor_uid"`
|
||
At int64 `json:"at"`
|
||
}
|
||
|
||
OpportunityPublic {
|
||
Id string `json:"id"`
|
||
WatchId string `json:"watch_id,optional"`
|
||
Source string `json:"source"` // threads | manual | scout_promote
|
||
SourceScoutPostId string `json:"source_scout_post_id,optional"`
|
||
ExternalId string `json:"external_id"`
|
||
Permalink string `json:"permalink"`
|
||
AuthorHandle string `json:"author_handle"`
|
||
Text string `json:"text"`
|
||
PostedAt int64 `json:"posted_at"`
|
||
Status string `json:"status"` // judging | qualified | rejected | accepted | dismissed
|
||
IntentScore int `json:"intent_score"`
|
||
IntentBand string `json:"intent_band"` // high | mid | low
|
||
Reasons []OpportunityReason `json:"reasons"`
|
||
RegionDetected string `json:"region_detected,optional"`
|
||
RegionMatch string `json:"region_match"` // match | mismatch | unknown
|
||
FreshnessHours int `json:"freshness_hours"`
|
||
MatchedService string `json:"matched_service,optional"`
|
||
MatchedTerms []string `json:"matched_terms"`
|
||
RejectReason string `json:"reject_reason,optional"`
|
||
Override *OpportunityOverride `json:"override,optional"`
|
||
ContactId string `json:"contact_id,optional"`
|
||
DefaultReply *ReplyVariantPublic `json:"default_reply,optional"`
|
||
CreatedAt int64 `json:"created_at"`
|
||
}
|
||
|
||
RadarTodayStats {
|
||
Total int `json:"total"`
|
||
High int `json:"high"`
|
||
Mid int `json:"mid"`
|
||
Low int `json:"low"`
|
||
}
|
||
|
||
RadarTodayData {
|
||
Stats RadarTodayStats `json:"stats"`
|
||
High []OpportunityPublic `json:"high"`
|
||
Mid []OpportunityPublic `json:"mid"`
|
||
Low []OpportunityPublic `json:"low"`
|
||
TruncatedCount int `json:"truncated_count"`
|
||
LastSweptAt int64 `json:"last_swept_at,optional"`
|
||
// EmptyReason: not_swept_yet | all_watches_paused | no_watch | no_profile | sweep_failed | no_hit
|
||
EmptyReason string `json:"empty_reason,optional"`
|
||
EmptyHint string `json:"empty_hint,optional"`
|
||
}
|
||
|
||
ListOpportunitiesReq {
|
||
Page int `form:"page,default=1"`
|
||
PageSize int `form:"pageSize,default=20"`
|
||
Band string `form:"band,optional"`
|
||
Status string `form:"status,optional"`
|
||
WatchId string `form:"watch_id,optional"`
|
||
From int64 `form:"from,optional"`
|
||
To int64 `form:"to,optional"`
|
||
}
|
||
|
||
OpportunityListData {
|
||
List []OpportunityPublic `json:"list"`
|
||
Pagination Pagination `json:"pagination"`
|
||
}
|
||
|
||
OpportunityIdReq {
|
||
Id string `path:"id"`
|
||
}
|
||
|
||
AcceptOpportunityReq {
|
||
Id string `path:"id"`
|
||
}
|
||
|
||
AcceptOpportunityData {
|
||
OpportunityId string `json:"opportunity_id"`
|
||
ContactId string `json:"contact_id,optional"`
|
||
Status string `json:"status"`
|
||
}
|
||
|
||
DismissOpportunityReq {
|
||
Id string `path:"id"`
|
||
Reason string `json:"reason,optional"`
|
||
}
|
||
|
||
OverrideOpportunityReq {
|
||
Id string `path:"id"`
|
||
Band string `json:"band,optional"`
|
||
Status string `json:"status,optional"`
|
||
Note string `json:"note,optional"`
|
||
}
|
||
|
||
// ---------- ReplyVariant ----------
|
||
ReplyVariantPublic {
|
||
Id string `json:"id"`
|
||
OpportunityId string `json:"opportunity_id"`
|
||
Variant string `json:"variant"` // public_comment | dm | no_sales | professional | humorous
|
||
Text string `json:"text"`
|
||
UsedAt int64 `json:"used_at,optional"`
|
||
SentChannel string `json:"sent_channel,optional"` // outbox | manual_copy
|
||
// 只在 sent_channel=outbox 且真的排入既有 Outbox 佇列時才有值。
|
||
OutboxId string `json:"outbox_id,optional"`
|
||
CreatedAt int64 `json:"created_at"`
|
||
}
|
||
|
||
ListRepliesReq {
|
||
Id string `path:"id"`
|
||
}
|
||
|
||
ReplyListData {
|
||
List []ReplyVariantPublic `json:"list"`
|
||
}
|
||
|
||
CreateReplyReq {
|
||
Id string `path:"id"`
|
||
Variant string `json:"variant"`
|
||
}
|
||
|
||
// MarkReplyUsedReq: channel=outbox|manual_copy（dm 僅 manual_copy）
|
||
MarkReplyUsedReq {
|
||
Id string `path:"id"`
|
||
ReplyId string `path:"replyId"`
|
||
Channel string `json:"channel"` // outbox | manual_copy
|
||
// channel=outbox 時必填：要用哪個 Threads 帳號送出。
|
||
AccountId string `json:"account_id,optional"`
|
||
}
|
||
|
||
MarkReplyUsedData {
|
||
Reply ReplyVariantPublic `json:"reply"`
|
||
HealthAdvice string `json:"health_advice,optional"`
|
||
}
|
||
|
||
// ---------- RadarSweep ----------
|
||
RadarSweepPublic {
|
||
Id string `json:"id"`
|
||
WatchId string `json:"watch_id"`
|
||
JobId string `json:"job_id,optional"`
|
||
Path string `json:"path"` // api | crawler
|
||
HitCount int `json:"hit_count"`
|
||
JudgedCount int `json:"judged_count"`
|
||
CreatedCount int `json:"created_count"`
|
||
TruncatedCount int `json:"truncated_count"`
|
||
FailedReason string `json:"failed_reason,optional"`
|
||
CreditsUsed int `json:"credits_used"`
|
||
StartedAt int64 `json:"started_at"`
|
||
EndedAt int64 `json:"ended_at,optional"`
|
||
}
|
||
|
||
ListSweepsReq {
|
||
Page int `form:"page,default=1"`
|
||
PageSize int `form:"pageSize,default=20"`
|
||
WatchId string `form:"watch_id,optional"`
|
||
From int64 `form:"from,optional"`
|
||
To int64 `form:"to,optional"`
|
||
}
|
||
|
||
SweepListData {
|
||
List []RadarSweepPublic `json:"list"`
|
||
Pagination Pagination `json:"pagination"`
|
||
}
|
||
|
||
// ---------- Manual Import（P1：不承諾全平台自動抓取的合規補位） ----------
|
||
ImportOpportunityItem {
|
||
Url string `json:"url"`
|
||
// 貼文內文；沒有官方 API／爬蟲可讀任意網址，判定一律吃使用者貼上的文字。
|
||
Text string `json:"text"`
|
||
// 缺省時從 threads 網址猜 @handle，猜不到就留空。
|
||
Author string `json:"author,optional"`
|
||
// unix nanoseconds UTC；缺省用匯入當下時間（新鮮度以匯入時間計）。
|
||
PostedAt int64 `json:"posted_at,optional"`
|
||
}
|
||
|
||
ImportOpportunitiesReq {
|
||
Items []ImportOpportunityItem `json:"items"`
|
||
}
|
||
|
||
ImportedOpportunityResult {
|
||
Url string `json:"url"`
|
||
OpportunityId string `json:"opportunity_id,optional"`
|
||
Status string `json:"status"` // qualified | rejected | skipped | failed
|
||
IntentBand string `json:"intent_band,optional"`
|
||
IntentScore int `json:"intent_score,optional"`
|
||
// skipped／failed 時的人話原因；qualified／rejected 時通常留空。
|
||
Error string `json:"error,optional"`
|
||
}
|
||
|
||
ImportOpportunitiesData {
|
||
Results []ImportedOpportunityResult `json:"results"`
|
||
}
|
||
|
||
// ---------- Explore（商機頁立即探索：短詞 fan-out → 五問判定） ----------
|
||
ExploreOpportunitiesReq {
|
||
// 1–6 組 Threads 短詞（契約 A）；不合規整組擋下，不默默修正。
|
||
Terms []string `json:"terms"`
|
||
}
|
||
|
||
ExploreOpportunitiesData {
|
||
SweepId string `json:"sweep_id"`
|
||
HitCount int `json:"hit_count"`
|
||
JudgedCount int `json:"judged_count"`
|
||
CreatedCount int `json:"created_count"`
|
||
TruncatedCount int `json:"truncated_count"`
|
||
CreditsUsed int `json:"credits_used"`
|
||
}
|
||
)
|
||
|
||
@server (
|
||
group: radar
|
||
prefix: /api/v1/radar
|
||
middleware: AuthJWT
|
||
)
|
||
service gateway {
|
||
@handler GetServiceProfile
|
||
get /service-profile returns (ServiceProfilePublic)
|
||
|
||
@handler UpsertServiceProfile
|
||
put /service-profile (UpsertServiceProfileReq) returns (ServiceProfilePublic)
|
||
|
||
@handler ListWatches
|
||
get /watches (ListWatchesReq) returns (WatchListData)
|
||
|
||
@handler CreateWatch
|
||
post /watches (CreateWatchReq) returns (RadarWatchPublic)
|
||
|
||
@handler SuggestWatchTerms
|
||
post /watches/suggest (SuggestWatchTermsReq) returns (WatchSuggestData)
|
||
|
||
@handler GetWatch
|
||
get /watches/:id (WatchIdReq) returns (RadarWatchPublic)
|
||
|
||
@handler UpdateWatch
|
||
put /watches/:id (UpdateWatchReq) returns (RadarWatchPublic)
|
||
|
||
@handler ArchiveWatch
|
||
delete /watches/:id (WatchIdReq) returns (OkData)
|
||
|
||
@handler PauseWatch
|
||
post /watches/:id/pause (WatchIdReq) returns (RadarWatchPublic)
|
||
|
||
@handler ResumeWatch
|
||
post /watches/:id/resume (WatchIdReq) returns (RadarWatchPublic)
|
||
|
||
@handler TriggerWatchSweep
|
||
post /watches/:id/sweep (WatchIdReq) returns (TriggerSweepData)
|
||
|
||
@handler GetRadarToday
|
||
get /today returns (RadarTodayData)
|
||
|
||
@handler ListOpportunities
|
||
get /opportunities (ListOpportunitiesReq) returns (OpportunityListData)
|
||
|
||
@handler GetOpportunity
|
||
get /opportunities/:id (OpportunityIdReq) returns (OpportunityPublic)
|
||
|
||
@handler AcceptOpportunity
|
||
post /opportunities/:id/accept (AcceptOpportunityReq) returns (AcceptOpportunityData)
|
||
|
||
@handler DismissOpportunity
|
||
post /opportunities/:id/dismiss (DismissOpportunityReq) returns (OpportunityPublic)
|
||
|
||
@handler OverrideOpportunity
|
||
post /opportunities/:id/override (OverrideOpportunityReq) returns (OpportunityPublic)
|
||
|
||
@handler ListOpportunityReplies
|
||
get /opportunities/:id/replies (ListRepliesReq) returns (ReplyListData)
|
||
|
||
@handler CreateOpportunityReply
|
||
post /opportunities/:id/replies (CreateReplyReq) returns (ReplyVariantPublic)
|
||
|
||
@handler MarkOpportunityReplyUsed
|
||
post /opportunities/:id/replies/:replyId/mark-used (MarkReplyUsedReq) returns (MarkReplyUsedData)
|
||
|
||
@handler ListSweeps
|
||
get /sweeps (ListSweepsReq) returns (SweepListData)
|
||
|
||
@handler ImportOpportunities
|
||
post /import (ImportOpportunitiesReq) returns (ImportOpportunitiesData)
|
||
|
||
@handler ExploreOpportunities
|
||
post /explore (ExploreOpportunitiesReq) returns (ExploreOpportunitiesData)
|
||
}
|