feat(ECR-013B): AccountLifecycle Closed；启用 Loop 连续执行

UserStatus 迁移、DeviceAuth 拒绝非 active、admin-h5 CTA； Reviewer Closed。Human 授权 LOOP_AUTHORIZATION（免逐闸确认）。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 17:47:18 +08:00
parent f75b42397f
commit e25cd94b0c
33 changed files with 799 additions and 56 deletions
@@ -43,6 +43,7 @@ func (h *AdminHandler) Register(api *gin.RouterGroup) {
 	authed.GET("/analytics/funnel", middleware.RequireAdminPermission(h.Svc, admin.PermAnalyticsRead), h.AnalyticsFunnel)
 	h.registerContent(authed)
 	h.registerRBAC(authed)
+	h.registerLifecycle(authed)
 }

 func (h *AdminHandler) Login(c *gin.Context) {
@@ -0,0 +1,78 @@
+package handler
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/middleware"
+	"github.com/yuxingu/digital-psychology/apps/api/internal/service/admin"
+	"github.com/yuxingu/digital-psychology/apps/api/pkg/response"
+)
+
+func (h *AdminHandler) registerLifecycle(authed *gin.RouterGroup) {
+	authed.POST("/users/:id/status", middleware.RequireAdminPermission(h.Svc, admin.PermUsersStatusWrite), h.PostUserStatus)
+	authed.GET("/users/:id/status-transitions", middleware.RequireAdminPermission(h.Svc, admin.PermUsersRead), h.ListUserStatusTransitions)
+}
+
+func (h *AdminHandler) PostUserStatus(c *gin.Context) {
+	adminID, ok := middleware.AdminIDFromContext(c)
+	if !ok {
+		response.Fail(c, http.StatusUnauthorized, 40102, "admin session invalid")
+		return
+	}
+	userID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40000, "invalid id")
+		return
+	}
+	var body struct {
+		Status string `json:"status"`
+		Reason string `json:"reason"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil || body.Status == "" {
+		response.Fail(c, http.StatusBadRequest, 40000, "status required")
+		return
+	}
+	err = h.Svc.TransitionUserStatus(c.Request.Context(), adminID, userID, body.Status, body.Reason)
+	if errors.Is(err, admin.ErrUserNotFound) {
+		response.Fail(c, http.StatusNotFound, 40400, "user not found")
+		return
+	}
+	if errors.Is(err, admin.ErrReasonRequired) || errors.Is(err, admin.ErrInvalidStatusEdge) {
+		response.Fail(c, http.StatusBadRequest, 40000, err.Error())
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	detail, err := h.Svc.GetUser(c.Request.Context(), userID)
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	response.OK(c, detail)
+}
+
+func (h *AdminHandler) ListUserStatusTransitions(c *gin.Context) {
+	userID, err := uuid.Parse(c.Param("id"))
+	if err != nil {
+		response.Fail(c, http.StatusBadRequest, 40000, "invalid id")
+		return
+	}
+	limit, _ := strconv.Atoi(c.DefaultQuery("limit", "50"))
+	items, err := h.Svc.ListStatusTransitions(c.Request.Context(), userID, limit)
+	if errors.Is(err, admin.ErrUserNotFound) {
+		response.Fail(c, http.StatusNotFound, 40400, "user not found")
+		return
+	}
+	if err != nil {
+		response.Fail(c, http.StatusInternalServerError, 50000, err.Error())
+		return
+	}
+	response.OK(c, gin.H{"items": items})
+}
@@ -1,6 +1,7 @@
 package handler

 import (
+	"errors"
 	"net/http"
 	"strings"

@@ -46,6 +47,10 @@ func (h *AuthHandler) RegisterAccount(c *gin.Context) {
 	deviceKey := c.GetHeader(middleware.DeviceKeyHeader)
 	res, err := h.Svc.Register(c.Request.Context(), userID, deviceKey, body.Phone, body.Password, body.Nickname)
 	if err != nil {
+		if errors.Is(err, auth.ErrAccountRestricted) {
+			response.Fail(c, http.StatusUnauthorized, 40113, err.Error())
+			return
+		}
 		response.Fail(c, http.StatusBadRequest, 40110, err.Error())
 		return
 	}
@@ -67,6 +72,10 @@ func (h *AuthHandler) Login(c *gin.Context) {
 	deviceKey := c.GetHeader(middleware.DeviceKeyHeader)
 	res, err := h.Svc.Login(c.Request.Context(), userID, deviceKey, body.Phone, body.Password)
 	if err != nil {
+		if errors.Is(err, auth.ErrAccountRestricted) {
+			response.Fail(c, http.StatusUnauthorized, 40113, err.Error())
+			return
+		}
 		response.Fail(c, http.StatusBadRequest, 40111, err.Error())
 		return
 	}
@@ -0,0 +1,166 @@
+package integration_test
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+	"golang.org/x/crypto/bcrypt"
+)
+
+func TestAccountLifecycle(t *testing.T) {
+	r, pool := setupAPIPool(t)
+	ctx := context.Background()
+	superTok := adminLogin(t, r, "admin", "change-me")
+
+	// AC-S-03 / AC-S-04: no admin session
+	_, code := doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+uuid.New().String()+"/status",
+		map[string]string{"status": "banned", "reason": "x"}, "")
+	if code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 POST status, got %d", code)
+	}
+	_, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/users/"+uuid.New().String()+"/status-transitions", nil, "")
+	if code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 GET transitions, got %d", code)
+	}
+
+	key := mustRegister(t, r)
+	env, code := doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/users", nil, superTok)
+	if code != 200 {
+		t.Fatalf("list users: %d", code)
+	}
+	var list struct {
+		Items []struct {
+			ID string `json:"id"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &list)
+	if len(list.Items) == 0 {
+		t.Fatal("need user")
+	}
+	userID := list.Items[0].ID
+
+	// AC-F-01 ban
+	env, code = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+userID+"/status",
+		map[string]string{"status": "banned", "reason": "abuse"}, superTok)
+	if code != 200 || env.Code != 0 {
+		t.Fatalf("ban failed http=%d code=%d msg=%s", code, env.Code, env.Message)
+	}
+	var detail struct {
+		Status string `json:"status"`
+	}
+	_ = json.Unmarshal(env.Data, &detail)
+	if detail.Status != "banned" {
+		t.Fatalf("expected banned, got %s", detail.Status)
+	}
+
+	// AC-F-03 same status
+	_, code = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+userID+"/status",
+		map[string]string{"status": "banned", "reason": "again"}, superTok)
+	if code != http.StatusBadRequest {
+		t.Fatalf("expected 400 same status, got %d", code)
+	}
+
+	// AC-S-02 C-end reject
+	if code := deviceGET(t, r, "/api/v1/auth/me", key, testBearer); code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 banned bearer, got %d", code)
+	}
+
+	// AC-F-04 + AC-P-01 + AC-O
+	start := time.Now()
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/users/"+userID+"/status-transitions?limit=50", nil, superTok)
+	if code != 200 || time.Since(start) > 500*time.Millisecond {
+		t.Fatalf("transitions failed/slow http=%d dur=%v", code, time.Since(start))
+	}
+	var tr struct {
+		Items []struct {
+			FromStatus string `json:"from_status"`
+			ToStatus   string `json:"to_status"`
+			Reason     string `json:"reason"`
+			AdminID    string `json:"admin_id"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &tr)
+	if len(tr.Items) == 0 || tr.Items[0].ToStatus != "banned" || tr.Items[0].Reason != "abuse" || tr.Items[0].AdminID == "" {
+		t.Fatalf("unexpected transitions %#v", tr.Items)
+	}
+
+	env, code = doAdminJSON(t, r, http.MethodGet, "/api/v1/admin/audit-logs", nil, superTok)
+	if code != 200 {
+		t.Fatalf("audit %d", code)
+	}
+	var audit struct {
+		Items []struct {
+			Action string `json:"action"`
+		} `json:"items"`
+	}
+	_ = json.Unmarshal(env.Data, &audit)
+	found := false
+	for _, it := range audit.Items {
+		if it.Action == "users.status.transition" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("missing users.status.transition audit")
+	}
+
+	// AC-F-02 restore
+	_, code = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+userID+"/status",
+		map[string]string{"status": "active", "reason": "appeal"}, superTok)
+	if code != 200 {
+		t.Fatalf("restore failed %d", code)
+	}
+	if code := deviceGET(t, r, "/api/v1/auth/me", key, testBearer); code != 200 {
+		t.Fatalf("expected me ok after unban, got %d", code)
+	}
+
+	// AC-S-01 limited admin without status.write
+	limitedRoleID := uuid.New()
+	_, err := pool.Exec(ctx, `
+		INSERT INTO admin_roles(id, name, system) VALUES ($1,$2,false)`, limitedRoleID, "lc_"+limitedRoleID.String()[:8])
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, _ = pool.Exec(ctx, `
+		INSERT INTO admin_role_permissions(role_id, code) VALUES ($1,'admin.users.read')`, limitedRoleID)
+	hash, _ := bcrypt.GenerateFromPassword([]byte("limited-pass"), bcrypt.DefaultCost)
+	limitedUser := fmt.Sprintf("lc_%d", time.Now().UnixNano())
+	_, err = pool.Exec(ctx, `
+		INSERT INTO admin_accounts(username, password_hash, role_id) VALUES ($1,$2,$3)`,
+		limitedUser, string(hash), limitedRoleID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_accounts WHERE username=$1`, limitedUser)
+		_, _ = pool.Exec(ctx, `DELETE FROM admin_roles WHERE id=$1`, limitedRoleID)
+	})
+	limitedTok := adminLogin(t, r, limitedUser, "limited-pass")
+	_, code = doAdminJSON(t, r, http.MethodPost, "/api/v1/admin/users/"+userID+"/status",
+		map[string]string{"status": "suspended", "reason": "nope"}, limitedTok)
+	if code != http.StatusForbidden {
+		t.Fatalf("expected 403 status.write, got %d", code)
+	}
+}
+
+func deviceGET(t *testing.T, r http.Handler, path, deviceKey, bearer string) int {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodGet, path, bytes.NewReader(nil))
+	if deviceKey != "" {
+		req.Header.Set("X-Device-Key", deviceKey)
+	}
+	if bearer != "" {
+		req.Header.Set("Authorization", "Bearer "+bearer)
+	}
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	return w.Code
+}
@@ -38,6 +38,9 @@ func DeviceAuth(pool *pgxpool.Pool) gin.HandlerFunc {
 				WHERE token=$1 AND revoked_at IS NULL AND expires_at > now()`, tok,
 			).Scan(&uid)
 			if err == nil {
+				if !ensureActiveUser(c, pool, uid) {
+					return
+				}
 				_, _ = pool.Exec(c.Request.Context(), `
 					INSERT INTO device_identities(device_key, user_id)
 					VALUES ($1,$2)
@@ -56,12 +59,29 @@ func DeviceAuth(pool *pgxpool.Pool) gin.HandlerFunc {
 			c.Abort()
 			return
 		}
+		if !ensureActiveUser(c, pool, userID) {
+			return
+		}
 		c.Set(string(UserIDKey), userID.String())
 		c.Header(DeviceKeyHeader, key)
 		c.Next()
 	}
 }

