feat(ECR-041): OpsCMS Banner 薄写面（Write-Wave 首刀）

Admin POST/PUT + admin.cms.write/审计；C 端 GET /home/banners；首页投影回退静态 homeFeeds；migration 000051；不碰 FeedSlot/支付/UGC。

Co-authored-by: Cursor <cursoragent@cursor.com>

apps/api/internal/handler/admin_cms.go

@@ -16,6 +16,8 @@ func (h *AdminHandler) registerCMS(authed *gin.RouterGroup) {
 	g := authed.Group("/cms")
 	g.GET("/banners", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.ListBanners)
 	g.GET("/banners/:id", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.GetBanner)
+	g.POST("/banners", middleware.RequireAdminPermission(h.Svc, admin.PermCMSWrite), h.CreateBanner)
+	g.PUT("/banners/:id", middleware.RequireAdminPermission(h.Svc, admin.PermCMSWrite), h.UpdateBanner)
 	g.GET("/feed-slots", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.ListFeedSlots)
 	g.GET("/feed-slots/:id", middleware.RequireAdminPermission(h.Svc, admin.PermCMSRead), h.GetFeedSlot)
 }
@@ -47,6 +49,69 @@ func (h *AdminHandler) GetBanner(c *gin.Context) {
 	response.OK(c, row)
 }
 
