328 lines
10 KiB
Go
328 lines
10 KiB
Go
|
package domain
|
|||
|
|
|
|||
|
|
import (
|
|||
|
|
"fmt"
|
|||
|
|
"strings"
|
|||
|
|
"time"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Opportunity status — spec §3.2.
|
|||
|
|
const (
|
|||
|
|
OppJudging = "judging"
|
|||
|
|
OppQualified = "qualified"
|
|||
|
|
OppRejected = "rejected"
|
|||
|
|
OppAccepted = "accepted"
|
|||
|
|
OppDismissed = "dismissed"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Intent band thresholds are locked by spec §3.3 (80 / 50). Do not change here.
|
|||
|
|
const (
|
|||
|
|
BandHigh = "high"
|
|||
|
|
BandMid = "mid"
|
|||
|
|
BandLow = "low"
|
|||
|
|
|
|||
|
|
BandHighMinScore = 80
|
|||
|
|
BandMidMinScore = 50
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Region match is three-state; unknown is not mismatch (OP-04).
|
|||
|
|
const (
|
|||
|
|
RegionMatch = "match"
|
|||
|
|
RegionMismatch = "mismatch"
|
|||
|
|
RegionUnknown = "unknown"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Opportunity sources.
|
|||
|
|
const (
|
|||
|
|
OppSourceThreads = "threads"
|
|||
|
|
OppSourceManual = "manual"
|
|||
|
|
OppSourceScoutPromote = "scout_promote"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// Five judge dimensions — reasons[] must include every one (OP-06).
|
|||
|
|
const (
|
|||
|
|
DimAuthenticity = "authenticity"
|
|||
|
|
DimIntent = "intent"
|
|||
|
|
DimRegion = "region"
|
|||
|
|
DimFreshness = "freshness"
|
|||
|
|
DimFit = "fit"
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
// RequiredReasonDimensions is the fixed set that must all be present to persist.
|
|||
|
|
var RequiredReasonDimensions = []string{
|
|||
|
|
DimAuthenticity,
|
|||
|
|
DimIntent,
|
|||
|
|
DimRegion,
|
|||
|
|
DimFreshness,
|
|||
|
|
DimFit,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// OpportunityReason is one scored dimension of the five-question judge.
|
|||
|
|
type OpportunityReason struct {
|
|||
|
|
Dimension string `bson:"dimension" json:"dimension"`
|
|||
|
|
Score int `bson:"score" json:"score"`
|
|||
|
|
Reason string `bson:"reason" json:"reason"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// OpportunityOverride records a human band/status correction for later calibration.
|
|||
|
|
type OpportunityOverride struct {
|
|||
|
|
FromBand string `bson:"from_band,omitempty" json:"from_band,omitempty"`
|
|||
|
|
ToBand string `bson:"to_band,omitempty" json:"to_band,omitempty"`
|
|||
|
|
FromStatus string `bson:"from_status,omitempty" json:"from_status,omitempty"`
|
|||
|
|
ToStatus string `bson:"to_status,omitempty" json:"to_status,omitempty"`
|
|||
|
|
ActorUID int64 `bson:"actor_uid" json:"actor_uid"`
|
|||
|
|
At int64 `bson:"at" json:"at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/*
|
|||
|
|
Opportunity 是經五問判定後的商機。
|
|||
|
|
|
|||
|
|
同一 owner 下 external_id 唯一：跨 watch 命中同一貼文只留一筆，新觸發 term
|
|||
|
|
併入 matched_terms，不重跑判定（SW-06）。
|
|||
|
|
*/
|
|||
|
|
type Opportunity struct {
|
|||
|
|
ID string `bson:"_id" json:"id"`
|
|||
|
|
OwnerUID int64 `bson:"owner_uid" json:"owner_uid"`
|
|||
|
|
WatchID string `bson:"watch_id,omitempty" json:"watch_id,omitempty"`
|
|||
|
|
Source string `bson:"source" json:"source"`
|
|||
|
|
SourceScoutPostID string `bson:"source_scout_post_id,omitempty" json:"source_scout_post_id,omitempty"`
|
|||
|
|
ExternalID string `bson:"external_id" json:"external_id"`
|
|||
|
|
Permalink string `bson:"permalink" json:"permalink"`
|
|||
|
|
AuthorHandle string `bson:"author_handle" json:"author_handle"`
|
|||
|
|
Text string `bson:"text" json:"text"`
|
|||
|
|
PostedAt int64 `bson:"posted_at" json:"posted_at"`
|
|||
|
|
Status string `bson:"status" json:"status"`
|
|||
|
|
IntentScore int `bson:"intent_score" json:"intent_score"`
|
|||
|
|
IntentBand string `bson:"intent_band" json:"intent_band"`
|
|||
|
|
Reasons []OpportunityReason `bson:"reasons" json:"reasons"`
|
|||
|
|
RegionDetected string `bson:"region_detected,omitempty" json:"region_detected,omitempty"`
|
|||
|
|
RegionMatch string `bson:"region_match" json:"region_match"`
|
|||
|
|
FreshnessHours int `bson:"freshness_hours" json:"freshness_hours"`
|
|||
|
|
MatchedService string `bson:"matched_service,omitempty" json:"matched_service,omitempty"`
|
|||
|
|
MatchedTerms []string `bson:"matched_terms" json:"matched_terms"`
|
|||
|
|
RejectReason string `bson:"reject_reason,omitempty" json:"reject_reason,omitempty"`
|
|||
|
|
Override *OpportunityOverride `bson:"override,omitempty" json:"override,omitempty"`
|
|||
|
|
ContactID string `bson:"contact_id,omitempty" json:"contact_id,omitempty"`
|
|||
|
|
CreatedAt int64 `bson:"created_at" json:"created_at"`
|
|||
|
|
UpdatedAt int64 `bson:"updated_at" json:"updated_at"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// OpportunityListFilter 支援 band／status／watch／日期區間。
|
|||
|
|
// Status 與 Statuses 擇一：Statuses 非空時用 $in；否則 Status 做單值比對。
|
|||
|
|
type OpportunityListFilter struct {
|
|||
|
|
Band string
|
|||
|
|
Status string
|
|||
|
|
Statuses []string // 多狀態；$in（今日頁：qualified／accepted／dismissed）
|
|||
|
|
WatchID string
|
|||
|
|
CreatedFrom int64 // inclusive, unix ns; 0 = no lower bound
|
|||
|
|
CreatedTo int64 // exclusive, unix ns; 0 = no upper bound
|
|||
|
|
Page int
|
|||
|
|
PageSize int
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// BandFromScore maps intent_score → band with locked 80／50 thresholds.
|
|||
|
|
func BandFromScore(score int) string {
|
|||
|
|
if score >= BandHighMinScore {
|
|||
|
|
return BandHigh
|
|||
|
|
}
|
|||
|
|
if score >= BandMidMinScore {
|
|||
|
|
return BandMid
|
|||
|
|
}
|
|||
|
|
return BandLow
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func IsOppStatus(s string) bool {
|
|||
|
|
switch s {
|
|||
|
|
case OppJudging, OppQualified, OppRejected, OppAccepted, OppDismissed:
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func IsIntentBand(s string) bool {
|
|||
|
|
switch s {
|
|||
|
|
case BandHigh, BandMid, BandLow:
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func IsRegionMatch(s string) bool {
|
|||
|
|
switch s {
|
|||
|
|
case RegionMatch, RegionMismatch, RegionUnknown:
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func IsOppSource(s string) bool {
|
|||
|
|
switch s {
|
|||
|
|
case OppSourceThreads, OppSourceManual, OppSourceScoutPromote:
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/*
|
|||
|
|
CanTransitionOpportunity 實作 spec §3.2。
|
|||
|
|
|
|||
|
|
accepted／dismissed 為使用者終態；rejected → qualified 僅經覆寫。
|
|||
|
|
judging 之後不可回到 judging。
|
|||
|
|
*/
|
|||
|
|
func CanTransitionOpportunity(from, to string) bool {
|
|||
|
|
if from == to {
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
switch from {
|
|||
|
|
case OppJudging:
|
|||
|
|
return to == OppQualified || to == OppRejected
|
|||
|
|
case OppQualified:
|
|||
|
|
return to == OppAccepted || to == OppDismissed
|
|||
|
|
case OppRejected:
|
|||
|
|
return to == OppQualified
|
|||
|
|
default:
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func (o *Opportunity) Transition(to string) error {
|
|||
|
|
if !IsOppStatus(to) {
|
|||
|
|
return fmt.Errorf("%w: unknown opportunity status %q", ErrValidation, to)
|
|||
|
|
}
|
|||
|
|
if !CanTransitionOpportunity(o.Status, to) {
|
|||
|
|
return fmt.Errorf("%w: cannot change opportunity from %s to %s", ErrValidation, o.Status, to)
|
|||
|
|
}
|
|||
|
|
o.Status = to
|
|||
|
|
o.UpdatedAt = NowNano()
|
|||
|
|
return nil
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// ApplyBandFromScore sets IntentBand from IntentScore (locked thresholds).
|
|||
|
|
func (o *Opportunity) ApplyBandFromScore() {
|
|||
|
|
o.IntentBand = BandFromScore(o.IntentScore)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/*
|
|||
|
|
ValidateReasons 要求五維度齊全、每條有非空白人話理由（OP-06）。
|
|||
|
|
|
|||
|
|
缺任一維度 → 明確錯誤，repository 不得寫入。
|
|||
|
|
*/
|
|||
|
|
func ValidateReasons(reasons []OpportunityReason) error {
|
|||
|
|
if len(reasons) == 0 {
|
|||
|
|
return fmt.Errorf("%w: reasons required (need all five dimensions)", ErrValidation)
|
|||
|
|
}
|
|||
|
|
seen := map[string]bool{}
|
|||
|
|
for _, r := range reasons {
|
|||
|
|
dim := strings.TrimSpace(r.Dimension)
|
|||
|
|
if dim == "" {
|
|||
|
|
return fmt.Errorf("%w: reasons entry missing dimension", ErrValidation)
|
|||
|
|
}
|
|||
|
|
if !isReasonDimension(dim) {
|
|||
|
|
return fmt.Errorf("%w: unknown reason dimension %q", ErrValidation, dim)
|
|||
|
|
}
|
|||
|
|
if seen[dim] {
|
|||
|
|
return fmt.Errorf("%w: duplicate reason dimension %q", ErrValidation, dim)
|
|||
|
|
}
|
|||
|
|
if strings.TrimSpace(r.Reason) == "" {
|
|||
|
|
return fmt.Errorf("%w: reasons[%s] needs a human-readable reason", ErrValidation, dim)
|
|||
|
|
}
|
|||
|
|
seen[dim] = true
|
|||
|
|
}
|
|||
|
|
for _, dim := range RequiredReasonDimensions {
|
|||
|
|
if !seen[dim] {
|
|||
|
|
return fmt.Errorf("%w: reasons missing dimension %q (need all five)", ErrValidation, dim)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
return nil
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
func isReasonDimension(s string) bool {
|
|||
|
|
switch s {
|
|||
|
|
case DimAuthenticity, DimIntent, DimRegion, DimFreshness, DimFit:
|
|||
|
|
return true
|
|||
|
|
}
|
|||
|
|
return false
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// NormalizeMatchedTerms lower-cases, trims, and de-duplicates terms.
|
|||
|
|
func NormalizeMatchedTerms(in []string) []string {
|
|||
|
|
out := make([]string, 0, len(in))
|
|||
|
|
seen := map[string]bool{}
|
|||
|
|
for _, raw := range in {
|
|||
|
|
t := strings.ToLower(strings.TrimSpace(strings.ReplaceAll(raw, "\u3000", " ")))
|
|||
|
|
t = strings.Join(strings.Fields(t), " ")
|
|||
|
|
if t == "" || seen[t] {
|
|||
|
|
continue
|
|||
|
|
}
|
|||
|
|
seen[t] = true
|
|||
|
|
out = append(out, t)
|
|||
|
|
}
|
|||
|
|
return out
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// MergeMatchedTerms returns a∪b with stable order (a first, then new from b).
|
|||
|
|
func MergeMatchedTerms(a, b []string) []string {
|
|||
|
|
return NormalizeMatchedTerms(append(append([]string{}, a...), b...))
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/*
|
|||
|
|
ValidateForWrite 在首次寫入／完整更新前檢查契約欄位。
|
|||
|
|
|
|||
|
|
Upsert 命中既有列時只併 term，不走這條（既有資料已通過判定）。
|
|||
|
|
*/
|
|||
|
|
func (o *Opportunity) ValidateForWrite() error {
|
|||
|
|
if o.OwnerUID <= 0 {
|
|||
|
|
return fmt.Errorf("%w: owner_uid required", ErrValidation)
|
|||
|
|
}
|
|||
|
|
if strings.TrimSpace(o.ExternalID) == "" {
|
|||
|
|
return fmt.Errorf("%w: external_id required", ErrValidation)
|
|||
|
|
}
|
|||
|
|
if o.Source == "" {
|
|||
|
|
o.Source = OppSourceThreads
|
|||
|
|
}
|
|||
|
|
if !IsOppSource(o.Source) {
|
|||
|
|
return fmt.Errorf("%w: unknown opportunity source %q", ErrValidation, o.Source)
|
|||
|
|
}
|
|||
|
|
if o.Status == "" {
|
|||
|
|
o.Status = OppJudging
|
|||
|
|
}
|
|||
|
|
if !IsOppStatus(o.Status) {
|
|||
|
|
return fmt.Errorf("%w: unknown opportunity status %q", ErrValidation, o.Status)
|
|||
|
|
}
|
|||
|
|
// judging 尚未出分時允許缺 reasons；一旦進入 qualified／rejected 必須五條齊全。
|
|||
|
|
if o.Status != OppJudging {
|
|||
|
|
if err := ValidateReasons(o.Reasons); err != nil {
|
|||
|
|
return err
|
|||
|
|
}
|
|||
|
|
} else if len(o.Reasons) > 0 {
|
|||
|
|
// 若呼叫端已帶 reasons，仍驗一次，避免半成品入庫。
|
|||
|
|
if err := ValidateReasons(o.Reasons); err != nil {
|
|||
|
|
return err
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
if o.RegionMatch == "" {
|
|||
|
|
o.RegionMatch = RegionUnknown
|
|||
|
|
}
|
|||
|
|
if !IsRegionMatch(o.RegionMatch) {
|
|||
|
|
return fmt.Errorf("%w: unknown region_match %q", ErrValidation, o.RegionMatch)
|
|||
|
|
}
|
|||
|
|
if o.IntentBand == "" && (o.Status == OppQualified || o.Status == OppRejected || o.Status == OppAccepted || o.Status == OppDismissed) {
|
|||
|
|
o.ApplyBandFromScore()
|
|||
|
|
}
|
|||
|
|
if o.IntentBand != "" && !IsIntentBand(o.IntentBand) {
|
|||
|
|
return fmt.Errorf("%w: unknown intent_band %q", ErrValidation, o.IntentBand)
|
|||
|
|
}
|
|||
|
|
o.MatchedTerms = NormalizeMatchedTerms(o.MatchedTerms)
|
|||
|
|
return nil
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// UTCDayBounds returns [start, end) unix ns for the UTC calendar day that contains at.
|
|||
|
|
func UTCDayBounds(at int64) (start, end int64) {
|
|||
|
|
if at <= 0 {
|
|||
|
|
at = NowNano()
|
|||
|
|
}
|
|||
|
|
t := time.Unix(0, at).UTC()
|
|||
|
|
day := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, time.UTC)
|
|||
|
|
return day.UnixNano(), day.Add(24 * time.Hour).UnixNano()
|
|||
|
|
}
|