feat: 卡实名时间以上游 archiveTime 为准并记录实名时间历史,新增二次实名批次
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled

This commit is contained in:
邹进
2026-11-08 19:12:46 +09:00
parent 94f86ab217
commit 4967f4df43
32 changed files with 1885 additions and 47 deletions

View File

@@ -28,7 +28,9 @@ type ObservationMetadata struct {
type RealnameObservation struct {
CardID uint
Verified bool
Metadata ObservationMetadata
// UpstreamRealnameAt 是上游返回的实名时间 archiveTime;未返回时为 nil。
UpstreamRealnameAt *time.Time
Metadata ObservationMetadata
}
// CardRealnameSnapshot 是应用层从持久化模型映射出的最小卡实名快照。

View File

@@ -0,0 +1,144 @@
package cardobservation
import (
"time"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// RealnameTimeSnapshot 是卡当前实名记录的最小快照;Exists=false 表示还没有当前实名记录。
type RealnameTimeSnapshot struct {
Exists bool
RealnameAt *time.Time
RealnameAtSource string
UpstreamRealnameAt *time.Time
FirstObservedAt *time.Time
ResetStatus string
ResetBaselineAt *time.Time
}
// RealnameResetGate 描述二次实名等待期间对一次"已实名"观测的处理。
type RealnameResetGate int
const (
// RealnameResetGateNone 卡不在等待二次实名,或本次不是已实名观测。
RealnameResetGateNone RealnameResetGate = iota
// RealnameResetGateBlocked 读到的仍是旧实名(或没有上游实名时间),不得改实名状态。
RealnameResetGateBlocked
// RealnameResetGateCompleted 上游实名时间晚于清除前时间,二次实名完成。
RealnameResetGateCompleted
)
// EvaluateRealnameResetGate 判断等待二次实名的卡本次已实名观测是新实名还是旧实名。
// 以上游 archiveTime 为准:晚于清除前的上游实名时间才算新实名;没有上游时间一律视为旧实名。
// 人工纠偏是运营明确操作,不受拦截。
func EvaluateRealnameResetGate(snapshot RealnameTimeSnapshot, observation RealnameObservation) RealnameResetGate {
if !observation.Verified || snapshot.ResetStatus != constants.RealnameResetStatusPending {
return RealnameResetGateNone
}
if observation.Metadata.Source == constants.CardObservationSourceManualOverride {
return RealnameResetGateCompleted
}
upstream := observation.UpstreamRealnameAt
if upstream == nil || snapshot.ResetBaselineAt == nil || !upstream.After(*snapshot.ResetBaselineAt) {
return RealnameResetGateBlocked
}
return RealnameResetGateCompleted
}
// RealnameTimeDecision 描述一次已实名观测后当前实名记录应如何更新。
type RealnameTimeDecision struct {
// Changed 表示当前实名记录有任何字段需要写入(含不写历史的上游最近时间等)。
Changed bool
// RealnameAt / Source 是写入后的当前实名时间与来源。
RealnameAt *time.Time
Source string
// UpstreamRealnameAt / FirstObservedAt 是写入后的值。
UpstreamRealnameAt *time.Time
FirstObservedAt *time.Time
// ClearReset 表示清除二次实名等待状态。
ClearReset bool
// WriteHistory 仅在当前实名时间变化时为 true。
WriteHistory bool
ChangeType string
BeforeAt *time.Time
}
// DecideRealnameTime 根据已被采纳为"已实名"的观测确定当前实名时间:
// 1. 有上游实名时间 → 以它为准(来源 upstream);
// 2. 否则已有当前实名时间 → 保持不变;
// 3. 否则 → 取本次观测时间(来源 first_observed)。
//
// 只有当前实名时间变化才写历史;相同时间只可能静默更新来源或上游最近返回时间。
// 调用方只应在观测被采纳为已实名(卡最终为已实名、且未被二次实名拦截)时调用。
func DecideRealnameTime(snapshot RealnameTimeSnapshot, observation RealnameObservation, gate RealnameResetGate) RealnameTimeDecision {
decision := RealnameTimeDecision{
RealnameAt: snapshot.RealnameAt, Source: snapshot.RealnameAtSource,
UpstreamRealnameAt: snapshot.UpstreamRealnameAt, FirstObservedAt: snapshot.FirstObservedAt,
BeforeAt: snapshot.RealnameAt,
}
if !snapshot.Exists {
decision.Changed = true
}
observedAt := observation.Metadata.ObservedAt
if decision.FirstObservedAt == nil {
decision.FirstObservedAt = timePtr(observedAt)
decision.Changed = true
}
upstream := observation.UpstreamRealnameAt
if upstream != nil && !sameTime(decision.UpstreamRealnameAt, upstream) {
decision.UpstreamRealnameAt = timePtr(*upstream)
decision.Changed = true
}
var next *time.Time
source := decision.Source
switch {
case upstream != nil:
next, source = timePtr(*upstream), constants.RealnameAtSourceUpstream
case snapshot.RealnameAt != nil:
next = snapshot.RealnameAt
default:
next, source = timePtr(observedAt), constants.RealnameAtSourceFirstObserved
}
if gate == RealnameResetGateCompleted {
decision.ClearReset = true
decision.Changed = true
decision.ChangeType = constants.RealnameChangeResetCompleted
}
if !sameTime(snapshot.RealnameAt, next) {
decision.RealnameAt, decision.Source = next, source
decision.Changed = true
decision.WriteHistory = true
if decision.ChangeType == "" {
if snapshot.RealnameAt == nil {
decision.ChangeType = constants.RealnameChangeFirst
} else {
decision.ChangeType = constants.RealnameChangeUpstreamFix
}
}
return decision
}
if source != decision.Source {
// 时间相同只是来源不同(如迁移时间恰好等于上游时间):静默更正来源,不写历史。
decision.Source = source
decision.Changed = true
}
if gate == RealnameResetGateCompleted {
// 二次实名完成但时间未变(理论上不会发生,上游时间一定晚于基准):仍记一条完成历史。
decision.WriteHistory = true
}
return decision
}
func sameTime(left, right *time.Time) bool {
if left == nil || right == nil {
return left == nil && right == nil
}
return left.Equal(*right)
}
func timePtr(value time.Time) *time.Time {
return &value
}

View File

@@ -0,0 +1,149 @@
package cardobservation
import (
"testing"
"time"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
var cst = time.FixedZone("CST", 8*3600)
func at(value string) *time.Time {
parsed, err := time.ParseInLocation("2006-01-02 15:04:05", value, cst)
if err != nil {
panic(err)
}
return &parsed
}
func verifiedObservation(source string, observedAt, upstream *time.Time) RealnameObservation {
return RealnameObservation{CardID: 1, Verified: true, UpstreamRealnameAt: upstream,
Metadata: ObservationMetadata{ObservationID: "o", Source: source, Scene: "s", ObservedAt: *observedAt}}
}
func TestDecideRealnameTime(t *testing.T) {
polling := constants.CardObservationSourcePolling
cases := []struct {
name string
snapshot RealnameTimeSnapshot
observation RealnameObservation
gate RealnameResetGate
wantAt *time.Time
wantSource string
wantHistory bool
wantChange string
wantChanged bool
wantUpstream *time.Time
}{
{
name: "每次轮询读到相同上游时间不写",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 19:43:39"), RealnameAtSource: constants.RealnameAtSourceUpstream,
UpstreamRealnameAt: at("2026-07-16 19:43:39"), FirstObservedAt: at("2026-07-16 20:03:25")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream,
wantUpstream: at("2026-07-16 19:43:39"),
},
{
name: "上游更正迁移时间",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 20:03:25"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-07-16 20:03:25")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeUpstreamFix, wantChanged: true, wantUpstream: at("2026-07-16 19:43:39"),
},
{
name: "不返回时间的运营商首次实名",
snapshot: RealnameTimeSnapshot{},
observation: verifiedObservation(polling, at("2026-11-08 10:00:00"), nil),
wantAt: at("2026-11-08 10:00:00"), wantSource: constants.RealnameAtSourceFirstObserved,
wantHistory: true, wantChange: constants.RealnameChangeFirst, wantChanged: true,
},
{
name: "不返回时间的运营商再次读到不写",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-11-08 10:00:00"), RealnameAtSource: constants.RealnameAtSourceFirstObserved,
FirstObservedAt: at("2026-11-08 10:00:00")},
observation: verifiedObservation(polling, at("2026-11-08 12:00:00"), nil),
wantAt: at("2026-11-08 10:00:00"), wantSource: constants.RealnameAtSourceFirstObserved,
},
{
name: "迁移沿用的时间在无上游时间时保持",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-09-01 10:00:00"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-09-01 10:00:00")},
observation: verifiedObservation(polling, at("2026-11-08 12:00:00"), nil),
wantAt: at("2026-09-01 10:00:00"), wantSource: constants.RealnameAtSourceMigrated,
},
{
name: "已实名但无记录的老卡首次读到上游时间",
snapshot: RealnameTimeSnapshot{},
observation: verifiedObservation(polling, at("2026-11-09 00:10:00"), at("2026-08-01 09:00:00")),
wantAt: at("2026-08-01 09:00:00"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeFirst, wantChanged: true, wantUpstream: at("2026-08-01 09:00:00"),
},
{
name: "二次实名完成",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: nil, RealnameAtSource: "", UpstreamRealnameAt: at("2026-07-16 19:43:39"),
FirstObservedAt: at("2026-07-16 20:03:25"), ResetStatus: constants.RealnameResetStatusPending, ResetBaselineAt: at("2026-07-16 19:43:39")},
observation: verifiedObservation(polling, at("2026-11-09 10:05:00"), at("2026-11-09 10:00:00")),
gate: RealnameResetGateCompleted,
wantAt: at("2026-11-09 10:00:00"), wantSource: constants.RealnameAtSourceUpstream,
wantHistory: true, wantChange: constants.RealnameChangeResetCompleted, wantChanged: true, wantUpstream: at("2026-11-09 10:00:00"),
},
{
name: "时间相同只是来源不同静默更正",
snapshot: RealnameTimeSnapshot{Exists: true, RealnameAt: at("2026-07-16 19:43:39"), RealnameAtSource: constants.RealnameAtSourceMigrated,
FirstObservedAt: at("2026-07-16 19:43:39")},
observation: verifiedObservation(polling, at("2026-11-08 17:10:51"), at("2026-07-16 19:43:39")),
wantAt: at("2026-07-16 19:43:39"), wantSource: constants.RealnameAtSourceUpstream, wantChanged: true,
wantUpstream: at("2026-07-16 19:43:39"),
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got := DecideRealnameTime(tc.snapshot, tc.observation, tc.gate)
if !sameTime(got.RealnameAt, tc.wantAt) || got.Source != tc.wantSource {
t.Fatalf("realname_at=%v source=%s, want %v %s", got.RealnameAt, got.Source, tc.wantAt, tc.wantSource)
}
if got.WriteHistory != tc.wantHistory || got.ChangeType != tc.wantChange {
t.Fatalf("history=%v change=%s, want %v %s", got.WriteHistory, got.ChangeType, tc.wantHistory, tc.wantChange)
}
if got.Changed != tc.wantChanged {
t.Fatalf("changed=%v, want %v", got.Changed, tc.wantChanged)
}
if tc.wantUpstream != nil && !sameTime(got.UpstreamRealnameAt, tc.wantUpstream) {
t.Fatalf("upstream=%v, want %v", got.UpstreamRealnameAt, tc.wantUpstream)
}
if tc.gate == RealnameResetGateCompleted && !got.ClearReset {
t.Fatal("reset completion must clear reset state")
}
})
}
}
func TestEvaluateRealnameResetGate(t *testing.T) {
pending := RealnameTimeSnapshot{Exists: true, ResetStatus: constants.RealnameResetStatusPending, ResetBaselineAt: at("2026-07-16 19:43:39")}
polling := constants.CardObservationSourcePolling
now := at("2026-11-09 10:05:00")
cases := []struct {
name string
snapshot RealnameTimeSnapshot
observation RealnameObservation
want RealnameResetGate
}{
{"不在等待", RealnameTimeSnapshot{Exists: true}, verifiedObservation(polling, now, nil), RealnameResetGateNone},
{"读到旧实名", pending, verifiedObservation(polling, now, at("2026-07-16 19:43:39")), RealnameResetGateBlocked},
{"读到更早实名", pending, verifiedObservation(polling, now, at("2026-07-01 00:00:00")), RealnameResetGateBlocked},
{"没有上游时间", pending, verifiedObservation(polling, now, nil), RealnameResetGateBlocked},
{"回调没有时间", pending, verifiedObservation(constants.CardObservationSourceCarrierCallback, now, nil), RealnameResetGateBlocked},
{"新实名", pending, verifiedObservation(polling, now, at("2026-11-09 10:00:00")), RealnameResetGateCompleted},
{"人工改为已实名", pending, verifiedObservation(constants.CardObservationSourceManualOverride, now, nil), RealnameResetGateCompleted},
{"未实名观测", pending, RealnameObservation{CardID: 1, Metadata: ObservationMetadata{Source: polling, ObservedAt: *now}}, RealnameResetGateNone},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if got := EvaluateRealnameResetGate(tc.snapshot, tc.observation); got != tc.want {
t.Fatalf("got %v, want %v", got, tc.want)
}
})
}
}