279 lines
8.3 KiB
Plaintext
279 lines
8.3 KiB
Plaintext
|
syntax = "v1"
|
|||
|
|
|
|||
|
|
// demand-radar: contacts / touches / follow-ups / conversion / stats
|
|||
|
|
// spec: docs/product/demand-radar/spec.md §5.2
|
|||
|
|
// 未實作能力一律回 501（crmDomain.ErrNotReady），禁止 102000 空成功。
|
|||
|
|
// 命名紅線：不得以 lead 指稱銷售線索。
|
|||
|
|
|
|||
|
|
type (
|
|||
|
|
// ---------- Contact ----------
|
|||
|
|
ContactPublic {
|
|||
|
|
Id string `json:"id"`
|
|||
|
|
SourcePlatform string `json:"source_platform"`
|
|||
|
|
AuthorHandle string `json:"author_handle"`
|
|||
|
|
DisplayName string `json:"display_name,optional"`
|
|||
|
|
Stage string `json:"stage"` // new_found | engaged | dm_sent | replied | quoted | won | lost
|
|||
|
|
NeedsFollowUp bool `json:"needs_follow_up"`
|
|||
|
|
FollowUpDays int `json:"follow_up_days"`
|
|||
|
|
LastTouchAt int64 `json:"last_touch_at,optional"`
|
|||
|
|
OpportunityIds []string `json:"opportunity_ids"`
|
|||
|
|
OpportunityCount int `json:"opportunity_count"`
|
|||
|
|
MergedFrom []string `json:"merged_from,optional"`
|
|||
|
|
TopIntentBand string `json:"top_intent_band,optional"`
|
|||
|
|
TopIntentScore int `json:"top_intent_score,optional"`
|
|||
|
|
CreatedAt int64 `json:"created_at"`
|
|||
|
|
UpdatedAt int64 `json:"updated_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactBrief {
|
|||
|
|
Id string `json:"id"`
|
|||
|
|
SourcePlatform string `json:"source_platform"`
|
|||
|
|
AuthorHandle string `json:"author_handle"`
|
|||
|
|
DisplayName string `json:"display_name,optional"`
|
|||
|
|
Stage string `json:"stage"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// StageCount — 八格視圖用；stage 值另含 needs_follow_up（跨階段檢視，非階段值）
|
|||
|
|
StageCount {
|
|||
|
|
Stage string `json:"stage"`
|
|||
|
|
Count int `json:"count"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ListContactsReq {
|
|||
|
|
Page int `form:"page,default=1"`
|
|||
|
|
PageSize int `form:"pageSize,default=20"`
|
|||
|
|
Stage string `form:"stage,optional"`
|
|||
|
|
// FollowUp: true | false（留空＝不篩選）
|
|||
|
|
FollowUp string `form:"follow_up,optional"`
|
|||
|
|
Band string `form:"band,optional"`
|
|||
|
|
// Sort: last_touch_at | intent_score（預設 last_touch_at 倒序）
|
|||
|
|
Sort string `form:"sort,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactListData {
|
|||
|
|
List []ContactPublic `json:"list"`
|
|||
|
|
Pagination Pagination `json:"pagination"`
|
|||
|
|
StageCounts []StageCount `json:"stage_counts"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactTouchPublic {
|
|||
|
|
Id string `json:"id"`
|
|||
|
|
ContactId string `json:"contact_id"`
|
|||
|
|
Type string `json:"type"` // stage | reply | note | conversion
|
|||
|
|
FromStage string `json:"from_stage,optional"`
|
|||
|
|
ToStage string `json:"to_stage,optional"`
|
|||
|
|
Body string `json:"body,optional"`
|
|||
|
|
ActorUid int64 `json:"actor_uid"`
|
|||
|
|
CreatedAt int64 `json:"created_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactOpportunityBrief {
|
|||
|
|
Id string `json:"id"`
|
|||
|
|
Permalink string `json:"permalink"`
|
|||
|
|
Text string `json:"text"`
|
|||
|
|
IntentScore int `json:"intent_score"`
|
|||
|
|
IntentBand string `json:"intent_band"`
|
|||
|
|
CreatedAt int64 `json:"created_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
GetContactReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Page int `form:"page,default=1"`
|
|||
|
|
PageSize int `form:"pageSize,default=20"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactDetailData {
|
|||
|
|
Contact ContactPublic `json:"contact"`
|
|||
|
|
Touches []ContactTouchPublic `json:"touches"`
|
|||
|
|
Pagination Pagination `json:"pagination"`
|
|||
|
|
Opportunities []ContactOpportunityBrief `json:"opportunities"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ContactIdReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
UpdateContactStageReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Stage string `json:"stage"`
|
|||
|
|
Note string `json:"note,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
SetContactFollowUpReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
NeedsFollowUp bool `json:"needs_follow_up"`
|
|||
|
|
Days int `json:"days,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
CreateContactNoteReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Body string `json:"body"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
MergeContactReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
SourceContactId string `json:"source_contact_id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
UnmergeContactReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
MergedContactId string `json:"merged_contact_id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ---------- Conversion（寫既有 growth_outcomes，不另建成交帳） ----------
|
|||
|
|
CreateCrmConversionReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Amount float64 `json:"amount,optional"`
|
|||
|
|
Currency string `json:"currency,optional"`
|
|||
|
|
Note string `json:"note,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
UpdateCrmConversionReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Amount float64 `json:"amount,optional"`
|
|||
|
|
Currency string `json:"currency,optional"`
|
|||
|
|
Note string `json:"note,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
DeleteCrmConversionReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
CrmConversionData {
|
|||
|
|
ContactId string `json:"contact_id"`
|
|||
|
|
OutcomeId string `json:"outcome_id,optional"`
|
|||
|
|
Stage string `json:"stage"`
|
|||
|
|
Amount float64 `json:"amount,optional"`
|
|||
|
|
Currency string `json:"currency,optional"`
|
|||
|
|
Note string `json:"note,optional"`
|
|||
|
|
UpdatedAt int64 `json:"updated_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ---------- FollowUp ----------
|
|||
|
|
FollowUpPublic {
|
|||
|
|
Id string `json:"id"`
|
|||
|
|
ContactId string `json:"contact_id"`
|
|||
|
|
DueAt int64 `json:"due_at"`
|
|||
|
|
Status string `json:"status"` // scheduled | notified | done | snoozed | escalated
|
|||
|
|
NotifiedCount int `json:"notified_count"`
|
|||
|
|
Contact ContactBrief `json:"contact"`
|
|||
|
|
CreatedAt int64 `json:"created_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
ListFollowUpsReq {
|
|||
|
|
Page int `form:"page,default=1"`
|
|||
|
|
PageSize int `form:"pageSize,default=20"`
|
|||
|
|
Status string `form:"status,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
FollowUpListData {
|
|||
|
|
List []FollowUpPublic `json:"list"`
|
|||
|
|
Pagination Pagination `json:"pagination"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
FollowUpIdReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
SnoozeFollowUpReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
Days int `json:"days"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
GenerateFollowUpMessageReq {
|
|||
|
|
Id string `path:"id"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
GenerateFollowUpMessageData {
|
|||
|
|
Text string `json:"text"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ---------- Stats（樣本 < 5 只給絕對數） ----------
|
|||
|
|
TermConversionStat {
|
|||
|
|
Term string `json:"term"`
|
|||
|
|
Accepted int `json:"accepted"`
|
|||
|
|
Replied int `json:"replied"`
|
|||
|
|
Won int `json:"won"`
|
|||
|
|
ConversionRate float64 `json:"conversion_rate,optional"`
|
|||
|
|
InsufficientSample bool `json:"insufficient_sample"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
VariantConversionStat {
|
|||
|
|
Variant string `json:"variant"`
|
|||
|
|
Used int `json:"used"`
|
|||
|
|
Replied int `json:"replied"`
|
|||
|
|
Won int `json:"won"`
|
|||
|
|
SuccessRate float64 `json:"success_rate,optional"`
|
|||
|
|
InsufficientSample bool `json:"insufficient_sample"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
SourceConversionStat {
|
|||
|
|
Source string `json:"source"` // radar | scout | manual_import
|
|||
|
|
Won int `json:"won"`
|
|||
|
|
InsufficientSample bool `json:"insufficient_sample"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
CrmStatsReq {
|
|||
|
|
From int64 `form:"from,optional"`
|
|||
|
|
To int64 `form:"to,optional"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
CrmStatsData {
|
|||
|
|
Terms []TermConversionStat `json:"terms"`
|
|||
|
|
Variants []VariantConversionStat `json:"variants"`
|
|||
|
|
Sources []SourceConversionStat `json:"sources"`
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
@server (
|
|||
|
|
group: crm
|
|||
|
|
prefix: /api/v1/crm
|
|||
|
|
middleware: AuthJWT
|
|||
|
|
)
|
|||
|
|
service gateway {
|
|||
|
|
@handler ListContacts
|
|||
|
|
get /contacts (ListContactsReq) returns (ContactListData)
|
|||
|
|
|
|||
|
|
@handler GetContact
|
|||
|
|
get /contacts/:id (GetContactReq) returns (ContactDetailData)
|
|||
|
|
|
|||
|
|
@handler UpdateContactStage
|
|||
|
|
post /contacts/:id/stage (UpdateContactStageReq) returns (ContactPublic)
|
|||
|
|
|
|||
|
|
@handler SetContactFollowUp
|
|||
|
|
post /contacts/:id/follow-up (SetContactFollowUpReq) returns (ContactPublic)
|
|||
|
|
|
|||
|
|
@handler CreateContactNote
|
|||
|
|
post /contacts/:id/notes (CreateContactNoteReq) returns (ContactTouchPublic)
|
|||
|
|
|
|||
|
|
@handler MergeContact
|
|||
|
|
post /contacts/:id/merge (MergeContactReq) returns (ContactPublic)
|
|||
|
|
|
|||
|
|
@handler UnmergeContact
|
|||
|
|
post /contacts/:id/unmerge (UnmergeContactReq) returns (ContactPublic)
|
|||
|
|
|
|||
|
|
@handler CreateContactConversion
|
|||
|
|
post /contacts/:id/conversion (CreateCrmConversionReq) returns (CrmConversionData)
|
|||
|
|
|
|||
|
|
@handler UpdateContactConversion
|
|||
|
|
put /contacts/:id/conversion (UpdateCrmConversionReq) returns (CrmConversionData)
|
|||
|
|
|
|||
|
|
@handler DeleteContactConversion
|
|||
|
|
delete /contacts/:id/conversion (DeleteCrmConversionReq) returns (OkData)
|
|||
|
|
|
|||
|
|
@handler ListFollowUps
|
|||
|
|
get /followups (ListFollowUpsReq) returns (FollowUpListData)
|
|||
|
|
|
|||
|
|
@handler DoneFollowUp
|
|||
|
|
post /followups/:id/done (FollowUpIdReq) returns (FollowUpPublic)
|
|||
|
|
|
|||
|
|
@handler SnoozeFollowUp
|
|||
|
|
post /followups/:id/snooze (SnoozeFollowUpReq) returns (FollowUpPublic)
|
|||
|
|
|
|||
|
|
@handler GenerateFollowUpMessage
|
|||
|
|
post /followups/:id/message (GenerateFollowUpMessageReq) returns (GenerateFollowUpMessageData)
|
|||
|
|
|
|||
|
|
@handler GetCrmStats
|
|||
|
|
get /stats (CrmStatsReq) returns (CrmStatsData)
|
|||
|
|
}
|