spark-store-project/spark-store
15
0
Fork 0
mirror of https://gitee.com/spark-store-project/spark-store synced 2026-06-23 06:33:49 +08:00
Code Issues 1 Packages Projects Releases Wiki Activity
Files
23b09ca863af0d63f9341ddb2cf45ad2e4e636f4
spark-store/docs/superpowers/plans/2026-05-18-spark-backend-account-reviews-sync.md
T

1669 lines
49 KiB
Markdown
Raw Blame History

# Spark Backend Account Reviews Sync Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Build the new `spark-store-backend` FastAPI + MySQL service for Flarum-backed login, app reviews/ratings, and default user app-list sync.
**Architecture:** The backend validates Flarum access tokens, maps Flarum users to local users, signs Spark Store JWTs, and persists Spark Store-specific data in MySQL. The API uses synchronous FastAPI routes, SQLAlchemy ORM, Alembic migrations, and pytest API tests with a SQLite test database.
**Tech Stack:** Python 3.11+, FastAPI, SQLAlchemy 2.x, Alembic, PyMySQL, Pydantic Settings, python-jose, httpx, pytest.
---
## File Structure
Create a new sibling repository at `/home/spark/Desktop/shenmo-spark-store/spark-store-backend`.
Backend files:
- Create: `README.md` - project overview, setup, test commands, API summary.
- Create: `.gitignore` - Python, virtualenv, test, and secret ignores.
- Create: `.env.example` - safe configuration template.
- Create: `pyproject.toml` - dependencies, pytest config, tooling config.
- Create: `alembic.ini` - Alembic config.
- Create: `alembic/env.py` - migration environment wired to app metadata.
- Create: `alembic/versions/0001_initial.py` - initial MySQL schema.
- Create: `app/main.py` - FastAPI app factory and router registration.
- Create: `app/core/config.py` - environment settings.
- Create: `app/core/security.py` - JWT creation and decoding.
- Create: `app/db/session.py` - SQLAlchemy engine/session dependency.
- Create: `app/db/base.py` - declarative base and model imports.
- Create: `app/models/user.py` - `User` ORM model.
- Create: `app/models/store_app.py` - `StoreApp` ORM model.
- Create: `app/models/review.py` - `Review` ORM model.
- Create: `app/models/app_list.py` - app-list ORM models.
- Create: `app/schemas/auth.py` - auth request/response schemas.
- Create: `app/schemas/review.py` - review request/response schemas.
- Create: `app/schemas/app_list.py` - app-list request/response schemas.
- Create: `app/services/flarum.py` - Flarum profile validation client.
- Create: `app/api/deps.py` - auth and DB dependencies.
- Create: `app/api/router.py` - API router aggregator.
- Create: `app/api/routes/auth.py` - auth endpoints.
- Create: `app/api/routes/reviews.py` - review and rating endpoints.
- Create: `app/api/routes/app_lists.py` - app-list endpoints.
- Create: `tests/conftest.py` - test app and database fixtures.
- Create: `tests/test_auth.py` - Flarum auth tests.
- Create: `tests/test_reviews.py` - review behavior tests.
- Create: `tests/test_app_lists.py` - app-list sync tests.
## Task 1: Initialize Backend Repository
**Files:**
- Create: `/home/spark/Desktop/shenmo-spark-store/spark-store-backend/README.md`
- Create: `/home/spark/Desktop/shenmo-spark-store/spark-store-backend/.gitignore`
- [ ] **Step 1: Verify parent directory exists**
Run: `ls "/home/spark/Desktop/shenmo-spark-store"`
Expected: output includes `spark-store`.
- [ ] **Step 2: Create repository directory**
Run: `mkdir "/home/spark/Desktop/shenmo-spark-store/spark-store-backend"`
Expected: command exits 0.
- [ ] **Step 3: Initialize Git repository**
Run: `git init`
Workdir: `/home/spark/Desktop/shenmo-spark-store/spark-store-backend`
Expected: output says an empty Git repository was initialized.
- [ ] **Step 4: Write initial README**
Create `README.md` with:
```markdown
# Spark Store Backend
Python backend for Spark Store account login, app reviews, ratings, and user app-list sync.
The service uses the Spark forum Flarum instance as the identity provider and stores Spark Store-specific data in MySQL.
## Development
```bash
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
```
```
- [ ] **Step 5: Write `.gitignore`**
Create `.gitignore` with:
```gitignore
.venv/
__pycache__/
*.py[cod]
.pytest_cache/
.coverage
htmlcov/
.env
*.sqlite3
dist/
build/
*.egg-info/
```
- [ ] **Step 6: Commit initial repository**
Run:
```bash
git add README.md .gitignore
git commit -m "first commit"
git remote add origin https://gitee.com/momen_official/spark-store-backend.git
```
Expected: commit succeeds and `git remote -v` shows the Gitee origin.
## Task 2: Add Backend Project Skeleton
**Files:**
- Create: `pyproject.toml`
- Create: `.env.example`
- Create: `app/__init__.py`
- Create: `app/main.py`
- Create: `app/core/config.py`
- Create: `app/api/router.py`
- Test: `tests/test_health.py`
- [ ] **Step 1: Write failing health test**
Create `tests/test_health.py` with:
```python
from fastapi.testclient import TestClient
from app.main import create_app
def test_health_returns_ok():
client = TestClient(create_app())
response = client.get("/health")
assert response.status_code == 200
assert response.json() == {"status": "ok"}
```
- [ ] **Step 2: Run test and verify failure**
Run: `pytest tests/test_health.py -v`
Expected: FAIL with `ModuleNotFoundError: No module named 'app'`.
- [ ] **Step 3: Add package config**
Create `pyproject.toml` with:
```toml
[build-system]
requires = ["setuptools>=69"]
build-backend = "setuptools.build_meta"
[project]
name = "spark-store-backend"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"fastapi>=0.115,<1.0",
"uvicorn[standard]>=0.30,<1.0",
"sqlalchemy>=2.0,<3.0",
"alembic>=1.13,<2.0",
"pymysql>=1.1,<2.0",
"pydantic-settings>=2.4,<3.0",
"python-jose[cryptography]>=3.3,<4.0",
"httpx>=0.27,<1.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.3,<9.0",
"pytest-cov>=5.0,<6.0",
]
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["."]
```
- [ ] **Step 4: Add settings**
Create `.env.example` with:
```env
APP_NAME="Spark Store Backend"
DATABASE_URL="mysql+pymysql://spark:spark_password@127.0.0.1:3306/spark_store"
JWT_SECRET_KEY="change-me-in-production"
JWT_ALGORITHM="HS256"
JWT_EXPIRE_MINUTES="10080"
FLARUM_BASE_URL="https://bbs.spark-app.store"
```
Create `app/core/config.py` with:
```python
from functools import lru_cache
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
app_name: str = "Spark Store Backend"
database_url: str = "sqlite:///./spark-store-dev.sqlite3"
jwt_secret_key: str = "dev-secret"
jwt_algorithm: str = "HS256"
jwt_expire_minutes: int = 10080
flarum_base_url: str = "https://bbs.spark-app.store"
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
@lru_cache
def get_settings() -> Settings:
return Settings()
```
- [ ] **Step 5: Add FastAPI app**
Create `app/__init__.py` as an empty file.
Create `app/api/router.py` with:
```python
from fastapi import APIRouter
api_router = APIRouter()
```
Create `app/main.py` with:
```python
from fastapi import FastAPI
from app.api.router import api_router
from app.core.config import get_settings
def create_app() -> FastAPI:
settings = get_settings()
app = FastAPI(title=settings.app_name)
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
app.include_router(api_router)
return app
app = create_app()
```
- [ ] **Step 6: Run test and verify pass**
Run: `pytest tests/test_health.py -v`
Expected: PASS.
- [ ] **Step 7: Commit skeleton**
Run:
```bash
git add .
git commit -m "feat: add FastAPI backend skeleton"
```
Expected: commit succeeds.
## Task 3: Add Database Models And Migration
**Files:**
- Create: `app/db/session.py`
- Create: `app/db/base.py`
- Create: `app/models/user.py`
- Create: `app/models/store_app.py`
- Create: `app/models/review.py`
- Create: `app/models/app_list.py`
- Create: `alembic.ini`
- Create: `alembic/env.py`
- Create: `alembic/versions/0001_initial.py`
- Test: `tests/test_models.py`
- [ ] **Step 1: Write failing model test**
Create `tests/test_models.py` with:
```python
from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from app.db.base import Base
from app.models.user import User
from app.models.store_app import StoreApp
from app.models.review import Review
def test_review_model_persists_tagged_rating():
engine = create_engine("sqlite:///:memory:")
Base.metadata.create_all(engine)
with Session(engine) as session:
user = User(flarum_user_id="123", username="momen", display_name="Momen")
app = StoreApp(
app_key="apm:amd64-apm:office:wps",
pkgname="wps",
origin="apm",
store_arch="amd64-apm",
category="office",
latest_seen_version="1.0.0",
)
session.add_all([user, app])
session.flush()
review = Review(
user_id=user.id,
app_id=app.id,
rating=5,
content="Works well.",
version="1.0.0",
package_arch="amd64",
client_arch="amd64",
distro="deepin 25",
origin="apm",
category="office",
)
session.add(review)
session.commit()
stored = session.query(Review).one()
assert stored.rating == 5
assert stored.version == "1.0.0"
assert stored.distro == "deepin 25"
```
- [ ] **Step 2: Run test and verify failure**
Run: `pytest tests/test_models.py -v`
Expected: FAIL with missing `app.db.base` or models.
- [ ] **Step 3: Add database session and base**
Create `app/db/session.py` with:
```python
from collections.abc import Generator
from sqlalchemy import create_engine
from sqlalchemy.orm import Session, sessionmaker
from app.core.config import get_settings
settings = get_settings()
engine = create_engine(settings.database_url, pool_pre_ping=True)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
def get_db() -> Generator[Session, None, None]:
db = SessionLocal()
try:
yield db
finally:
db.close()
```
Create `app/db/base.py` with:
```python
from sqlalchemy.orm import DeclarativeBase
class Base(DeclarativeBase):
pass
from app.models.app_list import UserAppList, UserAppListItem # noqa: E402,F401
from app.models.review import Review # noqa: E402,F401
from app.models.store_app import StoreApp # noqa: E402,F401
from app.models.user import User # noqa: E402,F401
```
- [ ] **Step 4: Add ORM models**
Create `app/models/user.py` with:
```python
from datetime import datetime, timezone
from sqlalchemy import DateTime, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
def utcnow() -> datetime:
return datetime.now(timezone.utc)
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
flarum_user_id: Mapped[str] = mapped_column(String(64), unique=True, index=True)
username: Mapped[str] = mapped_column(String(128), default="")
display_name: Mapped[str] = mapped_column(String(128), default="")
avatar_url: Mapped[str] = mapped_column(String(1024), default="")
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow)
reviews = relationship("Review", back_populates="user")
app_lists = relationship("UserAppList", back_populates="user")
```
Create `app/models/store_app.py` with:
```python
from datetime import datetime, timezone
from sqlalchemy import DateTime, String
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
def utcnow() -> datetime:
return datetime.now(timezone.utc)
class StoreApp(Base):
__tablename__ = "apps"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
app_key: Mapped[str] = mapped_column(String(512), unique=True, index=True)
pkgname: Mapped[str] = mapped_column(String(255), index=True)
origin: Mapped[str] = mapped_column(String(16), index=True)
store_arch: Mapped[str] = mapped_column(String(64), index=True)
category: Mapped[str] = mapped_column(String(128), index=True)
latest_seen_version: Mapped[str] = mapped_column(String(255), default="")
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow)
reviews = relationship("Review", back_populates="app")
```
Create `app/models/review.py` with:
```python
from datetime import datetime, timezone
from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, String, Text, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
def utcnow() -> datetime:
return datetime.now(timezone.utc)
class Review(Base):
__tablename__ = "reviews"
__table_args__ = (
CheckConstraint("rating >= 1 AND rating <= 5", name="ck_reviews_rating_range"),
UniqueConstraint(
"user_id",
"app_id",
"version",
"package_arch",
"client_arch",
"distro",
"origin",
"category",
name="uq_reviews_user_app_tags",
),
Index("ix_reviews_app_filters", "app_id", "version", "package_arch", "client_arch", "distro", "origin", "category"),
)
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
app_id: Mapped[int] = mapped_column(ForeignKey("apps.id"), index=True)
rating: Mapped[int]
content: Mapped[str] = mapped_column(Text)
version: Mapped[str] = mapped_column(String(255), default="unknown")
package_arch: Mapped[str] = mapped_column(String(64), default="unknown")
client_arch: Mapped[str] = mapped_column(String(64), default="unknown")
distro: Mapped[str] = mapped_column(String(255), default="unknown")
origin: Mapped[str] = mapped_column(String(16), default="")
category: Mapped[str] = mapped_column(String(128), default="")
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow)
user = relationship("User", back_populates="reviews")
app = relationship("StoreApp", back_populates="reviews")
```
Create `app/models/app_list.py` with:
```python
from datetime import datetime, timezone
from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
def utcnow() -> datetime:
return datetime.now(timezone.utc)
class UserAppList(Base):
__tablename__ = "user_app_lists"
__table_args__ = (UniqueConstraint("user_id", "snapshot_name", name="uq_user_app_lists_default"),)
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
user_id: Mapped[int] = mapped_column(ForeignKey("users.id"), index=True)
snapshot_name: Mapped[str] = mapped_column(String(128), default="default")
client_arch: Mapped[str] = mapped_column(String(64), default="unknown")
distro: Mapped[str] = mapped_column(String(255), default="unknown")
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow, onupdate=utcnow)
user = relationship("User", back_populates="app_lists")
items = relationship("UserAppListItem", back_populates="app_list", cascade="all, delete-orphan")
class UserAppListItem(Base):
__tablename__ = "user_app_list_items"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
list_id: Mapped[int] = mapped_column(ForeignKey("user_app_lists.id"), index=True)
pkgname: Mapped[str] = mapped_column(String(255), index=True)
origin: Mapped[str] = mapped_column(String(16), index=True)
category: Mapped[str] = mapped_column(String(128), index=True)
version: Mapped[str] = mapped_column(String(255), default="")
package_arch: Mapped[str] = mapped_column(String(64), default="unknown")
app_name: Mapped[str] = mapped_column(String(255), default="")
icon_url: Mapped[str] = mapped_column(String(1024), default="")
created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
app_list = relationship("UserAppList", back_populates="items")
```
- [ ] **Step 5: Run model test and verify pass**
Run: `pytest tests/test_models.py -v`
Expected: PASS.
- [ ] **Step 6: Add Alembic migration**
Create `alembic.ini` with:
```ini
[alembic]
script_location = alembic
prepend_sys_path = .
sqlalchemy.url = sqlite:///./spark-store-dev.sqlite3
[loggers]
keys = root,sqlalchemy,alembic
[handlers]
keys = console
[formatters]
keys = generic
[logger_root]
level = WARN
handlers = console
qualname =
[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine
[logger_alembic]
level = INFO
handlers =
qualname = alembic
[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic
[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S
```
Create `alembic/env.py` with:
```python
from logging.config import fileConfig
from alembic import context
from sqlalchemy import engine_from_config, pool
from app.core.config import get_settings
from app.db.base import Base
config = context.config
config.set_main_option("sqlalchemy.url", get_settings().database_url)
if config.config_file_name is not None:
fileConfig(config.config_file_name)
target_metadata = Base.metadata
def run_migrations_offline() -> None:
url = config.get_main_option("sqlalchemy.url")
context.configure(url=url, target_metadata=target_metadata, literal_binds=True, compare_type=True)
with context.begin_transaction():
context.run_migrations()
def run_migrations_online() -> None:
connectable = engine_from_config(
config.get_section(config.config_ini_section, {}),
prefix="sqlalchemy.",
poolclass=pool.NullPool,
)
with connectable.connect() as connection:
context.configure(connection=connection, target_metadata=target_metadata, compare_type=True)
with context.begin_transaction():
context.run_migrations()
if context.is_offline_mode():
run_migrations_offline()
else:
run_migrations_online()
```
Create `alembic/versions/0001_initial.py` with:
```python
from collections.abc import Sequence
import sqlalchemy as sa
from alembic import op
revision: str = "0001_initial"
down_revision: str | None = None
branch_labels: str | Sequence[str] | None = None
depends_on: str | Sequence[str] | None = None
def upgrade() -> None:
op.create_table(
"users",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
sa.Column("flarum_user_id", sa.String(length=64), nullable=False),
sa.Column("username", sa.String(length=128), nullable=False),
sa.Column("display_name", sa.String(length=128), nullable=False),
sa.Column("avatar_url", sa.String(length=1024), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
sa.UniqueConstraint("flarum_user_id"),
)
op.create_index("ix_users_flarum_user_id", "users", ["flarum_user_id"])
op.create_table(
"apps",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
sa.Column("app_key", sa.String(length=512), nullable=False),
sa.Column("pkgname", sa.String(length=255), nullable=False),
sa.Column("origin", sa.String(length=16), nullable=False),
sa.Column("store_arch", sa.String(length=64), nullable=False),
sa.Column("category", sa.String(length=128), nullable=False),
sa.Column("latest_seen_version", sa.String(length=255), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
sa.UniqueConstraint("app_key"),
)
op.create_index("ix_apps_app_key", "apps", ["app_key"])
op.create_index("ix_apps_pkgname", "apps", ["pkgname"])
op.create_index("ix_apps_origin", "apps", ["origin"])
op.create_index("ix_apps_store_arch", "apps", ["store_arch"])
op.create_index("ix_apps_category", "apps", ["category"])
op.create_table(
"reviews",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
sa.Column("app_id", sa.Integer(), sa.ForeignKey("apps.id"), nullable=False),
sa.Column("rating", sa.Integer(), nullable=False),
sa.Column("content", sa.Text(), nullable=False),
sa.Column("version", sa.String(length=255), nullable=False),
sa.Column("package_arch", sa.String(length=64), nullable=False),
sa.Column("client_arch", sa.String(length=64), nullable=False),
sa.Column("distro", sa.String(length=255), nullable=False),
sa.Column("origin", sa.String(length=16), nullable=False),
sa.Column("category", sa.String(length=128), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
sa.CheckConstraint("rating >= 1 AND rating <= 5", name="ck_reviews_rating_range"),
sa.UniqueConstraint("user_id", "app_id", "version", "package_arch", "client_arch", "distro", "origin", "category", name="uq_reviews_user_app_tags"),
)
op.create_index("ix_reviews_user_id", "reviews", ["user_id"])
op.create_index("ix_reviews_app_id", "reviews", ["app_id"])
op.create_index("ix_reviews_app_filters", "reviews", ["app_id", "version", "package_arch", "client_arch", "distro", "origin", "category"])
op.create_table(
"user_app_lists",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
sa.Column("user_id", sa.Integer(), sa.ForeignKey("users.id"), nullable=False),
sa.Column("snapshot_name", sa.String(length=128), nullable=False),
sa.Column("client_arch", sa.String(length=64), nullable=False),
sa.Column("distro", sa.String(length=255), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
sa.UniqueConstraint("user_id", "snapshot_name", name="uq_user_app_lists_default"),
)
op.create_index("ix_user_app_lists_user_id", "user_app_lists", ["user_id"])
op.create_table(
"user_app_list_items",
sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
sa.Column("list_id", sa.Integer(), sa.ForeignKey("user_app_lists.id"), nullable=False),
sa.Column("pkgname", sa.String(length=255), nullable=False),
sa.Column("origin", sa.String(length=16), nullable=False),
sa.Column("category", sa.String(length=128), nullable=False),
sa.Column("version", sa.String(length=255), nullable=False),
sa.Column("package_arch", sa.String(length=64), nullable=False),
sa.Column("app_name", sa.String(length=255), nullable=False),
sa.Column("icon_url", sa.String(length=1024), nullable=False),
sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
)
op.create_index("ix_user_app_list_items_list_id", "user_app_list_items", ["list_id"])
op.create_index("ix_user_app_list_items_pkgname", "user_app_list_items", ["pkgname"])
op.create_index("ix_user_app_list_items_origin", "user_app_list_items", ["origin"])
op.create_index("ix_user_app_list_items_category", "user_app_list_items", ["category"])
def downgrade() -> None:
op.drop_table("user_app_list_items")
op.drop_table("user_app_lists")
op.drop_table("reviews")
op.drop_table("apps")
op.drop_table("users")
```
Run: `alembic upgrade head`
Expected: local development database receives revision `0001_initial`.
- [ ] **Step 7: Commit database layer**
Run:
```bash
git add app/db app/models alembic.ini alembic tests/test_models.py
git commit -m "feat: add database schema"
```
Expected: commit succeeds.
## Task 4: Implement Flarum Auth And JWT
**Files:**
- Create: `app/core/security.py`
- Create: `app/services/flarum.py`
- Create: `app/schemas/auth.py`
- Create: `app/api/deps.py`
- Create: `app/api/routes/auth.py`
- Modify: `app/api/router.py`
- Test: `tests/conftest.py`
- Test: `tests/test_auth.py`
- [ ] **Step 1: Write failing auth tests**
Create `tests/conftest.py` with a SQLite test database, dependency override for `get_db`, and `TestClient(create_app())` fixture.
Create `tests/test_auth.py` with:
```python
from app.models.user import User
def test_auth_flarum_creates_user_and_returns_jwt(client, monkeypatch):
async def fake_fetch_profile(token: str, user_id: str):
assert token == "forum-token"
assert user_id == "123"
return {
"flarum_user_id": "123",
"username": "momen",
"display_name": "Momen",
"avatar_url": "https://bbs.spark-app.store/avatar.png",
}
monkeypatch.setattr("app.api.routes.auth.fetch_flarum_profile", fake_fetch_profile)
response = client.post("/auth/flarum", json={"flarum_user_id": "123", "flarum_token": "forum-token"})
assert response.status_code == 200
data = response.json()
assert data["token_type"] == "bearer"
assert data["access_token"]
assert data["user"]["display_name"] == "Momen"
def test_me_requires_jwt(client):
response = client.get("/me")
assert response.status_code == 401
```
- [ ] **Step 2: Run auth tests and verify failure**
Run: `pytest tests/test_auth.py -v`
Expected: FAIL with missing auth routes or schemas.
- [ ] **Step 3: Add JWT helpers**
Create `app/core/security.py` with:
```python
from datetime import datetime, timedelta, timezone
from jose import JWTError, jwt
from app.core.config import get_settings
def create_access_token(subject: str) -> str:
settings = get_settings()
expires = datetime.now(timezone.utc) + timedelta(minutes=settings.jwt_expire_minutes)
payload = {"sub": subject, "exp": expires}
return jwt.encode(payload, settings.jwt_secret_key, algorithm=settings.jwt_algorithm)
def decode_access_token(token: str) -> str | None:
settings = get_settings()
try:
payload = jwt.decode(token, settings.jwt_secret_key, algorithms=[settings.jwt_algorithm])
except JWTError:
return None
subject = payload.get("sub")
return subject if isinstance(subject, str) else None
```
- [ ] **Step 4: Add auth schemas and Flarum service**
Create `app/schemas/auth.py` with:
```python
from pydantic import BaseModel, Field
class FlarumAuthRequest(BaseModel):
flarum_user_id: str = Field(min_length=1, max_length=64)
flarum_token: str = Field(min_length=1)
class UserPublic(BaseModel):
id: int
flarum_user_id: str
username: str
display_name: str
avatar_url: str
model_config = {"from_attributes": True}
class AuthResponse(BaseModel):
access_token: str
token_type: str = "bearer"
user: UserPublic
```
Create `app/services/flarum.py` with:
```python
import httpx
from app.core.config import get_settings
async def fetch_flarum_profile(token: str, user_id: str) -> dict[str, str]:
settings = get_settings()
url = f"{settings.flarum_base_url.rstrip('/')}/api/users/{user_id}"
async with httpx.AsyncClient(timeout=10) as client:
response = await client.get(url, headers={"Authorization": f"Token {token}"})
if response.status_code != 200:
raise ValueError("invalid flarum token")
data = response.json()["data"]
attrs = data.get("attributes", {})
return {
"flarum_user_id": str(data.get("id", user_id)),
"username": attrs.get("username") or "",
"display_name": attrs.get("displayName") or attrs.get("username") or "",
"avatar_url": attrs.get("avatarUrl") or "",
}
```
- [ ] **Step 5: Add auth dependency and routes**
Create `app/api/deps.py` with:
```python
from typing import Annotated
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from sqlalchemy.orm import Session
from app.core.security import decode_access_token
from app.db.session import get_db
from app.models.user import User
bearer = HTTPBearer(auto_error=False)
def get_current_user(
credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer)],
db: Annotated[Session, Depends(get_db)],
) -> User:
if credentials is None:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="missing bearer token")
subject = decode_access_token(credentials.credentials)
if subject is None:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid bearer token")
user = db.get(User, int(subject)) if subject.isdigit() else None
if user is None:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
return user
```
Create `app/api/routes/auth.py` with:
```python
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy import select
from sqlalchemy.orm import Session
from app.api.deps import get_current_user
from app.core.security import create_access_token
from app.db.session import get_db
from app.models.user import User
from app.schemas.auth import AuthResponse, FlarumAuthRequest, UserPublic
from app.services.flarum import fetch_flarum_profile
router = APIRouter(tags=["auth"])
@router.post("/auth/flarum", response_model=AuthResponse)
async def auth_flarum(payload: FlarumAuthRequest, db: Session = Depends(get_db)) -> AuthResponse:
try:
profile = await fetch_flarum_profile(payload.flarum_token, payload.flarum_user_id)
except ValueError as exc:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="invalid flarum token") from exc
user = db.scalar(select(User).where(User.flarum_user_id == profile["flarum_user_id"]))
if user is None:
user = User(**profile)
db.add(user)
else:
user.username = profile["username"]
user.display_name = profile["display_name"]
user.avatar_url = profile["avatar_url"]
db.commit()
db.refresh(user)
return AuthResponse(access_token=create_access_token(str(user.id)), user=UserPublic.model_validate(user))
@router.get("/me", response_model=UserPublic)
def me(user: User = Depends(get_current_user)) -> User:
return user
```
Modify `app/api/router.py` to include:
```python
from fastapi import APIRouter
from app.api.routes import auth
api_router = APIRouter()
api_router.include_router(auth.router)
```
- [ ] **Step 6: Run auth tests and verify pass**
Run: `pytest tests/test_auth.py -v`
Expected: PASS.
- [ ] **Step 7: Commit auth**
Run:
```bash
git add app tests/test_auth.py tests/conftest.py
git commit -m "feat: add Flarum auth"
```
Expected: commit succeeds.
## Task 5: Implement Reviews And Rating Summary
**Files:**
- Create: `app/schemas/review.py`
- Create: `app/api/routes/reviews.py`
- Modify: `app/api/router.py`
- Test: `tests/test_reviews.py`
- [ ] **Step 1: Write failing review tests**
Create `tests/test_reviews.py` with:
```python
from app.core.security import create_access_token
from app.models.user import User
def seed_user(db_session):
user = User(flarum_user_id="123", username="momen", display_name="Momen", avatar_url="")
db_session.add(user)
db_session.commit()
db_session.refresh(user)
return user
def auth_headers(user: User) -> dict[str, str]:
return {"Authorization": f"Bearer {create_access_token(str(user.id))}"}
def test_create_review_and_rating_summary(client, db_session):
user = seed_user(db_session)
response = client.post(
"/apps/apm:amd64-apm:office:wps/reviews",
headers=auth_headers(user),
json={
"rating": 5,
"content": "Works well.",
"tags": {
"origin": "apm",
"category": "office",
"pkgname": "wps",
"version": "1.0.0",
"package_arch": "amd64",
"client_arch": "amd64",
"distro": "deepin 25",
},
},
)
assert response.status_code == 200
assert response.json()["rating"] == 5
summary = client.get("/apps/apm:amd64-apm:office:wps/rating-summary")
assert summary.status_code == 200
assert summary.json()["average_rating"] == 5.0
assert summary.json()["review_count"] == 1
assert summary.json()["star_counts"]["5"] == 1
def test_reviews_filter_by_version(client, db_session):
user = seed_user(db_session)
headers = auth_headers(user)
for version in ["1.0.0", "2.0.0"]:
response = client.post(
"/apps/apm:amd64-apm:office:wps/reviews",
headers=headers,
json={
"rating": 4,
"content": f"Version {version}",
"tags": {
"origin": "apm",
"category": "office",
"pkgname": "wps",
"version": version,
"package_arch": "amd64",
"client_arch": "amd64",
"distro": "deepin 25",
},
},
)
assert response.status_code == 200
response = client.get("/apps/apm:amd64-apm:office:wps/reviews", params={"version": "2.0.0"})
assert response.status_code == 200
assert len(response.json()) == 1
assert response.json()[0]["version"] == "2.0.0"
```
- [ ] **Step 2: Run review tests and verify failure**
Run: `pytest tests/test_reviews.py -v`
Expected: FAIL with `404 Not Found` for review endpoints.
- [ ] **Step 3: Add review schemas**
Create `app/schemas/review.py` with:
```python
from datetime import datetime
from pydantic import BaseModel, Field
class ReviewTags(BaseModel):
origin: str = Field(min_length=1, max_length=16)
category: str = Field(min_length=1, max_length=128)
pkgname: str = Field(min_length=1, max_length=255)
version: str = Field(default="unknown", max_length=255)
package_arch: str = Field(default="unknown", max_length=64)
client_arch: str = Field(default="unknown", max_length=64)
distro: str = Field(default="unknown", max_length=255)
class ReviewCreate(BaseModel):
rating: int = Field(ge=1, le=5)
content: str = Field(min_length=1, max_length=5000)
tags: ReviewTags
class ReviewPublic(BaseModel):
id: int
rating: int
content: str
version: str
package_arch: str
client_arch: str
distro: str
origin: str
category: str
created_at: datetime
updated_at: datetime
user_display_name: str
user_avatar_url: str
class RatingSummary(BaseModel):
average_rating: float
review_count: int
star_counts: dict[int, int]
```
- [ ] **Step 4: Add review routes**
Create `app/api/routes/reviews.py` with:
```python
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import func, select
from sqlalchemy.orm import Session
from app.api.deps import get_current_user
from app.db.session import get_db
from app.models.review import Review
from app.models.store_app import StoreApp
from app.models.user import User
from app.schemas.review import RatingSummary, ReviewCreate, ReviewPublic
router = APIRouter(tags=["reviews"])
def parse_app_key(app_key: str) -> dict[str, str]:
parts = app_key.split(":", 3)
if len(parts) != 4:
raise HTTPException(status_code=422, detail="invalid app key")
origin, store_arch, category, pkgname = parts
return {"origin": origin, "store_arch": store_arch, "category": category, "pkgname": pkgname}
def get_or_create_app(db: Session, app_key: str) -> StoreApp:
parsed = parse_app_key(app_key)
app = db.scalar(select(StoreApp).where(StoreApp.app_key == app_key))
if app is not None:
return app
app = StoreApp(app_key=app_key, latest_seen_version="", **parsed)
db.add(app)
db.flush()
return app
def to_public(review: Review) -> ReviewPublic:
return ReviewPublic(
id=review.id,
rating=review.rating,
content=review.content,
version=review.version,
package_arch=review.package_arch,
client_arch=review.client_arch,
distro=review.distro,
origin=review.origin,
category=review.category,
created_at=review.created_at,
updated_at=review.updated_at,
user_display_name=review.user.display_name,
user_avatar_url=review.user.avatar_url,
)
@router.post("/apps/{app_key}/reviews", response_model=ReviewPublic)
def upsert_review(
app_key: str,
payload: ReviewCreate,
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
) -> ReviewPublic:
app = get_or_create_app(db, app_key)
tags = payload.tags
review = db.scalar(
select(Review).where(
Review.user_id == user.id,
Review.app_id == app.id,
Review.version == tags.version,
Review.package_arch == tags.package_arch,
Review.client_arch == tags.client_arch,
Review.distro == tags.distro,
Review.origin == tags.origin,
Review.category == tags.category,
)
)
if review is None:
review = Review(user_id=user.id, app_id=app.id)
db.add(review)
review.rating = payload.rating
review.content = payload.content.strip()
review.version = tags.version or "unknown"
review.package_arch = tags.package_arch or "unknown"
review.client_arch = tags.client_arch or "unknown"
review.distro = tags.distro or "unknown"
review.origin = tags.origin
review.category = tags.category
app.latest_seen_version = review.version
db.commit()
db.refresh(review)
return to_public(review)
@router.get("/apps/{app_key}/reviews", response_model=list[ReviewPublic])
def list_reviews(
app_key: str,
version: str | None = None,
package_arch: str | None = None,
client_arch: str | None = None,
distro: str | None = None,
origin: str | None = None,
category: str | None = None,
rating: int | None = Query(default=None, ge=1, le=5),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=20, ge=1, le=100),
db: Session = Depends(get_db),
) -> list[ReviewPublic]:
app = db.scalar(select(StoreApp).where(StoreApp.app_key == app_key))
if app is None:
return []
stmt = select(Review).where(Review.app_id == app.id).order_by(Review.updated_at.desc())
filters = {
Review.version: version,
Review.package_arch: package_arch,
Review.client_arch: client_arch,
Review.distro: distro,
Review.origin: origin,
Review.category: category,
Review.rating: rating,
}
for column, value in filters.items():
if value is not None:
stmt = stmt.where(column == value)
reviews = db.scalars(stmt.offset((page - 1) * page_size).limit(page_size)).all()
return [to_public(review) for review in reviews]
@router.get("/apps/{app_key}/rating-summary", response_model=RatingSummary)
def rating_summary(app_key: str, db: Session = Depends(get_db)) -> RatingSummary:
app = db.scalar(select(StoreApp).where(StoreApp.app_key == app_key))
if app is None:
return RatingSummary(average_rating=0.0, review_count=0, star_counts={star: 0 for star in range(1, 6)})
rows = db.execute(select(Review.rating, func.count(Review.id)).where(Review.app_id == app.id).group_by(Review.rating)).all()
star_counts = {star: 0 for star in range(1, 6)}
total = 0
count = 0
for rating, rating_count in rows:
star_counts[int(rating)] = int(rating_count)
total += int(rating) * int(rating_count)
count += int(rating_count)
average = round(total / count, 2) if count else 0.0
return RatingSummary(average_rating=average, review_count=count, star_counts=star_counts)
```
- [ ] **Step 5: Include routes**
Modify `app/api/router.py` to include:
```python
from app.api.routes import auth, reviews
api_router = APIRouter()
api_router.include_router(auth.router)
api_router.include_router(reviews.router)
```
- [ ] **Step 6: Run review tests and verify pass**
Run: `pytest tests/test_reviews.py -v`
Expected: PASS.
- [ ] **Step 7: Commit reviews**
Run:
```bash
git add app tests/test_reviews.py
git commit -m "feat: add app reviews and ratings"
```
Expected: commit succeeds.
## Task 6: Implement App-List Sync
**Files:**
- Create: `app/schemas/app_list.py`
- Create: `app/api/routes/app_lists.py`
- Modify: `app/api/router.py`
- Test: `tests/test_app_lists.py`
- [ ] **Step 1: Write failing app-list tests**
Create `tests/test_app_lists.py` with:
```python
from app.core.security import create_access_token
from app.models.user import User
def seed_user(db_session):
user = User(flarum_user_id="123", username="momen", display_name="Momen", avatar_url="")
db_session.add(user)
db_session.commit()
db_session.refresh(user)
return user
def auth_headers(user: User) -> dict[str, str]:
return {"Authorization": f"Bearer {create_access_token(str(user.id))}"}
def test_put_and_get_default_app_list(client, db_session):
user = seed_user(db_session)
response = client.put(
"/me/app-list",
headers=auth_headers(user),
json={
"client_arch": "amd64",
"distro": "deepin 25",
"items": [
{
"pkgname": "spark-notes",
"origin": "spark",
"category": "office",
"version": "1.0.0",
"package_arch": "amd64",
"app_name": "Spark Notes",
"icon_url": "https://example.com/icon.png",
},
{
"pkgname": "wps",
"origin": "apm",
"category": "office",
"version": "2.0.0",
"package_arch": "amd64",
"app_name": "WPS",
"icon_url": "",
},
],
},
)
assert response.status_code == 200
assert len(response.json()["items"]) == 2
fetched = client.get("/me/app-list", headers=auth_headers(user))
assert fetched.status_code == 200
assert fetched.json()["client_arch"] == "amd64"
assert [item["pkgname"] for item in fetched.json()["items"]] == ["spark-notes", "wps"]
def test_put_default_app_list_replaces_previous_items(client, db_session):
user = seed_user(db_session)
headers = auth_headers(user)
first_payload = {
"client_arch": "amd64",
"distro": "deepin 25",
"items": [
{"pkgname": "one", "origin": "spark", "category": "tools", "version": "1", "package_arch": "amd64", "app_name": "One", "icon_url": ""},
{"pkgname": "two", "origin": "apm", "category": "tools", "version": "1", "package_arch": "amd64", "app_name": "Two", "icon_url": ""},
],
}
second_payload = {
"client_arch": "amd64",
"distro": "deepin 25",
"items": [
{"pkgname": "three", "origin": "spark", "category": "tools", "version": "1", "package_arch": "amd64", "app_name": "Three", "icon_url": ""},
],
}
assert client.put("/me/app-list", headers=headers, json=first_payload).status_code == 200
assert client.put("/me/app-list", headers=headers, json=second_payload).status_code == 200
fetched = client.get("/me/app-list", headers=headers)
assert [item["pkgname"] for item in fetched.json()["items"]] == ["three"]
```
- [ ] **Step 2: Run app-list tests and verify failure**
Run: `pytest tests/test_app_lists.py -v`
Expected: FAIL with `404 Not Found` for `/me/app-list`.
- [ ] **Step 3: Add app-list schemas**
Create `app/schemas/app_list.py` with:
```python
from datetime import datetime
from pydantic import BaseModel, Field
class AppListItemIn(BaseModel):
pkgname: str = Field(min_length=1, max_length=255)
origin: str = Field(min_length=1, max_length=16)
category: str = Field(min_length=1, max_length=128)
version: str = Field(default="", max_length=255)
package_arch: str = Field(default="unknown", max_length=64)
app_name: str = Field(default="", max_length=255)
icon_url: str = Field(default="", max_length=1024)
class AppListPut(BaseModel):
client_arch: str = Field(default="unknown", max_length=64)
distro: str = Field(default="unknown", max_length=255)
items: list[AppListItemIn]
class AppListItemOut(AppListItemIn):
id: int
model_config = {"from_attributes": True}
class AppListOut(BaseModel):
snapshot_name: str
client_arch: str
distro: str
updated_at: datetime
items: list[AppListItemOut]
```
- [ ] **Step 4: Add app-list routes**
Create `app/api/routes/app_lists.py` with:
```python
from fastapi import APIRouter, Depends
from sqlalchemy import select
from sqlalchemy.orm import Session
from app.api.deps import get_current_user
from app.db.session import get_db
from app.models.app_list import UserAppList, UserAppListItem
from app.models.user import User
from app.schemas.app_list import AppListOut, AppListPut
router = APIRouter(tags=["app-lists"])
def to_out(app_list: UserAppList) -> AppListOut:
return AppListOut(
snapshot_name=app_list.snapshot_name,
client_arch=app_list.client_arch,
distro=app_list.distro,
updated_at=app_list.updated_at,
items=list(app_list.items),
)
@router.get("/me/app-list", response_model=AppListOut | None)
def get_app_list(
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
) -> AppListOut | None:
app_list = db.scalar(
select(UserAppList).where(
UserAppList.user_id == user.id,
UserAppList.snapshot_name == "default",
)
)
return to_out(app_list) if app_list else None
@router.put("/me/app-list", response_model=AppListOut)
def put_app_list(
payload: AppListPut,
db: Session = Depends(get_db),
user: User = Depends(get_current_user),
) -> AppListOut:
app_list = db.scalar(
select(UserAppList).where(
UserAppList.user_id == user.id,
UserAppList.snapshot_name == "default",
)
)
if app_list is None:
app_list = UserAppList(user_id=user.id, snapshot_name="default")
db.add(app_list)
db.flush()
app_list.client_arch = payload.client_arch
app_list.distro = payload.distro
app_list.items.clear()
for item in payload.items:
app_list.items.append(UserAppListItem(**item.model_dump()))
db.commit()
db.refresh(app_list)
return to_out(app_list)
```
- [ ] **Step 5: Include routes**
Modify `app/api/router.py` to include:
```python
from app.api.routes import app_lists, auth, reviews
api_router = APIRouter()
api_router.include_router(auth.router)
api_router.include_router(reviews.router)
api_router.include_router(app_lists.router)
```
- [ ] **Step 6: Run app-list tests and verify pass**
Run: `pytest tests/test_app_lists.py -v`
Expected: PASS.
- [ ] **Step 7: Commit app-list sync**
Run:
```bash
git add app tests/test_app_lists.py
git commit -m "feat: add app list sync api"
```
Expected: commit succeeds.
## Task 7: Final Backend Verification And Push
**Files:**
- Modify: `README.md`
- [ ] **Step 1: Document run commands**
Add this section to `README.md`:
```markdown
## Run
```bash
uvicorn app.main:app --reload
```
## Verify
```bash
pytest
alembic upgrade head
```
## API Groups
- `POST /auth/flarum`
- `GET /me`
- `GET /apps/{app_key}/rating-summary`
- `GET /apps/{app_key}/reviews`
- `POST /apps/{app_key}/reviews`
- `GET /me/app-list`
- `PUT /me/app-list`
```
- [ ] **Step 2: Run full backend tests**
Run: `pytest -v`
Expected: all tests PASS.
- [ ] **Step 3: Verify migration command**
Run: `alembic upgrade head`
Expected: command exits 0.
- [ ] **Step 4: Commit docs**
Run:
```bash
git add README.md
git commit -m "docs: add backend run instructions"
```
Expected: commit succeeds if README changed.
- [ ] **Step 5: Push backend repository**
Run: `git push -u origin master`
Expected: push succeeds if credentials and remote permissions are available. If authentication fails, report the exact Git error and leave the local repository intact.
## Self-Review Checklist
Spec coverage:
- Flarum token validation: Task 4.
- Backend JWT: Task 4.
- Review/rating storage and filtering foundation: Task 5.
- Default app-list sync: Task 6.
- MySQL schema and migrations: Task 3.
- New Git repository and remote: Task 1.
Placeholder scan:
- The plan has no deferred implementation sections and no placeholder tasks.
Type consistency:
- User id is local integer `users.id` inside JWT `sub`.
- Flarum user id remains string `flarum_user_id`.
- App identity uses string `app_key` in all review routes.
Reference in New Issue View Git Blame Copy Permalink