bmc_hub/SAG_MODULE_IMPLEMENTATION_PLAN.md

# SAG MODULE IMPLEMENTATION PLAN
## Professional Sub-Agent Task Breakdown

**Document Version:** 2.0  
**Created:** 2026-01-30  
**Module Location:** `/app/modules/sag/`  
**API Path:** `/api/v1/cases`  
**Database Prefix:** `sag_`

---

## EXECUTIVE SUMMARY

The Sag (Case) Module is the **process backbone** of BMC Hub. It implements a universal entity model where tickets, tasks, and (eventually) orders are all represented as Cases differentiated by:
- **Relations** (directional, transitive connections between cases)
- **Tags** (workflow state and categorization)
- **Attached modules** (billing, hardware, etc.)

This plan provides a phased, task-based approach to complete the implementation with architectural constraints preserved.

---

## 1️⃣ CURRENT STATE ASSESSMENT

### ✅ What's Already Implemented

#### Database Schema (COMPLETE)
- ✅ `sag_sager` table (cases) - `/migrations/001_init.sql`
  - Binary status: `åben` / `lukket` (constraint enforced)
  - `template_key` as nullable field (creation-time only)
  - `deleted_at` for soft-deletes
  - Proper indexes on customer_id, status, ansvarlig_bruger_id
  - Auto-update trigger for `updated_at`

- ✅ `sag_relationer` table (relations)
  - Directional: `kilde_sag_id` → `målsag_id`
  - `relationstype` for categorization
  - Soft-delete support
  - Constraint preventing self-relations

- ✅ `sag_tags` table (tags)
  - `tag_navn` for categorization
  - `state` field: `open` / `closed` (constraint enforced)
  - `closed_at` timestamp
  - Soft-delete support

- ✅ `sag_kontakter` table (case-contact links) - `/migrations/002_sag_contacts_relations.sql`
  - Many-to-many with roles

- ✅ `sag_kunder` table (case-customer links)
  - Many-to-many with roles

#### Backend API (MOSTLY COMPLETE)
✅ **Cases CRUD** - `router.py` lines 1-671
  - `GET /api/v1/cases` - List with filters (status, tag, customer_id, ansvarlig)
  - `POST /api/v1/cases` - Create case
  - `GET /api/v1/cases/{id}` - Get case details
  - `PATCH /api/v1/cases/{id}` - Update case
  - `DELETE /api/v1/cases/{id}` - Soft-delete

✅ **Relations CRUD**
  - `GET /api/v1/cases/{id}/relations` - List relations with titles
  - `POST /api/v1/cases/{id}/relations` - Create relation
  - `DELETE /api/v1/cases/{id}/relations/{relation_id}` - Soft-delete

✅ **Tags CRUD**
  - `GET /api/v1/cases/{id}/tags` - List tags
  - `POST /api/v1/cases/{id}/tags` - Add tag (with state support)
  - `DELETE /api/v1/cases/{id}/tags/{tag_id}` - Soft-delete

✅ **Contact/Customer Links**
  - `POST /api/v1/cases/{id}/contacts` - Link contact
  - `GET /api/v1/cases/{id}/contacts` - List contacts
  - `DELETE /api/v1/cases/{id}/contacts/{contact_id}` - Remove contact
  - `POST /api/v1/cases/{id}/customers` - Link customer
  - `GET /api/v1/cases/{id}/customers` - List customers
  - `DELETE /api/v1/cases/{id}/customers/{customer_id}` - Remove customer

✅ **Search**
  - `GET /api/v1/search/cases` - Full-text search
  - `GET /api/v1/search/customers` - Customer search
  - `GET /api/v1/search/contacts` - Contact search

#### Frontend Views (MOSTLY COMPLETE)
✅ **List View** - `frontend/views.py`
  - `/cases` and `/sag` routes (dual paths)
  - Filter by status, tag, customer_id
  - Fetches statuses and tags for filters

✅ **Detail View**
  - `/cases/{id}` and `/sag/{id}` routes
  - Shows case, tags, relations, customer
  - Fetches contacts and customers (partially implemented)

✅ **Create Form**
  - `/cases/new` and `/sag/new` routes
  - Template exists (`create.html`)

❌ **Edit Form** - Template exists (`edit.html`) but no backend route

#### Templates (COMPLETE)
✅ All four templates exist:
  - `index.html` - Case list with Nordic Top design, filters, dark mode
  - `detail.html` - Case details with relations, tags, info sections
  - `create.html` - Create form with customer search, validation
  - `edit.html` - Edit form (needs backend route)

### 🔴 Architectural Violations Found

#### VIOLATION 1: Duplicate API Paths
**Issue:** Router has both `/sag/*` and `/cases/*` endpoints doing identical things.
- Lines 14-157: `/sag` prefix endpoints
- Lines 327-671: `/cases` prefix endpoints (duplicates)

**Fix Required:** Remove `/sag/*` endpoints, keep only `/cases/*` (architectural standard).

#### VIOLATION 2: Missing Tag State Management
**Issue:** Tag closing endpoint missing.
- `PATCH /api/v1/cases/{id}/tags/{tag_id}` should allow closing tags (set `state='closed'`, `closed_at=NOW()`)
- Currently only delete (soft) exists

**Fix Required:** Add tag state update endpoint.

#### VIOLATION 3: Missing Edit Route
**Issue:** `edit.html` template exists but no backend route to serve it.

**Fix Required:** Add `GET /cases/{id}/edit` view route.

### ⚠️ What Needs Enhancement

1. **Tag State Workflow** - Endpoint to close tags (not delete)
2. **Edit View Route** - Backend route for edit form
3. **Relation Type Validation** - Should validate allowed relation types
4. **Bulk Operations** - Close multiple tags, archive cases
5. **Activity Log** - Track who changed what (future phase)
6. **Order Integration** - Link cases to orders (future phase)

---

## 2️⃣ PHASE OVERVIEW

### Phase 1: Database Schema Validation (30 min)
- Verify all tables match architectural constraints
- Add any missing indexes
- Validate soft-delete coverage

### Phase 2: Backend API Enhancement (2-3 hours)
- Remove duplicate `/sag/*` endpoints
- Add tag state management endpoint
- Add edit view route
- Improve error handling
- Add relation type validation

### Phase 3: Frontend Enhancement (2-3 hours)
- Wire up edit form
- Add tag closing UI
- Improve relation visualization
- Add bulk operations UI
- Enhance mobile responsiveness

### Phase 4: Order Integration Planning (1 hour)
- Define order-case relation types
- Document order creation workflow
- Plan order table schema
- Define API contract

### Phase 5: Documentation (1 hour)
- Update module README
- Create API documentation
- Document relation types
- Create workflow examples

### Phase 6: QA & Testing (1-2 hours)
- Unit tests for CRUD operations
- Integration tests for relations
- Frontend E2E tests
- Soft-delete verification
- Module disable/enable test

**Total Estimate:** 8-12 hours

---

## 3️⃣ SUB-AGENT TASK BREAKDOWN

---

### PHASE 1: DATABASE SCHEMA VALIDATION

#### DB-001: Schema Compliance Audit
**Assigned:** DB-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** None

**Description:**
Audit all `sag_*` tables against architectural constraints. Verify:
- Binary status constraint on `sag_sager`
- Tag state constraint on `sag_tags`
- Soft-delete columns present
- No missing indexes
- Trigger functions working

**Inputs:**
- `/migrations/001_init.sql`
- `/migrations/002_sag_contacts_relations.sql`
- Database connection

**Outputs:**
- Validation report (pass/fail for each constraint)
- SQL script for any missing indexes/constraints

**Done Criteria:**
- All constraints match architectural rules
- All soft-delete columns present
- All indexes exist and performant

---

### PHASE 2: BACKEND API ENHANCEMENT

#### BE-001: Remove Duplicate `/sag/*` Endpoints
**Assigned:** Backend-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** None

**Description:**
Remove duplicate endpoints with `/sag` prefix (lines 14-330). Keep only `/cases` prefix endpoints. Update any internal references.

**Inputs:**
- `/app/modules/sag/backend/router.py`

**Outputs:**
- Modified `router.py` with only `/cases` endpoints
- Updated imports if needed

**Done Criteria:**
- No `/sag` prefix endpoints remain
- All functionality preserved under `/cases`
- No broken internal references

---

#### BE-002: Add Tag State Management Endpoint
**Assigned:** Backend-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** BE-001

**Description:**
Add `PATCH /api/v1/cases/{id}/tags/{tag_id}` endpoint to close tags without deleting. Should:
- Accept `{"state": "closed"}` payload
- Set `closed_at = NOW()`
- NOT set `deleted_at` (tags are closed, not deleted)
- Return updated tag

**Inputs:**
- `/app/modules/sag/backend/router.py`
- `sag_tags` table schema

**Outputs:**
- New endpoint in `router.py`
- Proper error handling

**Done Criteria:**
- Endpoint closes tag (state='closed', closed_at set)
- Returns 404 if tag not found
- Doesn't soft-delete
- Logs action with emoji prefix

---

#### BE-003: Add Edit View Route
**Assigned:** Backend-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** BE-001

**Description:**
Add `GET /cases/{id}/edit` route in `frontend/views.py` to serve the edit form. Should fetch case and render `edit.html` template.

**Inputs:**
- `/app/modules/sag/frontend/views.py`
- `/app/modules/sag/templates/edit.html`

**Outputs:**
- New route in `views.py`
- Template receives case data

**Done Criteria:**
- Route returns edit form
- Form pre-populated with case data
- Returns 404 if case not found

---

#### BE-004: Add Relation Type Validation
**Assigned:** Backend-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** BE-001

**Description:**
Add validation for allowed relation types when creating relations. Define allowed types:
- `derived` (spawned from)
- `blocks` (prevents progress)
- `executes` (performs work for)
- `relates_to` (generic link)

Reject other types with 400 error.

**Inputs:**
- `/app/modules/sag/backend/router.py` (relation creation endpoint)

**Outputs:**
- Updated `POST /api/v1/cases/{id}/relations` with validation
- Error message listing allowed types

**Done Criteria:**
- Only allowed types accepted
- 400 error with clear message for invalid types
- Logged validation failures

---

#### BE-005: Improve Error Handling
**Assigned:** Backend-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** BE-001, BE-002, BE-003, BE-004

**Description:**
Standardize error responses across all endpoints:
- Use consistent HTTPException format
- Include helpful error messages
- Log all errors with context
- Return proper status codes

**Inputs:**
- All endpoint functions in `router.py` and `views.py`

**Outputs:**
- Consistent error handling pattern
- Improved logging

**Done Criteria:**
- All errors return proper status codes
- Error messages are user-friendly
- All errors logged with context
- No uncaught exceptions

---

### PHASE 3: FRONTEND ENHANCEMENT

#### FE-001: Wire Up Edit Form Backend Connection
**Assigned:** Frontend-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** BE-003

**Description:**
Complete the edit form JavaScript to:
- Load case data into form
- Submit to `PATCH /api/v1/cases/{id}`
- Handle success/error responses
- Redirect to detail view on success

**Inputs:**
- `/app/modules/sag/templates/edit.html`
- Backend edit route
- PATCH endpoint

**Outputs:**
- Functional edit form with submission
- Success/error feedback
- Redirect on success

**Done Criteria:**
- Form loads case data
- Submission calls PATCH endpoint
- Success redirects to `/cases/{id}`
- Errors displayed to user

---

#### FE-002: Add Tag Closing UI
**Assigned:** Frontend-Agent  
**Estimated Time:** 60 minutes  
**Dependencies:** BE-002

**Description:**
Add UI to close tags (not delete) in detail view:
- Add "Close Tag" button next to each open tag
- Call `PATCH /api/v1/cases/{id}/tags/{tag_id}` with `state='closed'`
- Update UI to show closed state (greyed out, strikethrough)
- Keep closed tags visible in UI

**Inputs:**
- `/app/modules/sag/templates/detail.html`
- Tag closing endpoint

**Outputs:**
- Close button on each open tag
- Visual distinction for closed tags
- AJAX call to close endpoint

**Done Criteria:**
- Closed tags remain visible
- Visual feedback on state change
- No page reload needed
- Error handling for failures

---

#### FE-003: Improve Relation Visualization
**Assigned:** Frontend-Agent  
**Estimated Time:** 90 minutes  
**Dependencies:** None

**Description:**
Enhance relation display in detail view:
- Group relations by type (derived, blocks, executes, relates_to)
- Show directionality clearly (this case → target vs. source → this case)
- Add visual indicators (arrows, colors)
- Make relation targets clickable links

**Inputs:**
- `/app/modules/sag/templates/detail.html`
- Relation data from backend

**Outputs:**
- Updated relation section with grouping
- Visual indicators for direction
- Clickable links to related cases