+func (h *AdminHandler) CreateBanner(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40101, "admin auth required")
+		return
+	}
+	var body admin.BannerWriteBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		response.Fail(c, http.StatusBadRequest, 40050, "invalid body")
+		return
+	}
+	row, err := h.Svc.CreateBanner(c.Request.Context(), adminID, body)
+	if errors.Is(err, admin.ErrInvalidBanner) {
+		response.Fail(c, http.StatusBadRequest, 40051, "invalid banner")
+		return
+	}
+	if errors.Is(err, admin.ErrBannerConflict) {
+		response.Fail(c, http.StatusConflict, 40910, "banner code conflict")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50044, "create banner failed")
+		return
+	}
+	response.OK(c, row)
+}
+
+func (h *AdminHandler) UpdateBanner(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40101, "admin auth required")
+		return
+	}
+	id, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40002, "invalid id")
+		return
+	}
+	var body admin.BannerWriteBody
+	if err := c.ShouldBindJSON(&body); err != nil {
+		response.Fail(c, http.StatusBadRequest, 40050, "invalid body")
+		return
+	}
+	row, err := h.Svc.UpdateBanner(c.Request.Context(), adminID, id, body)
+	if errors.Is(err, admin.ErrBannerNotFound) {
+		response.Fail(c, http.StatusNotFound, 40410, "banner not found")
+		return
+	}
+	if errors.Is(err, admin.ErrInvalidBanner) {
+		response.Fail(c, http.StatusBadRequest, 40051, "invalid banner")
+		return
+	}
+	if errors.Is(err, admin.ErrBannerConflict) {
+		response.Fail(c, http.StatusConflict, 40910, "banner code conflict")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50045, "update banner failed")
+		return
+	}
+	response.OK(c, row)
+}
+
 func (h *AdminHandler) ListFeedSlots(c *gin.Context) {
 	items, err := h.Svc.ListFeedSlots(c.Request.Context())
 	if err != nil {

apps/api/internal/handler/home.go

@@ -20,6 +20,7 @@ type HomeHandler struct {
 func (h *HomeHandler) Register(api *gin.RouterGroup) {
 	g := api.Group("/home")
 	g.GET("/tools", h.Tools)
+	g.GET("/banners", h.Banners)
 	g.GET("/daily-tips", h.DailyTips)
 }
 
@@ -35,6 +36,16 @@ func (h *HomeHandler) Tools(c *gin.Context) {
 	response.OK(c, gin.H{"items": items})
 }
 
+func (h *HomeHandler) Banners(c *gin.Context) {
+	placement := c.DefaultQuery("placement", "home")
+	items, err := h.Svc.ListPublicBanners(c.Request.Context(), placement)
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50046, "home banners failed")
+		return
+	}
+	response.OK(c, gin.H{"items": items})
+}
+
 func (h *HomeHandler) DailyTips(c *gin.Context) {
 	uid, _ := middleware.UserIDFromContext(c)
 	tips, err := h.Svc.DailyTips(c.Request.Context(), uid)

apps/api/internal/httpserver/router.go

@@ -66,6 +66,7 @@ func NewRouter(pool *pgxpool.Pool, cfg config.Config) *gin.Engine {
 		Repo:     &repository.HomeToolsRepo{Pool: pool},
 		Tips:     &repository.HomeDailyTipsRepo{Pool: pool},
 		Profiles: profileRepo,
+		CMS:      adminRepo,
 		LLM:      llm,
 	}
 	analyticsSvc := &analyticssvc.Service{Repo: analyticsRepo}

apps/api/internal/integration/cms_banner_write_test.go

@@ -0,0 +1,137 @@
+package integration_test
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"golang.org/x/crypto/bcrypt"
+)
+
+func TestOpsCMSBannerWrite(t *testing.T) {
+	r, pool := setupAPIPool(t)
+	ctx := context.Background()
+	tok := adminLogin(t, r, "admin", "change-me")
+	devKey := fmt.Sprintf("banner-write-%d", time.Now().UnixNano())
+
+	code := fmt.Sprintf("home_w_%d", time.Now().UnixNano()%1_000_000)
+	body := map[string]any{
+		"code": code, "title": "写面横幅", "placement": "home",
+		"link_path": "/membership", "sort_order": 3, "active": true,
+	}
+	env, httpCode := doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/cms/banners", body, tok)
+	if httpCode != 200 || env.Code != 0 {
+		t.Fatalf("create http=%d code=%d msg=%s", httpCode, env.Code, env.Message)
+	}
+	var created struct {
+		ID   string `json:"id"`
+		Code string `json:"code"`
+	}
+	_ = json.Unmarshal(env.Data, &created)
+	if created.ID == "" || created.Code != code {
+		t.Fatalf("bad create %#v", created)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM ops_banners WHERE id=$1`, created.ID)
+	})
+
+	_, httpCode = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/cms/banners", body, tok)
+	if httpCode != http.StatusConflict {
+		t.Fatalf("dup expected 409 got %d", httpCode)
+	}
+
+	_, httpCode = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/cms/banners", map[string]any{
+		"code": code + "_x", "title": "外链", "placement": "home",
+		"link_path": "https://evil.example", "active": true,
+	}, tok)
+	if httpCode != http.StatusBadRequest {
+		t.Fatalf("ext link expected 400 got %d", httpCode)
+	}
+
+	env, _, httpCode = doJSONExpect(t, r, http.MethodGet, "/api/v1/home/banners?placement=home", nil, devKey, 0)
+	if httpCode != 200 {
+		t.Fatalf("home banners http=%d", httpCode)
+	}
+	var pub struct {
+		Items []struct {
+			Code string `json:"code"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &pub)
+	found := false
+	for _, it := range pub.Items {
+		if it.Code == code {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("active banner missing in C-end: %#v", pub.Items)
+	}
+
+	body["active"] = false
+	body["title"] = "已下架"
+	env, httpCode = doAdminJSON(t, r, http.MethodPut, "/api/v1/admin/cms/banners/"+created.ID, body, tok)
+	if httpCode != 200 || env.Code != 0 {
+		t.Fatalf("update %d %s", httpCode, env.Message)
+	}
+
+	env, _, httpCode = doJSONExpect(t, r, http.MethodGet, "/api/v1/home/banners?placement=home", nil, devKey, 0)
+	if httpCode != 200 {
+		t.Fatalf("home after deactivate %d", httpCode)
+	}
+	_ = json.Unmarshal(env.Data, &pub)
+	for _, it := range pub.Items {
+		if it.Code == code {
+			t.Fatalf("inactive still listed")
+		}
+	}
+
+	var n int
+	err := pool.QueryRow(ctx, `
+		SELECT COUNT(*) FROM admin_audit_logs
+		WHERE action IN ('cms.banner.create','cms.banner.update') AND target_id=$1`,
+		created.ID).Scan(&n)
+	if err != nil || n < 2 {
+		t.Fatalf("expected ≥2 audit rows, got %d err=%v", n, err)
+	}
+
+	limitedRoleID := uuid.New()
+	_, err = pool.Exec(ctx, `
+		INSERT INTO admin_roles(id, name, system) VALUES ($1,$2,false)`,
+		limitedRoleID, "cms_ro_"+limitedRoleID.String()[:8])
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = pool.Exec(ctx, `
+		INSERT INTO admin_role_permissions(role_id, code) VALUES ($1,'admin.cms.read')`, limitedRoleID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	hash, err := bcrypt.GenerateFromPassword([]byte("ro-pass"), bcrypt.DefaultCost)
+	if err != nil {
+		t.Fatal(err)
+	}
+	roUser := fmt.Sprintf("cmsro_%d", time.Now().UnixNano())
+	_, err = pool.Exec(ctx, `
+		INSERT INTO admin_accounts(username, password_hash, role_id) VALUES ($1,$2,$3)`,
+		roUser, string(hash), limitedRoleID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_accounts WHERE username=$1`, roUser)
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_roles WHERE id=$1`, limitedRoleID)
+	})
+	roTok := adminLogin(t, r, roUser, "ro-pass")
+	_, httpCode = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/cms/banners", map[string]any{
+		"code": "x_ro", "title": "no", "placement": "home", "active": true,
+	}, roTok)
+	if httpCode != http.StatusForbidden {
+		t.Fatalf("read-only write expected 403 got %d", httpCode)
+	}
+}

apps/api/internal/repository/cms_banner_write.go

@@ -0,0 +1,162 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+)
+
+// BannerWriteInput is create/update payload for ops_banners.
+type BannerWriteInput struct {
+	Code      string
+	Title     string
+	Placement string
+	ImageURL  *string
+	LinkPath  *string
+	SortOrder int
+	Active    bool
+}
+
+// ListActiveBanners returns active banners for a placement (C-end).
+func (r *AdminRepo) ListActiveBanners(ctx context.Context, placement string) ([]BannerRow, error) {
+	rows, err := r.Pool.Query(ctx, `
+		SELECT id, code, title, placement, image_url, link_path, sort_order, active, system, updated_at
+		FROM ops_banners
+		WHERE active = true AND placement = $1
+		ORDER BY sort_order ASC, code ASC
+		LIMIT 100`, placement)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []BannerRow
+	for rows.Next() {
+		var b BannerRow
+		if err := rows.Scan(
+			&b.ID, &b.Code, &b.Title, &b.Placement, &b.ImageURL, &b.LinkPath,
+			&b.SortOrder, &b.Active, &b.System, &b.UpdatedAt,
+		); err != nil {
+			return nil, err
+		}
+		out = append(out, b)
+	}
+	return out, rows.Err()
+}
+
+// CreateBannerWithAudit inserts a banner and audits.
+func (r *AdminRepo) CreateBannerWithAudit(
+	ctx context.Context,
+	adminID uuid.UUID,
+	in BannerWriteInput,
+	meta json.RawMessage,
+) (*BannerRow, error) {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var b BannerRow
+	err = tx.QueryRow(ctx, `
+		INSERT INTO ops_banners(code, title, placement, image_url, link_path, sort_order, active, system)
+		VALUES ($1,$2,$3,$4,$5,$6,$7,false)
+		RETURNING id, code, title, placement, image_url, link_path, sort_order, active, system, updated_at`,
+		in.Code, in.Title, in.Placement, in.ImageURL, in.LinkPath, in.SortOrder, in.Active,
+	).Scan(
+		&b.ID, &b.Code, &b.Title, &b.Placement, &b.ImageURL, &b.LinkPath,
+		&b.SortOrder, &b.Active, &b.System, &b.UpdatedAt,
+	)
+	if err != nil {
+		return nil, mapBannerWriteErr(err)
+	}
+	if meta == nil {
+		meta = json.RawMessage(`{}`)
+	}
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO admin_audit_logs(admin_id, action, target_type, target_id, meta)
+		VALUES ($1,'cms.banner.create','banner',$2,$3)`,
+		adminID, b.ID.String(), meta,
+	); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	return &b, nil
+}
+
+// UpdateBannerWithAudit updates mutable fields and audits.
+func (r *AdminRepo) UpdateBannerWithAudit(
+	ctx context.Context,
+	adminID, id uuid.UUID,
+	in BannerWriteInput,
+	meta json.RawMessage,
+) (*BannerRow, error) {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	defer tx.Rollback(ctx)
+
+	var system bool
+	var oldCode string
+	err = tx.QueryRow(ctx, `SELECT system, code FROM ops_banners WHERE id=$1`, id).Scan(&system, &oldCode)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, pgx.ErrNoRows
+	}
+	if err != nil {
+		return nil, err
+	}
+	code := in.Code
+	if system {
+		code = oldCode
+	}
+
+	var b BannerRow
+	err = tx.QueryRow(ctx, `
+		UPDATE ops_banners
+		SET code=$2, title=$3, placement=$4, image_url=$5, link_path=$6,
+		    sort_order=$7, active=$8, updated_at=now()
+		WHERE id=$1
+		RETURNING id, code, title, placement, image_url, link_path, sort_order, active, system, updated_at`,
+		id, code, in.Title, in.Placement, in.ImageURL, in.LinkPath, in.SortOrder, in.Active,
+	).Scan(
+		&b.ID, &b.Code, &b.Title, &b.Placement, &b.ImageURL, &b.LinkPath,
+		&b.SortOrder, &b.Active, &b.System, &b.UpdatedAt,
+	)
+	if err != nil {
+		return nil, mapBannerWriteErr(err)
+	}
+	if meta == nil {
+		meta = json.RawMessage(`{}`)
+	}
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO admin_audit_logs(admin_id, action, target_type, target_id, meta)
+		VALUES ($1,'cms.banner.update','banner',$2,$3)`,
+		adminID, id.String(), meta,
+	); err != nil {
+		return nil, err
+	}
+	if err := tx.Commit(ctx); err != nil {
+		return nil, err
+	}
+	return &b, nil
+}
+
+func mapBannerWriteErr(err error) error {
+	var pgErr *pgconn.PgError
+	if errors.As(err, &pgErr) && pgErr.Code == "23505" {
+		return errString("banner code conflict")
+	}
+	return err
+}
+
+// BannerCodeConflict reports unique code violation.
+func BannerCodeConflict(err error) bool {
+	return err != nil && strings.Contains(err.Error(), "banner code conflict")
+}

