qzl
ad06fe7de4
Consolidate backend modules/tests under the backend package while syncing Supabase compose/env config and related plans.
114 lines
6.7 KiB
Markdown
114 lines
6.7 KiB
Markdown
# Plan: Merge Supabase Compose and Base Services
|
|
|
|
**Date:** 2026-02-05
|
|
**Author:** AI Assistant
|
|
**Status:** Draft
|
|
|
|
## Overview
|
|
|
|
Integrate Supabase Docker services into the project's `infra/docker/docker-compose.yml` and align all environment variables with the project's `.env` conventions. Add reusable BaseRepository and BaseService abstractions (soft-delete filtering and auth/user validation) and refactor profile/auth services to use them, with full TDD coverage.
|
|
|
|
## Requirements
|
|
|
|
### Functional
|
|
- [ ] Merge Supabase Docker Compose services into `infra/docker/docker-compose.yml` using project `.env` variable names.
|
|
- [ ] Update `.env.example` to include all required Supabase compose variables.
|
|
- [ ] Implement BaseRepository with standard soft-delete filtering (excludes `deleted_at` rows by default).
|
|
- [ ] Implement BaseService with shared auth/user validation helpers.
|
|
- [ ] Refactor profile repository/service and auth service to use BaseRepository/BaseService.
|
|
- [ ] Add unit, integration, and E2E tests following TDD.
|
|
|
|
### Non-Functional
|
|
- [ ] Performance: keep repository queries indexed and avoid extra round-trips.
|
|
- [ ] Security: validate user identity consistently; no secrets in repo; no bypass of auth checks.
|
|
- [ ] Compatibility: keep Supabase config compatible with existing `Settings` and `.env` prefixes.
|
|
|
|
## Technical Approach
|
|
|
|
Introduce small, reusable base classes in `backend/src/core` for repository and service concerns, then refactor profile and auth modules to leverage them. Merge the Supabase compose services from the official template into `infra/docker/docker-compose.yml`, mapping variables to `SOCIAL_SUPABASE__*` and related infra keys already used in `backend/src/core/config/settings.py`.
|
|
|
|
### Key Decisions
|
|
| Decision | Rationale |
|
|
|----------|-----------|
|
|
| BaseRepository provides a `base_select()` or `apply_soft_delete_filter()` | Avoid duplicated `deleted_at` filters and enforce consistent behavior. |
|
|
| BaseService handles user validation helpers | Keeps auth checks consistent across services and reduces duplicated error handling. |
|
|
| Compose variables aligned to `SOCIAL_*` prefixes | Matches existing settings resolution and simplifies local/dev parity. |
|
|
|
|
## Implementation Steps
|
|
|
|
### Phase 1: Compose Merge and Env Alignment (3 hours)
|
|
1. Identify the Supabase Docker Compose template to merge (official Supabase Docker template) and list required services and env vars.
|
|
2. Merge Supabase services into `infra/docker/docker-compose.yml`, keeping existing Redis/Qdrant services intact and aligning ports/volumes.
|
|
3. Map Supabase compose env variables to project `.env` names (e.g., `SOCIAL_SUPABASE__*`, `SOCIAL_INFRA__*` where needed).
|
|
4. Update `.env.example` with all required Supabase-related variables, keeping comments updated for local vs. cloud usage.
|
|
5. Add/adjust docker compose healthchecks or depends_on as needed for startup ordering.
|
|
|
|
### Phase 2: BaseRepository and BaseService (4 hours)
|
|
1. Add `backend/src/core/db/repository.py` (or `backend/src/core/repository/base.py`) with a BaseRepository that applies `SoftDeleteMixin` filters by default.
|
|
2. Add `backend/src/core/services/base.py` with BaseService helpers for current user validation (e.g., `require_user`, `require_user_id`).
|
|
3. Add unit tests for BaseRepository soft delete filtering and BaseService auth validation (TDD red/green).
|
|
|
|
### Phase 3: Refactor Profile/Auth (4 hours)
|
|
1. Refactor `backend/src/v1/profile/repository.py` to inherit from BaseRepository and remove duplicated `deleted_at` logic.
|
|
2. Refactor `backend/src/v1/profile/service.py` to inherit from BaseService and use shared validation helpers where applicable.
|
|
3. Refactor `backend/src/v1/auth/service.py` to adopt BaseService helpers for user validation (where applicable) and keep gateway contract unchanged.
|
|
4. Update unit tests for profile and auth services to reflect base class usage and ensure behavior unchanged.
|
|
|
|
### Phase 4: Integration/E2E Tests and Hardening (4 hours)
|
|
1. Add integration tests for repository soft delete behavior using SQLAlchemy session fixtures.
|
|
2. Add or update E2E tests for profile flow to ensure auth/user validation still enforced.
|
|
3. Run coverage check (80%+), fix gaps, and verify CI pre-commit tooling passes.
|
|
|
|
## Files to Modify
|
|
|
|
| File | Changes |
|
|
|------|---------|
|
|
| infra/docker/docker-compose.yml | Merge Supabase services; map env vars to `SOCIAL_*`. |
|
|
| .env.example | Add Supabase compose variables and update comments. |
|
|
| backend/src/v1/profile/repository.py | Inherit BaseRepository; simplify soft delete filtering. |
|
|
| backend/src/v1/profile/service.py | Inherit BaseService; use shared validation helpers. |
|
|
| backend/src/v1/auth/service.py | Use BaseService helpers where applicable. |
|
|
| backend/tests/unit/v1/profile/* | Update tests for BaseRepository/BaseService. |
|
|
| backend/tests/unit/v1/auth/* | Update tests for base service helpers (if needed). |
|
|
| backend/tests/integration/* | Add/adjust tests for soft delete filtering. |
|
|
| backend/tests/e2e/* | Update/extend critical auth/profile flow tests. |
|
|
|
|
## Files to Create
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| backend/src/core/db/repository.py | BaseRepository with soft-delete filtering. |
|
|
| backend/src/core/services/base.py | BaseService with auth/user validation helpers. |
|
|
| backend/tests/unit/core/db/test_base_repository.py | Unit tests for soft delete filters. |
|
|
| backend/tests/unit/core/services/test_base_service.py | Unit tests for auth/user validation. |
|
|
|
|
## Dependencies
|
|
|
|
- [ ] Supabase official Docker Compose template (source of services/env vars).
|
|
- [ ] No new Python dependencies expected.
|
|
|
|
## Testing Strategy
|
|
|
|
- **Unit Tests:** BaseRepository soft-delete filter logic; BaseService user validation helpers; updated profile/auth service behavior.
|
|
- **Integration Tests:** SQLAlchemy queries exclude soft-deleted rows; profile endpoints still return expected responses.
|
|
- **E2E Tests:** Critical profile flow with authenticated user; verify unauthorized access remains blocked.
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Impact | Likelihood | Mitigation |
|
|
|------|--------|------------|------------|
|
|
| Missing or outdated Supabase compose template | Medium | Medium | Pin to official template version and document source in plan. |
|
|
| Env var mismatches break local auth or DB connections | High | Medium | Add validation checklist and update `.env.example` with exact mappings. |
|
|
| BaseRepository changes alter query behavior | Medium | Medium | Add unit/integration tests and verify no regressions. |
|
|
| Auth validation refactor introduces regressions | High | Low | TDD with unit + E2E tests; keep behavior parity. |
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Effort |
|
|
|-------|--------|
|
|
| Phase 1 | 3 hours |
|
|
| Phase 2 | 4 hours |
|
|
| Phase 3 | 4 hours |
|
|
| Phase 4 | 4 hours |
|
|
| **Total** | **15 hours** |
|