**Done Criteria:**
- Relations grouped by type
- Direction clear (outgoing vs incoming)
- All targets are clickable
- Mobile-responsive

---

#### FE-004: Add Bulk Operations UI
**Assigned:** Frontend-Agent  
**Estimated Time:** 90 minutes  
**Dependencies:** BE-002

**Description:**
Add bulk operations to list view:
- Checkboxes to select multiple cases
- "Close Selected" button (set status='lukket')
- "Archive Selected" button (soft-delete)
- Confirmation dialogs

**Inputs:**
- `/app/modules/sag/templates/index.html`
- Update/delete endpoints

**Outputs:**
- Selection UI in list view
- Bulk action buttons
- Confirmation dialogs

**Done Criteria:**
- Multiple cases selectable
- Bulk close works
- Bulk archive works (soft-delete)
- Confirmation required
- Success feedback shown

---

#### FE-005: Enhance Mobile Responsiveness
**Assigned:** Frontend-Agent  
**Estimated Time:** 60 minutes  
**Dependencies:** FE-001, FE-002, FE-003, FE-004

**Description:**
Ensure all views work on mobile:
- Stack filters vertically on small screens
- Make tables scrollable or card-based
- Touch-friendly buttons (min 44px)
- Collapsible sections for detail view

**Inputs:**
- All template files

**Outputs:**
- Updated CSS with media queries
- Mobile-optimized layouts

**Done Criteria:**
- All views usable on 375px width
- No horizontal scroll needed
- Touch targets large enough
- Text readable without zoom

---

### PHASE 4: ORDER INTEGRATION PLANNING

#### INT-001: Define Order-Case Relation Model
**Assigned:** Integration-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** None

**Description:**
Document how orders integrate with cases:
- Orders CAN be created independently
- Orders MUST be linkable to one or more cases
- When order created from case → create relation
- Define relation type for order links (e.g., `fulfills`, `invoices_for`)

**Inputs:**
- Architectural constraints document
- Current relation types

**Outputs:**
- Design document: `docs/ORDER_CASE_INTEGRATION.md`
- Relation type definitions
- Workflow diagrams

**Done Criteria:**
- Clear definition of order independence
- Relation type defined
- Creation workflow documented
- No violation of "orders are not cases" rule

---

#### INT-002: Plan Order Table Schema
**Assigned:** Integration-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** INT-001

**Description:**
Design order tables with case linking:
- `orders` table (id, title, description, status, etc.)
- `order_case_relations` table (order_id, case_id, relation_type)
- NO embedding of case logic in orders
- Soft-delete everywhere

**Inputs:**
- Order-case relation model (INT-001)
- Existing `sag_*` schema

**Outputs:**
- SQL migration draft: `migrations/XXX_orders.sql`
- Schema documentation

**Done Criteria:**
- Order table defined
- Many-to-many relation to cases
- No parent/child embedding
- Soft-delete columns present

---

#### INT-003: Define Order API Contract
**Assigned:** Integration-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** INT-002

**Description:**
Define order API endpoints:
- `GET /api/v1/orders` - List orders
- `POST /api/v1/orders` - Create order (optionally from case)
- `POST /api/v1/orders/{id}/cases` - Link to case
- `GET /api/v1/cases/{id}/orders` - Get orders for case

**Inputs:**
- Order schema (INT-002)
- Case API patterns

**Outputs:**
- API specification document
- Example requests/responses

**Done Criteria:**
- All CRUD operations defined
- Case linking endpoints defined
- Consistent with case API patterns
- Examples provided

---

### PHASE 5: DOCUMENTATION

#### DOC-001: Update Module README
**Assigned:** Docs-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** BE-001 through BE-005

**Description:**
Update `/app/modules/sag/README.md` with:
- Current implementation status
- All API endpoints with examples
- Relation types and meanings
- Tag workflow explanation
- Architectural constraints summary

**Inputs:**
- Current implementation
- Backend router
- Templates

**Outputs:**
- Updated `README.md`

**Done Criteria:**
- All endpoints documented
- Examples provided
- Architectural rules explained
- Easy to understand for new developers

---

#### DOC-002: Create API Documentation
**Assigned:** Docs-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** BE-001 through BE-005

**Description:**
Create OpenAPI-style documentation for all endpoints:
- Request/response schemas
- Status codes
- Error responses
- Example curl commands