apps/api/internal/service/admin/cms_write.go

@@ -0,0 +1,110 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/repository"
+)
+
+var (
+	ErrInvalidBanner   = errors.New("invalid banner")
+	ErrBannerConflict  = errors.New("banner code conflict")
+	bannerPathRe       = regexp.MustCompile(`^/[a-zA-Z0-9_./-]{1,200}$`)
+	bannerPlacements   = map[string]struct{}{"home": {}, "explore": {}, "ask": {}}
+	bannerCodeRe       = regexp.MustCompile(`^[a-z][a-z0-9_]{1,62}$`)
+)
+
+// BannerWriteBody is JSON for create/update.
+type BannerWriteBody struct {
+	Code      string  `json:"code"`
+	Title     string  `json:"title"`
+	Placement string  `json:"placement"`
+	ImageURL  *string `json:"image_url"`
+	LinkPath  *string `json:"link_path"`
+	SortOrder int     `json:"sort_order"`
+	Active    bool    `json:"active"`
+}
+
+// CreateBanner validates, inserts, audits.
+func (s *Service) CreateBanner(ctx context.Context, adminID uuid.UUID, body BannerWriteBody) (*repository.BannerRow, error) {
+	in, err := normalizeBannerWrite(body, true)
+	if err != nil {
+		return nil, err
+	}
+	meta, _ := json.Marshal(map[string]any{"code": in.Code, "active": in.Active})
+	row, err := s.Repo.CreateBannerWithAudit(ctx, adminID, in, meta)
+	if repository.BannerCodeConflict(err) {
+		return nil, ErrBannerConflict
+	}
+	return row, err
+}
+
+// UpdateBanner validates, updates, audits.
+func (s *Service) UpdateBanner(ctx context.Context, adminID, id uuid.UUID, body BannerWriteBody) (*repository.BannerRow, error) {
+	in, err := normalizeBannerWrite(body, true)
+	if err != nil {
+		return nil, err
+	}
+	meta, _ := json.Marshal(map[string]any{"code": in.Code, "active": in.Active})
+	row, err := s.Repo.UpdateBannerWithAudit(ctx, adminID, id, in, meta)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrBannerNotFound
+	}
+	if repository.BannerCodeConflict(err) {
+		return nil, ErrBannerConflict
+	}
+	return row, err
+}
+
+func normalizeBannerWrite(body BannerWriteBody, requireCode bool) (repository.BannerWriteInput, error) {
+	code := strings.TrimSpace(body.Code)
+	title := strings.TrimSpace(body.Title)
+	placement := strings.TrimSpace(body.Placement)
+	if requireCode && code == "" {
+		return repository.BannerWriteInput{}, ErrInvalidBanner
+	}
+	if code != "" && !bannerCodeRe.MatchString(code) {
+		return repository.BannerWriteInput{}, ErrInvalidBanner
+	}
+	if title == "" || utf8.RuneCountInString(title) > 128 {
+		return repository.BannerWriteInput{}, ErrInvalidBanner
+	}
+	if _, ok := bannerPlacements[placement]; !ok {
+		return repository.BannerWriteInput{}, ErrInvalidBanner
+	}
+	var link *string
+	if body.LinkPath != nil {
+		lp := strings.TrimSpace(*body.LinkPath)
+		if lp == "" {
+			link = nil
+		} else {
+			if strings.Contains(lp, "://") || !bannerPathRe.MatchString(lp) {
+				return repository.BannerWriteInput{}, ErrInvalidBanner
+			}
+			link = &lp
+		}
+	}
+	var img *string
+	if body.ImageURL != nil {
+		u := strings.TrimSpace(*body.ImageURL)
+		if u == "" {
+			img = nil
+		} else if utf8.RuneCountInString(u) > 2000 {
+			return repository.BannerWriteInput{}, ErrInvalidBanner
+		} else {
+			img = &u
+		}
+	}
+	return repository.BannerWriteInput{
+		Code: code, Title: title, Placement: placement,
+		ImageURL: img, LinkPath: link, SortOrder: body.SortOrder, Active: body.Active,
+	}, nil
+}

