docs(04-02): complete plan 04-02 summary and state update
- Add 04-02-SUMMARY.md with verification results and decisions - Update STATE.md to reflect plan 2/9 complete, next action 04-03
This commit is contained in:
curo1305
@@ -0,0 +1,133 @@
|
||||
---
|
||||
phase: 04-folders-sharing-quotas-document-ux
|
||||
plan: "02"
|
||||
subsystem: database
|
||||
tags: [alembic, minio, postgresql, gin-index, full-text-search]
|
||||
|
||||
requires:
|
||||
- phase: 03-document-migration-multi-user-isolation
|
||||
provides: migration 0003 (multi-user isolation, users table, documents table)
|
||||
|
||||
provides:
|
||||
- Alembic migration 0004 with users.pdf_open_mode column, GIN FTS index on extracted_text, audit-logs MinIO bucket creation
|
||||
- MinIOBackend.put_object_raw() for caller-supplied bucket+key uploads
|
||||
|
||||
affects:
|
||||
- 04-folders-sharing-quotas-document-ux (downstream plans reading pdf_open_mode or ix_documents_fts)
|
||||
- audit tasks that call put_object_raw for CSV export
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "GIN expression index created via op.execute() raw SQL (not Index()) to prevent Alembic autogenerate collision (issue #1390)"
|
||||
- "MinIO bucket creation gated on MINIO_ENDPOINT env var for SQLite test compatibility"
|
||||
- "MinIOBackend.put_object_raw() mirrors put_object() asyncio.to_thread pattern but accepts caller-supplied bucket+key"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- backend/migrations/versions/0004_phase4_pdf_open_mode_tsvector.py
|
||||
modified:
|
||||
- backend/storage/minio_backend.py
|
||||
|
||||
key-decisions:
|
||||
- "GIN index created via raw SQL op.execute() to avoid Alembic autogenerate re-creating it on every revision run (issue #1390)"
|
||||
- "put_object_raw not added to StorageBackend ABC — audit-logs is MinIO-only, local backends have no audit bucket concept"
|
||||
- "MinIO bucket creation uses deferred import inside the env-var guard to avoid test environment Minio import dependency"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: env-var-gated MinIO operations in migrations (same as 0003)"
|
||||
- "Pattern: manually-managed GIN expression indexes via raw SQL with comment marking them as non-autogenerated"
|
||||
|
||||
requirements-completed:
|
||||
- FOLD-05
|
||||
- DOC-02
|
||||
- ADMIN-06
|
||||
|
||||
duration: 8min
|
||||
completed: 2026-05-25
|
||||
---
|
||||
|
||||
# Phase 4 Plan 02: Alembic Migration 0004 + MinIOBackend.put_object_raw() Summary
|
||||
|
||||
**Alembic migration 0004 adds users.pdf_open_mode column, GIN expression index for full-text search on documents.extracted_text, and audit-logs MinIO bucket creation; MinIOBackend gains put_object_raw() for arbitrary bucket+key uploads**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 8 min
|
||||
- **Started:** 2026-05-25T00:00:00Z
|
||||
- **Completed:** 2026-05-25T00:08:00Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 2
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Created Alembic migration 0004 with three upgrade steps: pdf_open_mode column on users table (server_default='in_app'), GIN expression index ix_documents_fts on documents.extracted_text via raw SQL, and audit-logs MinIO bucket creation gated on MINIO_ENDPOINT env var
|
||||
- Added MinIOBackend.put_object_raw() async method that accepts caller-supplied bucket and key (bypassing the document key schema) for use by audit CSV export tasks
|
||||
- All 122 passing tests continue to pass; the 1 pre-existing failure (test_extract_docx, missing 'docx' package in local dev environment) is unchanged and unrelated to this plan
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically as part of a single combined commit:
|
||||
|
||||
1. **Task 1: Alembic migration 0004** + **Task 2: put_object_raw()** - `b6bab5a` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/migrations/versions/0004_phase4_pdf_open_mode_tsvector.py` — Alembic migration: pdf_open_mode column, GIN FTS index, audit-logs MinIO bucket
|
||||
- `/Users/nik/Documents/Progamming/document_scanner/backend/storage/minio_backend.py` — Added put_object_raw() method after put_object()
|
||||
|
||||
## Verification Results
|
||||
|
||||
**Task 1 — Syntax check:**
|
||||
```
|
||||
python3 -c "import py_compile; py_compile.compile('migrations/versions/0004_phase4_pdf_open_mode_tsvector.py')"
|
||||
# Output: OK
|
||||
```
|
||||
|
||||
**Task 1 — Grep confirms all required identifiers present:**
|
||||
```
|
||||
grep -n "ix_documents_fts|audit-logs|pdf_open_mode" 0004_phase4_pdf_open_mode_tsvector.py
|
||||
# Lines: 1, 8, 9, 10, 24, 42, 48, 58, 62, 73, 74, 79, 81, 83
|
||||
```
|
||||
|
||||
**Task 2 — Import and inspect verification:**
|
||||
```
|
||||
python3 -c "from storage.minio_backend import MinIOBackend; import inspect; src = inspect.getsource(MinIOBackend.put_object_raw); print('OK')"
|
||||
# Output: OK
|
||||
```
|
||||
|
||||
**base.py unchanged:** `grep -n "put_object_raw" base.py` returns no output (confirmed absent).
|
||||
|
||||
**Test suite:** 122 passed, 7 skipped, 39 xfailed, 1 pre-existing failure (docx module not installed in local env)
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- GIN index created via `op.execute()` raw SQL to prevent Alembic autogenerate from treating it as a diff on every `alembic revision --autogenerate` run (Alembic issue #1390)
|
||||
- `put_object_raw` not added to StorageBackend ABC — audit-logs bucket is a MinIO-specific concept; local/WebDAV backends have no equivalent
|
||||
- Minio client import is deferred inside the `if os.environ.get("MINIO_ENDPOINT")` guard (same pattern as migration 0003) to keep SQLite test runs free of MinIO import dependency
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None. The `python` command was not found in the PATH (macOS uses `python3`); switched to `python3` for all verification commands with no impact on deliverables.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None - this plan creates infrastructure (migration + storage method), not UI or data-serving code.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None - no new network endpoints, auth paths, or trust boundary changes introduced beyond what the plan's threat model already covers.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Migration 0004 is ready for `alembic upgrade 0004` once PostgreSQL is running
|
||||
- `put_object_raw()` is callable by audit tasks (04-xx plans)
|
||||
- FTS index `ix_documents_fts` is available for full-text search queries against `documents.extracted_text`
|
||||
|
||||
---
|
||||
*Phase: 04-folders-sharing-quotas-document-ux*
|
||||
*Completed: 2026-05-25*
|
||||
Reference in New Issue
Block a user