**Inputs:**
- Backend router
- Pydantic models (if any)

**Outputs:**
- `docs/SAG_API_REFERENCE.md`

**Done Criteria:**
- All endpoints documented
- Schemas defined
- Examples provided
- Status codes listed

---

#### DOC-003: Document Relation Types
**Assigned:** Docs-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** BE-004

**Description:**
Create reference guide for relation types:
- `derived` - Target case spawned from source
- `blocks` - Source blocks target from progressing
- `executes` - Target performs work for source
- `relates_to` - Generic association

Include use cases and examples.

**Inputs:**
- Relation type validation (BE-004)
- Existing use patterns

**Outputs:**
- `docs/CASE_RELATION_TYPES.md`

**Done Criteria:**
- All types explained
- Use cases provided
- Examples given
- Directionality clear

---

#### DOC-004: Create Workflow Examples
**Assigned:** Docs-Agent  
**Estimated Time:** 45 minutes  
**Dependencies:** DOC-001, DOC-002, DOC-003

**Description:**
Document common workflows:
1. Customer calls → create support case → derive hardware order case → execute fulfillment case
2. Billing cycle → create invoice case → relate to completed support cases
3. Project → create project case → derive task cases → track via tags

**Inputs:**
- All documentation
- Current implementation

**Outputs:**
- `docs/SAG_WORKFLOWS.md`

**Done Criteria:**
- At least 3 workflows documented
- Step-by-step instructions
- API calls shown
- Relation chains visualized

---

### PHASE 6: QA & TESTING

#### QA-001: Backend CRUD Tests
**Assigned:** QA-Agent  
**Estimated Time:** 90 minutes  
**Dependencies:** BE-001 through BE-005

**Description:**
Write integration tests for all CRUD operations:
- Create case
- Read case
- Update case
- Delete case (soft)
- Verify deleted_at set correctly

**Inputs:**
- Backend router
- Test database

**Outputs:**
- Test file: `tests/test_sag_crud.py`
- At least 20 test cases

**Done Criteria:**
- All CRUD operations tested
- Soft-delete verified
- Error cases tested
- All tests pass

---

#### QA-002: Relation Tests
**Assigned:** QA-Agent  
**Estimated Time:** 60 minutes  
**Dependencies:** BE-001, BE-004

**Description:**
Test relation operations:
- Create relation between cases
- List relations (both directions)
- Validate relation type validation
- Delete relation (soft)
- Prevent self-relations

**Inputs:**
- Relation endpoints
- Test database

**Outputs:**
- Test file: `tests/test_sag_relations.py`
- At least 10 test cases

**Done Criteria:**
- Create/delete tested
- Type validation tested
- Self-relation prevention tested
- Directionality correct

---

#### QA-003: Tag Workflow Tests
**Assigned:** QA-Agent  
**Estimated Time:** 60 minutes  
**Dependencies:** BE-002

**Description:**
Test tag lifecycle:
- Add tag to case
- Close tag (state='closed', closed_at set)
- Verify closed tags not deleted
- Delete tag (soft)
- List tags (filter by state)

**Inputs:**
- Tag endpoints
- Test database

**Outputs:**
- Test file: `tests/test_sag_tags.py`
- At least 8 test cases

**Done Criteria:**
- Add/close/delete tested
- State transitions verified
- Soft-delete vs close distinction tested
- All tests pass

---

#### QA-004: Frontend E2E Tests
**Assigned:** QA-Agent  
**Estimated Time:** 90 minutes  
**Dependencies:** FE-001 through FE-005

**Description:**
Test frontend user flows:
- Navigate to case list
- Filter by status/tag
- Create new case
- View case details
- Edit case
- Add/close tag
- Add relation
- Delete case

**Inputs:**
- All frontend templates
- Browser automation tool (Playwright/Selenium)

**Outputs:**
- Test file: `tests/test_sag_frontend.py`
- At least 10 E2E scenarios

**Done Criteria:**
- All major flows tested
- Form submissions work
- Navigation works
- Error handling tested

---

#### QA-005: Module Disable/Enable Test
**Assigned:** QA-Agent  
**Estimated Time:** 30 minutes  
**Dependencies:** QA-001, QA-002, QA-003, QA-004

**Description:**
Test module deactivation:
1. Create test cases/relations/tags
2. Disable module (enabled=false in module.json)
3. Verify endpoints return 404
4. Verify database data intact
5. Re-enable module
6. Verify data still accessible

