merge: maestro/tsk_x7wrlA87orsY [devices + 订阅校验中间件] (tsk_VRzw-af__qWx)

手动合并 tsk_x7wrlA87orsY（设备管理 + 订阅校验中间件）到 main：

冲突解决：
- server/internal/apierr/apierr.go：保留 tsk_GXDoc3Cs07Rn 版本（New/StatusFor/
  Middleware/ErrConflict/改善文档），并入 tsk_x7wrlA87orsY 新增的 ErrAccountBanned
  及对应 StatusFor case（→ 403）。

新增文件（来自 tsk_x7wrlA87orsY）：
- server/internal/devices/doc.go       package 文档（替换占位 stub）
- server/internal/devices/context.go   CtxKeyUserID / Plan / WithPlan / PlanFromCtx
- server/internal/devices/handler.go   GET /v1/me/devices · DELETE /v1/me/devices/{id}
- server/internal/devices/middleware.go SubscriptionMiddleware · CheckDeviceQuota · RequirePaidTier
- server/internal/devices/service.go   RegisterIfAbsent / DeleteDevice / ResolvePlan + 纯函数 resolveEffectivePlan
- server/internal/devices/store.go     MySQL 数据访问层
- server/internal/devices/service_test.go          15 个单测（全通过）
- server/internal/devices/devices_integration_test.go  testcontainers 集成测试

OpenAPI 更新（来自 tsk_x7wrlA87orsY）：
- server/api/openapi.yaml：SubscriptionInfo.source 枚举补 free
- design/server/openapi.yaml：SubscriptionInfo.source 枚举补 admin, free

测试：go build ./... ✓；go test ./internal/apierr/... ✓（8 tests）；
      go test ./internal/devices/... ✓（15 tests）。

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

server/internal/devices/middleware.go

@@ -0,0 +1,102 @@
+package devices
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+	"github.com/wangjia/pangolin/server/internal/apierr"
+)
+
+// Middleware resolves the caller's effective subscription and injects it into
+// the request context. It MUST run after the JWT auth middleware (module #2),
+// which is responsible for setting CtxKeyUserID.
+type Middleware struct {
+	svc *Service
+
+	// rdb and cacheTTL reserve a future 60s per-user plan cache. When cacheTTL
+	// > 0 and rdb != nil the resolved plan could be cached under
+	// "sub:plan:<userID>"; this is intentionally left disabled (cacheTTL == 0)
+	// for the initial direct-DB implementation (subscription volume is low).
+	// NOTE: a cache must not mask account bans — ban status would need a
+	// separate, uncached check before serving any cached plan.
+	rdb      *redis.Client
+	cacheTTL time.Duration
+}
+
+// NewMiddleware creates the subscription-resolving middleware. Pass rdb=nil and
+// cacheTTL=0 to use the direct-DB path (current default).
+func NewMiddleware(svc *Service, rdb *redis.Client, cacheTTL time.Duration) *Middleware {
+	return &Middleware{svc: svc, rdb: rdb, cacheTTL: cacheTTL}
+}
+
+// Handler is the net/http middleware. It writes a JSON apierr and stops the
+// chain on failure (missing user / banned / internal error); otherwise it
+// injects the resolved Plan and calls next.
+func (m *Middleware) Handler(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		userID, ok := UserIDFromContext(r.Context())
+		if !ok {
+			apierr.WriteJSON(w, http.StatusUnauthorized, apierr.ErrUnauthorized)
+			return
+		}
+
+		plan, apiErr := m.svc.ResolvePlan(r.Context(), userID)
+		if apiErr != nil {
+			apierr.WriteJSON(w, StatusForError(apiErr), apiErr)
+			return
+		}
+
+		ctx := WithPlan(r.Context(), plan)
+		next.ServeHTTP(w, r.WithContext(ctx))
+	})
+}
+
+// --------------------------------------------------------------------------
+// Helpers consumed by other modules (nodes catalogue filtering / connect, etc.)
+// --------------------------------------------------------------------------
+
+// CheckDeviceQuota returns a bilingual error when currentDevices already meets
+// or exceeds the plan's device cap, otherwise nil.
+func CheckDeviceQuota(p Plan, currentDevices int) *apierr.Error {
+	if p.MaxDevices > 0 && currentDevices >= p.MaxDevices {
+		return errDeviceLimit(p.MaxDevices)
+	}
+	return nil
+}
+
+// RequirePaidTier returns a 403 error when the plan is the free tier; nil for
+// pro/team. Used to gate paid-only nodes and features.
+func RequirePaidTier(p Plan) *apierr.Error {
+	if planTier(p.PlanCode) < planTier("pro") {
+		return &apierr.Error{
+			Code:      "PAID_TIER_REQUIRED",
+			MessageZH: "该功能仅限付费会员，请升级后使用",
+			MessageEn: "This feature requires a paid plan. Please upgrade to continue.",
+		}
+	}
+	return nil
+}
+
+// StatusForError maps an apierr.Error code to an HTTP status code.
+func StatusForError(e *apierr.Error) int {
+	if e == nil {
+		return http.StatusOK
+	}
+	switch e.Code {
+	case "UNAUTHORIZED":
+		return http.StatusUnauthorized
+	case "FORBIDDEN", "ACCOUNT_BANNED", "PAID_TIER_REQUIRED":
+		return http.StatusForbidden
+	case "NOT_FOUND":
+		return http.StatusNotFound
+	case "DEVICE_LIMIT_EXCEEDED":
+		return http.StatusForbidden
+	case "BAD_REQUEST":
+		return http.StatusBadRequest
+	case "INTERNAL_ERROR":
+		return http.StatusInternalServerError
+	default:
+		return http.StatusBadRequest
+	}
+}