+// ensureActiveUser aborts with 401 when UserStatus is not active.
+func ensureActiveUser(c *gin.Context, pool *pgxpool.Pool, userID uuid.UUID) bool {
+	var status string
+	err := pool.QueryRow(c.Request.Context(), `
+		SELECT status FROM users WHERE id=$1 AND deleted_at IS NULL`, userID,
+	).Scan(&status)
+	if err != nil || status != "active" {
+		response.Fail(c, http.StatusUnauthorized, 40113, "账户已受限")
+		c.Abort()
+		return false
+	}
+	return true
+}
+
 func bearerFromHeader(h string) string {
 	if len(h) < 8 {
 		return ""
@@ -0,0 +1,104 @@
+package repository
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// AccountTransition is an append-only UserStatus change.
+type AccountTransition struct {
+	ID         uuid.UUID `json:"id"`
+	UserID     uuid.UUID `json:"user_id"`
+	FromStatus string    `json:"from_status"`
+	ToStatus   string    `json:"to_status"`
+	AdminID    uuid.UUID `json:"admin_id"`
+	Reason     string    `json:"reason"`
+	CreatedAt  time.Time `json:"created_at"`
+}
+
+// GetUserStatus returns users.status or empty if missing.
+func (r *AdminRepo) GetUserStatus(ctx context.Context, userID uuid.UUID) (string, error) {
+	var status string
+	err := r.Pool.QueryRow(ctx, `
+		SELECT status FROM users WHERE id=$1 AND deleted_at IS NULL`, userID,
+	).Scan(&status)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	return status, err
+}
+
+// TransitionUserStatusWithAudit updates status, inserts transition + audit in one tx.
+func (r *AdminRepo) TransitionUserStatusWithAudit(
+	ctx context.Context,
+	adminID, userID uuid.UUID,
+	fromStatus, toStatus, reason string,
+	meta json.RawMessage,
+) error {
+	tx, err := r.Pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback(ctx)
+
+	tag, err := tx.Exec(ctx, `
+		UPDATE users SET status=$2, updated_at=now()
+		WHERE id=$1 AND deleted_at IS NULL AND status=$3`,
+		userID, toStatus, fromStatus,
+	)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return errString("status conflict")
+	}
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO account_state_transitions(user_id, from_status, to_status, admin_id, reason)
+		VALUES ($1,$2,$3,$4,$5)`,
+		userID, fromStatus, toStatus, adminID, reason,
+	); err != nil {
+		return 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,'users.status.transition','user',$2,$3)`,
+		adminID, userID.String(), meta,
+	); err != nil {
+		return err
+	}
+	return tx.Commit(ctx)
+}
+
+// ListStatusTransitions returns newest first.
+func (r *AdminRepo) ListStatusTransitions(ctx context.Context, userID uuid.UUID, limit int) ([]AccountTransition, error) {
+	if limit <= 0 || limit > 100 {
+		limit = 50
+	}
+	rows, err := r.Pool.Query(ctx, `
+		SELECT id, user_id, from_status, to_status, admin_id, reason, created_at
+		FROM account_state_transitions
+		WHERE user_id=$1
+		ORDER BY created_at DESC
+		LIMIT $2`, userID, limit)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []AccountTransition
+	for rows.Next() {
+		var t AccountTransition
+		if err := rows.Scan(&t.ID, &t.UserID, &t.FromStatus, &t.ToStatus, &t.AdminID, &t.Reason, &t.CreatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, t)
+	}
+	return out, rows.Err()
+}
@@ -0,0 +1,76 @@
+package admin
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/google/uuid"
+
+	"github.com/yuxingu/digital-psychology/apps/api/internal/repository"
+)
+
+var (
+	ErrInvalidStatusEdge = errString("invalid status transition")
+	ErrReasonRequired    = errString("reason required")
+)
+
+var allowedStatusEdges = map[string]map[string]struct{}{
+	"active":    {"disabled": {}, "banned": {}, "suspended": {}},
+	"disabled":  {"active": {}, "banned": {}},
+	"suspended": {"active": {}, "banned": {}, "disabled": {}},
+	"banned":    {"active": {}, "disabled": {}},
+}
+
+// TransitionUserStatus migrates UserStatus with audit.
+func (s *Service) TransitionUserStatus(ctx context.Context, adminID, userID uuid.UUID, toStatus, reason string) error {
+	toStatus = strings.TrimSpace(toStatus)
+	reason = strings.TrimSpace(reason)
+	if reason == "" {
+		return ErrReasonRequired
+	}
+	ok, err := s.Repo.UserExists(ctx, userID)
+	if err != nil {
+		return err
+	}
+	if !ok {
+		return ErrUserNotFound
+	}
+	from, err := s.Repo.GetUserStatus(ctx, userID)
+	if err != nil || from == "" {
+		return ErrUserNotFound
+	}
+	if from == toStatus {
+		return ErrInvalidStatusEdge
+	}
+	next, okEdge := allowedStatusEdges[from]
+	if !okEdge {
+		return ErrInvalidStatusEdge
+	}
+	if _, okEdge = next[toStatus]; !okEdge {
+		return ErrInvalidStatusEdge
+	}
+	meta, _ := json.Marshal(map[string]string{
+		"from": from, "to": toStatus, "reason": reason,
+	})
+	return s.Repo.TransitionUserStatusWithAudit(ctx, adminID, userID, from, toStatus, reason, meta)
+}
+
+// ListStatusTransitions returns recent transitions.
+func (s *Service) ListStatusTransitions(ctx context.Context, userID uuid.UUID, limit int) ([]repository.AccountTransition, error) {
+	ok, err := s.Repo.UserExists(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	if !ok {
+		return nil, ErrUserNotFound
+	}
+	items, err := s.Repo.ListStatusTransitions(ctx, userID, limit)
+	if err != nil {
+		return nil, err
+	}
+	if items == nil {
+		items = []repository.AccountTransition{}
+	}
+	return items, nil
+}
@@ -19,12 +19,14 @@ const (
 	PermContentWrite      = "admin.content.write"
 	PermRolesRead         = "admin.roles.read"
 	PermRolesWrite        = "admin.roles.write"
+	PermUsersStatusWrite  = "admin.users.status.write"
 )

 var knownPermissions = map[string]struct{}{
 	PermUsersRead: {}, PermMembershipGrant: {}, PermAskQuotaGrant: {},
 	PermOrdersRead: {}, PermAuditRead: {}, PermAnalyticsRead: {},
 	PermContentWrite: {}, PermRolesRead: {}, PermRolesWrite: {},
+	PermUsersStatusWrite: {},
 }

 var (
@@ -35,6 +35,9 @@ type SessionResult struct {
 	User      Me        `json:"user"`
 }

+// ErrAccountRestricted is returned when UserStatus is not active.
+var ErrAccountRestricted = errors.New("账户已受限")
+
 // Register upgrades or opens an account (same open rules as Login).
 func (s *Service) Register(ctx context.Context, userID uuid.UUID, deviceKey, phone, password, nickname string) (*SessionResult, error) {
 	return s.OpenLogin(ctx, userID, deviceKey, phone, password, nickname)
@@ -60,6 +63,9 @@ func (s *Service) OpenLogin(ctx context.Context, deviceUserID uuid.UUID, deviceK

 	acc, err := s.Repo.GetByPhone(ctx, phone)
 	if err == nil {
+		if acc.Status != "active" {
+			return nil, ErrAccountRestricted
+		}
 		_ = s.Repo.TouchPassword(ctx, acc.ID, hashStr)
 		if deviceKey != "" {
 			_ = s.Repo.BindDevice(ctx, deviceKey, acc.ID)
@@ -78,6 +84,9 @@ func (s *Service) OpenLogin(ctx context.Context, deviceUserID uuid.UUID, deviceK
 	cur, curErr := s.Repo.GetAccount(ctx, deviceUserID)
 	uid := deviceUserID
 	if curErr == nil && cur.Phone == "" {
+		if cur.Status != "active" {
+			return nil, ErrAccountRestricted
+		}
 		if err := s.Repo.RegisterOnUser(ctx, deviceUserID, phone, hashStr, nickname); err != nil {
 			return nil, errors.New("登录失败，请重试")
 		}