**Inputs:**
- Module loader
- Test database

**Outputs:**
- Test file: `tests/test_sag_module_lifecycle.py`

**Done Criteria:**
- Disable prevents access
- Data preserved
- Re-enable restores access
- No data loss

---

## 4️⃣ DEPENDENCY GRAPH

### Sequential Dependencies (Critical Path)

```
DB-001 (30m)
  ↓
BE-001 (45m)  ← MUST complete before any backend work
  ↓
  ├→ BE-002 (45m)
  ├→ BE-003 (30m)
  ├→ BE-004 (45m)
  └→ BE-005 (45m)  ← Touches all other BE tasks
       ↓
  ┌────┴────┐
  ↓         ↓
FE-001   QA-001 (90m)
(45m)       ↓
  ↓      QA-002 (60m)
FE-002     ↓
(60m)   QA-003 (60m)
  ↓         ↓
FE-003   QA-004 (90m)
(90m)       ↓
  ↓      QA-005 (30m)
FE-004
(90m)
  ↓
FE-005
(60m)
```

### Parallel Opportunities

**Wave 1 (after BE-001):**
- BE-002, BE-003, BE-004 can run in parallel
- Saves ~90 minutes

**Wave 2 (after BE-005):**
- FE-001, FE-003, QA-001, QA-002 can run in parallel
- DOC-001, DOC-002, DOC-003 can run in parallel
- Saves ~2 hours

**Wave 3 (after FE-004):**
- FE-005, QA-004, DOC-004 can run in parallel
- Saves ~1 hour

**Wave 4 (order integration):**
- INT-001, INT-002, INT-003 can run in parallel (independent of other work)

### Critical Path Time
If executed sequentially: **~12 hours**  
If parallelized optimally: **~6-7 hours**

### Where Orders Integrate

**Order Integration is PARALLEL to Case Enhancement:**
- INT-001, INT-002, INT-003 can start immediately
- Do NOT block case module completion
- Orders gain meaning when linked to cases via relations
- No architectural changes to cases needed

**Order-Case Interface:**
```
Cases Module (Complete)
    ↓
Orders Module (New)
    ↓
order_case_relations table
    ↓
Relation type: "fulfills" / "invoices_for"
```

---

## 5️⃣ VALIDATION CHECKLIST

### Phase 1: Database Schema
- [ ] Binary status constraint verified (`åben` / `lukket`)
- [ ] Tag state constraint verified (`open` / `closed`)
- [ ] All soft-delete columns present
- [ ] All indexes exist and performant
- [ ] Triggers working (updated_at auto-update)
- [ ] No foreign key errors
- [ ] Relation self-reference prevented

### Phase 2: Backend API
- [ ] No duplicate `/sag/*` endpoints exist
- [ ] Only `/cases` prefix used
- [ ] Tag closing endpoint works (PATCH tags/{id})
- [ ] Edit view route serves form
- [ ] Relation type validation enforces allowed types
- [ ] All endpoints return consistent error format
- [ ] All errors logged with context
- [ ] Soft-deletes set `deleted_at`, not physical delete

### Phase 3: Frontend
- [ ] Edit form loads case data
- [ ] Edit form submits to PATCH endpoint
- [ ] Tag closing UI doesn't delete tags
- [ ] Closed tags remain visible (greyed out)
- [ ] Relations grouped by type
- [ ] Directionality clear (in/out)
- [ ] Bulk operations work
- [ ] All views mobile-responsive (375px)

### Phase 4: Order Integration
- [ ] Order-case relation model documented
- [ ] Orders can be created independently
- [ ] Orders linkable to multiple cases
- [ ] No case logic embedded in orders
- [ ] Order table schema has soft-deletes
- [ ] API contract consistent with case API

### Phase 5: Documentation
- [ ] README updated with current state
- [ ] All endpoints documented
- [ ] Relation types explained
- [ ] Workflows documented
- [ ] Examples provided

### Phase 6: Testing
- [ ] All CRUD operations tested
- [ ] Relation creation/deletion tested
- [ ] Tag state transitions tested
- [ ] Frontend flows tested
- [ ] Module disable/enable tested
- [ ] Data preserved after disable
- [ ] All tests pass

---

## ARCHITECTURAL CONSTRAINT RE-VALIDATION

