From ca57f604bfbf6dabf7d1cd5d304073c05698bce5 Mon Sep 17 00:00:00 2001 From: yml Date: Sun, 15 Nov 2026 15:25:33 +0800 Subject: [PATCH] =?UTF-8?q?feat(tenant):=20=E5=A2=9E=E5=8A=A0=E7=A7=9F?= =?UTF-8?q?=E6=88=B7=E5=9F=BA=E7=A1=80=E4=B8=8E=E5=9F=9F=E5=90=8D=E8=A7=A3?= =?UTF-8?q?=E6=9E=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- backend/.env.example | 4 + backend/.env.prod.example | 2 + backend/cmd/api/main.go | 7 + backend/internal/config/config.go | 4 + backend/internal/middleware/tenant_context.go | 67 + .../middleware/tenant_context_test.go | 87 + backend/internal/model/tenant.go | 50 + backend/internal/router/router.go | 35 + backend/internal/router/router_test.go | 72 + backend/internal/tenancy/context.go | 57 + backend/internal/tenancy/handler.go | 46 + backend/internal/tenancy/repository.go | 219 ++ backend/internal/tenancy/repository_test.go | 94 + .../migrations/000097_tenant_foundation.sql | 53 + deploy/caddy/Caddyfile | 10 +- docs/双运营主体多租户改造分析.md | 1910 ----------------- docs/解忧商行双站点改造实施计划.md | 369 ++++ .../admin/views/AdminListingsView.vue | 5 - .../src/features/listings/views/HomeView.vue | 2 +- .../listings/views/MobileHomeView.vue | 8 +- frontend/src/layouts/AppLayout.vue | 6 +- frontend/src/stores/distributionSite.ts | 130 ++ frontend/src/stores/siteContext.spec.ts | 21 + 24 files changed, 1329 insertions(+), 1931 deletions(-) create mode 100644 backend/internal/middleware/tenant_context.go create mode 100644 backend/internal/middleware/tenant_context_test.go create mode 100644 backend/internal/model/tenant.go create mode 100644 backend/internal/tenancy/context.go create mode 100644 backend/internal/tenancy/handler.go create mode 100644 backend/internal/tenancy/repository.go create mode 100644 backend/internal/tenancy/repository_test.go create mode 100644 backend/migrations/000097_tenant_foundation.sql delete mode 100644 docs/双运营主体多租户改造分析.md create mode 100644 docs/解忧商行双站点改造实施计划.md create mode 100644 frontend/src/stores/siteContext.spec.ts diff --git a/README.md b/README.md index 86d0c8a8..4334565c 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ SKIP_CHECKS=1 git push - [接口规划](docs/api.md) - [业务规则](docs/business-rules.md) - [分销网管理后台设计方案](docs/分销网管理后台设计方案.md) -- [双运营主体多租户改造分析](docs/双运营主体多租户改造分析.md) +- [解忧商行双站点改造方案](docs/解忧商行双站点改造实施计划.md) ### 分销独立测试库 diff --git a/backend/.env.example b/backend/.env.example index de9b04ba..87319128 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -21,6 +21,10 @@ REDIS_DB=0 JWT_SECRET=change-me +# 经营租户域名;本地留空时通过 X-Tenant-Code 或旧分销站点方式调试。 +CADDY_DOMAIN= +TENANT_JIEYOU_DOMAIN= + # 前端后台页面入口;本地默认 /admin,生产建议改成不公开的单段路径。 VITE_ADMIN_BASE_PATH=/admin diff --git a/backend/.env.prod.example b/backend/.env.prod.example index 9bd14b4c..73e5c828 100644 --- a/backend/.env.prod.example +++ b/backend/.env.prod.example @@ -5,6 +5,8 @@ APP_ADDR=:8080 # Caddy 自动申请和续签 HTTPS 证书使用。 CADDY_DOMAIN=hfb.221329.cc.cd CADDY_EMAIL=admin@example.com +# 解忧商行前台域名;未启用解忧时留空。 +TENANT_JIEYOU_DOMAIN=zuhaox.com # 选号网(hfb_show)独立域名,与主站同机;不部署选号网可留空。 # CADDY_SHOW_DOMAIN=show.example.com # 选号网源码目录(相对 hfb_sys 根或绝对路径),默认 ../hfb_show diff --git a/backend/cmd/api/main.go b/backend/cmd/api/main.go index dc5a6fb3..e47258a9 100644 --- a/backend/cmd/api/main.go +++ b/backend/cmd/api/main.go @@ -26,6 +26,7 @@ import ( "hfb_sys/backend/internal/modules/paymentconfig" "hfb_sys/backend/internal/modules/systemconfig" "hfb_sys/backend/internal/router" + "hfb_sys/backend/internal/tenancy" "go.uber.org/zap" "gorm.io/gorm" @@ -84,6 +85,12 @@ func main() { }); err != nil { logger.Fatal("初始管理员创建失败", zap.Error(err)) } + if err := tenancy.BootstrapDomains(context.Background(), db, tenancy.BootstrapConfig{ + PrimaryDomain: cfg.PrimaryDomain, + JieyouDomain: cfg.TenantJieyouDomain, + }); err != nil { + logger.Fatal("经营租户域名初始化失败", zap.Error(err)) + } } redisClient, err := database.OpenRedis(context.Background(), database.RedisConfig{ Addr: cfg.RedisAddr, diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go index 57785733..330144a2 100644 --- a/backend/internal/config/config.go +++ b/backend/internal/config/config.go @@ -24,6 +24,8 @@ type Config struct { BootstrapAdminUsername string BootstrapAdminPassword string BootstrapAdminNickname string + PrimaryDomain string + TenantJieyouDomain string Storage StorageConfig StorageMirror StorageConfig SMS SMSConfig @@ -102,6 +104,8 @@ func Load() Config { BootstrapAdminUsername: getEnv("ADMIN_BOOTSTRAP_USERNAME", ""), BootstrapAdminPassword: getEnv("ADMIN_BOOTSTRAP_PASSWORD", ""), BootstrapAdminNickname: getEnv("ADMIN_BOOTSTRAP_NICKNAME", "超级管理员"), + PrimaryDomain: strings.TrimSpace(getEnv("CADDY_DOMAIN", "")), + TenantJieyouDomain: strings.TrimSpace(getEnv("TENANT_JIEYOU_DOMAIN", "")), Storage: StorageConfig{ Endpoint: getEnv("STORAGE_ENDPOINT", "http://localhost:19090"), Bucket: getEnv("STORAGE_BUCKET", "hfb-sys"), diff --git a/backend/internal/middleware/tenant_context.go b/backend/internal/middleware/tenant_context.go new file mode 100644 index 00000000..80bbe643 --- /dev/null +++ b/backend/internal/middleware/tenant_context.go @@ -0,0 +1,67 @@ +package middleware + +import ( + "context" + "strings" + + "hfb_sys/backend/internal/config" + "hfb_sys/backend/internal/sitecode" + "hfb_sys/backend/internal/tenancy" + + "github.com/gin-gonic/gin" + "go.uber.org/zap" +) + +const ( + ContextTenantID = "tenant_id" + ContextTenantCode = "tenant_code" + tenantCodeHeader = "X-Tenant-Code" +) + +type TenantResolver interface { + ResolveHost(ctx context.Context, host string) (*tenancy.Scope, error) + ResolveCode(ctx context.Context, code string) (*tenancy.Scope, error) +} + +func TenantContext(resolver TenantResolver, appEnv string, logger *zap.Logger) gin.HandlerFunc { + if resolver == nil { + return func(c *gin.Context) { c.Next() } + } + production := config.IsProductionEnv(appEnv) + return func(c *gin.Context) { + var ( + scope *tenancy.Scope + err error + ) + if !production { + code := strings.TrimSpace(firstNonEmpty(c.GetHeader(tenantCodeHeader), c.Query("tenant_code"))) + if code != "" { + scope, err = resolver.ResolveCode(c.Request.Context(), code) + } + } + if scope == nil && err == nil { + scope, err = resolver.ResolveHost(c.Request.Context(), c.Request.Host) + } + if err != nil && logger != nil { + logger.Warn("经营租户解析失败,按旧站点上下文继续", + zap.String("host", sitecode.ExtractHost(c.Request.Host)), + zap.Error(err), + ) + } + if scope != nil { + c.Request = c.Request.WithContext(tenancy.WithScope(c.Request.Context(), *scope)) + c.Set(ContextTenantID, scope.TenantID) + c.Set(ContextTenantCode, scope.TenantCode) + } + c.Next() + } +} + +func firstNonEmpty(values ...string) string { + for _, value := range values { + if trimmed := strings.TrimSpace(value); trimmed != "" { + return trimmed + } + } + return "" +} diff --git a/backend/internal/middleware/tenant_context_test.go b/backend/internal/middleware/tenant_context_test.go new file mode 100644 index 00000000..fb5cf74e --- /dev/null +++ b/backend/internal/middleware/tenant_context_test.go @@ -0,0 +1,87 @@ +package middleware + +import ( + "net/http" + "net/http/httptest" + "testing" + + "hfb_sys/backend/internal/database" + "hfb_sys/backend/internal/model" + "hfb_sys/backend/internal/tenancy" + + "github.com/gin-gonic/gin" +) + +func newTenantContextTestEngine(t *testing.T, appEnv string) (*gin.Engine, model.Tenant) { + t.Helper() + db := database.NewTestDB() + tenant := model.Tenant{Code: "dachui", Name: "大锤商行", Status: "active"} + if err := db.Create(&tenant).Error; err != nil { + t.Fatalf("create tenant: %v", err) + } + repo := tenancy.NewRepository(db) + if err := repo.UpsertDomain(t.Context(), tenant.Code, "hao858.com", "storefront"); err != nil { + t.Fatalf("create domain: %v", err) + } + + gin.SetMode(gin.TestMode) + engine := gin.New() + engine.Use(TenantContext(repo, appEnv, nil)) + engine.GET("/probe", func(c *gin.Context) { + scope, ok := tenancy.FromContext(c.Request.Context()) + if !ok { + c.JSON(http.StatusNotFound, gin.H{"found": false}) + return + } + c.JSON(http.StatusOK, gin.H{"tenant_id": scope.TenantID, "tenant_code": scope.TenantCode}) + }) + return engine, tenant +} + +func TestTenantContextResolvesHost(t *testing.T) { + engine, tenant := newTenantContextTestEngine(t, "production") + req := httptest.NewRequest(http.MethodGet, "/probe", nil) + req.Host = "hao858.com" + rec := httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d, body=%s", rec.Code, rec.Body.String()) + } + if body := rec.Body.String(); body == "" || !contains(body, `"tenant_id":`) { + t.Fatalf("unexpected body: %s", body) + } + if tenant.ID == 0 { + t.Fatal("tenant ID should not be zero") + } +} + +func TestTenantContextAllowsDevelopmentCodeAndIgnoresItInProduction(t *testing.T) { + engine, _ := newTenantContextTestEngine(t, "development") + req := httptest.NewRequest(http.MethodGet, "/probe", nil) + req.Host = "localhost" + req.Header.Set(tenantCodeHeader, "dachui") + rec := httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != http.StatusOK { + t.Fatalf("development code status = %d, body=%s", rec.Code, rec.Body.String()) + } + + engine, _ = newTenantContextTestEngine(t, "production") + req = httptest.NewRequest(http.MethodGet, "/probe", nil) + req.Host = "localhost" + req.Header.Set(tenantCodeHeader, "dachui") + rec = httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != http.StatusNotFound { + t.Fatalf("production header status = %d, want 404", rec.Code) + } +} + +func contains(value, target string) bool { + for i := 0; i+len(target) <= len(value); i++ { + if value[i:i+len(target)] == target { + return true + } + } + return false +} diff --git a/backend/internal/model/tenant.go b/backend/internal/model/tenant.go new file mode 100644 index 00000000..5f39eba4 --- /dev/null +++ b/backend/internal/model/tenant.go @@ -0,0 +1,50 @@ +package model + +import ( + "time" + + "gorm.io/datatypes" +) + +type Tenant struct { + ID uint64 `gorm:"primaryKey" json:"id"` + Code string `gorm:"size:32;not null;uniqueIndex:uk_tenants_code" json:"code"` + Name string `gorm:"size:64;not null" json:"name"` + Status string `gorm:"size:16;not null;default:'active';index" json:"status"` + ProfileJSON datatypes.JSON `gorm:"type:json" json:"profile_json"` + FeaturesJSON datatypes.JSON `gorm:"type:json" json:"features_json"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +func (Tenant) TableName() string { + return "tenants" +} + +type TenantDomain struct { + ID uint64 `gorm:"primaryKey" json:"id"` + TenantID uint64 `gorm:"not null;index:idx_tenant_domains_tenant" json:"tenant_id"` + Host string `gorm:"size:255;not null;uniqueIndex:uk_tenant_domains_host" json:"host"` + DomainType string `gorm:"size:32;not null;default:'storefront'" json:"domain_type"` + Status string `gorm:"size:16;not null;default:'active';index:idx_tenant_domains_tenant" json:"status"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +func (TenantDomain) TableName() string { + return "tenant_domains" +} + +type TenantListingOffer struct { + ID uint64 `gorm:"primaryKey" json:"id"` + TenantID uint64 `gorm:"not null;uniqueIndex:uk_tenant_listing_offers_listing;index:idx_tenant_listing_offers_display" json:"tenant_id"` + ListingID uint64 `gorm:"not null;uniqueIndex:uk_tenant_listing_offers_listing;index:idx_tenant_listing_offers_display" json:"listing_id"` + DisplayStatus string `gorm:"size:16;not null;default:'enabled';index:idx_tenant_listing_offers_display" json:"display_status"` + PriceCent *int64 `json:"price_cent"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} + +func (TenantListingOffer) TableName() string { + return "tenant_listing_offers" +} diff --git a/backend/internal/router/router.go b/backend/internal/router/router.go index d9337b1e..c0acf8a2 100644 --- a/backend/internal/router/router.go +++ b/backend/internal/router/router.go @@ -2,6 +2,7 @@ package router import ( "context" + "net/http" "strings" "hfb_sys/backend/internal/config" @@ -43,6 +44,7 @@ import ( "hfb_sys/backend/internal/modules/user" "hfb_sys/backend/internal/modules/wallet" "hfb_sys/backend/internal/modules/withdrawal" + "hfb_sys/backend/internal/tenancy" _ "hfb_sys/backend/docs" // Swagger 文档 @@ -64,6 +66,12 @@ func New(cfg config.Config, deps Dependencies, logger *zap.Logger) *gin.Engine { engine.Use(middleware.RequestID()) engine.Use(middleware.RequestLogger(logger)) engine.Use(middleware.Recovery(logger)) + var tenantRepo *tenancy.Repository + if deps.DB != nil { + tenantRepo = tenancy.NewRepository(deps.DB) + engine.Use(middleware.TenantContext(tenantRepo, cfg.AppEnv, logger)) + } + tenantHandler := tenancy.NewHandler() jwtManager := auth.NewJWTManager(cfg.JWTSecret) health := handler.NewHealthHandler(newReadinessChecks(deps)) @@ -462,6 +470,33 @@ func New(cfg config.Config, deps Dependencies, logger *zap.Logger) *gin.Engine { api.GET("/home-announcements", systemConfigHandler.HomeAnnouncements) api.GET("/mobile-home-config", systemConfigHandler.HomeConfig) api.GET("/public/files/object", fileHandler.PublicObject) + api.GET("/site/context", tenantHandler.SiteContext) + api.GET("/site/check-domain", func(c *gin.Context) { + domain := strings.TrimSpace(c.Query("domain")) + if domain == "" { + c.String(http.StatusBadRequest, "domain required") + return + } + if tenantRepo != nil { + allowed, err := tenantRepo.IsActiveDomain(c.Request.Context(), domain) + if err != nil { + c.String(http.StatusServiceUnavailable, "tenant domain check failed") + return + } + if allowed { + c.String(http.StatusOK, "ok") + return + } + } + if distributionService != nil { + info, err := distributionService.GetPublicSiteInfo(c.Request.Context(), "", domain) + if err == nil && info != nil && info.Status == "active" { + c.String(http.StatusOK, "ok") + return + } + } + c.String(http.StatusNotFound, "domain not allowed") + }) // Gin 同一前缀只能有一种通配符名;管理端已用 /sites/:id/*,公开列表必须同名。 api.GET("/distribution/sites/:id/listings", distributionHandler.ListPublicSiteListings) api.GET("/distribution/site-info", distributionHandler.GetPublicSiteInfo) diff --git a/backend/internal/router/router_test.go b/backend/internal/router/router_test.go index c31f0885..39e9572a 100644 --- a/backend/internal/router/router_test.go +++ b/backend/internal/router/router_test.go @@ -3,10 +3,12 @@ package router import ( "net/http" "net/http/httptest" + "strings" "testing" "hfb_sys/backend/internal/config" "hfb_sys/backend/internal/database" + "hfb_sys/backend/internal/model" "go.uber.org/zap" ) @@ -56,6 +58,8 @@ func TestExtractedAdminRoutesRemainRegisteredWithoutDuplicates(t *testing.T) { "PUT /api/admin/roles/:id/permissions", "PUT /api/admin/admin-users/:id/password", "POST /api/admin/announcements/:id/publish", + "GET /api/site/context", + "GET /api/site/check-domain", "GET /api/distribution/sites/:id/listings", "GET /api/distribution/sites/:id/wallet", } { @@ -64,3 +68,71 @@ func TestExtractedAdminRoutesRemainRegisteredWithoutDuplicates(t *testing.T) { } } } + +func TestSiteContextRouteUsesTenantHost(t *testing.T) { + db := database.NewTestDB() + tenant := model.Tenant{ + Code: "jieyou", + Name: "解忧商行", + Status: "active", + ProfileJSON: []byte(`{"site_name":"解忧商行","logo_url":"https://cdn.example/logo.png"}`), + FeaturesJSON: []byte( + `{"rental_listing":true}`, + ), + } + if err := db.Create(&tenant).Error; err != nil { + t.Fatalf("create tenant: %v", err) + } + if err := db.Create(&model.TenantDomain{ + TenantID: tenant.ID, + Host: "zuhaox.com", + DomainType: "storefront", + Status: "active", + }).Error; err != nil { + t.Fatalf("create tenant domain: %v", err) + } + if err := db.Create(&model.DistributionSite{ + SiteCode: "legacy_dist", + SiteName: "历史分销站", + Domain: "legacy.example.com", + Status: "active", + }).Error; err != nil { + t.Fatalf("create legacy distribution site: %v", err) + } + + engine := New(testConfig(), Dependencies{DB: db}, zap.NewNop()) + req := httptest.NewRequest(http.MethodGet, "/api/site/context", nil) + req.Host = "zuhaox.com" + rec := httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != http.StatusOK { + t.Fatalf("status = %d, body=%s", rec.Code, rec.Body.String()) + } + body := rec.Body.String() + for _, want := range []string{`"tenant_code":"jieyou"`, `"site_name":"解忧商行"`, `"rental_listing":true`} { + if !strings.Contains(body, want) { + t.Fatalf("body missing %s: %s", want, body) + } + } + + req = httptest.NewRequest(http.MethodGet, "/api/site/context", nil) + req.Host = "unknown.example.com" + rec = httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != http.StatusNotFound { + t.Fatalf("unknown host status = %d, want 404", rec.Code) + } + + for domain, wantStatus := range map[string]int{ + "zuhaox.com": http.StatusOK, + "legacy.example.com": http.StatusOK, + "unknown.example.com": http.StatusNotFound, + } { + req = httptest.NewRequest(http.MethodGet, "/api/site/check-domain?domain="+domain, nil) + rec = httptest.NewRecorder() + engine.ServeHTTP(rec, req) + if rec.Code != wantStatus { + t.Fatalf("check domain %s status = %d, want %d; body=%s", domain, rec.Code, wantStatus, rec.Body.String()) + } + } +} diff --git a/backend/internal/tenancy/context.go b/backend/internal/tenancy/context.go new file mode 100644 index 00000000..4050e48a --- /dev/null +++ b/backend/internal/tenancy/context.go @@ -0,0 +1,57 @@ +package tenancy + +import ( + "context" + "encoding/json" + + "gorm.io/datatypes" +) + +type contextKey struct{} + +type Scope struct { + TenantID uint64 + TenantCode string + TenantName string + TenantStatus string + Host string + DomainType string + ProfileJSON datatypes.JSON + FeaturesJSON datatypes.JSON +} + +func WithScope(ctx context.Context, scope Scope) context.Context { + return context.WithValue(ctx, contextKey{}, scope) +} + +func FromContext(ctx context.Context) (Scope, bool) { + scope, ok := ctx.Value(contextKey{}).(Scope) + return scope, ok && scope.TenantID > 0 +} + +func MustFromContext(ctx context.Context) Scope { + scope, ok := FromContext(ctx) + if !ok { + panic("tenant scope missing from context") + } + return scope +} + +func (s Scope) Profile() map[string]any { + return decodeJSONMap(s.ProfileJSON) +} + +func (s Scope) Features() map[string]any { + return decodeJSONMap(s.FeaturesJSON) +} + +func decodeJSONMap(raw datatypes.JSON) map[string]any { + if len(raw) == 0 { + return map[string]any{} + } + var value map[string]any + if err := json.Unmarshal(raw, &value); err != nil || value == nil { + return map[string]any{} + } + return value +} diff --git a/backend/internal/tenancy/handler.go b/backend/internal/tenancy/handler.go new file mode 100644 index 00000000..78fe0e8e --- /dev/null +++ b/backend/internal/tenancy/handler.go @@ -0,0 +1,46 @@ +package tenancy + +import ( + "net/http" + + "hfb_sys/backend/pkg/response" + + "github.com/gin-gonic/gin" +) + +type SiteContextDTO struct { + Mode string `json:"mode"` + TenantID uint64 `json:"tenant_id"` + TenantCode string `json:"tenant_code"` + TenantName string `json:"tenant_name"` + Host string `json:"host"` + DomainType string `json:"domain_type"` + Status string `json:"status"` + Profile map[string]any `json:"profile"` + Features map[string]any `json:"features"` +} + +type Handler struct{} + +func NewHandler() *Handler { + return &Handler{} +} + +func (h *Handler) SiteContext(c *gin.Context) { + scope, ok := FromContext(c.Request.Context()) + if !ok { + response.Error(c, http.StatusNotFound, "site_not_found", "当前域名未配置站点") + return + } + response.OK(c, SiteContextDTO{ + Mode: "tenant", + TenantID: scope.TenantID, + TenantCode: scope.TenantCode, + TenantName: scope.TenantName, + Host: scope.Host, + DomainType: scope.DomainType, + Status: scope.TenantStatus, + Profile: scope.Profile(), + Features: scope.Features(), + }) +} diff --git a/backend/internal/tenancy/repository.go b/backend/internal/tenancy/repository.go new file mode 100644 index 00000000..6efb24ab --- /dev/null +++ b/backend/internal/tenancy/repository.go @@ -0,0 +1,219 @@ +package tenancy + +import ( + "context" + "errors" + "strings" + "sync" + "time" + + "hfb_sys/backend/internal/model" + "hfb_sys/backend/internal/sitecode" + + "gorm.io/gorm" +) + +var ( + ErrDependencyUnavailable = errors.New("tenancy dependency unavailable") + ErrTenantNotFound = errors.New("tenant not found") + ErrDomainConflict = errors.New("tenant domain belongs to another tenant") +) + +const domainCacheTTL = time.Minute + +type domainCacheEntry struct { + scope *Scope + expiresAt time.Time +} + +type Repository struct { + db *gorm.DB + mu sync.RWMutex + cache map[string]domainCacheEntry +} + +func NewRepository(db *gorm.DB) *Repository { + return &Repository{db: db, cache: make(map[string]domainCacheEntry)} +} + +func (r *Repository) ResolveHost(ctx context.Context, rawHost string) (*Scope, error) { + if r == nil || r.db == nil { + return nil, ErrDependencyUnavailable + } + host := sitecode.ExtractHost(rawHost) + if host == "" { + return nil, nil + } + if cached, ok := r.cachedHost(host); ok { + return cached, nil + } + + var row struct { + TenantID uint64 `gorm:"column:tenant_id"` + TenantCode string `gorm:"column:tenant_code"` + TenantName string `gorm:"column:tenant_name"` + TenantStatus string `gorm:"column:tenant_status"` + Host string `gorm:"column:host"` + DomainType string `gorm:"column:domain_type"` + ProfileJSON []byte `gorm:"column:profile_json"` + FeaturesJSON []byte `gorm:"column:features_json"` + } + err := r.db.WithContext(ctx). + Table("tenant_domains AS d"). + Select(`t.id AS tenant_id, t.code AS tenant_code, t.name AS tenant_name, t.status AS tenant_status, + d.host, d.domain_type, t.profile_json, t.features_json`). + Joins("JOIN tenants AS t ON t.id = d.tenant_id"). + Where("d.host = ? AND d.status = ? AND t.status = ?", host, "active", "active"). + Take(&row).Error + if err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + r.cacheHost(host, nil) + return nil, nil + } + return nil, err + } + scope := &Scope{ + TenantID: row.TenantID, + TenantCode: row.TenantCode, + TenantName: row.TenantName, + TenantStatus: row.TenantStatus, + Host: row.Host, + DomainType: row.DomainType, + ProfileJSON: row.ProfileJSON, + FeaturesJSON: row.FeaturesJSON, + } + r.cacheHost(host, scope) + return scope, nil +} + +func (r *Repository) ResolveCode(ctx context.Context, code string) (*Scope, error) { + if r == nil || r.db == nil { + return nil, ErrDependencyUnavailable + } + code = strings.TrimSpace(strings.ToLower(code)) + if code == "" { + return nil, nil + } + var tenant model.Tenant + if err := r.db.WithContext(ctx). + Where("code = ? AND status = ?", code, "active"). + First(&tenant).Error; err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + return nil, nil + } + return nil, err + } + return &Scope{ + TenantID: tenant.ID, + TenantCode: tenant.Code, + TenantName: tenant.Name, + TenantStatus: tenant.Status, + DomainType: "development", + ProfileJSON: tenant.ProfileJSON, + FeaturesJSON: tenant.FeaturesJSON, + }, nil +} + +func (r *Repository) IsActiveDomain(ctx context.Context, rawHost string) (bool, error) { + scope, err := r.ResolveHost(ctx, rawHost) + return scope != nil, err +} + +func (r *Repository) Invalidate() { + r.mu.Lock() + r.cache = make(map[string]domainCacheEntry) + r.mu.Unlock() +} + +func (r *Repository) cachedHost(host string) (*Scope, bool) { + r.mu.RLock() + entry, ok := r.cache[host] + r.mu.RUnlock() + if !ok || time.Now().After(entry.expiresAt) { + return nil, false + } + if entry.scope == nil { + return nil, true + } + copied := *entry.scope + return &copied, true +} + +func (r *Repository) cacheHost(host string, scope *Scope) { + r.mu.Lock() + r.cache[host] = domainCacheEntry{scope: scope, expiresAt: time.Now().Add(domainCacheTTL)} + r.mu.Unlock() +} + +type BootstrapConfig struct { + PrimaryDomain string + JieyouDomain string +} + +func BootstrapDomains(ctx context.Context, db *gorm.DB, cfg BootstrapConfig) error { + if db == nil { + return nil + } + repo := NewRepository(db) + primary := sitecode.ExtractHost(cfg.PrimaryDomain) + jieyou := sitecode.ExtractHost(cfg.JieyouDomain) + + if primary != "" { + if err := repo.UpsertDomain(ctx, "dachui", primary, "storefront"); err != nil { + return err + } + h5 := "h5." + primary + if err := repo.UpsertDomain(ctx, "dachui", h5, "storefront_alias"); err != nil { + return err + } + } + if jieyou != "" && jieyou != primary { + if err := repo.UpsertDomain(ctx, "jieyou", jieyou, "storefront"); err != nil { + return err + } + } + return nil +} + +func (r *Repository) UpsertDomain(ctx context.Context, tenantCode, rawHost, domainType string) error { + if r == nil || r.db == nil { + return ErrDependencyUnavailable + } + host := sitecode.ExtractHost(rawHost) + if host == "" { + return nil + } + var tenant model.Tenant + if err := r.db.WithContext(ctx).Where("code = ?", tenantCode).First(&tenant).Error; err != nil { + if errors.Is(err, gorm.ErrRecordNotFound) { + return ErrTenantNotFound + } + return err + } + if err := r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error { + var existing model.TenantDomain + err := tx.Where("host = ?", host).First(&existing).Error + if err == nil { + if existing.TenantID != tenant.ID { + return ErrDomainConflict + } + return tx.Model(&existing).Updates(map[string]any{ + "domain_type": domainType, + "status": "active", + }).Error + } + if !errors.Is(err, gorm.ErrRecordNotFound) { + return err + } + return tx.Create(&model.TenantDomain{ + TenantID: tenant.ID, + Host: host, + DomainType: domainType, + Status: "active", + }).Error + }); err != nil { + return err + } + r.Invalidate() + return nil +} diff --git a/backend/internal/tenancy/repository_test.go b/backend/internal/tenancy/repository_test.go new file mode 100644 index 00000000..31820a51 --- /dev/null +++ b/backend/internal/tenancy/repository_test.go @@ -0,0 +1,94 @@ +package tenancy + +import ( + "errors" + "testing" + + "hfb_sys/backend/internal/database" + "hfb_sys/backend/internal/model" +) + +func setupTenantRepoTest(t *testing.T) (*Repository, model.Tenant, model.Tenant) { + t.Helper() + db := database.NewTestDB() + dachui := model.Tenant{Code: "dachui", Name: "大锤商行", Status: "active"} + jieyou := model.Tenant{Code: "jieyou", Name: "解忧商行", Status: "active"} + if err := db.Create(&dachui).Error; err != nil { + t.Fatalf("create dachui tenant: %v", err) + } + if err := db.Create(&jieyou).Error; err != nil { + t.Fatalf("create jieyou tenant: %v", err) + } + return NewRepository(db), dachui, jieyou +} + +func TestResolveHostNormalizesAndIgnoresInactiveDomains(t *testing.T) { + repo, dachui, jieyou := setupTenantRepoTest(t) + if err := repo.UpsertDomain(t.Context(), "dachui", "hao858.com", "storefront"); err != nil { + t.Fatalf("upsert dachui domain: %v", err) + } + if err := repo.db.Create(&model.TenantDomain{ + TenantID: jieyou.ID, + Host: "disabled.example.com", + DomainType: "storefront", + Status: "disabled", + }).Error; err != nil { + t.Fatalf("create disabled domain: %v", err) + } + + scope, err := repo.ResolveHost(t.Context(), "HAO858.COM:443") + if err != nil { + t.Fatalf("resolve host: %v", err) + } + if scope == nil || scope.TenantID != dachui.ID || scope.TenantCode != "dachui" { + t.Fatalf("resolved scope = %#v, want dachui", scope) + } + + scope, err = repo.ResolveHost(t.Context(), "disabled.example.com") + if err != nil { + t.Fatalf("resolve disabled host: %v", err) + } + if scope != nil { + t.Fatalf("disabled domain resolved to %#v", scope) + } +} + +func TestBootstrapDomainsIsIdempotentAndRejectsHostConflict(t *testing.T) { + repo, _, _ := setupTenantRepoTest(t) + cfg := BootstrapConfig{PrimaryDomain: "hao858.com", JieyouDomain: "zuhaox.com"} + if err := BootstrapDomains(t.Context(), repo.db, cfg); err != nil { + t.Fatalf("bootstrap domains: %v", err) + } + if err := BootstrapDomains(t.Context(), repo.db, cfg); err != nil { + t.Fatalf("bootstrap domains second run: %v", err) + } + + var count int64 + if err := repo.db.Model(&model.TenantDomain{}).Count(&count).Error; err != nil { + t.Fatalf("count domains: %v", err) + } + if count != 3 { + t.Fatalf("domain count = %d, want 3", count) + } + if err := repo.UpsertDomain(t.Context(), "jieyou", "hao858.com", "storefront"); !errors.Is(err, ErrDomainConflict) { + t.Fatalf("conflicting domain error = %v, want ErrDomainConflict", err) + } +} + +func TestResolveCode(t *testing.T) { + repo, dachui, _ := setupTenantRepoTest(t) + scope, err := repo.ResolveCode(t.Context(), " DAC HUI ") + if err != nil { + t.Fatalf("resolve empty code: %v", err) + } + if scope != nil { + t.Fatalf("invalid code resolved to %#v", scope) + } + scope, err = repo.ResolveCode(t.Context(), "DACHUI") + if err != nil { + t.Fatalf("resolve code: %v", err) + } + if scope == nil || scope.TenantID != dachui.ID { + t.Fatalf("resolved scope = %#v, want dachui", scope) + } +} diff --git a/backend/migrations/000097_tenant_foundation.sql b/backend/migrations/000097_tenant_foundation.sql new file mode 100644 index 00000000..e5d35820 --- /dev/null +++ b/backend/migrations/000097_tenant_foundation.sql @@ -0,0 +1,53 @@ +-- +goose Up + +CREATE TABLE IF NOT EXISTS tenants ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + code VARCHAR(32) NOT NULL, + name VARCHAR(64) NOT NULL, + status VARCHAR(16) NOT NULL DEFAULT 'active', + profile_json JSON NULL, + features_json JSON NULL, + created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + UNIQUE KEY uk_tenants_code (code), + KEY idx_tenants_status (status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='经营租户'; + +INSERT INTO tenants (code, name, status, profile_json, features_json) +VALUES + ('dachui', '大锤商行', 'active', JSON_OBJECT('site_name', '大锤商行'), JSON_OBJECT()), + ('jieyou', '解忧商行', 'active', JSON_OBJECT('site_name', '解忧商行'), JSON_OBJECT()) +ON DUPLICATE KEY UPDATE + name = VALUES(name), + status = VALUES(status), + updated_at = CURRENT_TIMESTAMP; + +CREATE TABLE IF NOT EXISTS tenant_domains ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + host VARCHAR(255) NOT NULL, + domain_type VARCHAR(32) NOT NULL DEFAULT 'storefront', + status VARCHAR(16) NOT NULL DEFAULT 'active', + created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + UNIQUE KEY uk_tenant_domains_host (host), + KEY idx_tenant_domains_tenant (tenant_id, domain_type, status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='经营租户域名'; + +CREATE TABLE IF NOT EXISTS tenant_listing_offers ( + id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, + tenant_id BIGINT UNSIGNED NOT NULL, + listing_id BIGINT UNSIGNED NOT NULL, + display_status VARCHAR(16) NOT NULL DEFAULT 'enabled', + price_cent BIGINT NULL, + created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, + updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + UNIQUE KEY uk_tenant_listing_offers_listing (tenant_id, listing_id), + KEY idx_tenant_listing_offers_display (tenant_id, display_status, listing_id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='经营租户商品货架'; + +-- +goose Down + +DROP TABLE IF EXISTS tenant_listing_offers; +DROP TABLE IF EXISTS tenant_domains; +DROP TABLE IF EXISTS tenants; diff --git a/deploy/caddy/Caddyfile b/deploy/caddy/Caddyfile index 5aa6d8aa..4734aad4 100644 --- a/deploy/caddy/Caddyfile +++ b/deploy/caddy/Caddyfile @@ -1,7 +1,7 @@ { email {$CADDY_EMAIL} on_demand_tls { - ask http://backend:8080/api/distribution/check-domain + ask http://backend:8080/api/site/check-domain } } @@ -47,8 +47,8 @@ } } -# 前台商城静态资源与安全头配置(主站与所有分销站点共享): -# 前端通过 window.location.hostname 自动向 /api/distribution/site-info 请求分销配置。 +# 前台商城静态资源与安全头配置(经营站点与历史分销站点共享): +# 前端先通过 /api/site/context 解析经营租户,历史分销域名继续走 /api/distribution/site-info。 (storefront) { encode zstd gzip @@ -143,8 +143,8 @@ gitea.hao858.com { reverse_proxy gitea:3000 } -# 分销站点动态域名入口: -# 支持任意二级域名及分销商独立域名,首次访问时通过 on_demand_tls 触发后端白名单校验并自动签发 SSL 证书。 +# 动态域名入口: +# 支持经营租户域名、二级域名及历史分销独立域名,首次访问时通过 on_demand_tls 白名单校验后签发 SSL 证书。 https:// { tls { on_demand diff --git a/docs/双运营主体多租户改造分析.md b/docs/双运营主体多租户改造分析.md deleted file mode 100644 index a7602458..00000000 --- a/docs/双运营主体多租户改造分析.md +++ /dev/null @@ -1,1910 +0,0 @@ -# 双运营主体多租户改造分析 - -> 状态:分析稿 v0.2(第一轮现状审计 + 第二轮业务与数据边界设计) -> 更新时间:2026-11-14 -> 目标:在现有 HFB Sys 上增加“解忧”网站,使其与当前网站共享号库,但对外表现为两个独立公司,且用户、支付、钱包、客服、后台权限和统计相互独立。 -> 本文只分析现状和方案,不包含代码实施。 - -> 阅读提示:第 1~18 节保留第一轮现状审计和总体方案;第 19 节以后是第二轮深度分析,重点回答跨公司订单、敏感信息交接、资金对账、全量数据归属、迁移顺序和首期范围。若两轮表述有冲突,以第 19 节以后更明确的“买方租户 / 货源租户 / 支付租户”模型为准。 - -## 文档导航 - -- [第一轮结论与现状审计](#1-结论摘要) -- [第二轮深度分析结论](#19-第二轮深度分析结论) -- [角色化订单与跨公司履约](#21-角色化订单模型) -- [全量数据归属矩阵](#22-全量数据归属矩阵) -- [资金、退款与公司间结算](#23-资金退款和公司间结算) -- [认证与后台隔离](#24-认证后台和异步任务的隔离) -- [迁移与上线顺序](#25-数据迁移与兼容策略) -- [仍需确认的业务决策](#27-仍需最终确认的业务决策) -- [最终建议](#29-最终建议) - -## 1. 结论摘要 - -当前项目已经具备“同一平台下的分销子站”,但没有完成“两个独立运营主体”的租户隔离。 - -现有多数实现仍然假设: - -- 当前主站是唯一主站,使用 `0` 或 `NULL` 表示。 -- 分销站是挂在主站下面的销售渠道。 -- 用户手机号全局唯一。 -- 登录和令牌没有绑定站点。 -- 支付找不到分站商户时可以回退主站默认商户。 -- 主站运营后台可以查看全平台用户、订单、支付和财务。 -- 统计主要通过商品来源、订单角色和分成参与方推导,而不是通过明确的“买方租户、货源租户、支付租户”。 - -因此,“解忧”不能只按现有分销站新增一条站点记录并更换 Logo。推荐将其升级为: - -> 共享商品与库存的多租户平台,每个网站是独立租户;用户、认证、支付、钱包、客服、后台权限、统计和品牌配置按租户隔离。 - -推荐架构: - -- 单套 Go 后端。 -- 单套 MySQL 主库。 -- 同一套前端代码,可按域名加载不同租户配置。 -- 每个租户使用独立域名和独立后台入口。 -- 共享 `game_accounts`、`rental_listings` 和库存锁定。 -- 所有租户私有数据必须带显式 `tenant_id`。 -- 旧站也必须成为显式租户,不再使用 `0=主站` 作为长期模型。 -- 跨租户订单使用“买方租户、货源租户、支付租户、用户所属租户”多字段建模。 -- 首期由买方网站作为对客合同卖方和收款方,货源网站作为内部供货方,两家公司通过应收应付对账。 -- 跨租户订单的客服、账号交接、敏感附件和通知必须按订单角色授权,不能只绑定一个站点字段。 - -只有在两家公司要求数据库管理员、备份和物理存储层面也完全隔离时,才建议采用租户独立数据库。独立数据库会显著增加共享库存锁定、跨站订单、退款和对账的复杂度。 - -## 2. 术语定义 - -| 术语 | 含义 | -|---|---| -| 平台 | 提供共享号库、订单基础设施和平台级运维能力的内部系统 | -| 租户 | 一个对外独立运营的网站和公司主体,例如当前旧站、解忧 | -| 主站 | 当前旧站。改造后应成为普通租户,而不是特殊值 `0` | -| 站点 | 产品界面中的租户载体。本文建议继续沿用现有 `distribution_sites` 表作为租户主体,减少无关表重命名 | -| 货源租户 | 商品或游戏账号由哪个租户的卖家上传,以及由哪个租户负责来源归属 | -| 买方租户 | 用户实际下单和收银的网站 | -| 支付租户 | 实际创建支付单、使用支付商户并收取款项的租户 | -| 租户私有数据 | 只能被所属租户用户和后台查看的数据 | -| 平台内部数据 | 平台超级管理员用于运维、审计和跨租户对账的数据,不向公司后台开放 | - -本文中的“租户”和“站点”在大多数场景可视为同一个对象。落地时建议避免同时引入两套概念,否则权限、支付和财务归属会继续模糊。 - -## 3. 当前项目总体架构 - -### 3.1 技术架构 - -当前是模块化单体: - -- 后端:Go、Gin、GORM、MySQL、Redis。 -- 用户前台与主运营后台:Vue 3、TypeScript、Element Plus。 -- 分销后台:React、TypeScript、Ant Design。 -- 公网入口:Caddy,托管静态资源并反代后端。 -- 文件:OSS/MinIO,通过后端鉴权或公开接口访问。 -- 定时任务:订单超时、分销结算释放、短信发送、文件清理等。 - -主要模块: - -- 用户与认证 -- 实名与风控 -- 商品、游戏账号、审核和货架 -- 租赁订单、交接、归还、结账、争议 -- 支付、退款、支付商户配置 -- 钱包、提现、收款账户 -- 分销站点、分账、结算和财务快照 -- 客服、群聊、二维码、通知 -- 邀请返利、广告归因 -- 主站运营后台、财务后台、分销后台 - -### 3.2 当前前端部署 - -Caddy 将主站和所有分销域名都指向同一份前台静态资源: - -- 主站静态资源位于 `/srv/dist`。 -- 分销管理后台位于 `/srv/distribution-admin`。 -- 任意绑定的租户域名都使用同一个 `storefront` 配置。 -- 分销后台固定使用 `distribution.<主站域名>`。 - -参考: - -- [Caddyfile](../deploy/caddy/Caddyfile) -- [deploy/README.md](../deploy/README.md) - -这意味着解忧可以在不改部署拓扑的情况下上线独立域名,但“看起来独立”还必须依赖运行时租户配置和严格的后端隔离。 - -## 4. 当前分销系统分析 - -### 4.1 已具备的能力 - -现有分销主体表已经存储了大部分站点级配置: - -- 站点编码 -- 站点名称 -- 域名 -- 状态 -- 是否自动铺货 -- Logo、favicon、轮播、公告和页脚 -- 首页文案 -- 默认客服组 -- 分站收号比例、收号成本差 -- 税费 -- 结算冷却期 -- 分站短信配置 - -核心模型见: - -- [distribution.go](../backend/internal/model/distribution.go) -- [分销网管理后台设计方案.md](分销网管理后台设计方案.md) -- [分站收号定价分析与改造方案.md](分站收号定价分析与改造方案.md) - -### 4.2 共享号库与站点货架 - -现有商品模型已经是“共享商品库 + 站点展示关系”: - -- `game_accounts` 保存游戏账号资产。 -- `rental_listings` 保存商品和卖家。 -- `distribution_site_accounts` 保存某商品在某租户货架上的展示状态和站点加价。 - -商品被审核通过后,系统可为启用自动铺货的站点写入货架关系。站点可以: - -- 隐藏商品。 -- 重新同步商品。 -- 调整本站售价。 -- 按站点展示商品详情。 - -库存锁定仍然在共享商品上完成,下单事务会锁定商品并检查 `in_transaction`,可以避免两个网站同时卖出同一个账号。 - -这部分是最值得复用的领域。 - -### 4.3 当前订单来源模式 - -分销模块根据“买方站点”和“商品来源站点”推导订单模式: - -| 场景 | 模式 | -|---|---| -| 主站商品、主站购买 | 普通订单 | -| 分站商品、主站购买 | `two_party_distributor_receive` | -| 主站商品、分站购买 | `two_party_platform_receive` | -| 同一分站商品、同一分站购买 | `site_self_sell` | -| A 分站商品、B 分站购买 | `three_party` | - -实现见: - -- [distribution/lifecycle.go](../backend/internal/modules/distribution/lifecycle.go) -- [distribution/pricing.go](../backend/internal/modules/distribution/pricing.go) - -订单会记录: - -- `distribution_site_id` -- `distribution_mode` -- `distribution_rule_version_id` -- 商品货架加价快照 -- 号主价格、买家价格和平台利润快照 - -支付成功后会生成分销财务快照和参与方快照: - -- `distribution_order_financials` -- `distribution_order_parties` - -这套能力可以继续支撑租户间供货分成,但不能直接把一个 `distribution_site_id` 理解为“这个订单只属于这个租户”。 - -### 4.4 当前支付与财务 - -现状: - -- `payment_merchant_configs` 是全局表。 -- `distribution_site_payment_channels` 将商户配置绑定到站点。 -- 分站订单优先使用本站绑定商户。 -- 找不到本站商户时会回退主站默认商户。 -- `payment_orders` 没有独立的站点字段。 -- 分销站点有站点钱包,使用 `user_id=0 + site_id` 表示租户主体资金。 -- 站点钱包、提现和结算已有部分站点隔离。 - -关键代码: - -- [payment/repository.go](../backend/internal/modules/payment/repository.go) -- [payment/payment_start.go](../backend/internal/modules/payment/payment_start.go) -- [payment.go](../backend/internal/model/payment.go) -- [wallet.go](../backend/internal/model/wallet.go) -- [distribution.go](../backend/internal/model/distribution.go) - -### 4.5 当前统计 - -当前存在两套统计视角: - -1. 主站运营后台统计全平台。 -2. 分销后台按站点统计站点业务。 - -主站运营后台直接统计全局用户、商品、订单、钱包流水和待办: - -- [admindashboard/repository.go](../backend/internal/modules/admindashboard/repository.go) - -分销后台通过订单主字段和分销参与方联合判断站点相关订单: - -```text -distribution_site_id = 当前站点 -OR distribution_order_parties.site_id/party_id = 当前站点 -``` - -参考: - -- [distribution/repository.go](../backend/internal/modules/distribution/repository.go) - -该口径适合“平台查看分销商全部贡献”,不适合直接作为两个公司的独立业务报表。 - -## 5. 当前端到端流程 - -### 5.1 当前分站注册 - -```text -用户访问分站域名 - -> 前端识别站点编码 - -> 请求携带 X-Distribution-Site-Code - -> 后端按站点编码查询 distribution_sites - -> 创建或查找 users.phone - -> 新用户写入 distribution_site_id - -> 签发 JWT -``` - -问题: - -- 用户表仍按手机号全局唯一。 -- 已存在用户不会更新站点归属。 -- 登录查询不区分站点。 -- 客户端请求头是站点编码的权威来源。 -- 无效站点编码可能被解析为 `0`,即旧站。 - -### 5.2 当前浏览和下单 - -```text -分站域名 - -> 列表查询检查 distribution_site_accounts - -> 前端选择商品 - -> 下单接口携带站点编码 - -> 检查商品是否在站点货架展示 - -> 检查共享库存并锁定 - -> 根据买方站点和货源站点计算订单模式 - -> 保存订单和价格快照 -``` - -问题: - -- 列表检查了货架,但详情和图片没有完全检查货架。 -- 订单只保存一个主站点字段,并不能直接表达购买租户、货源租户和支付租户。 -- 用户身份未绑定当前租户。 - -### 5.3 当前支付和退款 - -```text -租客发起支付 - -> 根据订单 distribution_site_id 查站点支付通道 - -> 找不到则回退全局默认商户 - -> 创建支付单 - -> 渠道回调 - -> 更新支付和订单状态 - -> 写入分销财务快照 - -> 后续退款使用支付单当时配置 -``` - -问题: - -- 支付单没有显式租户。 -- 默认回退可能造成跨公司收款。 -- 主站运营后台可以看到全部支付,不能直接给公司使用。 - -### 5.4 当前结算 - -```text -订单完成 - -> 计算号主收入、站点加价、平台利润、服务费和分成 - -> 写入分销财务和参与方 - -> 进入站点结算冷却期 - -> 释放到站点钱包 - -> 站长发起提现 -``` - -现有财务拆分能力可复用,但需要重新明确两家公司之间的应付、应收和退款责任。 - -## 6. 当前隔离能力审计 - -### 6.1 已有站点字段的表 - -| 业务 | 表/字段 | 当前情况 | -|---|---|---| -| 用户 | `users.distribution_site_id` | 有字段,但手机号全局唯一,登录不校验站点 | -| 商品货源 | `rental_listings.distribution_site_id` | 表示商品由哪个分站收取,不表示商品只属于该站 | -| 商品货架 | `distribution_site_accounts.site_id` | 已有站点货架关系和站点加价 | -| 订单 | `rental_orders.distribution_site_id` | 一个角色锚点字段,不能表达所有参与租户 | -| 分销财务 | `distribution_order_financials.site_id` | 有站点维度 | -| 分销参与方 | `distribution_order_parties.site_id` | 用于分成归属 | -| 钱包 | `wallet_accounts.distribution_site_id` | 已按用户和站点建立独立账户 | -| 钱包流水 | `wallet_ledger.distribution_site_id` | 已有站点维度 | -| 提现 | `withdrawal_requests.distribution_site_id` | 已有站点维度 | -| 公告 | `announcements.distribution_site_id` | 已有站点维度,支持继承主站 | -| 通知 | `notifications.distribution_site_id` | 部分依赖订单模式自动推断 | -| 聊天会话 | `chat_conversations.distribution_site_id` | 部分站点隔离 | -| 二维码 | `chat_qrcode_pool.distribution_site_id` | 主站为 `NULL`,分站为 ID | -| 邀请 | `user_invitations`、返利配置和流水 | 有站点字段,但邀请码和用户关系仍受全局用户模型影响 | -| 短信 | `sms_messages.distribution_site_id` | 已有站点维度 | - -### 6.2 完全没有完整租户边界的关键表 - -| 业务 | 表 | 风险 | -|---|---|---| -| 用户唯一性 | `users` | 手机号全局唯一,两边不能独立注册 | -| 实名 | `user_realname` | 身份证全局唯一,两个租户的用户信息是否共享未定义 | -| 用户收款账户 | `user_payment_accounts` | 仅绑定全局用户,没有租户字段 | -| 支付单 | `payment_orders` | 没有租户字段,统计和回调回溯只能通过订单间接判断 | -| 支付商户 | `payment_merchant_configs` | 全局表,通过绑定关系服务站点 | -| 系统配置 | `system_configs` | 大部分配置全局,只对少数首页入口做站点覆盖 | -| 客服组 | `chat_support_groups` | 没有租户字段 | -| 客服组成员 | `chat_support_group_members` | 通过全局管理员关联 | -| 撞车商品 | `mohong_products`、`mohong_orders` | 没有站点字段 | -| 线下提号店铺 | `pickup_shops`、`pickup_shop_mappings` | 没有完整站点字段 | -| 积分商城 | `points_mall_products`、`points_mall_redemptions` | 没有租户字段 | -| 广告归因 | `ad_tracking_links`、`ad_tracking_clicks` | 没有租户字段 | -| 客服手工录单 | `cs_manual_entries` | 需要确认是否允许跨租户 | -| 主站财务 | `manual_disbursements`、`operating_expenses` | 当前是平台级财务视角 | - -结论:不能只修改用户和订单两张表。必须明确解忧首期开放哪些业务模块。任何未完成租户隔离的模块都不能直接暴露在解忧。 - -### 6.3 全局表与平台内部表 - -以下表可以继续保持平台内部或全局,但必须有明确边界: - -- `permissions` -- `roles` -- `role_permissions` -- `admin_users` -- `audit_logs` -- `file_upload_owners` -- 数据库迁移和平台监控 - -其中 `admin_users` 可以继续全局存储账号,但管理员与租户的访问关系必须通过租户成员表强制验证。 - -## 7. 关键风险 - -### 7.1 P0:用户跨站串号 - -当前: - -- `users.phone` 是全局唯一索引。 -- 短信登录按手机号查找全局用户。 -- 密码登录不接收站点编码。 -- 注册只在首次创建时写入站点。 -- 短信验证码 Redis Key 没有站点维度。 - -后果: - -- 解忧用户可能进入旧站账号。 -- 用户可能在解忧看到旧站订单、钱包和通知。 -- 解忧无法给同一手机号建立独立账户。 -- 两个公司的实名、密码和风控状态无法独立。 - -### 7.2 P0:租户上下文可以被客户端控制 - -当前站点解析优先级是: - -```text -X-Distribution-Site-Code - > X-Site-Code - > query 参数 - > Host 域名兜底 -``` - -前端还支持 `?site=` 和 `sessionStorage` 保存站点编码。 - -后果: - -- 用户可以伪造租户编码。 -- 页面切站可能导致发布、下单和注册归属错误。 -- 后端无法仅凭 JWT 验证用户是否属于当前网站。 - -### 7.3 P0:支付跨租户回退 - -当前站点支付配置不可用时,会回退全局默认商户。 - -后果: - -- 解忧订单可能进入旧站公司账户。 -- 收银台商户名称、退款主体和对账主体可能错误。 -- 对外两个公司,但资金归属不是两个公司。 - -支付必须失败关闭,而不是回退到其他租户。 - -### 7.4 P1:商品详情和文件绕过货架 - -商品列表按货架过滤,但商品详情按 ID 直接读取公开商品。文件接口也按商品 ID 读取截图。 - -后果: - -- 未在解忧货架展示的商品可能通过 ID 被访问。 -- 共享号库可能被误解为“所有租户可以查看所有商品”。 - -租户货架边界必须覆盖列表、详情、图片、搜索和下单。 - -### 7.5 P1:订单和统计归属不明确 - -当前订单主要依赖: - -- 一个 `distribution_site_id` -- 一个 `distribution_mode` -- 多个参与方分成记录 - -跨站销售时,一笔订单可能同时出现在两个租户的报表中,但当前逻辑无法明确回答: - -- 买方租户是谁 -- 货源租户是谁 -- 支付租户是谁 -- 哪个租户拥有买家客户 -- 哪个租户承担退款 -- 哪个租户应付供货款 - -必须改为显式多租户字段。 - -### 7.6 P1:主站运营后台是全局后台 - -主站运营后台当前可以查看: - -- 全量用户 -- 全量实名信息 -- 全量商品 -- 全量订单 -- 全量支付和退款 -- 全量财务 -- 全量客服和争议 - -如果旧站公司继续使用该后台,而解忧数据写入同一库,旧站管理员可能看到解忧数据。解忧也会面临反向风险。 - -需要区分: - -- 平台内部超级管理员 -- 旧站公司管理员 -- 解忧公司管理员 -- 租户客服 -- 租户财务 - -### 7.7 P1:系统配置大多全局 - -当前 `system_configs` 基本是全局配置。只有少量首页内容通过 `distribution_sites` 覆盖。 - -解忧上线前必须明确哪些配置共享、哪些继承、哪些独立: - -- 用户协议 -- 隐私政策 -- 发布协议 -- 订单协议 -- 结算规则 -- 押金和免押规则 -- 成长等级 -- 积分规则 -- 客服规则 -- 节点短信模板 -- 支付开关 -- 页面公告 - -### 7.8 P2:非租赁业务模块未租户化 - -撞车商品、积分商城、线下提号、广告归因等模块没有完整站点字段。 - -建议首期解忧只开放租赁主链路,其余模块通过功能开关隐藏;如需开放,必须先补租户字段和权限测试。 - -### 7.9 P2:对外品牌与法律主体不一致 - -当前前台存在“分站 × 主站”的联名逻辑。直接复用会让解忧仍然显示旧站品牌。 - -两个公司对外展示至少需要独立: - -- 网站名 -- Logo -- 域名 -- ICP -- 版权 -- 联系方式 -- 隐私政策 -- 用户协议 -- 客服入口 -- 短信签名 -- 支付收银主体 - -这里不仅是视觉问题,也是支付、退款、投诉和数据合规问题。 - -## 8. 目标设计 - -### 8.1 总体目标 - -```text - 共享商品/号库 - game_accounts + rental_listings - │ - ┌──────────────┴──────────────┐ - │ │ - 租户 A:旧站 租户 B:解忧 - 域名 A 域名 B - 用户 A 用户 B - 支付 A 支付 B - 钱包 A 钱包 B - 后台 A 后台 B - 统计 A 统计 B - │ │ - └──── 跨租户订单与供货结算 ────┘ -``` - -### 8.2 设计原则 - -1. 共享商品,不共享用户、支付、钱包和公司报表。 -2. 旧站也必须是显式租户。 -3. 租户上下文由服务端根据域名确定。 -4. 认证令牌必须绑定租户。 -5. 所有租户私有表必须有不可为空的 `tenant_id`。 -6. 查询租户数据时默认强制加租户条件。 -7. 找不到租户时失败关闭,不回退旧站。 -8. 找不到支付通道时失败关闭,不回退其他公司。 -9. 跨租户订单使用显式买方、货源、支付和用户租户字段。 -10. 公司管理员只能访问所属租户;平台超级管理员另设入口和审计。 -11. 历史订单使用创建时快照,不因租户规则变更重算。 -12. 未完成租户隔离的模块不向新公司开放。 - -### 8.3 租户主体 - -建议继续使用现有 `distribution_sites` 作为租户主体,避免全项目重命名表。但必须调整语义: - -- 当前旧站创建一条正式租户记录。 -- 解忧创建第二条正式租户记录。 -- 后续代码中的显式租户 ID 可以为旧站 ID 或解忧 ID。 -- 长期不再使用 `0` 表示旧站。 - -建议增加或明确以下配置: - -```text -tenant_code -tenant_name -primary_domain -status -legal_entity_name -icp_no -copyright -support_contact -privacy_policy_ref -terms_ref -admin_entry_domain -timezone -currency -default_payment_mode -``` - -具体字段名可以后定,但每个租户都必须有稳定的唯一 ID。 - -### 8.4 租户上下文 - -目标请求链路: - -```text -请求 Host - -> 查询 domain 对应 tenant - -> 检查 tenant 状态 - -> 写入服务端 TenantContext - -> 校验 JWT.tenant_id - -> 业务查询自动附加 tenant_id -``` - -规则: - -- 生产环境不信任客户端 `X-Distribution-Site-Code`。 -- 生产环境不允许 `?site=` 切换真实租户。 -- 本地开发可通过显式环境变量或受保护请求头切换,但不能带入生产。 -- 未知域名返回 404。 -- 停用租户返回 503 或维护页。 -- 域名解析失败不能默认进入旧站。 -- 管理端同样需要租户上下文。 - -### 8.5 用户与认证 - -建议将用户视为租户私有: - -```text -UNIQUE(tenant_id, phone) -``` - -同一手机号可以在两个租户分别注册独立账号。 - -用户独立范围: - -- 密码 -- 昵称和头像 -- 实名状态 -- 风控状态 -- 成长等级 -- 积分 -- 钱包 -- 收款账户 -- 邀请关系 -- 通知 -- 历史订单视图 - -认证规则: - -- 短信验证码 Key 包含租户 ID。 -- 登录失败限流包含租户 ID。 -- JWT 包含租户 ID。 -- 刷新 token 时校验用户仍属于当前租户。 -- 密码重置和注销只作用于当前租户用户。 -- 后台管理员与租户成员关系分开校验。 - -实名有两种可选策略: - -1. 租户私有实名:两个租户分别认证,互不可见。 -2. 平台统一身份:平台保存唯一实名身份,租户用户关联该身份,但公司后台只看到本租户用户投影。 - -如果两家公司是独立经营主体,首期建议默认“租户私有实名”,避免在未明确授权的情况下共享身份证信息。 - -### 8.6 商品和货架 - -共享部分: - -- 游戏账号资产 -- 商品主体 -- 商品状态 -- 商品审核结果 -- 库存锁定 -- 商品租用历史 - -租户相关部分: - -- 商品货源租户 -- 商品卖家所属租户 -- 商品在哪些租户货架展示 -- 每个租户的售价和加价 -- 每个租户的商品可见性 -- 每个租户的客服组 - -建议字段语义: - -```text -rental_listings.source_tenant_id -rental_listings.owner_user_id -distribution_site_accounts.tenant_id -distribution_site_accounts.listing_id -``` - -货架规则应覆盖: - -- 列表 -- 搜索 -- 详情 -- 截图和封面 -- 推荐区 -- 下单 -- 分享链接 - -未在当前租户货架展示的商品,访问详情也应返回 404,而不是只隐藏列表。 - -### 8.7 订单模型 - -目标订单需要明确以下字段: - -```text -order_id -sale_tenant_id # 下单和收银的租户 -source_tenant_id # 商品货源租户 -owner_user_tenant_id # 卖家用户所属租户 -renter_user_tenant_id # 买家用户所属租户 -owner_user_id -renter_user_id -payment_tenant_id # 实际收款租户 -listing_id -account_id -``` - -订单仍是一份全局业务事实,但需要为不同租户生成不同的订单投影。 - -买方租户看到: - -- 本站订单 -- 本站支付 -- 本站买家账号 -- 本站客服 -- 本站成交和退款 - -货源租户看到: - -- 本租户商品出库 -- 卖家交接 -- 号主收入 -- 对买方租户的供货应收 - -平台内部看到: - -- 完整跨租户订单 -- 两家公司的资金流 -- 应付款和应收款 -- 可能的平台服务费 - -### 8.8 跨租户交易与公司间结算 - -共享号库后,最常见的新问题是: - -> 解忧卖出了旧站卖家的商品,买家的钱进入解忧,谁给旧站和卖家结算? - -必须单独定义公司间结算账,而不是只依赖站点分成金额。 - -建议新增: - -```text -intercompany_ledger - order_id - from_tenant_id - to_tenant_id - amount_cent - biz_type - status - settled_at -``` - -典型流: - -1. 买家在解忧支付。 -2. 支付款进入解忧商户。 -3. 解忧对买家订单负责退款和客服。 -4. 旧站对卖家交接和号主收入负责。 -5. 解忧向旧站或平台形成供货应付款。 -6. 旧站或平台再向号主结算。 - -现有 35/40/25 分成规则可以复用为初始财务口径,但需要明确它是否等价于两家公司之间的供货协议。 - -### 8.9 支付 - -目标: - -- `payment_merchant_configs.tenant_id` 必填。 -- `payment_orders.tenant_id` 必填。 -- `payment_orders.payment_config_id` 必须属于同一租户的订单。 -- 解忧订单只允许使用解忧商户。 -- 找不到商户时返回“暂不可支付”,不回退。 -- 回调根据支付单定位租户和原商户。 -- 退款使用原支付商户。 -- 支付统计按 `payment_orders.tenant_id`。 -- 支付后台按租户过滤。 - -支付回调流程: - -```text -第三方回调 - -> 定位 payment_order - -> 读取 payment_order.tenant_id - -> 加载该租户原支付配置 - -> 验签 - -> 幂等更新支付和订单 - -> 写入该租户与货源租户财务记录 -``` - -如果两家公司共用同一支付服务商,也必须使用独立商户号、独立密钥或至少独立配置记录,不能共用默认配置。 - -### 8.10 钱包与提现 - -现有 `wallet_accounts(user_id, distribution_site_id)` 可以继续使用,但建议明确: - -- 用户钱包属于用户所属租户。 -- 租户主体钱包用于公司收入和提现。 -- 跨租户结算单独记公司间账。 -- 提现账户属于租户用户,不能跨站复用。 -- 租户财务只能查看和审核本租户提现。 - -如果用户已在旧站有钱包,再在解忧注册,应创建解忧独立钱包,不继承旧站余额。 - -### 8.11 统计口径 - -“每个网站统计独立”不是给所有查询简单加一个站点条件,而是先定义每项指标的归属。 - -| 指标 | 归属 | -|---|---| -| 注册用户数 | 用户所属租户 | -| 实名用户数 | 用户所属租户 | -| 买家订单数 | 买方租户 | -| 买家成交人数 | 买方租户 | -| GMV | 支付租户 | -| 收款金额 | 支付租户 | -| 退款金额 | 原支付租户 | -| 商品上架数 | 货源租户 | -| 本站货架商品数 | 货架所属租户 | -| 号主收入 | 卖家用户租户 | -| 跨站供货收入 | 货源租户 | -| 服务费 | 实际财务规则归属 | -| 待交接订单 | 当前需要操作的租户投影 | - -一笔跨租户订单可以同时进入两家公司的报表,但指标含义不同: - -- 解忧看到本站成交、买家支付和买家用户。 -- 旧站看到本商品出库、卖家交接和号主收入。 -- 平台内部总表显示完整订单和公司间结算。 - -### 8.12 后台与权限 - -后台层级建议: - -1. 平台超级管理员 - - 跨租户运维 - - 系统配置 - - 数据库和备份监控 - - 强制审计 - - 不直接服务普通公司运营 -2. 租户管理员 - - 只管理本租户用户、商品、订单、客服、财务和配置 - - 不能切换其他租户 -3. 租户客服 - - 只查看本租户订单投影和客服会话 -4. 租户财务 - - 只查看本租户支付、钱包、结算和提现 - -现有分销后台的超级管理员站点切换能力,只能用于平台内部账号,不能提供给两家公司。 - -租户后台的域名建议: - -```text -admin.旧站域名 -admin.解忧域名 -``` - -即使复用同一个 React 构建产物,也应通过域名解析固定租户,而不是允许在页面中自由切换。 - -### 8.13 客服、通知和聊天 - -现有聊天和通知已有部分站点字段,但仍依赖订单模式推断。 - -目标规则: - -- 每条通知必须直接带 `tenant_id`。 -- 每个客服组必须属于一个租户。 -- 每个客服工单和会话必须有明确租户。 -- 跨租户订单允许买家和卖家通过平台受控会话沟通。 -- 买家租户客服不能自动查看卖家租户的完整实名和联系方式。 -- 客服消息、附件和导出都要租户鉴权。 - -### 8.14 文件与附件 - -文件隔离不能只依赖随机对象 Key。 - -建议: - -- 每个租户使用独立对象前缀或租户字段。 -- `file_upload_owners` 增加租户 ID。 -- 上传时绑定租户、上传人和业务场景。 -- 私有文件访问校验租户和业务权限。 -- 公开商品图片也必须校验商品在当前租户的货架可见性。 -- 切站后不能通过旧 URL 继续访问其他租户私有附件。 - -### 8.15 系统配置 - -建议将配置分为三类: - -| 类型 | 例子 | 处理 | -|---|---|---| -| 平台共享 | 支付服务商协议、全局风控、运行参数 | 平台内部维护 | -| 租户继承 | 默认短信模板、默认客服规则、默认成长规则 | 租户可覆盖 | -| 租户独立 | 协议、隐私、品牌、支付、客服、结算、公告 | 必须独立 | - -所有“继承”都必须显式记录来源,不能因为租户配置缺失就无提示地使用另一家公司的敏感配置。 - -## 9. 数据模型建议 - -### 9.1 新增统一租户字段 - -建议所有租户私有表使用统一字段名,例如 `tenant_id`。如果短期继续沿用 `distribution_site_id`,也应确保语义一致。 - -不建议一个表同时出现 `site_id`、`distribution_site_id`、`tenant_id` 表示同一概念。 - -### 9.2 必须带租户 ID 的核心表 - -- `users` -- `user_realname` -- `user_payment_accounts` -- `payment_merchant_configs` -- `payment_orders` -- `wallet_accounts` -- `wallet_ledger` -- `withdrawal_requests` -- `notifications` -- `chat_conversations` -- `chat_qrcode_pool` -- `chat_support_groups` -- `announcements` -- `user_invitations` -- `invitation_rebate_configs` -- `invitation_rebate_ledgers` -- `sms_messages` -- 租户专属系统配置 -- 租户专属文件 - -### 9.3 需要增加“角色租户”字段的表 - -- `rental_orders` -- `rental_listings` -- `distribution_order_financials` -- `distribution_order_parties` -- `distribution_settlement_batches` -- `disputes` -- `handoff_records` -- `process_events` -- `order_checkouts` - -订单相关表不能只有一个租户字段,需要明确角色。 - -### 9.4 应继续保持共享的表 - -- `game_accounts` -- `rental_listings` 的商品和库存主体 -- `listing_status_events` -- 平台权限定义 -- 平台审计 -- 数据库迁移版本 - -共享表必须通过关联表控制租户可见性,而不是直接复制商品。 - -### 9.5 首期建议隐藏的模块 - -如果解忧首期只做租赁: - -- 撞车商品 -- 积分商城 -- 线下提号 -- 广告投放 -- 复杂运营财务 - -这些模块在完成租户化前不应出现在解忧菜单和公开路由中。 - -## 10. 方案对比 - -| 方案 | 隔离强度 | 共享号库 | 改造复杂度 | 适用性 | -|---|---|---|---|---| -| 现有分销站简单加品牌 | 低 | 好 | 低 | 只适合同一公司渠道 | -| 单后端 + 单库 + 强制租户 | 高 | 好 | 中高 | 推荐 | -| 两个独立后端 + 共享库存 API | 很高 | 中 | 高 | 公司完全独立运营时可选 | -| 每个租户独立数据库 | 很高 | 困难 | 很高 | 法律或数据库管理要求物理隔离时 | -| 完整复制两套项目 | 表面高 | 差 | 长期最高 | 不推荐 | - -### 10.1 为什么推荐单库多租户 - -- 库存锁定在同一事务内完成。 -- 跨站订单可以原子创建。 -- 支付、退款、结算和财务快照容易保持一致。 -- 现有代码和数据迁移成本最低。 -- 统计可以直接基于租户字段。 -- 共享商品不需要跨服务同步。 - -### 10.2 单库多租户的主要风险 - -- 任意查询漏加租户条件都可能造成数据泄漏。 -- 数据库管理员能看到全部租户数据。 -- 缓存 Key、日志和异步任务必须带租户。 -- 备份恢复按整库执行,不是单租户恢复。 - -这些风险需要通过: - -- 统一租户上下文。 -- 统一查询作用域。 -- 数据库复合索引。 -- 跨租户越权测试。 -- 缓存 Key 租户化。 -- 日志租户化。 -- 代码审查门禁 - -来控制。 - -### 10.3 什么情况下应改用独立数据库 - -满足以下任一条件时,应重新评估独立数据库: - -- 两家公司要求数据库管理员也无法互相访问。 -- 两家公司数据不能放在同一个备份中。 -- 两家公司要求独立恢复和独立删除数据。 -- 支付或实名数据必须物理分区。 -- 法规或合同明确要求独立存储。 - -此时仍应保留中央库存服务,商品发布、库存锁定和跨租户订单通过接口和事件同步,不能复制成两套互不通信的商品库。 - -## 11. 实施阶段 - -### 阶段 0:业务规则确认 - -必须先确认: - -- 同一手机号是否允许两边独立注册。 -- 两家公司是否使用独立支付商户。 -- 共享商品是否默认双向铺货。 -- 站点是否可以单方面隐藏共享商品。 -- 跨租户销售如何结算。 -- 退款责任由买方租户还是货源租户承担。 -- 两家公司的客服是否允许查看对方用户信息。 -- 解忧首期开放哪些业务模块。 -- 解忧是否使用独立 ICP、协议、隐私政策和经营主体。 - -输出: - -- 业务规则确认表 -- 财务归属确认表 -- 租户可见性矩阵 -- 数据迁移口径 - -### 阶段 1:显式租户基础 - -- 为旧站创建正式租户记录。 -- 创建解忧租户记录。 -- 域名解析改为 Host 权威。 -- 新增租户 Context。 -- 建立统一租户查询作用域。 -- 兼容旧数据中的 `0=主站`,但不新增长期依赖。 -- 未识别域名改为失败关闭。 - -完成标准: - -- 所有请求都能得到明确租户上下文。 -- 伪造请求头不能切换租户。 -- 停用租户不能访问业务。 - -### 阶段 2:用户、实名和后台权限 - -- `users` 改为 `(tenant_id, phone)` 唯一。 -- JWT 加入租户。 -- 短信验证码加入租户。 -- 登录、刷新、密码重置校验租户。 -- 实名和收款账户加租户边界。 -- 管理员成员关系绑定租户。 -- 主站全局后台拆分平台后台和租户后台。 - -完成标准: - -- 同一手机号可创建两个独立账号。 -- 旧站 token 无法访问解忧接口。 -- 解忧管理员无法查看旧站用户。 - -### 阶段 3:商品和货架 - -- 商品明确货源租户。 -- 货架关系明确租户。 -- 详情、搜索、图片和下单统一检查货架。 -- 缓存按租户隔离。 -- 自动铺货按租户配置执行。 - -完成标准: - -- 未在解忧展示的商品详情和图片均不可访问。 -- 同一商品不能被两个网站同时下单。 -- 站点隐藏不影响其他租户历史订单。 - -### 阶段 4:订单、支付和退款 - -- 订单增加买方租户、货源租户、支付租户和用户所属租户。 -- 支付商户和支付单增加租户。 -- 禁止支付回退其他租户。 -- 退款使用原支付商户。 -- 支付回调按支付单定位租户。 -- 通知和客服按租户投影。 - -完成标准: - -- 解忧订单只进入解忧商户。 -- 解忧无商户时不能支付。 -- 退款不会误用旧站商户。 - -### 阶段 5:财务和统计 - -- 用户钱包继续按用户和租户隔离。 -- 租户主体钱包按租户隔离。 -- 新增公司间供货结算。 -- 重写统计查询,使用明确租户字段。 -- 租户后台只显示本租户指标。 -- 平台后台单独显示跨租户总账。 - -完成标准: - -- 两边 GMV、支付、退款、用户和利润口径可对账。 -- 跨租户订单在两边展示正确角色信息。 -- 平台总账与两边账不重复不丢失。 - -### 阶段 6:解忧前台和后台 - -- 解忧独立域名。 -- 独立 Logo、名称、页脚和客服。 -- 独立协议和隐私政策。 -- 独立后台入口。 -- 独立短信配置。 -- 独立支付配置。 -- 移除联名和旧站品牌。 -- 隐藏未租户化模块。 - -### 阶段 7:迁移与上线 - -- 建立旧站租户 ID。 -- 回填用户所属租户。 -- 按订单模式回填买方、货源和支付租户。 -- 支付单通过订单和商户配置回填租户。 -- 通知、聊天、邀请和文件补齐租户。 -- 先在测试库运行完整迁移和回填校验。 -- 新旧统计口径双跑。 -- 选择低峰期切换写入。 -- 保留回滚和备份恢复方案。 - -### 阶段 8:隔离验收与运营 - -- 越权测试。 -- 支付对账。 -- 退款演练。 -- 跨租户订单演练。 -- 数据导出和删除演练。 -- 停用租户和域名切换演练。 - -## 12. 数据迁移注意事项 - -### 12.1 旧站必须获得显式 ID - -迁移时先创建旧站租户记录,得到 `legacy_tenant_id`。 - -现有 `0` 或 `NULL` 的语义需要按表映射: - -- 用户 `0` -> 旧站租户 -- 钱包 `0` -> 旧站租户 -- 通知 `NULL/0` -> 旧站租户或平台通知 -- 公告 `0` -> 旧站租户 -- 主站订单 `NULL/0` -> 旧站买方与货源租户 - -不能在所有表上机械执行同一条替换规则,因为同一个 `distribution_site_id` 在不同订单模式下可能代表买方、卖方或来源。 - -### 12.2 订单回填必须按模式推导 - -示例: - -```text -主站商品 + 主站购买 - buyer_tenant = 旧站 - source_tenant = 旧站 - payment_tenant = 旧站 - -分站 A 商品 + 主站购买 - buyer_tenant = 旧站 - source_tenant = A - payment_tenant = 旧站 - -主站商品 + 分站 B 购买 - buyer_tenant = B - source_tenant = 旧站 - payment_tenant = B - -分站 A 商品 + 分站 B 购买 - buyer_tenant = B - source_tenant = A - payment_tenant = B -``` - -必须用历史订单和参与方快照交叉校验。 - -### 12.3 迁移采用兼容窗口 - -建议顺序: - -1. 新增字段,允许为空。 -2. 写入双字段。 -3. 读接口切换为主字段。 -4. 对账历史数据。 -5. 加非空约束和复合索引。 -6. 删除旧分支。 - -不要在一次大迁移中同时修改表结构、业务逻辑和前端租户识别。 - -## 13. 验收用例 - -| 编号 | 场景 | 预期 | -|---|---|---| -| T01 | 同一手机号在旧站和解忧分别注册 | 产生两个独立用户,各自密码和实名互不影响 | -| T02 | 用旧站 JWT 访问解忧受保护接口 | 401/403 | -| T03 | 伪造 `X-Distribution-Site-Code` | 不改变服务端租户上下文 | -| T04 | 访问不存在的租户域名 | 404,不进入旧站 | -| T05 | 访问未在解忧货架展示的商品详情 | 404 | -| T06 | 访问未在解忧货架展示的商品图片 | 404 | -| T07 | 解忧订单支付但没有解忧商户 | 支付不可用,不调用旧站商户 | -| T08 | 解忧支付成功 | 支付单、订单、通知、钱包均记录解忧 | -| T09 | 解忧订单退款 | 使用原解忧支付商户 | -| T10 | 解忧管理员查询用户 | 只返回解忧用户 | -| T11 | 旧站管理员查询支付 | 不返回解忧支付 | -| T12 | 解忧财务查看提现 | 只能看到解忧提现 | -| T13 | 旧站商品在解忧售出 | 两边看到符合自身角色的订单投影 | -| T14 | 跨租户订单完成 | 号主收入、租户收入、公司间应付可对账 | -| T15 | 两个租户同时下单同一商品 | 只有一个订单成功锁定库存 | -| T16 | 停用解忧租户 | 解忧域名不可访问,旧站正常 | -| T17 | 解忧用户访问旧站邀请码 | 不建立跨租户归属 | -| T18 | 解忧用户查看通知 | 不出现旧站通知 | -| T19 | 解忧客服查看会话 | 不出现旧站用户会话 | -| T20 | 导出解忧用户数据 | 只包含解忧用户和业务记录 | - -## 14. 测试与门禁建议 - -### 14.1 静态门禁 - -- 禁止生产代码直接读取站点请求头作为租户权威来源。 -- 新增租户私有表必须声明租户字段。 -- Repository 查询租户私有表必须带租户条件。 -- 新增公开路由必须声明是否租户相关。 -- 新增支付配置必须有租户。 -- 新增缓存 Key 必须带租户。 - -### 14.2 集成测试 - -- 租户 A 和 B 同时存在。 -- 每个跨租户读取接口做反向访问测试。 -- 支付回调和退款按租户验证。 -- 统计结果在迁移前后对账。 -- 跨租户订单双边账务验证。 - -### 14.3 运维测试 - -- 单租户停用。 -- 域名改绑。 -- 商户密钥轮换。 -- 单租户支付切换。 -- 回滚。 -- 备份恢复后的租户数据一致性。 - -## 15. 尚待确认的业务决策 - -以下问题会直接决定数据模型,建议在开发前逐项确认。 - -| 决策 | 推荐默认 | 影响 | -|---|---|---| -| 同一手机号能否两边独立注册 | 能,两个独立用户 | 决定用户唯一索引和登录模型 | -| 实名信息是否两边共享 | 默认不共享 | 决定实名表租户化 | -| 两家公司是否使用独立支付商户 | 必须独立 | 决定支付和退款隔离 | -| 共享商品是否默认双向展示 | 默认展示,可单站隐藏 | 决定货架铺货规则 | -| 解忧是否允许采集旧站商品 | 允许,按供货关系结算 | 决定商品货源租户 | -| 解忧是否允许自己的商品展示到旧站 | 取决于商业合作 | 决定双向铺货 | -| 解忧卖出旧站商品,钱先到谁 | 先到解忧商户 | 决定支付租户 | -| 谁负责退款 | 买方租户负责对客退款 | 决定退款流程 | -| 旧站与解忧如何结算 | 公司间供货应付 | 决定财务模型 | -| 跨站卖家能否被买家看到手机号 | 默认脱敏,通过平台会话沟通 | 决定客服和隐私 | -| 两家公司是否独立经营主体 | 需要真实配置 | 决定协议、支付、ICP 和合规 | -| 解忧首期业务范围 | 只开放租赁主链路 | 避免未隔离模块泄漏 | -| 平台超级管理员是否可见全部 | 可见,但独立内部后台并审计 | 决定后台分级 | -| 旧站是否保留全局后台 | 不应直接给公司运营使用 | 决定旧后台拆分 | -| 租户删除和导出规则 | 每个租户独立 | 决定数据生命周期 | - -## 16. 建议的首期范围 - -为了降低风险,建议解忧首期只做: - -- 独立域名 -- 独立品牌和协议 -- 独立注册、登录、实名 -- 共享商品浏览 -- 独立货架和价格 -- 独立下单和支付 -- 独立订单视图 -- 独立钱包和退款 -- 独立客服和通知 -- 独立基础统计 -- 独立后台管理员 - -首期暂不开放: - -- 积分商城 -- 撞车商品 -- 线下提号 -- 广告投放后台 -- 复杂平台财务 -- 跨租户综合运营报表给公司管理员 - -这样可以先把租赁核心链路的租户边界做正确。 - -## 17. 主要证据索引 - -- 用户模型:[user.go](../backend/internal/model/user.go) -- 用户登录与注册:[auth/service.go](../backend/internal/modules/auth/service.go) -- 用户仓储:[auth/repository.go](../backend/internal/modules/auth/repository.go) -- 站点编码解析:[sitecode.go](../backend/internal/sitecode/sitecode.go) -- 域名兜底:[site_domain_fallback.go](../backend/internal/middleware/site_domain_fallback.go) -- 分销主体和货架:[distribution.go](../backend/internal/model/distribution.go) -- 商品公开查询:[public_query.go](../backend/internal/modules/listing/public_query.go) -- 订单创建:[order/lifecycle.go](../backend/internal/modules/order/lifecycle.go) -- 订单查询:[order/queries.go](../backend/internal/modules/order/queries.go) -- 支付配置解析:[payment/repository.go](../backend/internal/modules/payment/repository.go) -- 支付单:[payment.go](../backend/internal/model/payment.go) -- 钱包:[wallet.go](../backend/internal/model/wallet.go) -- 分销统计:[distribution/repository.go](../backend/internal/modules/distribution/repository.go) -- 主站仪表盘:[admindashboard/repository.go](../backend/internal/modules/admindashboard/repository.go) -- 公告站点范围:[announcement/repository.go](../backend/internal/modules/announcement/repository.go) -- 聊天站点过滤:[chat/conversation.go](../backend/internal/modules/chat/conversation.go) -- 前端站点状态:[distributionSite.ts](../frontend/src/stores/distributionSite.ts) -- Caddy 部署:[Caddyfile](../deploy/caddy/Caddyfile) -- 现有分销设计:[分销网管理后台设计方案.md](分销网管理后台设计方案.md) -- 现有分站收号定价:[分站收号定价分析与改造方案.md](分站收号定价分析与改造方案.md) - -## 18. 第一轮分析总结 - -“解忧”最合理的实现方式不是复制项目,也不是把现有分销站简单换名,而是把现有分销能力升级为共享库存的多租户平台。 - -最关键的改造不是页面,而是四个边界: - -1. 租户身份边界:域名、用户、JWT、后台权限。 -2. 资金边界:支付商户、支付单、退款、钱包和公司间结算。 -3. 库存边界:共享商品、站点货架、详情和文件可见性。 -4. 数据边界:订单角色、用户统计、支付统计和后台查询。 - -只要这四条边界没有同时完成,就不建议让解忧正式承载真实用户和资金。 - -下一步建议先把第 15 节的业务决策确认,再形成: - -- 租户权限矩阵 -- 数据表改造清单 -- 跨租户订单和财务流 -- 数据库迁移与回填方案 -- 上线验收清单 - -确认这些内容后再进入数据库迁移和代码实施,返工风险最低。 - -## 19. 第二轮深度分析结论 - -### 19.1 对需求的最终理解 - -这个需求不应被表述为“再开一个分销站”,而应被表述为: - -> 建设一个共享租赁货源的内部平台,前台承载两个独立运营主体。旧站和解忧各自拥有独立的客户、账号、支付、钱包、客服、后台和报表;解忧可以销售旧站供货的共享商品;一笔跨公司订单在内部形成供货应付,但对外仍由买方网站独立完成交易和售后。 - -需要同时满足两组完全不同的目标: - -| 视角 | 必须达到的效果 | -|---|---| -| 用户视角 | 两个独立域名、独立品牌、独立账号、独立支付、独立订单、独立客服、独立协议;看不出是同一套平台的两个频道 | -| 内部视角 | 商品和库存只有一份;跨公司订单可追溯;两家公司能各自对账;平台可以处理共享库存、退款和异常 | - -不能把“共享号库”理解成“共享账号、共享登录、共享支付或共享统计”。这里共享的只有商品主体、库存状态和必要的履约事实。 - -### 19.2 首先需要统一一个商业模型 - -推荐采用“买方网站对客成交、货源网站内部供货”的模型,而不是让用户直接和另一个公司建立买卖合同。 - -以解忧用户购买旧站商品为例: - -- 解忧用户与解忧形成对外交易关系。 -- 解忧负责展示、下单、收款、退款和对客客服。 -- 旧站负责提供商品、完成号主侧交接和商品质量责任。 -- 解忧把全部款项收入自己的支付商户,再按内部供货规则向旧站形成应付。 -- 旧站向自己的号主结算,不直接操作解忧用户的钱包。 -- 两家公司之间用供货单、应付单、退款冲销和对账单解决,不把内部利润分成直接暴露给用户。 - -这个模型的最大优点是:支付、退款、发票、协议、客服和用户数据都能自然地落在买方租户,不需要让用户在付款时看到另一家公司。 - -如果实际业务要求“解忧只做导流,旧站直接向用户收款”,那么支付租户将不再是解忧,用户协议、退款责任、数据归属和统计口径都会改变。这不是一个可以后期随手切换的小选项,必须在开发前确定。 - -### 19.3 现有 `distribution_site_id` 不能直接充当订单租户 - -当前订单中的 `distribution_site_id` 是分账锚点,不是买方站点。代码会根据买家站点和商品来源站点计算 `distribution_mode`,再让该模式的锚点站点决定规则: - -| 当前模式 | 当前锚点 | 当前含义 | -|---|---|---| -| `two_party_distributor_receive` | 货源站 | 主站买分站货,分站作为收号参与方 | -| `two_party_platform_receive` | 买方站 | 分站买主站货,主站作为收号参与方 | -| `site_self_sell` | 买方站 | 同一分站买本站货 | -| `three_party` | 买方站 | 两个分站之间买卖,货源站由商品反推 | - -支付模块直接使用订单的 `distribution_site_id` 选择商户,因此历史上这个字段还隐含了“支付锚点”的含义。它同时承担了分账锚点、支付归属和查询过滤三种职责,无法再安全承载“买方、货源方、支付方、卖家用户方”四种角色。 - -新增一个 `tenant_id` 只会把四种角色压缩成一个错误答案。订单必须角色化建模。 - -### 19.4 推荐的首期落地策略 - -架构上保留双向供货能力,但首期业务只开放一个方向: - -1. 旧站现有库存可铺到解忧。 -2. 解忧用户可以在解忧注册、下单、支付和申请售后。 -3. 解忧自己新增的账号首期只在解忧销售,不反向铺到旧站。 -4. 解忧是首批跨租户订单的买方、收款方和第一责任客服。 -5. 旧站是货源方和履约方,只看到自己负责的供货订单和必要的买家脱敏信息。 - -首期限制为单向供货,不会妨碍数据模型支持双向交易,却能显著降低以下风险: - -- 旧站用户被解忧商品质量、退款和客服流程影响。 -- 两边客服都需要理解对方全部业务规则。 -- 双向跨公司应收应付同时发生,财务对账复杂。 -- 旧站原客户看到解忧商品后产生品牌混淆。 - -## 20. 两个公司的业务边界与法律边界 - -### 20.1 对外交易主体 - -每一笔订单都必须明确一个面向用户的合同卖方,推荐使用 `merchant_of_record_tenant_id` 单独表示。默认规则: - -```text -merchant_of_record_tenant_id = buyer_tenant_id -payment_tenant_id = buyer_tenant_id -source_tenant_id = 商品来源租户 -``` - -只有在法务或支付方案明确要求其他结构时,才允许三者不一致。允许字段不一致不等于允许流程口径模糊;任何不一致都必须在订单快照中记录原因。 - -### 20.2 两家公司需要各自具备的外部配置 - -解忧至少需要独立准备: - -- 域名和 HTTPS。 -- 公司名称、经营主体、ICP备案信息。 -- 用户协议、隐私政策、租赁规则和售后规则。 -- 支付商户、结算银行卡和回调地址。 -- 客服入口、客服身份、服务时间和投诉渠道。 -- 短信签名和模板。 -- 发票或收据规则,如业务需要。 -- 数据保存期限和用户注销规则。 - -“共用同一套后端”不能作为免除这些配置的理由。即使用户不知道两个网站共用一个数据库,法律文件仍应真实说明数据由谁处理、共享哪些必要履约信息,以及用户应向哪家公司主张权利。 - -### 20.3 不能对外暴露的内部信息 - -解忧前台默认不得出现: - -- 旧站品牌、主站后台入口和“分销 / 分站”字样。 -- 平台内部公司间分成比例。 -- 旧站支付商户名称或内部订单资金来源。 -- 旧站号主的手机号、实名信息、收款账户。 -- 平台超级管理员的身份和跨租户统计。 - -旧站后台默认不得出现: - -- 解忧用户的完整个人资料和全部订单历史。 -- 解忧支付流水和钱包余额。 -- 解忧客服会话全文。 -- 解忧公司的客户统计和营销数据。 - -跨租户订单只向双方暴露履约所需的最小投影。 - -## 21. 角色化订单模型 - -### 21.1 订单必填角色 - -建议订单主表至少增加以下字段: - -| 字段 | 含义 | 是否允许不同 | -|---|---|---| -| `buyer_tenant_id` | 用户下单和接受服务的网站 | 是 | -| `source_tenant_id` | 商品及库存所属公司 | 是 | -| `payment_tenant_id` | 实际创建支付单和收取款项的网站 | 首期应等于买方 | -| `merchant_of_record_tenant_id` | 对用户承担合同义务的公司 | 首期应等于买方 | -| `buyer_user_tenant_id` | 买家账号所属租户 | 是 | -| `seller_user_tenant_id` | 号主账号所属租户 | 是 | -| `listing_source_tenant_id` | 下单时商品来源租户快照 | 是,必须快照 | -| `fulfillment_owner_tenant_id` | 当前负责商品交接和账号质量的一方 | 默认等于货源方 | -| `dispute_owner_tenant_id` | 当前处理售后的第一责任方 | 默认等于买方 | - -订单创建时必须验证: - -```text -buyer_user_tenant_id = buyer_tenant_id -seller_user_tenant_id = source_tenant_id -listing_source_tenant_id = source_tenant_id -``` - -若历史用户或商品存在迁移例外,必须通过受审计的数据修复处理,不能在正常下单路径静默放宽。 - -### 21.2 为什么不能只用 `buyer_tenant_id + source_tenant_id` - -只有买卖双方字段仍然不够: - -- 支付方可能因特殊合同不等于买方。 -- 实际履约方可能从货源公司转给平台代管。 -- 售后责任可能在争议升级后转给平台或货源方。 -- 用户所属租户和订单所属租户需要在数据审计中分别证明。 -- 同一用户未来若发生租户迁移,历史订单仍要保留成交时归属。 - -因此订单既要保留四个核心角色,也要保留用户租户和履约责任快照。 - -### 21.3 租户可见范围 - -同一笔跨公司订单应生成两个不同的业务投影,而不是把同一条完整订单给双方后台: - -| 信息 | 解忧(买方) | 旧站(货源方) | 平台内部 | -|---|---|---|---| -| 订单号 | 可见 | 可见 | 可见 | -| 商品标题和必要资产信息 | 可见 | 可见 | 可见 | -| 买家昵称 | 可见 | 脱敏可见 | 可见 | -| 买家手机号/实名 | 可见,限于本站客服权限 | 默认不可见 | 按审计权限可见 | -| 号主昵称 | 脱敏可见 | 可见 | 可见 | -| 号主手机号/实名 | 默认不可见 | 可见 | 按审计权限可见 | -| 对客实收、退款 | 完整可见 | 只可见供货结算口径 | 完整可见 | -| 号主应得 | 不可见 | 可见 | 可见 | -| 公司间应付 | 应付方可见 | 应收方可见 | 完整可见 | -| 支付商户和渠道流水 | 可见 | 不直接可见 | 完整可见 | -| 交接账号信息 | 按订单参与者授权 | 按订单参与者授权 | 严格审计可见 | - -首期可以把两个投影实现为同一服务上的不同权限 DTO;不要依赖前端隐藏字段。 - -### 21.4 跨租户履约与聊天是当前方案遗漏的 P1 问题 - -当前 `chat_conversations` 只有一个 `distribution_site_id`,通知也主要依赖一个 `distribution_site_id` 或订单模式反推。跨公司订单可能同时属于买方和货源方,单个站点字段无法表达以下关系: - -- 谁是对客客服。 -- 谁负责交接。 -- 哪个租户可以查看哪些消息。 -- 争议升级后由谁接管。 -- 买家是否能看到货源公司的客服身份。 - -推荐新增“订单履约案件”视角,把会话绑定到订单和参与角色,而不是只绑定一个网站: - -| 角色 | 默认权限 | -|---|---| -| 买家 | 查看本订单对客消息和交接结果 | -| 号主 | 只查看自己需要执行的交接与归还消息 | -| 买方客服 | 查看对客会话,可向货源方发起内部协作 | -| 货源客服 | 查看货源履约信息,不自动查看买家实名和支付资料 | -| 平台仲裁 | 仅在争议升级或审计授权时查看完整信息 | - -首期如果复用现有聊天表,至少要增加会话参与租户和角色表,禁止只靠 `distribution_site_id` 决定可见性。 - -### 21.5 交接凭据必须作为独立敏感数据设计 - -当前 `handoff_records.content` 和过程日志可以直接保存文本,业务上很可能包含游戏账号、密码或辅助登录说明;这些表目前没有独立租户、加密或按订单角色访问的设计。跨公司交易会扩大暴露面。 - -建议: - -- 将账号密码类交接内容存为独立 `order_secrets`,使用字段级加密。 -- 只允许买家和当前履约责任人查看,客服需额外权限并记录审计。 -- 默认到期隐藏或删除可读明文;历史审计只保留操作事实。 -- 禁止写日志、导出表格、搜索索引和普通客服列表。 -- 交接记录中的截图、聊天附件同样执行订单角色鉴权。 - -这不是“锦上添花”的安全项。两家公司共享货源后,用户问“另一个公司的人为什么能看到我的手机号或账号密码”会直接成为运营与合规问题。 - -## 22. 全量数据归属矩阵 - -下表按业务能力列出当前 71 张业务表的处理建议。`新表` 指现有结构无法表达目标语义,需要通过迁移新增。 - -| 数据组 | 当前主要表 | 当前状态 | 目标处理 | -|---|---|---|---| -| 租户主体与品牌 | `distribution_sites` | 已有站点、域名、品牌、短信、结算冷却 | 作为显式租户主体;补齐法律主体、状态、时区和数据保留策略 | -| 租户域名 | 仅 `distribution_sites.domain` | 每站一个域名,后台域名由部署配置固定 | 建议新增 `tenant_domains`,支持主站、H5、管理后台、别名域名和域名类型 | -| 租户后台成员 | `distribution_site_members` | 已有成员关系 | 保留并绑定显式租户;禁止一个普通租户管理员通过切换站点访问其他租户 | -| 租户货架 | `distribution_site_accounts` | 已有逐站展示和价格差值 | 保留;增加来源租户快照、可见性策略和同商品唯一约束 | -| 后台账号 | `admin_users` | 用户名全局唯一,JWT 无租户 | 租户管理员用户名改为 `(tenant_id, username)`;平台管理员独立入口和身份域 | -| 角色和权限 | `roles`、`permissions`、`admin_user_roles`、`role_permissions` | 定义和授权均偏平台全局 | 权限定义可共享;角色和成员授权必须带租户或明确标记平台级 | -| 用户 | `users` | 有 `distribution_site_id`,手机号全局唯一 | 改为显式 `tenant_id`,唯一键改为 `(tenant_id, phone)`;JWT 和刷新令牌带租户 | -| 实名 | `user_realname` | 无租户,身份证哈希全局唯一 | 加租户;身份唯一键改为 `(tenant_id, id_no_hash)`,是否跨租户复用需单独决策 | -| 收款账户 | `user_payment_accounts` | 无租户,只按用户查 | 加租户;同一租户内保留默认账户规则 | -| 成长与积分 | `renter_growth_ledger`、用户上的成长字段 | 无租户,按用户聚合 | 按用户租户隔离;跨站订单不能给买家账户累计另一公司的成长权益 | -| 积分商城 | `points_mall_products`、`points_mall_redemptions` | 商品和兑换均全局 | 首期隐藏;开放前给商品、兑换和库存加租户 | -| 邀请关系 | `user_invitations`、邀请字段 | 有站点字段但邀请码全局唯一 | 邀请码按租户唯一;邀请人和被邀请人必须同租户 | -| 邀请返利 | `invitation_rebate_configs`、`invitation_rebate_ledgers` | 已有站点字段 | 保留;明确成本由买方还是货源方承担,不能根据利润表猜 | -| 游戏账号 | `game_accounts` | 共享,无来源租户 | 增加 `source_tenant_id`;号主租户从创建时固化,不依赖当前用户表推断 | -| 租赁商品 | `rental_listings` | 有可空 `distribution_site_id`,`NULL` 表示主站 | 增加非空或统一默认的来源租户;保存商品来源快照和供货可见策略 | -| 商品生命周期 | `listing_status_events` | 无租户,不是财务事件 | 可继续按商品共享;查询和导出时通过商品来源租户鉴权 | -| 商品编号 | `listing_no_sequences` | 平台全局序列 | 可继续共享;若两边要求完全看不出关联,可改为租户前缀 + 本地序列 | -| 外部上传 | `listing_uploads` 及其关联字段 | 无租户,存在来源渠道和管理员 | 加来源租户、上传人租户和渠道;导入接口必须绑定可信域名或签名来源 | -| 文件 | `file_upload_owners` 及对象存储路径 | 主要按用户授权,无租户 | 加租户、业务场景和订单角色;租户管理员默认看不到另一租户私有文件 | -| 货架规则 | `distribution_rule_versions` | 已有站点维度;允许全局规则回退 | 保留版本化;跨公司规则不得静默回退到另一公司的费率 | -| 订单主表 | `rental_orders` | 单 `distribution_site_id` 兼作锚点和支付选择依据 | 新增买家、货源、支付、合同卖方、用户租户和履约责任字段;保留旧字段兼容期 | -| 订单角色投影 | 当前无独立授权表 | 通过 `owner_id`、`renter_id` 和模式条件拼接 | 新增 `order_tenant_roles` 或等价投影表,统一后台可见范围 | -| 结算单 | `order_checkouts` | 无租户,只能通过订单反查 | 通过订单角色鉴权;财务导出增加买卖双方角色字段 | -| 交接记录 | `handoff_records` | 无租户,内容可能含凭据 | 通过订单角色鉴权;凭据迁移到加密敏感表 | -| 流程事件 | `process_events` | 无租户、无访问侧 | 增加 `tenant_id`、`actor_tenant_id` 和可见角色;平台事件和业务事件分开 | -| 争议 | `disputes` | 无租户,平台仲裁为主 | 增加买方责任租户、货源责任租户和处理队列;平台仲裁账号不能下放给普通租户 | -| 支付商户 | `payment_merchant_configs` | 无商户归属租户,可被多站绑定 | 增加 `owner_tenant_id`;租户只能使用自己商户,平台代收需独立标记 | -| 支付单 | `payment_orders` | 无租户,只关联订单、用户、配置 | 增加 `tenant_id`、`merchant_owner_tenant_id`;商户和配置做不可变快照 | -| 支付配置日志 | `payment_config_usage_logs` | 无租户 | 增加租户和订单角色;只供平台和商户所属租户审计 | -| 支付通道绑定 | `distribution_site_payment_channels` | 可把任意商户绑定给站点 | 绑定前校验商户归属;禁止跨公司使用未授权商户 | -| 用户钱包 | `wallet_accounts`、`wallet_ledger` | 已按用户 + 站点隔离 | 显式化租户;禁止 0 表示主站的长期特例 | -| 提现 | `withdrawal_requests` | 已有站点字段 | 加审查租户、付款租户和银行流水归属;租户财务只能看本站 | -| 分销财务 | `distribution_order_financials`、`distribution_order_parties` | 单锚点、平台/站点两类参与方 | 改为角色化快照;公司间应收应付另建账,不能只存利润比例 | -| 分销结算 | `distribution_settlement_batches`、`distribution_settlement_items` | 单站点批次,内部钱包转账 | 增加付款租户、收款租户、合同/供货单号;支持冲销和部分退款 | -| 公司账本 | 当前缺失 | 无独立公司间真实账务 | 新增 `tenant_ledger_entries`、`intercompany_documents`、`intercompany_reconciliation` | -| 通知 | `notifications` | 一个站点字段,部分依赖订单模式推断 | 明确 `recipient_user_id`、`recipient_tenant_id`、`source_tenant_id` 和可见角色 | -| 后台通知 | `admin_notifications` | 只关联管理员 | 增加租户或通过管理员成员关系强校验;平台通知独立类型 | -| 客服分组 | `chat_support_groups`、成员表 | 分组全局,成员全局 | 分组加租户;租户管理员只能分配本站客服 | -| 客服会话 | `chat_*` 系列表 | 会话一个站点字段,消息继承会话 | 普通客服会话按租户;跨公司订单使用订单履约案件和角色可见性 | -| 快捷回复与推送 | `chat_quick_replies`、`push_channels`、`push_rules` | 全局或个人,推送规则全局 | 按租户配置;平台级通道密钥与租户业务模板分开 | -| 二维码池 | `chat_qrcode_pool`、交付任务 | 有可空站点字段 | 按租户或平台共享池明确类型;跨订单交付记录绑定来源租户 | -| 系统配置 | `system_configs` | 全局 `key` 唯一 | 改为平台配置 + 租户覆盖两层;敏感配置禁止跨租户继承 | -| 公告与首页 | `announcements`、站点 JSON 配置 | 已有站点字段 | 保留;默认只显示本站公告,不能自动混入另一公司公告 | -| 短信 | `sms_messages`、站点短信配置 | 有可空站点字段,失败时可回退主站通道 | 每条显式绑定租户和发送身份;跨公司短信不得回退另一公司的签名 | -| 广告归因 | `ad_tracking_links`、`ad_tracking_clicks` | 全局 | 加租户和投放主体;短链解析不能修改其他租户归因 | -| 客服录单 | `cs_manual_entries`、`cs_manual_entry_options` | 全局唯一编号和选项 | 首期隐藏;开放前按租户分配编号空间和选项 | -| 线下提号 | `admin_pickups`、`pickup_shops`、映射表 | 全局平台运营 | 首期不在解忧开放;完成租户化且明确库存归属后再开放 | -| 摸红商品 | `mohong_products`、`mohong_orders` | 全局业务模块 | 首期隐藏;有独立供应商和结算规则时再租户化 | -| 运营财务 | `manual_disbursements`、`operating_expenses`、财务调整表 | 全局 | 每笔费用明确租户;平台公共成本单列,不自动分摊给两家公司 | -| 审计日志 | `audit_logs` | 平台全局,缺少统一租户字段 | 增加租户、操作者和跨租户标记;平台审计不能直接开放给租户后台 | -| 平台基础表 | 权限定义、迁移版本、全局序列 | 适合共享 | 保持平台级;不得混入租户业务数据 | - -这张矩阵最重要的结论是:`users`、`payment_merchant_configs` 和 `system_configs` 目前都没有真正独立的租户边界;只给订单加站点字段无法解决它们。 - -## 23. 资金、退款和公司间结算 - -### 23.1 实收不等于收入 - -解忧商户收到用户 100 元,不代表解忧直接确认 100 元收入。推荐拆成以下事实: - -| 事件 | 解忧(买方/收款方) | 旧站(货源方) | 号主 | -|---|---|---|---| -| 用户支付 G | 现金增加 G;形成用户预收款负债 | 无现金变化 | 无变化 | -| 订单完成,应给货源方 S | 预收款减少 G;确认收入约 `G-S-通道费`;形成对旧站应付 S | 形成对解忧应收 S;形成对号主应付 O;确认自身毛利 `S-O` | 形成钱包应收 O | -| 退款 R | 原路退回;冲减收入和应付;必要时形成对旧站追偿 | 冲减应收和号主应得 | 尚未发放则取消,已发放则冲销或追偿 | -| 通道手续费 C | 由实际收款租户承担;计入费用 | 不承担解忧商户手续费 | 不承担 | - -这里的 `S` 必须来自明确的供货结算规则,不能直接使用现有 35% / 40% / 25% 利润分成字段。现有逻辑把 35%/40%/25% 当作利润拆分比例,并且明确“通道手续费由主站承担,只记录”,适合单公司渠道,不适合两个公司的真实账务。 - -### 23.2 现有分账逻辑需要拆成两层 - -建议保留两层,但不要混为一张表: - -1. **对客价格与退款层**:用户实付、租金、押金、优惠、退款、通道费。 -2. **公司间供货与结算层**:旧站供货价、解忧服务收入、号主应得、平台服务费、应付/应收、冲销。 - -现有 `distribution_order_financials` 可以作为用户订单财务快照继续演进,但 `distribution_order_parties` 不能继续承担所有公司和平台的利润语义。新增公司间单据至少需要: - -- `intercompany_supply_orders`:一笔跨租户订单对应的供货单。 -- `intercompany_ledger_entries`:应收、应付、退款冲销和实际打款。 -- `intercompany_reconciliations`:双方确认的对账批次。 -- `platform_service_fees`:若平台独立收费,单独记录服务方、承担方和计税口径。 - -若两家公司的业务规模还不大,可以先用一张规范化总账加单据类型,不必马上引入完整会计系统;但每一笔跨公司金额都必须有来源订单、责任租户、付款租户、收款租户和冲销关系。 - -### 23.3 退款责任 - -首期推荐以下规则: - -1. 用户只向解忧申请退款。 -2. 解忧必须使用原支付单和原支付商户退款。 -3. 解忧不能因为自己商户不可用而使用旧站商户退款。 -4. 退款完成后,系统按订单费用快照自动生成公司间应付冲销。 -5. 如果退款由货源质量问题导致,旧站承担对应供货款和号主款冲销。 -6. 如果已经向号主结算,旧站负责从其用户钱包或后续收入中追偿;不能直接扣解忧用户账户。 -7. 争议、押金暂扣和线下补款必须保留独立的状态与证据。 - -首期不要自动实现复杂跨公司追偿。先把“原路退款、应付冲销、人工仲裁”做正确,再扩展自动分摊。 - -### 23.4 押金和优惠 - -押金是负债,不应计入 GMV 或公司收入。跨租户订单需要明确: - -- 押金由买方租户收取和退还。 -- 押金转消费、损坏扣除或补偿时,才根据规则转为某一方的收入。 -- 买方的成长等级免押与优惠不能消耗货源租户的权益。 -- 货源租户的号主补贴、保险和赔偿规则必须体现在供货价或独立补偿单中。 - -### 23.5 统计不得重复计算 - -建议把指标分成四套口径: - -| 口径 | 旧站报表 | 解忧报表 | 平台总报表 | -|---|---|---|---| -| 用户/GMV/支付 | 仅旧站买方订单和旧站用户 | 仅解忧买方订单和解忧用户 | 按买方租户汇总,可重复展示分组但不做跨租户相加后的“公司GMV” | -| 供货/出库 | 旧站作为货源的供货单和号主收入 | 解忧作为货源时才展示 | 全部货源订单 | -| 公司收入 | 旧站自身成交 + 对外供货收入 | 解忧自身成交利润 | 内部交易抵消后的平台合并口径 | -| 应收应付 | 对解忧应收等 | 对旧站应付等 | 内部往来必须抵消,不能把公司间转账算成新增 GMV | - -跨租户订单可以同时出现在两家公司报表中,但指标名称必须不同,例如“本站成交额”“本商品供货额”“号主应结算额”,不能都叫“成交额”。 - -## 24. 认证、后台和异步任务的隔离 - -### 24.1 用户认证目标规则 - -| 场景 | 目标行为 | -|---|---| -| 访问解忧注册 | Host 解析为解忧租户;验证码写入解忧租户键 | -| 同一手机号在旧站注册 | 创建旧站账号;不覆盖解忧账号 | -| 解忧短信登录 | 只按 `(解忧租户, 手机号)` 查用户 | -| 密码登录 | 请求 Host 或令牌租户必须与账号租户一致 | -| 刷新令牌 | 校验令牌租户与当前网站租户;不允许跨域刷新后继续访问 | -| 登出 | 只撤销当前账号令牌;不能依赖手机号全局操作 | -| 短信重发与风控 | 验证码按租户隔离;防刷限额可叠加一个平台全局手机号限额 | - -JWT 至少应包含 `tenant_id`、`subject_type`、`user_id`、`token_version`。认证中间件应把“当前请求租户”和“令牌租户”做相等校验。Cookie 天然按域名隔离,但服务端仍必须校验声明,不能把浏览器隔离当安全边界。 - -### 24.2 后台认证目标规则 - -平台超级管理员和租户管理员应属于不同身份域: - -- 平台管理员使用独立后台域名和独立登录入口。 -- 租户管理员只能登录自己的后台域名。 -- 租户管理员用户名唯一键为 `(tenant_id, username)`,或使用独立 `tenant_admin_users`。 -- 租户管理员 JWT 包含租户;不能通过修改请求头、query 或前端站点选择器切换。 -- 角色权限可以复用定义,但授权数据必须绑定租户。 -- “切换站点”能力只提供给平台审计账号,并记录每次跨租户访问。 - -当前分销管理后台登录后读取第一个成员站点,以及多个站点共用 `admin_users` 的方式,不适合两个公司正式使用。两家公司的后台账号必须相互不可登录、不可枚举。 - -### 24.3 请求租户必须由服务端决定 - -生产环境推荐: - -```text -请求 Host -> tenant_domains 映射 -> tenant context -``` - -具体规则: - -- 只信任 Caddy 透传且未被客户端覆盖的原始 Host。 -- 未识别、停用或域名冲突时失败关闭,返回 404/503,不能回落主站。 -- `X-Distribution-Site-Code` 只在开发环境允许模拟租户。 -- query 参数不能在生产环境切换租户。 -- 后台域名和前台域名分别绑定同一租户,不允许前台域名登录后台后跨租户。 -- 支付回调等无业务 Host 的入口,先按支付单号定位租户,再验签和处理,禁止按回调 Host 选择商户。 - -### 24.4 查询隔离方式 - -MySQL 没有像 PostgreSQL RLS 那样可靠的行级安全默认能力,因此需要在应用层建立强约束: - -- 每个租户业务仓储方法都显式接收 `TenantScope`。 -- 禁止提供无租户参数的通用 `ListAll` 给租户后台。 -- 对外 API 使用买方租户。 -- 对账和平台后台使用显式平台权限和跨租户审计。 -- 所有租户表建立 `(tenant_id, status, created_at)`、`(tenant_id, user_id)` 等复合索引。 -- 缓存 Key、异步消息、任务日志、指标标签必须带租户。 -- DTO 序列化前检查字段级权限,不能只检查是否命中主表。 - -### 24.5 异步任务和通知 - -订单超时、结算释放、短信发送、退款重试和文件清理都是平台任务,不能人为要求每个请求都带 Host。正确做法是: - -1. 任务从数据库读取明确的 `tenant_id` 或订单角色。 -2. 任务内部构造显式租户上下文。 -3. 每个收件人按 `recipient_tenant_id` 生成通知。 -4. 短信签名、客服分组和通知模板按发送方租户选择。 -5. 无法解析租户的记录暂停处理并告警,禁止默认按旧站发送。 - -## 25. 数据迁移与兼容策略 - -### 25.1 使用扩展、回填、收缩三段式迁移 - -不要直接在一个发布版本里把 `0=主站` 改成外键,也不要先删除旧唯一索引。推荐: - -1. **扩展**:新增显式租户、角色字段、复合索引和新表;旧代码继续可写。 -2. **回填**:按可证明规则填历史和新增数据;进入双读校验。 -3. **切换**:新代码只写显式字段,旧字段进入只读兼容。 -4. **收缩**:连续观察一个完整结算周期后,再删除旧唯一键和兼容逻辑。 - -### 25.2 旧站必须获得固定租户 ID - -迁移第一步创建旧站正式租户,并把以下值统一映射到该 ID: - -- `users.distribution_site_id = 0` -- `rental_listings.distribution_site_id IS NULL` -- `wallet_accounts.distribution_site_id = 0` -- `notifications.distribution_site_id IS NULL OR = 0` -- 其他历史 `NULL / 0 = 主站` 的字段 - -主站租户 ID 一旦确定,不得因为数据库重建、测试环境或再开通站点而变化。 - -### 25.3 历史订单角色回填建议 - -历史订单不能简单把 `distribution_site_id` 复制到买方租户。可按以下原则推导,再抽样人工核对: - -| 历史模式 | 买方租户 | 货源租户 | 历史支付租户 | 备注 | -|---|---|---|---|---| -| 空模式且无站点 | 旧站 | 商品来源租户 | 实际支付配置归属 | 主站内部订单 | -| `two_party_distributor_receive` | 旧站 | `distribution_site_id` 对应站点 | 现有实现通常按该站点配置支付 | 不能把旧主站买家改成货源站 | -| `two_party_platform_receive` | `distribution_site_id` 对应站点 | 旧站 | 该站点 | 常见的解忧买旧站货历史形态 | -| `site_self_sell` | 站点 | 同一站点 | 该站点 | 本站内部订单 | -| `three_party` | `distribution_site_id` 对应买方站点 | 通过 `listing_id` 反查商品来源 | 需按支付配置核对 | 现有锚点不能证明货源方 | - -历史支付租户必须优先从 `payment_orders.payment_config_id`、实际商户归属和支付通道绑定反查。若历史商户被多个站点共享,应标记为 `legacy_shared`,交由财务抽样确认,不能凭空假定。 - -### 25.4 唯一键迁移顺序 - -以用户手机号为例: - -1. 新增可空 `tenant_id` 并回填。 -2. 校验无空值、无非法租户。 -3. 新增 `(tenant_id, phone)` 唯一索引。 -4. 双读验证按租户查询不会再命中其他租户。 -5. 切换登录、注册和刷新逻辑。 -6. 观察后删除旧的 `phone` 全局唯一索引。 - -实名身份证、后台用户名、邀请码也采用同样顺序。不能在业务切换前先放开全局唯一约束,否则会产生无法自动判定归属的重复数据。 - -### 25.5 上线顺序建议 - -建议采用五个阶段,而不是一次性全量上线: - -1. **影子验证**:新字段双写、旧逻辑不变,后台对比订单角色和财务归属。 -2. **内部租户演练**:用测试域名和测试商户完成注册、下单、支付、退款、结算和客服全链路。 -3. **解忧小流量**:只开放旧站供货给解忧,关闭未租户化模块,限制首批用户。 -4. **财务对账**:至少跑完一个结算冷却周期,核对实收、退款、号主结算和公司间应付。 -5. **正式放量**:确认没有跨租户泄漏后,再开放更多商品、营销和后台能力。 - -每一步都必须有功能开关、域名级回滚和未完成订单处置方案。数据库回滚不能依赖“删除解忧数据”,因为支付和退款一旦发生就必须保留。 - -## 26. 修订后的实施优先级 - -### 26.1 P0 上线阻断项 - -以下事项任何一项未完成,都不应开放真实支付: - -1. 生产租户只按可信 Host 解析,未知域名失败关闭。 -2. 用户、JWT、短信验证码和刷新令牌带租户;同一手机号可建立两个独立账号。 -3. 订单显式保存买方、货源、支付、合同卖方和用户租户角色。 -4. 支付商户明确归属租户;买方无可用商户时直接失败,不回退旧站。 -5. 退款只使用原支付商户,并生成公司间冲销。 -6. 跨公司订单的信息投影和客服权限已实现,不能把完整订单给双方。 -7. 账号交接敏感内容已加密并按订单角色授权。 -8. 两边后台不能通过请求头、query、站点 ID 或成员关系越权查看对方数据。 - -### 26.2 P1 正式运营前完成项 - -- 全量报表改为角色口径,尤其区分买家订单、货源供货和号主收入。 -- 解忧独立公告、协议、短信、客服组、支付配置和通知模板。 -- 商品详情、图片、搜索、筛选和文件访问统一校验货架归属。 -- 所有租户后台导出、批量操作和审计日志检查租户边界。 -- 租户停用、用户注销、数据导出和保留期限流程。 -- 公司间对账单和退款冲销的财务确认流程。 - -### 26.3 P2 后续增强项 - -- 双向共享库存。 -- 租户级独立数据库或独立备份。 -- 自动清算和银行对账。 -- 多个品牌共享同一公司租户。 -- 独立应用服务和事件总线。 -- 平台成本自动分摊。 - -### 26.4 建议的首期明确不做 - -- 不复制两份后端代码。 -- 不让两个站点共享用户、JWT、支付商户或钱包余额。 -- 不在首期开放解忧商品反向供给旧站。 -- 不在首期开放积分商城、摸红、线下提号、广告后台和复杂运营财务。 -- 不让普通分销管理员保留“跨站切换”能力。 -- 不把“加一个 Logo”当作租户改造完成标准。 - -## 27. 仍需最终确认的业务决策 - -以下决策会改变数据模型或财务流程,建议按此顺序确认: - -| 顺序 | 决策 | 推荐答案 | 如果不这样选择的影响 | -|---|---|---|---| -| 1 | 谁来对解忧用户承担合同卖方责任 | 解忧 | 协议、发票、退款和支付商户都要重做 | -| 2 | 解忧购买旧站商品,钱进哪个商户 | 解忧商户 | 若进旧站商户,则解忧不是实际收款方,统计和披露会改变 | -| 3 | 首期是否只做旧站向解忧单向供货 | 是 | 双向供货需要同时开放两岸客服、售后和应付流程 | -| 4 | 同一手机号是否可在两个站独立注册 | 是,两个独立账号 | 若共享账号,就不是独立用户域,租户隔离边界失效 | -| 5 | 实名是否跨租户共享 | 默认不共享 | 若共享,需要用户明确授权、统一保留期限和跨公司访问审计 | -| 6 | 解忧用户的成长积分和优惠是否独立 | 独立 | 跨站共享会把一家公司的营销成本转嫁给另一家 | -| 7 | 跨站订单的号主收入记在哪 | 货源租户钱包 | 记在买方会形成跨公司用户资金混用 | -| 8 | 支付通道费由谁承担 | 实际收款租户 | 沿用“主站承担”会使解忧利润失真 | -| 9 | 公司间供货价如何确定 | 每单快照,可按商品或类目配置 | 只靠利润比例无法形成法律和财务应付 | -| 10 | 退款由谁对客处理 | 买方租户 | 货源方直接退款会暴露另一公司商户和主体 | -| 11 | 货源质量问题是否自动追偿 | 首期人工确认,自动生成冲销待办 | 全自动追偿容易造成错误扣款 | -| 12 | 买家能否看到号主手机号和实名 | 默认不能,仅通过受控订单会话 | 共享号库会增加跨公司个人信息暴露 | -| 13 | 两家公司后台是否允许查看对方用户 | 默认不允许,平台内部后台可审计查看 | 若允许,必须提供明确角色、目的和日志 | -| 14 | 哪一方负责跨站争议 | 买方先行、货源协作、平台仲裁 | 无责任归属会导致用户和号主互相推诿 | -| 15 | 是否需要独立 ICP、支付商户和隐私政策 | 需要 | 共用主体或政策会破坏“两个公司网站”的外部事实 | -| 16 | 是否需要物理数据库隔离 | 当前不需要 | 如合同要求 DBA 也不可互访,应改为独立库加中央库存服务 | -| 17 | 解忧首期开放哪些模块 | 仅租赁主链路 | 未租户化模块会直接形成越权和财务缺口 | - -建议先确认第 1~5 项和第 7~9 项。它们决定订单主模型、支付模型、实名唯一键和公司间账务,后期返工成本最高。 - -## 28. 第二轮新增证据索引 - -- 分账模式判定:[lifecycle.go](../backend/internal/modules/distribution/lifecycle.go) -- 分账计算与手续费口径:[pricing.go](../backend/internal/modules/distribution/pricing.go) -- 支付单按订单单站点选商户:[payment_start.go](../backend/internal/modules/payment/payment_start.go) -- 支付商户回退:[repository.go](../backend/internal/modules/payment/repository.go) -- 订单创建与来源快照:[lifecycle.go](../backend/internal/modules/order/lifecycle.go) -- 通知按订单模式反推站点:[repository.go](../backend/internal/modules/notification/repository.go) -- 会话单站点过滤:[conversation.go](../backend/internal/modules/chat/conversation.go) -- 交接记录明文内容:[handoff.go](../backend/internal/modules/order/handoff.go) -- 身份证全局唯一:[repository.go](../backend/internal/modules/realname/repository.go) -- 收款账户无租户:[repository.go](../backend/internal/modules/paymentaccount/repository.go) -- 后台管理员全局用户名:[admin_user.go](../backend/internal/model/admin_user.go) -- 分销成员登录读取首个站点:[repository.go](../backend/internal/modules/distribution/repository.go) -- 系统配置全局键:[repository.go](../backend/internal/modules/systemconfig/repository.go) -- 邀请返利配置和来源:[invitation.go](../backend/internal/model/invitation.go) -- 积分商城无租户:[points_mall.go](../backend/internal/model/points_mall.go) -- 文件所有权:[file_upload.go](../backend/internal/model/file_upload.go) - -## 29. 最终建议 - -当前项目可以支撑“渠道分站”,但距离“两个独立公司共用号库”还缺少四类基础能力:可信租户身份、角色化订单、租户化资金账务、跨公司履约与数据授权。 - -推荐最终落地为: - -1. 单后端、单主库,旧站和解忧都是显式租户。 -2. 商品和库存共享,租户货架和价格独立。 -3. 买方租户对客收款、退款、开票和承担第一责任客服。 -4. 货源租户提供库存、交接和号主结算。 -5. 支付商户严格归属,任何跨租户回退都失败关闭。 -6. 跨公司订单使用买方/货源/支付/合同卖方多角色建模。 -7. 用户信息、实名、钱包、后台权限、客服和统计按租户隔离。 -8. 跨公司资金使用独立应收应付账,不把利润比例当真实结算。 -9. 首期只开放旧站向解忧单向供货,完成验收后再考虑双向。 -10. 在真实支付和退款链路全部通过跨租户测试前,不解忧正式对外运营。 - -下一步应输出一份独立的实施设计稿,把本文第 21~25 节的方案细化为:租户权限矩阵、精确字段和索引变更、历史订单回填 SQL、跨租户状态机、公司间对账规则、测试用例和上线回滚清单。当前阶段仍不建议直接改业务代码或执行迁移。 diff --git a/docs/解忧商行双站点改造实施计划.md b/docs/解忧商行双站点改造实施计划.md new file mode 100644 index 00000000..f189421b --- /dev/null +++ b/docs/解忧商行双站点改造实施计划.md @@ -0,0 +1,369 @@ +# 解忧商行双站点改造方案 + +> 状态:MVP 基调稿 v2.0 +> 更新时间:2026-11-15 +> 目标:用一套后端、一套数据库和一套前端,上线大锤商行、解忧商行两个经营站点 + +## 1. 基调 + +首期只解决以下问题: + +- 两个站点共享同一号库和租赁库存。 +- 两个站点都有独立用户、登录、支付、钱包、后台权限和统计。 +- 两个站点都能发布商品,也都能购买对方货架上的商品。 +- 同一商品只能被一个租户成功锁定和出租。 +- 现有分销系统继续按旧逻辑运行,不升级成经营租户。 + +首期不建设完整公司会计系统,不做自动公司间结算、自动打款、复杂对账、双履约状态机或跨站内部案件。公司间货款先按订单报表线下确认和结算。 + +## 2. 不可混淆的概念 + +| 概念 | 定义 | +|---|---| +| 经营租户 | 大锤商行或解忧商行,存储于 `tenants` | +| 买方租户 | 用户实际下单、支付和接受对客服务的站点 | +| 货源租户 | 商品和号主所属的站点 | +| 支付租户 | 实际收取款项的站点,首期等于买方租户 | +| 租户货架 | `tenant_listing_offers`,表示共享商品在某个站点的展示和售价 | +| 历史分销站 | 现有 `distribution_sites`,仅保留旧分销渠道语义 | + +解忧不是分销站。不得把解忧写入 `distribution_sites`,不得用 `distribution_mode`、分销规则或分销结算表达经营租户。 + +买卖方向不固定: + +- 大锤用户可以购买解忧商品。 +- 解忧用户可以购买大锤商品。 +- 哪个站点发布商品,哪个站点就是货源租户。 +- 哪个站点的用户下单和付款,哪个站点就是买方租户和支付租户。 + +## 3. 首期范围 + +### 3.1 必须完成 + +- 域名到经营租户的服务端解析。 +- 两个站点独立注册、登录、JWT、短信和实名。 +- 共享商品、号主来源租户和双站货架。 +- 双站商品列表、详情、图片、搜索、货架价格和下单校验。 +- 订单记录买方租户、货源租户和支付租户。 +- 两个站点互相购买。 +- 支付商户、支付单和退款按租户隔离。 +- 用户钱包、提现、通知和后台数据按租户隔离。 +- 站点用户数、成交额、支付、退款、货源出货和号主结算统计。 +- 订单、会话、缓存、文件和定时任务带租户上下文。 +- 现有分销链路回归测试保持通过。 + +### 3.2 首期不做 + +- 公司间自动应收应付、总账、冲销和对账系统。 +- 自动银行清算、分账和公司间打款。 +- 独立的客户订单状态和货源供货状态机。 +- `fulfillment_tasks`、`order_tenant_roles` 等额外订单体系。 +- 客户会话、号主会话和平台内部案件三套聊天体系。 +- 独立租户二维码表。 +- 独立平台后台域名和租户后台域名。 +- 统一跨站客服工作台。 +- 双向自动铺货规则、复杂供货合同和自动追偿。 +- 与首期无关的撞车、积分、邀请、成长、优质号主、线下提号和广告归因改造。 + +## 4. 目标架构 + +```text +大锤域名 / 解忧域名 + | + Caddy / HTTPS + | + 同一套 Go 后端 + | + 同一个 MySQL + | + 共享号库和租赁库存 +``` + +保持一套后端、一套数据库和一套前端代码。两个站点通过 Host 解析租户,不复制服务,不建立租户独立数据库。 + +生产环境只信任服务端解析的 Host。未知域名失败关闭,不使用 query、`sessionStorage` 或 `X-Distribution-Site-Code` 切换经营租户。开发环境可以使用显式租户标识模拟站点。 + +## 5. 最小数据模型 + +### 5.1 新增核心表 + +| 表 | 作用 | +|---|---| +| `tenants` | 租户编码、名称、状态、品牌配置和功能配置 | +| `tenant_domains` | 租户域名、域名类型和启用状态 | +| `tenant_listing_offers` | 商品在某个租户货架的展示状态和销售价格 | + +首期不新增 `tenant_profiles`、`tenant_configs`、`tenant_feature_flags`、`tenant_memberships` 等重复抽象: + +- 品牌和功能配置放 `tenants.profile_json`、`tenants.features_json`。 +- 配置覆盖使用现有 `system_configs` 增加 `tenant_id`。 +- 后台人员租户范围通过现有 `admin_user_roles` 增加 `tenant_id`。 + +### 5.2 现有表增加租户字段 + +| 表 | 字段 | +|---|---| +| `users` | `tenant_id`,手机号唯一键改为 `(tenant_id, phone)` | +| `user_realname` | `tenant_id`,身份证唯一键改为 `(tenant_id, id_no_hash)` | +| `user_payment_accounts` | `tenant_id` | +| `wallet_accounts`、`wallet_ledger` | `tenant_id` | +| `withdrawal_requests` | `tenant_id` | +| `game_accounts` | `source_tenant_id` | +| `rental_listings` | `source_tenant_id`、`owner_tenant_id` | +| `rental_orders` | `buyer_tenant_id`、`source_tenant_id`、`payment_tenant_id`、`source_amount_cent` | +| `payment_merchant_configs` | `owner_tenant_id` | +| `payment_orders` | `tenant_id` | +| `notifications`、`sms_messages` | `tenant_id`、`source_tenant_id` | +| `chat_conversations`、`chat_support_groups`、`chat_quick_replies` | `tenant_id` | +| `chat_qrcode_pool`、`chat_qrcode_delivery_tasks` | `tenant_id` | +| `announcements` | `tenant_id` | +| `file_upload_owners` | `tenant_id` | +| `system_configs` | `tenant_id`,租户唯一键为 `(tenant_id, key)` | +| `admin_user_roles` | `tenant_id`,平台角色使用 `0` | + +现有 `distribution_*` 表不增加经营租户语义,继续服务历史分销。 + +### 5.3 订单必须保存的最小角色快照 + +```text +buyer_tenant_id +source_tenant_id +payment_tenant_id +source_amount_cent +``` + +约束: + +- 首期 `payment_tenant_id = buyer_tenant_id`。 +- 买方用户所属租户必须等于买方租户。 +- 号主用户所属租户必须等于货源租户。 +- 买方商品价格取租户货架价格。 +- 货源金额取商品基础价或双方确认的供货价,并在下单时固化。 + +不再增加合同卖方、履约方、争议方等可由上述字段推导的角色字段。 + +## 6. 用户、后台和权限 + +- 同一手机号可以在两个租户分别注册。 +- JWT 必须包含 `tenant_id` 和 `scope`。 +- 用户令牌只能访问令牌所属经营租户。 +- 短信验证码、登录失败、限流、实名和钱包 Key 都带租户。 +- 管理员仍是全局身份,通过 `admin_user_roles.tenant_id` 获得一个或多个租户角色。 +- 共享客服可以同时拥有两个租户的客服角色。 +- `super_admin` 使用 `tenant_id=0` 的平台角色,可以查看全部租户。 +- 首期复用同一套后台页面,通过当前 Host 确定租户;不拆独立后台域名。 +- 权限缓存 Key 至少包含管理员 ID 和租户 ID。 + +## 7. 共享号库和双站货架 + +### 7.1 商品来源 + +- 商品和游戏账号只有一份。 +- 商品发布人所属租户即为货源租户。 +- 货源租户负责商品、号主、交接和号主结算。 +- 买方租户不能修改货源租户的商品和号主信息。 + +### 7.2 货架 + +商品审核通过后,为大锤和解忧各创建一条 `tenant_listing_offers`: + +- 两个站点默认都可见。 +- 每个站点可以单独关闭展示。 +- 每个站点可以设置自己的销售价格。 +- 站点未启用的商品不得通过列表、详情、图片、搜索、分享链接或下单访问。 + +商品详情和图片必须根据当前租户货架校验,不能只依赖列表过滤。 + +### 7.3 库存 + +库存锁定继续使用 `rental_listings` 和共享账号行锁。两个租户同时下单时,只允许一笔订单成功占用商品。 + +## 8. 订单和双向购买 + +### 8.1 下单 + +同一数据库事务内完成: + +1. 校验买方用户属于当前租户。 +2. 校验租户货架已启用。 +3. 锁定商品和账号。 +4. 读取买方货架售价和货源金额。 +5. 创建一笔 `rental_orders`。 +6. 保存买方、货源、支付租户和价格快照。 +7. 锁定商品并写入买方订单通知。 + +### 8.2 订单展示 + +只保留一份订单和一套现有租赁状态机,按访问者角色过滤字段和操作: + +- 买方用户看到支付、客户资料、交付、归还、结账和退款操作。 +- 号主看到商品、交接、归还确认和结算信息。 +- 买方租户后台负责对客订单和退款。 +- 货源租户后台负责号主交接和货源出货。 +- 平台超级管理员可以查看完整订单。 + +同一订单可以在两个站点出现,但必须明确显示“本站买入”或“本站出货”,不能都叫“本站成交”。 + +### 8.3 跨租户流程 + +```text +A 站商品进入 B 站货架 + -> B 站用户下单并支付到 B 站商户 + -> A 站号主在 A 站处理交接 + -> B 站买方在 B 站确认收号和归还 + -> B 站记录客户成交和退款 + -> A 站记录货源出货和号主收入 + -> 两站货款线下结算 +``` + +大锤买解忧和 解忧买大锤使用同一逻辑,不写两套代码。 + +## 9. 支付、退款和钱包 + +- 买方订单只使用买方租户的支付商户。 +- 找不到本租户商户时支付失败,不回退其他租户。 +- 支付回调通过支付单定位租户,不依赖回调 Host。 +- 退款固定使用原支付单和原商户。 +- 原商户不可用时停止自动退款并告警。 +- 买方用户钱包、提现按买方租户隔离。 +- 号主收入进入货源租户用户钱包。 +- 支付成功不等于号主收入到账,号主结算仍由订单完成流程触发。 +- 首期不生成公司间总账。跨公司应结算金额通过订单快照和报表输出。 + +## 10. 独立统计 + +每个租户至少提供以下两组口径: + +| 口径 | 统计来源 | +|---|---| +| 本站用户 | `users.tenant_id` | +| 本站买入订单和客户 GMV | `rental_orders.buyer_tenant_id` | +| 本站支付和退款 | `payment_orders.tenant_id` | +| 本站卖出商品 | `rental_listings.source_tenant_id` | +| 本站出货订单 | `rental_orders.source_tenant_id` | +| 号主应结算 | 订单货源金额和号主结算金额 | + +平台统计按租户分组展示,不把两个租户的内部交易重复相加为公司 GMV。 + +## 11. 客服、通知、文件和任务 + +首期使用最小隔离: + +- 一笔订单创建一个订单会话,会话归属买方租户。 +- 买方和货源号主按订单角色参与该会话。 +- 共享客服必须拥有当前租户的客服角色才能查看和回复。 +- SSE 事件带 `tenant_id`,无权限管理员不能收到会话内容。 +- 二维码池增加 `tenant_id`,订单会话使用买方租户二维码。 +- 通知、短信、未读统计和消息缓存按租户隔离。 +- 私有文件上传和读取校验租户及业务角色。 +- 定时任务从订单、支付、会话等业务记录恢复租户,无法解析时暂停并告警。 + +首期不做客户会话、货源会话、内部案件的复杂拆分。 + +## 12. 历史分销兼容 + +- `distribution_sites`、分销后台、分销订单和分销结算保持现有逻辑。 +- 分销用户继续按 `distribution_site_id` 保持渠道归属。 +- 历史分销域名继续由现有分销解析逻辑处理。 +- 新经营租户订单不写分销财务快照。 +- 历史分销订单不根据 `distribution_site_id` 猜测经营租户。 +- 现有分销 E2E 测试必须全部保持通过。 + +## 13. 实施阶段 + +### 阶段 0:确认基调,1~2 天 + +- 确认两个站点都允许发布和购买。 +- 确认买方租户负责收款和退款。 +- 确认站间货款线下结算。 +- 确认首期不建设公司总账和双状态机。 + +### 阶段 1:租户和域名,3~5 天 + +- 新增 3 张核心表。 +- 实现 Host 解析和前端租户配置。 +- 完成 Caddy 域名校验和未知域名失败关闭。 + +### 阶段 2:用户、认证和后台权限,5~7 天 + +- 用户、实名、收款账户、钱包和提现增加租户。 +- JWT、短信和登录限流增加租户。 +- 后台角色和权限增加租户范围。 +- 完成同手机号双租户注册和越权测试。 + +### 阶段 3:共享商品和双站货架,4~6 天 + +- 商品增加来源租户。 +- 审核通过后生成两个站点的货架。 +- 列表、详情、图片、搜索和下单统一校验货架。 +- 完成双站并发抢号测试。 + +### 阶段 4:订单和统计,6~8 天 + +- 订单增加买方、货源、支付租户及货源金额快照。 +- 两个站点支持互相下单和角色化订单展示。 +- 完成买方统计、货源统计和平台统计。 + +### 阶段 5:支付、退款和钱包,4~6 天 + +- 支付配置和支付单增加租户。 +- 禁止跨租户商户回退。 +- 退款固定原商户。 +- 号主收入进入货源租户钱包。 + +### 阶段 6:客服、通知、文件和任务,4~6 天 + +- 会话、二维码、通知、短信和未读统计增加租户。 +- 文件访问增加租户和角色校验。 +- 定时任务按记录租户处理。 + +### 阶段 7:迁移、灰度上线,5~7 天 + +- 创建大锤和解忧租户。 +- 回填历史大锤用户和业务数据。 +- 生产库副本执行迁移和并发、支付、退款、越权测试。 +- 解忧先内部访问,再灰度开放。 + +预计 30~40 人日。两个后端、一个前端和测试并行时,约 4~6 周进入灰度。 + +## 14. 迁移和回滚 + +迁移顺序: + +1. 创建租户、域名和货架表。 +2. 创建大锤、解忧两个固定租户。 +3. 增加可空租户字段并回填历史大锤数据。 +4. 创建货架关系和复合索引。 +5. 切换新租户读写路径。 +6. 验证后给关键字段增加非空约束。 + +现有分销表不迁移为经营租户。 + +启用解忧前必须保留大锤完整回归数据。启用同手机号双租户后,应用回滚不能再退回旧全局手机号版本;故障回滚通过关闭解忧域名和功能开关、保留兼容代码完成。 + +## 15. 上线验收 + +- 未知域名不会落到大锤。 +- 同一手机号可以在两个租户注册。 +- 大锤 JWT 不能访问解忧数据,反向同样拒绝。 +- 两个站点都能看到双方开放的商品。 +- 未开放商品无法通过详情、图片、搜索或分享链接访问。 +- 两个租户并发购买同一账号只能成功一单。 +- 大锤用户能买解忧商品。 +- 解忧用户能买大锤商品。 +- 支付只进入买方租户商户,缺失时失败关闭。 +- 退款只使用原支付租户和原商户。 +- 两个站点的用户、订单、支付、钱包和统计互不串数据。 +- 无租户上下文的任务暂停并告警。 +- 现有分销 E2E 全部通过。 + +## 16. 后续增强 + +以下能力单独设计,不进入本次上线: + +- 公司间自动总账、对账和打款。 +- 自动供货合同和追偿。 +- 客户会话、货源会话、平台内部案件拆分。 +- 统一跨站客服工作台。 +- 独立平台后台域名和租户后台域名。 +- 自动双向铺货策略和复杂定价规则。 diff --git a/frontend/src/features/admin/views/AdminListingsView.vue b/frontend/src/features/admin/views/AdminListingsView.vue index ccfbc6d1..ecdffd3e 100644 --- a/frontend/src/features/admin/views/AdminListingsView.vue +++ b/frontend/src/features/admin/views/AdminListingsView.vue @@ -697,11 +697,6 @@ function resourceText(row: Listing, key: string) { return quantity > 0 ? formatQuantity(quantity) : '-' } -function skinGroupText(row: Listing, groupKey: string) { - const skins = getSkinGroup(row, groupKey) - return skins.length ? skins.join('、') : '-' -} - function skinAssetText(row: Listing) { const groups = [ { label: '刀', key: 'melee' }, diff --git a/frontend/src/features/listings/views/HomeView.vue b/frontend/src/features/listings/views/HomeView.vue index 65d0623c..2fd8bbf4 100644 --- a/frontend/src/features/listings/views/HomeView.vue +++ b/frontend/src/features/listings/views/HomeView.vue @@ -68,7 +68,7 @@ const displayAnnouncements = computed(() => { const banners = ref(defaultHomeBanners) const displayBanners = computed(() => { const list = - siteStore.isDistribution && siteStore.banners.length > 0 + siteStore.hasCustomBrand && siteStore.banners.length > 0 ? mapDistributionHomeBanners(siteStore.banners, siteStore.siteName) : banners.value return list.filter(slide => slide.enabled !== false) diff --git a/frontend/src/features/listings/views/MobileHomeView.vue b/frontend/src/features/listings/views/MobileHomeView.vue index 08fbfb74..cc16479a 100644 --- a/frontend/src/features/listings/views/MobileHomeView.vue +++ b/frontend/src/features/listings/views/MobileHomeView.vue @@ -114,7 +114,7 @@ const displayAnnouncements = computed(() => { const bannerSlides = ref(defaultHomeBanners) const displayBanners = computed(() => { const list = - siteStore.isDistribution && siteStore.banners.length > 0 + siteStore.hasCustomBrand && siteStore.banners.length > 0 ? mapDistributionHomeBanners(siteStore.banners, siteStore.siteName) : bannerSlides.value return list.filter(slide => slide.enabled !== false) @@ -873,15 +873,13 @@ if (!restoreHomeConfigFromCache()) {
- +
{{ siteStore.siteName }}
{{ - siteStore.isDistribution ? siteStore.storefrontText.tagline : '哈夫币租号' + siteStore.hasCustomBrand ? siteStore.storefrontText.tagline : '哈夫币租号' }}
diff --git a/frontend/src/layouts/AppLayout.vue b/frontend/src/layouts/AppLayout.vue index b0cf6a85..a0b40289 100644 --- a/frontend/src/layouts/AppLayout.vue +++ b/frontend/src/layouts/AppLayout.vue @@ -155,15 +155,13 @@ async function handleSupportClick() { alt="Site Logo" class="pc-brand-logo-img" /> - {{ - siteStore.isDistribution ? siteStore.siteName.slice(0, 1) : '锤' - }} + {{ siteStore.brandMark }}
{{ siteStore.siteName }}
{{ - siteStore.isDistribution ? siteStore.storefrontText.tagline : '哈夫币租号' + siteStore.hasCustomBrand ? siteStore.storefrontText.tagline : '哈夫币租号' }}
diff --git a/frontend/src/stores/distributionSite.ts b/frontend/src/stores/distributionSite.ts index c2c9aedb..2259e6c9 100644 --- a/frontend/src/stores/distributionSite.ts +++ b/frontend/src/stores/distributionSite.ts @@ -140,6 +140,27 @@ export interface DistributionSiteInfo { receive_cost_delta?: number } +export interface TenantSiteContext { + mode: 'tenant' + tenant_id: number + tenant_code: string + tenant_name: string + host: string + domain_type: string + status: string + profile: Record + features: Record +} + +export function shouldProbeTenantContext( + hostname: string, + _querySite: string, + _envCode: string +): boolean { + if (!hostname || hostname === 'localhost' || hostname === '127.0.0.1') return false + return !hostname.endsWith('.localhost') +} + /** * 获取当前上下文生效的分销站点编码 * 优先级: @@ -173,6 +194,10 @@ export const useDistributionSiteStore = defineStore('distributionSite', { return { siteCode: code, siteName: sessionStorage.getItem('hfb_site_name') || '大锤商行', + tenantId: 0, + tenantCode: '', + siteMode: 'legacy' as 'legacy' | 'tenant', + features: {} as Record, domain: '', isDistribution: Boolean(code), displayAccountEnabled: true, @@ -192,10 +217,18 @@ export const useDistributionSiteStore = defineStore('distributionSite', { getters: { /** 品牌标识字符:分站取站名首字,主站沿用「锤」。 */ brandMark(state): string { + if (state.siteMode === 'tenant') return state.siteName.slice(0, 1) || '锤' return state.isDistribution && state.siteName ? state.siteName.slice(0, 1) : '锤' }, + isTenant(state): boolean { + return state.siteMode === 'tenant' + }, + hasCustomBrand(state): boolean { + return state.siteMode === 'tenant' || state.isDistribution + }, /** 分站首页主标题:站名与主站联名。 */ coBrandName(state): string { + if (state.siteMode === 'tenant') return state.siteName || '大锤商行' return formatDistributionCoBrandName(state.siteName, state.isDistribution) }, }, @@ -212,6 +245,23 @@ export const useDistributionSiteStore = defineStore('distributionSite', { '' ).trim() + if (shouldProbeTenantContext(hostname, querySite, envCode)) { + try { + const { data } = await apiClient.get>('/site/context', { + silent: true, + skipErrorHandler: true, + }) + const info = data.data + if (info?.mode === 'tenant' && info.status === 'active') { + this.applyTenantContext(info) + this.initialized = true + return + } + } catch { + // 当前域名不是经营租户时继续走历史分销站点识别。 + } + } + // 1. 显式清除或重置为主站 if (querySite === 'main' || querySite === 'clear' || querySite === '0') { this.resetToMainSite() @@ -262,6 +312,10 @@ export const useDistributionSiteStore = defineStore('distributionSite', { if (info && info.site_code && info.status === 'active') { this.siteCode = info.site_code this.siteName = info.site_name || info.site_code + this.tenantId = 0 + this.tenantCode = '' + this.siteMode = 'legacy' + this.features = {} this.domain = info.domain || '' this.isDistribution = true this.displayAccountEnabled = info.display_account_enabled ?? true @@ -342,6 +396,10 @@ export const useDistributionSiteStore = defineStore('distributionSite', { resetToMainSite() { this.siteCode = '' this.siteName = '大锤商行' + this.tenantId = 0 + this.tenantCode = '' + this.siteMode = 'legacy' + this.features = {} this.domain = '' this.isDistribution = false this.displayAccountEnabled = true @@ -360,5 +418,77 @@ export const useDistributionSiteStore = defineStore('distributionSite', { localStorage.removeItem('hfb_site_name') document.title = '大锤商行 - 官方租号平台' }, + + applyTenantContext(info: TenantSiteContext) { + const profile = info.profile || {} + this.tenantId = Number(info.tenant_id || 0) + this.tenantCode = info.tenant_code || '' + this.siteMode = 'tenant' + this.features = info.features || {} + this.siteCode = '' + this.siteName = text(profile.site_name) || info.tenant_name || info.tenant_code + this.domain = info.host || '' + this.isDistribution = false + this.displayAccountEnabled = + typeof profile.display_account_enabled === 'boolean' + ? profile.display_account_enabled + : true + this.defaultSupportGroupId = + typeof profile.default_support_group_id === 'number' + ? profile.default_support_group_id + : null + this.logoUrl = text(profile.logo_url) + this.faviconUrl = text(profile.favicon_url) + this.banners = parseJSONArray(profile.banners_json) + this.announcements = normalizeAnnouncements( + parseJSONArray(profile.announcements_json) + ) + this.footerInfo = parseJSONObject(profile.footer_info_json) + this.storefrontText = mergeStorefrontText( + parseJSONObject>(profile.storefront_text_json) + ) + this.receiveRatioDelta = Math.max(0, Number(profile.receive_ratio_delta || 0)) + this.receiveCostDelta = Math.max(0, Number(profile.receive_cost_delta || 0)) + + sessionStorage.removeItem('hfb_site_code') + sessionStorage.removeItem('hfb_site_name') + localStorage.removeItem('hfb_site_code') + localStorage.removeItem('hfb_site_name') + document.title = `${this.siteName} - 官方租号平台` + this.applyFavicon() + }, + + applyFavicon() { + if (!this.faviconUrl || typeof document === 'undefined') return + let link = document.querySelector("link[rel*='icon']") as HTMLLinkElement | null + if (!link) { + link = document.createElement('link') + link.rel = 'icon' + document.head.appendChild(link) + } + link.href = this.faviconUrl + }, }, }) + +function parseJSONArray(value: unknown): T[] { + if (Array.isArray(value)) return value as T[] + if (typeof value !== 'string' || !value.trim()) return [] + try { + const parsed = JSON.parse(value) + return Array.isArray(parsed) ? parsed : [] + } catch { + return [] + } +} + +function parseJSONObject(value: unknown): T | null { + if (value && typeof value === 'object' && !Array.isArray(value)) return value as T + if (typeof value !== 'string' || !value.trim()) return null + try { + const parsed = JSON.parse(value) + return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as T) : null + } catch { + return null + } +} diff --git a/frontend/src/stores/siteContext.spec.ts b/frontend/src/stores/siteContext.spec.ts new file mode 100644 index 00000000..2030b820 --- /dev/null +++ b/frontend/src/stores/siteContext.spec.ts @@ -0,0 +1,21 @@ +import { describe, expect, it } from 'vitest' + +import { shouldProbeTenantContext } from './distributionSite' + +describe('shouldProbeTenantContext', () => { + it('正式域名优先探测经营租户', () => { + expect(shouldProbeTenantContext('zuhaox.com', '', '')).toBe(true) + expect(shouldProbeTenantContext('hfb.example.com', '', '')).toBe(true) + }) + + it('本地开发不主动探测,避免覆盖旧分销调试模式', () => { + expect(shouldProbeTenantContext('localhost', '', '')).toBe(false) + expect(shouldProbeTenantContext('127.0.0.1', '', '')).toBe(false) + expect(shouldProbeTenantContext('site.localhost', '', '')).toBe(false) + }) + + it('正式域名先识别经营租户,不能通过旧分站参数覆盖', () => { + expect(shouldProbeTenantContext('zuhaox.com', 'branch_a', '')).toBe(true) + expect(shouldProbeTenantContext('zuhaox.com', '', 'branch_b')).toBe(true) + }) +})