apps/api/internal/service/admin/rbac.go

@@ -31,6 +31,7 @@ const (
 	PermAIConfigRead         = "admin.ai_config.read"
 	PermCrisisRead           = "admin.crisis.read"
 	PermCMSRead              = "admin.cms.read"
+	PermCMSWrite             = "admin.cms.write"
 	PermPrivacyRead = "admin.privacy.read"
 	PermExploreRead = "admin.explore.read"
 	PermGrowthRead = "admin.growth.read"
@@ -43,7 +44,7 @@ var knownPermissions = map[string]struct{}{
 	PermUsersStatusWrite: {}, PermMembershipPlansRead: {}, PermMembershipPlansWrite: {},
 	PermMembershipCodesRead: {}, PermMembershipCodesWrite: {},
 	PermAskRead: {}, PermAskTranscriptRead: {}, PermAskFeedbackWrite: {}, PermContentSafetyRead: {},
-	PermAIConfigRead: {}, PermCrisisRead: {}, PermCMSRead: {}, PermGrowthRead: {}, PermExploreRead: {}, PermPrivacyRead: {},
+	PermAIConfigRead: {}, PermCrisisRead: {}, PermCMSRead: {}, PermCMSWrite: {}, PermGrowthRead: {}, PermExploreRead: {}, PermPrivacyRead: {},
 }
 
 var (

apps/api/internal/service/home/service.go

@@ -31,6 +31,7 @@ type Service struct {
 	Repo     *repository.HomeToolsRepo
 	Tips     *repository.HomeDailyTipsRepo
 	Profiles *repository.ProfileRepo
+	CMS      *repository.AdminRepo
 	LLM      *deepseek.Client
 }
 
@@ -39,6 +40,24 @@ func (s *Service) ListPublic(ctx context.Context) ([]repository.HomeTool, error)
 	return s.Repo.ListEnabled(ctx)
 }
 
+// ListPublicBanners returns active banners for placement (default home).
+func (s *Service) ListPublicBanners(ctx context.Context, placement string) ([]repository.BannerRow, error) {
+	if placement == "" {
+		placement = "home"
+	}
+	if s.CMS == nil {
+		return []repository.BannerRow{}, nil
+	}
+	items, err := s.CMS.ListActiveBanners(ctx, placement)
+	if err != nil {
+		return nil, err
+	}
+	if items == nil {
+		items = []repository.BannerRow{}
+	}
+	return items, nil
+}
+
 // ListAdmin returns all tools.
 func (s *Service) ListAdmin(ctx context.Context) ([]repository.HomeTool, error) {
 	return s.Repo.ListAll(ctx)