After each phase, validate these rules:

### Core Entity Rule
- ✅ Only one entity: Case
- ✅ Tickets/tasks are cases with different tags/relations
- ⚠️ Orders are transactional objects, NOT cases (separate table)

### Orders Exception
- ⚠️ Orders can be created independently (INT-002)
- ⚠️ Orders linkable to cases via relations (INT-002)
- ⚠️ No case logic in order workflow (INT-001)

### Template Usage
- ✅ `template_key` only used at creation
- ✅ No business logic depends on it

### Case Status
- ✅ Binary only: `åben` / `lukket`
- ✅ Workflow state via tags

### Tags
- ✅ Represent work to be done
- ✅ Have state: `open` / `closed`
- ✅ Never deleted when completed (closed instead)
- ✅ Closing = completion of responsibility

### Relations
- ✅ First-class data (own table)
- ✅ Directional (kilde → mål)
- ✅ Transitive (chains allowed)
- ✅ No parent/child duality in stored data
- ✅ UI derives parent/child views

### Deletion Policy
- ✅ All deletes are soft-deletes
- ✅ `deleted_at` mandatory everywhere

### Modeling Rule
- ✅ If you think you need a new table → use relations instead
- ⚠️ Exception: Orders (per architectural rule)

---

## TEST SCENARIOS BY PHASE

### Phase 1: Database
1. Insert case with status='other' → constraint violation
2. Insert tag with state='pending' → constraint violation
3. Create relation with kilde_sag_id = målsag_id → constraint violation
4. Soft-delete case → deleted_at set, not physical delete
5. Query cases WHERE deleted_at IS NULL → deleted cases excluded

### Phase 2: Backend
1. Call `/sag/cases` → 404 (removed endpoint)
2. Call `/cases` → 200 with case list
3. PATCH tag state to 'closed' → closed_at set, deleted_at NULL
4. DELETE tag → deleted_at set, state unchanged
5. POST relation with type='invalid' → 400 error
6. POST relation with type='derived' → 201 created

### Phase 3: Frontend
1. Edit case form → loads current values
2. Submit edit form → case updated, redirect to detail
3. Click "Close Tag" → tag state='closed', remains visible, greyed
4. Add relation → dropdown shows allowed types
5. Bulk close cases → all selected closed
6. View on 375px screen → no horizontal scroll

### Phase 4: Order Integration
1. Create order without case → success
2. Link order to case → relation created
3. View case → shows linked orders
4. View order → shows linked cases
5. Delete case → order remains (independent)

### Phase 5: Documentation
1. Developer reads README → understands architecture
2. Developer reads API docs → can call endpoints
3. Developer reads relation types → understands usage
4. Developer reads workflows → can implement feature

### Phase 6: QA
1. All CRUD operations → success
2. Soft-delete case → data preserved
3. Module disabled → endpoints return 404
4. Module re-enabled → data accessible again
5. Tag closed → not deleted
6. Relation created → directionality correct

---

## ANTI-PATTERNS TO AVOID

### DO NOT:
- ❌ Create `tickets` or `tasks` tables (use cases with tags)
- ❌ Embed workflow logic in orders
- ❌ Introduce parent/child trees outside relations
- ❌ Add state machines (use tags)
- ❌ Optimize prematurely (no Redis, no caching yet)
- ❌ Physical delete anything (always soft-delete)
- ❌ Skip validation (enforce constraints)
- ❌ Duplicate endpoints (one path per resource)

### DO:
- ✅ Use relations to express connections
- ✅ Use tags to express workflow state
- ✅ Keep orders independent but relatable
- ✅ Soft-delete everything
- ✅ Log all actions with emoji prefixes
- ✅ Return user-friendly errors
- ✅ Preserve data on module disable

---

## ROLLOUT PLAN

### Development Environment
1. Complete Phases 1-3 in dev
2. Test with test data
3. Verify module disable/enable

### Staging/QA
1. Run full QA suite (Phase 6)
2. Performance test with 10k+ cases
3. Load test endpoints
4. Verify soft-deletes work at scale

### Production
1. Run schema validation (DB-001)
2. Deploy backend changes (Phase 2)
3. Deploy frontend changes (Phase 3)
4. Monitor logs for errors
5. Verify no downtime
6. Roll back if issues (soft-deletes preserve data)

