mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-04-25 08:46:22 +02:00
Epic 5 Complete: Billing, Subscriptions, and Admin Features
Resolve all 5 deferred items from Epic 5 adversarial code review: - Migration 124: Add CASCADE to subscriptionstatus enum drop (prevent orphaned references) - Stripe rate limiting: In-memory per-user limiter (20 calls/60s) on verify-checkout-session - Subscription request cooldown: 24h cooldown before resubmitting rejected requests - Token reset date: Initialize on first subscription activation - Checkout URL validation: Confirmed HTTPS-only (Stripe always returns HTTPS) Implement Story 5.4 (Usage Tracking & Rate Limit Enforcement): - Page quota pre-check at HTTP upload layer - Extend UserRead schema with token quota fields - Frontend 402 error handling in document upload - Quota indicator in dashboard sidebar Story 5.5 (Admin Seed & Approval Flow): - Seed admin user migration with default credentials warning - Subscription approval/rejection routes with admin guard - 24h rejection cooldown enforcement Story 5.6 (Admin-Only Model Config): - Global model config visible across all search spaces - Per-search-space model configs with user access control - Superuser CRUD for global configs Additional fixes from code review: - PageLimitService: PAST_DUE subscriptions enforce free-tier limits - TokenQuotaService: PAST_DUE subscriptions enforce free-tier limits - Config routes: Fixed user_id.is_(None) filter on mutation endpoints - Stripe webhook: Added guard against silent plan downgrade on unrecognized price_id All changes formatted with Ruff (Python) and Biome (TypeScript). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Vonic
parent
20c4f128bb
commit
4eb6ed18d6
41 changed files with 1771 additions and 318 deletions
|
|
@ -13,6 +13,8 @@ so that tôi có thể điền thông tin thẻ tín dụng mà không sợ bị
|
|||
1. Khi User bấm thanh toán, BE gọi API Stripe lấy `sessionId` với **`mode='subscription'`** (recurring billing, không phải one-time payment).
|
||||
2. Hệ thống redirect User an toàn qua cổng Stripe Hosted Checkout.
|
||||
3. Sau thanh toán thành công, user được redirect về app với subscription activated.
|
||||
4. **[Admin-approval mode]** Khi `STRIPE_SECRET_KEY` chưa được cấu hình, endpoint trả về `{ checkout_url: "", admin_approval_mode: true }` thay vì gọi Stripe — frontend hiển thị toast "Subscription request submitted! An admin will approve it shortly." và không redirect.
|
||||
5. **[Admin-approval mode]** Nếu user đã có request đang pending, endpoint trả về 409 Conflict để tránh duplicate.
|
||||
|
||||
## As-Is (Code hiện tại)
|
||||
|
||||
|
|
@ -40,6 +42,15 @@ so that tôi có thể điền thông tin thẻ tín dụng mà không sợ bị
|
|||
- [x] Subtask 2.4: Gọi `stripe.checkout.sessions.create(mode='subscription', customer=stripe_customer_id, ...)`.
|
||||
- [x] Subtask 2.5: Trả về `{ "checkout_url": "https://checkout.stripe.com/..." }`.
|
||||
|
||||
- [x] Task 2b: Admin-approval fallback khi Stripe chưa cấu hình
|
||||
- [x] Subtask 2b.1: Kiểm tra `config.STRIPE_SECRET_KEY` ở đầu checkout endpoint — nếu falsy, bỏ qua toàn bộ Stripe logic.
|
||||
- [x] Subtask 2b.2: Guard active subscription: nếu `user.subscription_status == ACTIVE` → 409.
|
||||
- [x] Subtask 2b.3: Guard duplicate pending request: query `SubscriptionRequest` table — nếu đã có pending → 409.
|
||||
- [x] Subtask 2b.4: Tạo `SubscriptionRequest(user_id, plan_id)` row và commit.
|
||||
- [x] Subtask 2b.5: Trả về `CreateSubscriptionCheckoutResponse(checkout_url="", admin_approval_mode=True)`.
|
||||
- [x] Subtask 2b.6: Thêm `admin_approval_mode: bool = False` vào `CreateSubscriptionCheckoutResponse` schema.
|
||||
- [x] Subtask 2b.7: Frontend `handleUpgradePro()` — nếu `data.admin_approval_mode` là `true`, hiển thị toast thành công và return (không redirect).
|
||||
|
||||
- [x] Task 3: Kết nối Frontend với Endpoint mới
|
||||
- [x] Subtask 3.1: `pricing-section.tsx` đã gọi endpoint với `plan_id` — done trong Story 5.1.
|
||||
- [x] Subtask 3.2: Redirect đến `checkout_url` — done trong Story 5.1.
|
||||
|
|
@ -79,9 +90,11 @@ Sau checkout, Stripe sẽ gửi `checkout.session.completed` → webhook handler
|
|||
|
||||
### File List
|
||||
- `surfsense_backend/app/config/__init__.py` — added `STRIPE_PRO_MONTHLY_PRICE_ID`, `STRIPE_PRO_YEARLY_PRICE_ID`
|
||||
- `surfsense_backend/app/schemas/stripe.py` — added `PlanId` enum, `CreateSubscriptionCheckoutRequest`, `CreateSubscriptionCheckoutResponse`
|
||||
- `surfsense_backend/app/routes/stripe_routes.py` — added `_get_subscription_success_url`, `_get_price_id_for_plan`, `get_or_create_stripe_customer`, `POST /create-subscription-checkout`
|
||||
- `surfsense_backend/app/schemas/stripe.py` — added `PlanId` enum, `CreateSubscriptionCheckoutRequest`, `CreateSubscriptionCheckoutResponse` (including `admin_approval_mode: bool = False`)
|
||||
- `surfsense_backend/app/routes/stripe_routes.py` — added `_get_subscription_success_url`, `_get_price_id_for_plan`, `get_or_create_stripe_customer`, `POST /create-subscription-checkout` + admin-approval fallback branch
|
||||
- `surfsense_web/app/subscription-success/page.tsx` — new success page with toast + user query invalidation
|
||||
- `surfsense_web/components/pricing/pricing-section.tsx` — added `admin_approval_mode` toast handling in `handleUpgradePro()`
|
||||
- *(See Story 5.5 for admin-approval infrastructure: migrations 126/127, `SubscriptionRequest` model, admin routes, admin UI page)*
|
||||
|
||||
### Review Findings
|
||||
|
||||
|
|
@ -96,3 +109,4 @@ Sau checkout, Stripe sẽ gửi `checkout.session.completed` → webhook handler
|
|||
|
||||
### Change Log
|
||||
- 2026-04-14: Implement subscription checkout endpoint with Stripe customer creation and success page.
|
||||
- 2026-04-15: Add admin-approval fallback mode — when `STRIPE_SECRET_KEY` is not configured, checkout endpoint creates a `SubscriptionRequest` row instead of calling Stripe (see Story 5.5).
|
||||
|
|
|
|||
|
|
@ -116,3 +116,7 @@ Webhook endpoint **PHẢI** parse raw body bằng `await request.body()` TRƯỚ
|
|||
### Change Log
|
||||
- 2026-04-15: Implement Stripe webhook subscription event handlers — subscription lifecycle, invoice payment reset, checkout activation.
|
||||
- 2026-04-15: Code review patches applied — 12 fixes: pages_limit upgrade/downgrade, period_end guards, token reset billing reasons, idempotency plan_id check, UTC date fix, unrecognized price ID warning.
|
||||
|
||||
## Review Findings (2026-04-15)
|
||||
|
||||
- [x] [Review][Patch] Unrecognized Stripe price ID silently downgrades active subscription to "free" [stripe_routes.py] — **Fixed**: Added early return when plan_id=="free" but subscription status is "active" and price ID was unrecognized
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Story 5.4: Hệ thống Khóa Tác vụ dựa trên Hạn Mức (Usage Tracking & Rate Limit Enforcement)
|
||||
|
||||
Status: ready-for-dev
|
||||
Status: done
|
||||
|
||||
## Story
|
||||
|
||||
|
|
@ -35,35 +35,28 @@ so that mô hình kinh doanh không bị lỗ do chi phí LLM và Storage, áp d
|
|||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [ ] Task 1: Thêm Page Quota Pre-check vào Document Upload Route (Backend)
|
||||
- [ ] Subtask 1.1: Tìm document upload route (search trong `surfsense_backend/app/routes/`).
|
||||
- [ ] Subtask 1.2: Inject `PageLimitService`, gọi `estimate_pages_from_metadata(filename, file_size)` rồi `check_page_limit(user_id, estimated_pages)`.
|
||||
- [ ] Subtask 1.3: Nếu `PageLimitExceededError` → raise `HTTPException(402, detail={"error": "page_quota_exceeded", "pages_used": X, "pages_limit": Y, "message": "..."})`.
|
||||
- [ ] Subtask 1.4: Giữ nguyên enforcement trong Celery tasks (double-check layer cho trường hợp estimate sai).
|
||||
- [x] Task 1: Thêm Page Quota Pre-check vào Document Upload Route (Backend)
|
||||
- [x] Subtask 1.1: Tìm document upload route — `surfsense_backend/app/routes/documents_routes.py`
|
||||
- [x] Subtask 1.2: Inject `PageLimitService`, gọi `estimate_pages_from_metadata(filename, file_size)` rồi `check_page_limit(user_id, estimated_pages)`.
|
||||
- [x] Subtask 1.3: `PageLimitExceededError` → `HTTPException(402)` với message mô tả quota.
|
||||
- [x] Subtask 1.4: Giữ nguyên enforcement trong Celery tasks (double-check layer).
|
||||
- [x] Subtask 1.5: Thêm pre-check cho `create_documents` endpoint (extension/YouTube connector).
|
||||
|
||||
- [ ] Task 2: Plan-based Limits (Backend)
|
||||
- [ ] Subtask 2.1: Tạo config mapping `plan_id` → limits (liên kết với Story 5.3):
|
||||
```python
|
||||
PLAN_LIMITS = {
|
||||
"free": {"pages_limit": 500, "monthly_token_limit": 50_000, "max_docs": 10},
|
||||
"pro": {"pages_limit": 5000, "monthly_token_limit": 1_000_000, "max_docs": 100},
|
||||
}
|
||||
```
|
||||
- [ ] Subtask 2.2: Khi subscription activate/update (webhook Story 5.3), update `pages_limit` và `monthly_token_limit` theo plan mới.
|
||||
- [x] Task 2: Plan-based Limits (Backend)
|
||||
- [x] Subtask 2.1: `PLAN_LIMITS` config đã có trong `config/__init__.py:314`.
|
||||
- [x] Subtask 2.2: Webhook Story 5.3 + admin approval đã update limits khi subscription change.
|
||||
|
||||
- [ ] Task 3: Frontend — Bắt lỗi Quota Exceeded
|
||||
- [ ] Subtask 3.1: Document upload component — bắt HTTP 402 response, phân biệt `page_quota_exceeded` vs `token_quota_exceeded`.
|
||||
- [ ] Subtask 3.2: Hiển thị toast/modal: "Bạn đã dùng X/Y pages. Nâng cấp lên Pro để tiếp tục." với link đến `/pricing`.
|
||||
- [ ] Subtask 3.3: Chat component — bắt HTTP 402 từ SSE stream (tương tự Story 3.5 Task 6).
|
||||
- [x] Task 3: Frontend — Bắt lỗi Quota Exceeded
|
||||
- [x] Subtask 3.1: Document upload — `DocumentUploadTab.tsx` bắt HTTP 402 (check `error.status`) cho cả file và folder upload.
|
||||
- [x] Subtask 3.2: Toast error với "Upgrade" action button → navigate to `/pricing`.
|
||||
- [x] Subtask 3.3: Chat SSE — đã có `QuotaExceededError` pattern từ Story 3.5 (`page.tsx`).
|
||||
|
||||
- [ ] Task 4: Frontend — Quota Indicator (Dashboard)
|
||||
- [ ] Subtask 4.1: Expose `pages_used`, `pages_limit`, `tokens_used_this_month`, `monthly_token_limit` qua user endpoint hoặc Zero sync.
|
||||
- [ ] Subtask 4.2: Tạo component `QuotaIndicator` — hiển thị 2 progress bars (Pages, Tokens) trong sidebar/header.
|
||||
- [ ] Subtask 4.3: Warning state (amber) khi usage > 80%, critical state (red) khi > 95%.
|
||||
- [x] Task 4: Frontend — Quota Indicator (Dashboard)
|
||||
- [x] Subtask 4.1: Extend `UserRead` schema + Zod type với `monthly_token_limit`, `tokens_used_this_month`, `plan_id`, `subscription_status`.
|
||||
- [x] Subtask 4.2: Extend `PageUsageDisplay` — hiển thị 2 progress bars (Pages, Tokens) trong sidebar.
|
||||
- [x] Subtask 4.3: Warning state (amber) khi usage > 80%, critical state (red) khi > 95%.
|
||||
|
||||
- [ ] Task 5: Anti-spam Rate Limiting (Optional — nếu cần)
|
||||
- [ ] Subtask 5.1: Thêm rate limit cho chat endpoint (e.g. max 60 requests/hour cho free tier).
|
||||
- [ ] Subtask 5.2: Dùng Redis counter hoặc FastAPI dependency.
|
||||
- [ ] Task 5: Anti-spam Rate Limiting (Optional — skipped per spec)
|
||||
|
||||
## Dev Notes
|
||||
|
||||
|
|
@ -86,5 +79,34 @@ PageLimitService.update_page_usage() [COMMIT — tăng pages_used]
|
|||
### References
|
||||
- `surfsense_backend/app/services/page_limit_service.py` — page quota (đọc, ít sửa)
|
||||
- `surfsense_backend/app/tasks/celery_tasks/document_tasks.py` — enforcement pattern hiện tại
|
||||
- `surfsense_backend/app/routes/` — document upload route (cần tìm)
|
||||
- Frontend upload component (cần tìm)
|
||||
- `surfsense_backend/app/routes/documents_routes.py` — document upload route
|
||||
- `surfsense_web/components/sources/DocumentUploadTab.tsx` — frontend upload component
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Implementation (2026-04-15)
|
||||
|
||||
**Backend:**
|
||||
- `documents_routes.py`: Added page quota pre-check to both `create_documents` and `create_documents_file_upload` endpoints. Uses `PageLimitService.estimate_pages_from_metadata()` for fast estimation before any I/O, raises HTTP 402 on exceeded quota.
|
||||
- `schemas/users.py`: Extended `UserRead` with `monthly_token_limit`, `tokens_used_this_month`, `plan_id`, `subscription_status` — exposed via `/api/v1/users/me`.
|
||||
|
||||
**Frontend:**
|
||||
- `DocumentUploadTab.tsx`: 402 handling in both file upload (`onError`) and folder upload (`catch`) paths — shows toast with "Upgrade" action linking to `/pricing`.
|
||||
- `user.types.ts`: Zod schema extended with token quota fields.
|
||||
- `PageUsageDisplay.tsx`: Extended with token usage bar, color-coded warning (amber >80%, red >95%).
|
||||
- `layout.types.ts`: `PageUsage` interface extended with `tokensUsed`/`tokensLimit`.
|
||||
- `LayoutDataProvider.tsx`: Passes token data to sidebar.
|
||||
|
||||
### File List
|
||||
- `surfsense_backend/app/routes/documents_routes.py` — page quota pre-check in upload endpoints
|
||||
- `surfsense_backend/app/schemas/users.py` — extended UserRead
|
||||
- `surfsense_web/components/sources/DocumentUploadTab.tsx` — 402 error handling
|
||||
- `surfsense_web/contracts/types/user.types.ts` — quota fields in Zod schema
|
||||
- `surfsense_web/components/layout/ui/sidebar/PageUsageDisplay.tsx` — token usage bar + color states
|
||||
- `surfsense_web/components/layout/types/layout.types.ts` — extended PageUsage interface
|
||||
- `surfsense_web/components/layout/providers/LayoutDataProvider.tsx` — pass token data
|
||||
- `surfsense_web/components/layout/ui/sidebar/Sidebar.tsx` — pass token props to PageUsageDisplay
|
||||
|
||||
## Review Findings (2026-04-15)
|
||||
|
||||
- [x] [Review][Patch] PAST_DUE users retain pro-tier limits and can continue consuming resources [page_limit_service.py, token_quota_service.py] — **Fixed**: Both services now check subscription_status and apply free-tier limits when PAST_DUE
|
||||
|
|
|
|||
|
|
@ -0,0 +1,125 @@
|
|||
# Story 5.5: Admin Seed Account & Admin-Approval Subscription Flow
|
||||
|
||||
Status: done
|
||||
|
||||
## Story
|
||||
|
||||
As a Kỹ sư / Admin,
|
||||
I want hệ thống tự tạo sẵn một tài khoản admin với đầy đủ quyền khi khởi động lần đầu, và khi Stripe chưa được cấu hình thì vẫn có thể test toàn bộ luồng Pro subscription thông qua giao diện duyệt thủ công của admin,
|
||||
so that development và testing không bị chặn bởi việc thiếu Stripe credentials.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. Khi chạy `alembic upgrade head` trên database trống, hệ thống tự seed một user admin với thông tin mặc định (`admin@surfsense.local` / `Admin@SurfSense1`), overridable qua env vars `ADMIN_EMAIL` / `ADMIN_PASSWORD`.
|
||||
2. Admin được seed với `is_superuser=TRUE`, `subscription_status='active'`, `plan_id='pro_yearly'`, `monthly_token_limit=1_000_000`, `pages_limit=5000` và có đủ search space, roles, membership, và default prompts.
|
||||
3. Migration seed là idempotent: nếu đã có bất kỳ user nào trong DB thì bỏ qua, không insert lại.
|
||||
4. Superuser có thể xem danh sách pending subscription requests tại `GET /api/v1/admin/subscription-requests`.
|
||||
5. Superuser có thể approve request: `POST /api/v1/admin/subscription-requests/{id}/approve` → user được activate Pro plan ngay lập tức (không cần Stripe).
|
||||
6. Superuser có thể reject request: `POST /api/v1/admin/subscription-requests/{id}/reject` → request bị đánh dấu rejected.
|
||||
7. Non-superuser bị từ chối với HTTP 403 khi truy cập các endpoint admin.
|
||||
8. Frontend tại `/admin/subscription-requests` hiển thị bảng pending requests với nút Approve / Reject; chuyển hướng về `/login` nếu chưa đăng nhập, hiển thị "Access denied" nếu không có quyền superuser.
|
||||
|
||||
## As-Is (Code trước Story này)
|
||||
|
||||
| Component | Hiện trạng |
|
||||
|-----------|-----------|
|
||||
| Admin user | Không có — DB trống sau fresh install |
|
||||
| Subscription flow khi không có Stripe | Trả về HTTP 503 (xem Story 5.2) |
|
||||
| Admin routes | Không có |
|
||||
| `subscription_requests` table | Không có |
|
||||
| `SubscriptionRequest` model | Không có |
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Task 1: Admin Seed Migration
|
||||
- [x] Subtask 1.1: Tạo migration `126_seed_admin_user.py` — chỉ insert khi `SELECT 1 FROM "user" LIMIT 1` trả về empty.
|
||||
- [x] Subtask 1.2: Hash password bằng `argon2-cffi` (đã cài sẵn qua fastapi-users) bên trong migration function.
|
||||
- [x] Subtask 1.3: Insert admin user với tất cả subscription fields đầy đủ.
|
||||
- [x] Subtask 1.4: Insert default search space (với `citations_enabled=TRUE`), Owner/Editor/Viewer roles, owner membership.
|
||||
- [x] Subtask 1.5: Insert 8 default prompts (`fix-grammar`, `make-shorter`, `translate`, `rewrite`, `summarize`, `explain`, `ask-knowledge-base`, `look-up-web`) với `ON CONFLICT DO NOTHING`.
|
||||
- [x] Subtask 1.6: Downgrade là no-op (không xóa users).
|
||||
|
||||
- [x] Task 2: Subscription Requests Table Migration
|
||||
- [x] Subtask 2.1: Tạo migration `127_add_subscription_requests_table.py` — dùng raw SQL để tránh SQLAlchemy enum auto-create conflict.
|
||||
- [x] Subtask 2.2: `DROP TYPE IF EXISTS subscriptionrequeststatus` trước khi `CREATE TYPE ... AS ENUM ('pending', 'approved', 'rejected')`.
|
||||
- [x] Subtask 2.3: Tạo bảng `subscription_requests` với columns: `id` (UUID PK), `user_id` (FK → user CASCADE), `plan_id` (VARCHAR 50), `status` (subscriptionrequeststatus DEFAULT 'pending'), `created_at`, `approved_at` (nullable), `approved_by` (FK → user nullable).
|
||||
- [x] Subtask 2.4: Tạo index trên `user_id`.
|
||||
|
||||
- [x] Task 3: SubscriptionRequest Model & ORM
|
||||
- [x] Subtask 3.1: Thêm `SubscriptionRequestStatus(StrEnum)` enum vào `db.py` — values: `PENDING="pending"`, `APPROVED="approved"`, `REJECTED="rejected"`.
|
||||
- [x] Subtask 3.2: Thêm `SubscriptionRequest(Base)` model sau class `PagePurchase` trong `db.py`.
|
||||
- [x] Subtask 3.3: Thêm `values_callable=lambda x: [e.value for e in x]` vào tất cả `SQLAlchemyEnum(SubscriptionStatus)` và `SQLAlchemyEnum(SubscriptionRequestStatus)` — bắt buộc để ORM map DB lowercase values thay vì enum member names uppercase.
|
||||
- [x] Subtask 3.4: Thêm relationship `subscription_requests` vào cả hai nhánh User model (LOCAL và Google OAuth).
|
||||
|
||||
- [x] Task 4: Admin Routes Backend
|
||||
- [x] Subtask 4.1: Tạo `surfsense_backend/app/routes/admin_routes.py` với `APIRouter(prefix="/admin")`.
|
||||
- [x] Subtask 4.2: Dùng `fastapi_users.current_user(active=True, superuser=True)` làm dependency — tự động trả 403 cho non-superuser.
|
||||
- [x] Subtask 4.3: `GET /admin/subscription-requests` — query tất cả PENDING requests, JOIN lấy user email, trả về `List[SubscriptionRequestItem]`.
|
||||
- [x] Subtask 4.4: `POST /admin/subscription-requests/{id}/approve` — set `status=APPROVED`, `approved_at=now()`, `approved_by=current_user.id`; activate user subscription dùng cùng logic với `_activate_subscription_from_checkout` (Story 5.3): set `subscription_status=ACTIVE`, `plan_id`, `monthly_token_limit`, `pages_limit=max(pages_used, plan_limit)`, `tokens_used_this_month=0`, `token_reset_date=today`.
|
||||
- [x] Subtask 4.5: `POST /admin/subscription-requests/{id}/reject` — set `status=REJECTED`.
|
||||
- [x] Subtask 4.6: Đăng ký router trong `surfsense_backend/app/routes/__init__.py` và `app.py`.
|
||||
|
||||
- [x] Task 5: Admin Frontend Page
|
||||
- [x] Subtask 5.1: Tạo `surfsense_web/app/admin/subscription-requests/page.tsx` — client component.
|
||||
- [x] Subtask 5.2: Auth guard: gọi `isAuthenticated()` — nếu false redirect `/login`; nếu API trả 403 hiển thị "Access denied. Superuser privileges required."
|
||||
- [x] Subtask 5.3: Hiển thị bảng: User email | Plan | Requested At | Actions (Approve / Reject).
|
||||
- [x] Subtask 5.4: Approve/Reject gọi endpoint tương ứng; sau khi thành công xóa row khỏi danh sách local.
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Tại sao cần Admin Seed?
|
||||
Fresh install không có user nào → không thể login để test. Admin seed giải quyết cold-start problem, đặc biệt cho CI/CD và development.
|
||||
|
||||
### Tại sao dùng raw SQL trong migration 127?
|
||||
`op.create_table` với `SQLAlchemy.Enum(create_type=True/False)` vẫn trigger `_on_table_create` event tự động tạo enum type. Dùng raw SQL tránh `DuplicateObjectError` khi enum đã tồn tại từ `Base.metadata.create_all()`.
|
||||
|
||||
### ORM `values_callable` là bắt buộc
|
||||
SQLAlchemy `Enum` mặc định dùng member **names** (uppercase: FREE, ACTIVE) để map vào DB, nhưng migration tạo enum với **values** lowercase (free, active). Không có `values_callable` → `LookupError: 'active' is not among enum values; Possible values: FREE, ACTIVE`. Fix: `values_callable=lambda x: [e.value for e in x]`.
|
||||
|
||||
### Admin Approval Activation Logic
|
||||
Reuse `PLAN_LIMITS` config từ `config/__init__.py`. `pages_limit = max(user.pages_used, PLAN_LIMITS[plan_id]["pages_limit"])` để không lock out user khỏi content đã upload.
|
||||
|
||||
### Luồng test E2E (không có Stripe)
|
||||
1. Register user → Login → `/pricing` → "Upgrade to Pro" → toast "Subscription request submitted"
|
||||
2. Login admin (`admin@surfsense.local` / `Admin@SurfSense1`) → `/admin/subscription-requests` → Approve
|
||||
3. Login lại user → DB: `subscription_status=active`, `plan_id=pro_monthly`, `monthly_token_limit=1_000_000`
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Implementation Notes
|
||||
- Migration 126: Dùng `argon2-cffi` (`from argon2 import PasswordHasher`) để hash password. Không dùng `bcrypt` vì fastapi-users mặc định dùng argon2 với cấu hình chuẩn.
|
||||
- Migration 126: Không có cột `created_at`/`updated_at` trên bảng `user` (fastapi-users base không có) — không insert các cột này.
|
||||
- Migration 126: `searchspaces` cần `citations_enabled=TRUE` vì cột NOT NULL và không có server default.
|
||||
- Migration 127: Dùng hoàn toàn raw SQL — không dùng `op.create_table`, không dùng `SQLAlchemy.Enum`.
|
||||
- `SubscriptionRequest` model: `__allow_unmapped__ = True` để tương thích với codebase hiện tại.
|
||||
- Admin routes: `SubscriptionRequestItem` Pydantic schema thêm field `user_email` (không có trong ORM model, populated thủ công khi query).
|
||||
- Frontend: dùng `authenticatedFetch` từ `@/lib/auth-utils` và `BACKEND_URL` từ `@/lib/env-config`.
|
||||
|
||||
### Completion Notes
|
||||
✅ AC 1-3: Migration 126 seed admin user — idempotent, argon2 hashed, full setup.
|
||||
✅ AC 4-7: Admin routes với superuser guard — list/approve/reject subscription requests.
|
||||
✅ AC 8: Frontend `/admin/subscription-requests` với auth guard và approve/reject UI.
|
||||
|
||||
### E2E Test Results (2026-04-15)
|
||||
- Backend restarted với `STRIPE_SECRET_KEY=""` → admin-approval mode active.
|
||||
- User `epic5user@example.com` click "Upgrade to Pro" → toast hiển thị đúng.
|
||||
- Login `admin@surfsense.local` → `/admin/subscription-requests` → thấy pending request của epic5user.
|
||||
- Click Approve → request biến mất khỏi danh sách.
|
||||
- Query DB xác nhận: `subscription_status=active`, `plan_id=pro_monthly`, `monthly_token_limit=1000000`, `pages_limit=5000`.
|
||||
|
||||
### File List
|
||||
- `surfsense_backend/alembic/versions/126_seed_admin_user.py` — NEW: admin seed migration (no-op if users exist)
|
||||
- `surfsense_backend/alembic/versions/127_add_subscription_requests_table.py` — NEW: subscription_requests table (raw SQL)
|
||||
- `surfsense_backend/app/db.py` — MODIFIED: `SubscriptionRequestStatus` enum, `SubscriptionRequest` model, `subscription_requests` relationship trên User, `values_callable` fix trên tất cả `SubscriptionStatus` enum columns
|
||||
- `surfsense_backend/app/routes/admin_routes.py` — NEW: GET/approve/reject subscription requests, superuser-only
|
||||
- `surfsense_backend/app/routes/__init__.py` — MODIFIED: import và include `admin_router`
|
||||
- `surfsense_web/app/admin/subscription-requests/page.tsx` — NEW: admin UI page
|
||||
|
||||
### Change Log
|
||||
- 2026-04-15: Implement admin seed migration + admin-approval subscription flow.
|
||||
|
||||
## Review Findings (2026-04-15)
|
||||
|
||||
- [x] [Review][Patch] Hard-coded default admin password should warn operators [126_seed_admin_user.py:53] — **Fixed**: Added runtime print warning when ADMIN_PASSWORD env var is not set
|
||||
- [x] [Review][Patch] Race condition: concurrent approval lacks row-level lock [admin_routes.py:98] — **Fixed**: Added `.with_for_update()` to SubscriptionRequest and User selects in approve endpoint
|
||||
- [x] [Review][Patch] N+1 query in list_subscription_requests [admin_routes.py:62] — **Fixed**: Batch-loaded users with `.where(User.id.in_(user_ids))` instead of per-request query
|
||||
|
|
@ -0,0 +1,161 @@
|
|||
# Story 5.6: Admin-only Model Configuration (LLM / Image / Vision)
|
||||
|
||||
Status: done
|
||||
|
||||
## Story
|
||||
|
||||
As a Quản trị viên (Admin),
|
||||
I want chỉ mình có quyền thêm/sửa/xóa cấu hình LLM, Image Generation, và Vision models,
|
||||
so that người dùng thông thường chỉ có thể chọn model để sử dụng mà không thể thêm BYOK credentials hay thay đổi cấu hình model.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. Chỉ superuser (`is_superuser=TRUE`) mới có thể gọi `POST/PUT/DELETE` cho cả 3 loại model config — non-superuser nhận HTTP 403 Forbidden.
|
||||
2. Regular user vẫn có thể `GET` (đọc/liệt kê) model configs trong search space của họ.
|
||||
3. Trong chat interface, nút "Add Model", "Add Image Model", "Add Vision Model" bị ẩn hoàn toàn với regular user.
|
||||
4. Trong search space settings dialog (LLM/Image/Vision tabs), nút Add/Edit/Delete bị ẩn với regular user — chỉ hiển thị danh sách model read-only.
|
||||
5. Admin-created configs lưu với `user_id=NULL` (không gắn với user cụ thể) — visible cho tất cả members trong search space.
|
||||
6. DB migration: `user_id` trên cả 3 bảng config trở thành nullable để cho phép admin configs với `user_id=NULL`.
|
||||
|
||||
## As-Is (Code trước Story này)
|
||||
|
||||
| Component | Hiện trạng |
|
||||
|-----------|-----------|
|
||||
| `new_llm_configs.user_id` | NOT NULL — mọi config đều gắn với user cụ thể |
|
||||
| `image_generation_configs.user_id` | NOT NULL |
|
||||
| `vision_llm_configs.user_id` | NOT NULL |
|
||||
| Backend CUD permissions | RBAC per search space (`check_permission`) — bất kỳ member có `llm_configs:create` đều tạo được |
|
||||
| Frontend Add buttons | Hiển thị dựa theo RBAC permissions — owner và editor đều thấy |
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
- [x] Task 1: DB Migration
|
||||
- [x] Subtask 1.1: Tạo migration `128_make_model_config_user_id_nullable.py`
|
||||
- [x] Subtask 1.2: `ALTER TABLE new_llm_configs ALTER COLUMN user_id DROP NOT NULL`
|
||||
- [x] Subtask 1.3: Tương tự cho `image_generation_configs` và `vision_llm_configs`
|
||||
- [x] Subtask 1.4: Downgrade: xóa rows có `user_id=NULL` rồi re-add NOT NULL
|
||||
|
||||
- [x] Task 2: Shared Superuser Dependency
|
||||
- [x] Subtask 2.1: Thêm `current_superuser = fastapi_users.current_user(active=True, superuser=True)` vào `users.py`
|
||||
- [x] Subtask 2.2: Cập nhật `admin_routes.py` để import `current_superuser` từ `users.py` thay vì định nghĩa lại
|
||||
|
||||
- [x] Task 3: Backend — Gate CUD endpoints với superuser
|
||||
- [x] Subtask 3.1: `new_llm_config_routes.py` — POST/PUT/DELETE dùng `Depends(current_superuser)`, set `user_id=None`, xóa `check_permission`
|
||||
- [x] Subtask 3.2: `image_generation_routes.py` — tương tự (POST/PUT/DELETE config endpoints)
|
||||
- [x] Subtask 3.3: `vision_llm_routes.py` — tương tự
|
||||
|
||||
- [x] Task 4: Frontend — Settings dialog managers
|
||||
- [x] Subtask 4.1: `model-config-manager.tsx` — import `currentUserAtom`, replace RBAC flags (`canCreate/Update/Delete`) với `currentUser.is_superuser`
|
||||
- [x] Subtask 4.2: `image-model-manager.tsx` — tương tự
|
||||
- [x] Subtask 4.3: `vision-model-manager.tsx` — tương tự
|
||||
|
||||
- [x] Task 5: Frontend — Chat interface model selector
|
||||
- [x] Subtask 5.1: `model-selector.tsx` — thêm `?` vào `onAddNewLLM` prop (optional), wrap "Add Model" button với `{onAddNewLLM && (...)}`
|
||||
- [x] Subtask 5.2: `chat-header.tsx` — import `currentUserAtom`, compute `isAdmin`, truyền `onAddNew*={isAdmin ? handler : undefined}` cho cả 3 model types
|
||||
|
||||
## Dev Notes
|
||||
|
||||
### Tại sao làm optional thay vì truyền boolean?
|
||||
`ModelSelector` đã có pattern `{onAddNewImage && (...)}` cho Image và Vision — consistent nhất là làm `onAddNewLLM` optional và dùng cùng pattern, thay vì thêm prop `showAddButton`.
|
||||
|
||||
### Existing model configs (có user_id)
|
||||
Existing configs của các user trước kia vẫn hoạt động bình thường — migration chỉ làm nullable, không xóa data. Tuy nhiên, vì GET endpoint không filter theo user_id nên tất cả configs (kể cả cũ) đều visible cho mọi member trong search space.
|
||||
|
||||
### Image/Vision edit buttons trong model selector
|
||||
`onEditImage` và `onEditVision` props không được gated — regular user vẫn có thể click edit nhưng sẽ xem ở mode "view" (dialog opens in view mode for global configs). Việc submit edit sẽ bị 403 từ backend. Đây là acceptable — UX nhất quán đủ dùng.
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
### Verification Results (2026-04-15)
|
||||
|
||||
**Regular user (epic5user@example.com):**
|
||||
- Model selector popup: "No models found" — NO Add/Add Image Model/Add Vision Model buttons ✅
|
||||
- `POST /api/v1/new-llm-configs` with regular user token → HTTP 403 Forbidden ✅
|
||||
|
||||
**Admin (admin@surfsense.local):**
|
||||
- `POST /api/v1/new-llm-configs` → HTTP 422 (schema validation error, NOT 403) → superuser check passed ✅
|
||||
|
||||
**DB:**
|
||||
- `new_llm_configs.user_id`: `is_nullable=YES` ✅
|
||||
- `image_generation_configs.user_id`: `is_nullable=YES` ✅
|
||||
- `vision_llm_configs.user_id`: `is_nullable=YES` ✅
|
||||
|
||||
### File List
|
||||
- `surfsense_backend/alembic/versions/128_make_model_config_user_id_nullable.py` — NEW migration
|
||||
- `surfsense_backend/app/users.py` — added `current_superuser` export
|
||||
- `surfsense_backend/app/routes/admin_routes.py` — import `current_superuser` from `users.py` instead of defining locally
|
||||
- `surfsense_backend/app/routes/new_llm_config_routes.py` — superuser gate on POST/PUT/DELETE, `user_id=None`
|
||||
- `surfsense_backend/app/routes/image_generation_routes.py` — superuser gate on config POST/PUT/DELETE
|
||||
- `surfsense_backend/app/routes/vision_llm_routes.py` — superuser gate on POST/PUT/DELETE
|
||||
- `surfsense_web/components/settings/model-config-manager.tsx` — `is_superuser` replaces RBAC flags
|
||||
- `surfsense_web/components/settings/image-model-manager.tsx` — same
|
||||
- `surfsense_web/components/settings/vision-model-manager.tsx` — same
|
||||
- `surfsense_web/components/new-chat/model-selector.tsx` — `onAddNewLLM` made optional, LLM Add button gated
|
||||
- `surfsense_web/components/new-chat/chat-header.tsx` — `isAdmin` check gates all 3 `onAddNew*` props
|
||||
|
||||
### Change Log
|
||||
- 2026-04-15: Implement admin-only model configuration — superuser gate on backend CUD, hide Add/Edit/Delete UI for regular users in both chat selector and settings dialog.
|
||||
|
||||
---
|
||||
|
||||
## Post-Story Bug Fixes & Enhancements (2026-04-15)
|
||||
|
||||
### Bug 1: "No models found" for regular users
|
||||
|
||||
**Root Cause:** Admin configs scoped to `search_space_id=5`. Each user has their own space. GET filtered strictly by space ID → configs invisible to other users.
|
||||
|
||||
**Fix:**
|
||||
- Migration 129: `search_space_id` nullable in all 3 config tables
|
||||
- `db.py`: `search_space_id = nullable=True` in all 3 SQLAlchemy models (also fixed `user_id` mismatch)
|
||||
- Schemas: `search_space_id: int | None = None` in Create/Read for all 3 types
|
||||
- GET list query: `WHERE search_space_id = :id OR search_space_id IS NULL`
|
||||
- Re-seeded all configs without `search_space_id` → global (visible to all spaces)
|
||||
|
||||
### Bug 2: Chat error with stale config ID
|
||||
|
||||
**Root Cause:** Frontend kept `agent_llm_id` pointing to a deleted config.
|
||||
|
||||
**Fix:** `model-selector.tsx` — `useEffect` auto-resets `agent_llm_id` to `null` when saved preference ID no longer exists in fetched configs.
|
||||
|
||||
### Bug 3: db.py `nullable=False` mismatch
|
||||
|
||||
**Root Cause:** Migration 128 made DB columns nullable but SQLAlchemy models still said `nullable=False`.
|
||||
|
||||
**Fix:** All 3 models in `db.py` updated to `nullable=True` for both `user_id` and `search_space_id`.
|
||||
|
||||
### Security: api_key exposed in GET list
|
||||
|
||||
**Fix:** GET list response model changed from `*Read` (exposes `api_key`) to `*Public` (hides it) for all 3 config types.
|
||||
|
||||
### New: Image configs (3 global, via v98store)
|
||||
|
||||
| Name | model_name |
|
||||
|------|-----------|
|
||||
| DALL-E 3 | `dall-e-3` |
|
||||
| GPT-Image 1 | `gpt-image-1` |
|
||||
| Flux Pro | `flux-pro` |
|
||||
|
||||
### New: Vision configs (3 global, via v98store)
|
||||
|
||||
| Name | model_name |
|
||||
|------|-----------|
|
||||
| GPT-4o Vision | `gpt-4o` |
|
||||
| Claude Sonnet 4 Vision | `claude-sonnet-4-20250514` |
|
||||
| Gemini 2.5 Flash Vision | `gemini-2.5-flash` |
|
||||
|
||||
### Enhancement: Edit buttons admin-only in model selector
|
||||
|
||||
**Fix:** `onEditLLM` prop in `ModelSelectorProps` changed from required → optional. In `chat-header.tsx`, all 3 `onEdit*` props now gated with `isAdmin ? handler : undefined` — consistent với `onAdd*` pattern đã có. Regular users thấy model list read-only, không có edit button trên hover.
|
||||
|
||||
### Additional Files Changed
|
||||
- `surfsense_backend/alembic/versions/129_make_model_config_search_space_id_nullable.py`
|
||||
- `surfsense_backend/app/db.py`
|
||||
- `surfsense_backend/app/schemas/new_llm_config.py`, `image_generation.py`, `vision_llm.py`
|
||||
- `surfsense_backend/app/routes/new_llm_config_routes.py`, `image_generation_routes.py`, `vision_llm_routes.py`
|
||||
- `surfsense_web/components/new-chat/model-selector.tsx`
|
||||
- `surfsense_web/components/new-chat/chat-header.tsx`
|
||||
|
||||
## Review Findings (2026-04-15)
|
||||
|
||||
- [x] [Review][Patch] Superuser config update/delete can modify any config (not just global ones) [new_llm_config_routes.py:274,357, image_generation_routes.py:373,405, vision_llm_routes.py:222,254] — **Fixed**: Added `user_id.is_(None)` filter to all superuser PUT/DELETE endpoints
|
||||
- [x] [Review][Patch] admin_approval_mode field missing from CreateSubscriptionCheckoutResponse — **Already fixed**: field was already present in schemas/stripe.py with `bool = False` default
|
||||
|
|
@ -15,7 +15,19 @@
|
|||
- Subscription lifecycle events (`invoice.paid`, `customer.subscription.updated/deleted`, `invoice.payment_failed`) not handled — scope of Story 5.3.
|
||||
- `_get_or_create_stripe_customer` can create orphaned Stripe customers if `db_session.commit()` fails after `customers.create`. Consider idempotency key in future.
|
||||
|
||||
## Deferred from: Story 5.6 post-story bug fixes (2026-04-15)
|
||||
|
||||
- **`api_key` exposed in LLM preferences response** [`surfsense_backend/app/routes/search_space_routes.py`] — `GET/PUT /search-spaces/{id}/llm-preferences` returns full config objects including `api_key` (nested `agent_llm`, `document_summary_llm`, etc. fields). Should return sanitized Public versions (no api_key). Low risk since endpoint requires authentication, but still a credentials leak.
|
||||
|
||||
## Deferred from: code review of story-5.3 (2026-04-15)
|
||||
|
||||
- Race condition: `checkout.session.completed` and `customer.subscription.deleted` can fire near-simultaneously; if deleted arrives between checkout handlers, subscription can be reactivated. Fix requires Stripe API call to verify subscription status before activation.
|
||||
- `invoice.payment_succeeded` does not update `subscription_current_period_end` — currently relies on `customer.subscription.updated` firing in the same event sequence. If that event is lost, period_end is stale.
|
||||
|
||||
## Deferred from: code review of Epic 5 (2026-04-15) — RESOLVED 2026-04-15
|
||||
|
||||
- ~~**Migration 124 drops enum type unconditionally**~~ — **Fixed**: Added `CASCADE` to `DROP TYPE IF EXISTS subscriptionstatus CASCADE` in `124_add_subscription_token_quota_columns.py`.
|
||||
- ~~**`checkout_url` rejects non-HTTPS URLs**~~ — **Closed as invalid**: Original `startsWith("https://")` check is intentionally correct — Stripe always returns HTTPS URLs even in test mode. Relaxing to `http` would weaken security. No change made.
|
||||
- ~~**`verify-checkout-session` endpoint lacks rate limiting**~~ — **Fixed**: Added in-memory per-user rate limit (20 calls/60s) via `_check_verify_session_rate_limit()` in `stripe_routes.py`.
|
||||
- ~~**Rejected user can re-submit approval request immediately**~~ — **Fixed**: Added 24h cooldown check using `created_at >= now() - 24h` on REJECTED requests before creating a new SubscriptionRequest.
|
||||
- ~~**`token_reset_date` not set in `_handle_subscription_event`**~~ — **Fixed**: When `new_status == ACTIVE` and `token_reset_date is None`, now sets `user.token_reset_date = datetime.now(UTC).date()`.
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@
|
|||
# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
|
||||
|
||||
generated: 2026-04-13T02:50:25+07:00
|
||||
last_updated: 2026-04-15T00:14:00+07:00
|
||||
last_updated: 2026-04-15T03:00:00+07:00
|
||||
project: SurfSense
|
||||
project_key: NOKEY
|
||||
tracking_system: file-system
|
||||
|
|
@ -69,5 +69,7 @@ development_status:
|
|||
5-1-pricing-plan-selection-ui: done
|
||||
5-2-stripe-payment-integration: done
|
||||
5-3-stripe-webhook-sync: done
|
||||
5-4-usage-tracking-rate-limit-enforcement: ready-for-dev
|
||||
5-4-usage-tracking-rate-limit-enforcement: done
|
||||
5-5-admin-seed-and-approval-flow: done
|
||||
5-6-admin-only-model-config: done
|
||||
epic-5-retrospective: optional
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue