`:
```html
```
The `item` shape gains a `progress` field (0-100, set from `uploadProgress` state in `useDocumentsStore`).
**Existing `defineProps` pattern** (lines 33-35):
```javascript
defineProps({
items: { type: Array, default: () => [] },
})
```
No change needed — `progress` is a field on each item object, not a separate prop.
---
## Shared Patterns
### Authentication / Auth Guard
**Source:** `backend/deps/auth.py` lines 38-75 (`get_current_user`) and lines 78-92 (`get_current_admin`)
**Apply to:** All handlers in `api/documents.py`, `api/topics.py`, and the new `GET /api/auth/me/quota` endpoint
```python
from deps.auth import get_current_user, get_current_admin
from db.models import User
# Regular user guard (all document endpoints):
current_user: User = Depends(get_current_user)
# Admin-only guard (admin topics, admin quota):
_admin: User = Depends(get_current_admin)
# Derived "no admin" guard — define once in api/documents.py, reuse across all handlers:
async def get_regular_user(user: User = Depends(get_current_user)) -> User:
if user.role == "admin":
raise HTTPException(403, "Admin accounts cannot access document content")
return user
```
### Ownership Assertion (SEC-04)
**Source:** RESEARCH.md Finding 7 / CONTEXT.md D-16
**Apply to:** Every handler in `api/documents.py` that accepts a `doc_id` path parameter
```python
doc = await session.get(Document, uuid.UUID(doc_id))
if doc is None or doc.user_id != current_user.id:
raise HTTPException(status_code=404, detail="Document not found")
# Returns 404 (not 403) for both "not found" and "wrong owner" — SEC-04 / D-16
```
### Atomic Quota SQL
**Source:** RESEARCH.md Finding 4 / CONTEXT.md D-07
**Apply to:** `api/documents.py` confirm endpoint (increment) and `services/storage.py` `delete_document` (decrement)
```python
from sqlalchemy import text
# Increment (confirm endpoint):
result = await session.execute(
text("""
UPDATE quotas
SET used_bytes = used_bytes + :delta
WHERE user_id = :uid
AND (used_bytes + :delta) <= limit_bytes
RETURNING used_bytes, limit_bytes
"""),
{"delta": file_size, "uid": str(user_id)},
)
# Decrement (delete):
await session.execute(
text("UPDATE quotas SET used_bytes = GREATEST(0, used_bytes - :delta) WHERE user_id = :uid"),
{"delta": size_bytes, "uid": str(user_id)},
)
```
### asyncio.to_thread for MinIO SDK
**Source:** `backend/storage/minio_backend.py` lines 63-70, 86-88, 90-99
**Apply to:** All new methods in `MinIOBackend` (`generate_presigned_put_url`, `stat_object`)
```python
# Simple single-call pattern:
await asyncio.to_thread(self._client.remove_object, self._bucket, object_key)
# With return value:
return await asyncio.to_thread(
self._client.presigned_get_object,
self._bucket,
object_key,
timedelta(minutes=expires_minutes),
)
```
### Celery Task Structure (sync entry-point + async body)
**Source:** `backend/tasks/document_tasks.py` lines 22-25 and `backend/tasks/email_tasks.py` lines 19-36
**Apply to:** New `cleanup_abandoned_uploads` task in `document_tasks.py`
```python
@celery_app.task(name="tasks.document_tasks.cleanup_abandoned_uploads")
def cleanup_abandoned_uploads() -> dict:
return asyncio.run(_cleanup_abandoned())
async def _cleanup_abandoned() -> dict:
# All imports deferred here (celery_app.py circular import rule)
from db.session import AsyncSessionLocal
...
async with AsyncSessionLocal() as session:
...
```
### Frontend API Client `request()` Helper
**Source:** `frontend/src/api/client.js` lines 11-41
**Apply to:** All new API functions (`getUploadUrl`, `confirmUpload`, `getMyQuota`) added to `api/client.js`
```javascript
// GET:
export function getMyQuota() {
return request('/api/auth/me/quota')
}
// POST with JSON body:
export function getUploadUrl(filename, contentType) {
return request('/api/documents/upload-url', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ filename, content_type: contentType }),
})
}
export function confirmUpload(documentId) {
return request(`/api/documents/${documentId}/confirm`, { method: 'POST' })
}
```
### Pinia Store Action Pattern
**Source:** `frontend/src/stores/documents.js` lines 25-29 and `frontend/src/stores/auth.js` lines 55-83
**Apply to:** Modified `upload` action in `stores/documents.js`
```javascript
// Pattern: loading flag + try/catch/finally + error ref
async function someAction(...args) {
loading.value = true
error.value = null
try {
const data = await api.someApiCall(args)
// update state
return data
} catch (e) {
error.value = e.message
throw e
} finally {
loading.value = false
}
}
```
---
## No Analog Found
All files have analogs. The following files have partial analogs (research patterns used instead of codebase patterns for specific sub-sections):
| File | Sub-section | Reason | Source |
|---|---|---|---|
| `backend/migrations/versions/0003_multi_user_isolation.py` | Inline MinIO SDK calls | No existing migration has side-effect MinIO calls | RESEARCH.md Finding 1 |
| `backend/api/documents.py` | Atomic quota SQL | No existing handler uses raw `text()` UPDATE | RESEARCH.md Finding 4 |
| `frontend/src/stores/documents.js` | XHR upload helper | No existing XHR code in codebase (fetch-only) | RESEARCH.md Finding 9 |
| `frontend/src/components/layout/QuotaBar.vue` | Full component (NEW) | No progress-bar component with `onMounted` fetch exists | PasswordStrengthBar.vue (visual style only) |
---
## Metadata
**Analog search scope:** `backend/` (all .py), `frontend/src/` (all .js, .vue)
**Files scanned:** 14 source files read in full
**Pattern extraction date:** 2026-05-23