### Post-Deployment
1. Monitor case creation rate
2. Track relation usage patterns
3. Identify most-used tags
4. Plan order integration (Phase 4)

---

## SUCCESS CRITERIA

The Sag Module implementation is COMPLETE when:

✅ **Database**
- All constraints enforced
- Soft-deletes everywhere
- Indexes performant

✅ **Backend**
- No duplicate endpoints
- Tag closing works
- Relations validated
- Edit route exists
- Errors consistent

✅ **Frontend**
- Edit form works
- Tag closing UI works
- Relations visualized
- Bulk operations work
- Mobile responsive

✅ **Order Integration**
- Model documented
- Schema planned
- API defined
- No constraint violations

✅ **Documentation**
- README complete
- API documented
- Relation types explained
- Workflows documented

✅ **Testing**
- All CRUD tested
- Relations tested
- Tags tested
- Frontend tested
- Module lifecycle tested

✅ **Architectural Compliance**
- One entity: Case
- Orders separate but linkable
- Template key not used in logic
- Status binary
- Tags never deleted (closed)
- Relations directional
- Soft-deletes everywhere
- No new tables (except orders)

---

## APPENDIX A: TASK TIME SUMMARY

| Phase | Task Count | Sequential Time | Parallel Time |
|-------|-----------|----------------|---------------|
| Phase 1: Database | 1 | 30m | 30m |
| Phase 2: Backend | 5 | 3h 30m | 1h 45m |
| Phase 3: Frontend | 5 | 5h 45m | 2h 30m |
| Phase 4: Orders | 3 | 2h | 30m (parallel) |
| Phase 5: Docs | 4 | 2h 30m | 45m (parallel) |
| Phase 6: QA | 5 | 4h 30m | 2h |
| **TOTAL** | **23** | **18h 45m** | **~8h** |

---

## APPENDIX B: RELATION TYPE REFERENCE

| Type | Direction | Meaning | Example |
|------|-----------|---------|---------|
| `derived` | A → B | B spawned from A | Support call → hardware order |
| `blocks` | A → B | A prevents B | Missing part → installation task |
| `executes` | A → B | A performs work for B | Packing task → customer order |
| `relates_to` | A ↔ B | Generic association | Related support tickets |

**Validation:** Only these four types allowed in `POST /api/v1/cases/{id}/relations`

---

## APPENDIX C: TAG STATE LIFECYCLE

```
Tag Created (state='open', closed_at=NULL)
    ↓
[Work happens]
    ↓
Tag Closed (state='closed', closed_at=NOW(), deleted_at=NULL)
    ↓
Tag Remains Visible (greyed out in UI)
    ↓
[Optional: Technical cleanup]
    ↓
Tag Soft-Deleted (deleted_at=NOW())
```

**Key Rule:** Closing ≠ Deleting. Tags are closed when work is done, deleted only if added by mistake.

---

## APPENDIX D: ORDER-CASE INTEGRATION EXAMPLE

**Scenario:** Customer needs new laptop

```
1. Support Call (Case ID: 1001)
   - Type: Case
   - Tags: [support, hardware]
   - Status: åben

2. Create Hardware Order (Order ID: 5001)
   - Type: Order (separate table)
   - Items: [Laptop, Charger]
   - Status: pending

3. Link Order to Case
   - POST /api/v1/orders/5001/cases
   - Body: {"case_id": 1001, "relation_type": "fulfills"}
   - Creates entry in order_case_relations

4. Fulfillment Task (Case ID: 1002)
   - Type: Case
   - Tags: [fulfillment]
   - Status: åben
   - Relation: 1002 executes 1001

5. Query Cases for Order
   - GET /api/v1/orders/5001/cases
   - Returns: [Case 1001]

6. Query Orders for Case
   - GET /api/v1/cases/1001/orders
   - Returns: [Order 5001]
```

**Architecture Preserved:**
- Order is NOT a case
- Order is independent (can exist without case)
- Order gains context through case relation
- Cases remain the process backbone

---

## DOCUMENT CONTROL

**Version History:**

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | 2026-01-30 | GitHub Copilot | Initial plan |
| 2.0 | 2026-01-30 | GitHub Copilot | Sub-agent task breakdown added |

**Approval:**
- [ ] Architect Review
- [ ] Technical Lead Review
- [ ] Project Manager Approval

**Next Review Date:** After Phase 2 completion

---

**END OF IMPLEMENTATION PLAN**