docs: add bible/ as single source of architectural truth
- Created bible/ with hierarchical documentation (architecture, pricelists, vendor mapping, background tasks, data rules, patterns, API, operations, history) - CLAUDE.md reduced to one instruction: read and follow the bible - README.md reduced to quick start only - Removed MEMORY.md and csv_export.md (content consolidated into bible/) - Fixed stale facts found during audit: weighted_avg (not weighted_median), correct API route names (/export-csv, /recalculate-all) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
86
bible/background-tasks.md
Normal file
86
bible/background-tasks.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# Background Tasks (Task Manager)
|
||||
|
||||
## Principle
|
||||
|
||||
**All long-running operations use the Task Manager. SSE (Server-Sent Events) must not be used.**
|
||||
|
||||
---
|
||||
|
||||
## Flow
|
||||
|
||||
```
|
||||
1. Client sends POST request
|
||||
│
|
||||
▼
|
||||
2. Handler creates task: taskManager.Submit(...)
|
||||
│
|
||||
▼
|
||||
3. Handler returns { "task_id": "uuid" }
|
||||
│
|
||||
▼
|
||||
4. Client polls GET /api/tasks/:id every 500ms
|
||||
│
|
||||
▼
|
||||
5. On completed/error — show toast notification
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task Types
|
||||
|
||||
| Constant | Purpose |
|
||||
|----------|---------|
|
||||
| `TaskTypeRecalculate` | Recalculate all component prices |
|
||||
| `TaskTypeStockImport` | Import stock file (.mxl/.xlsx) |
|
||||
| `TaskTypePricelistCreate` | Create pricelist (estimate/warehouse/competitor) |
|
||||
|
||||
---
|
||||
|
||||
## Task Structure
|
||||
|
||||
```go
|
||||
type Task struct {
|
||||
ID string // Task UUID
|
||||
Type TaskType // Task type
|
||||
Status TaskStatus // running | completed | error
|
||||
Progress int // 0-100
|
||||
Message string // Current UI message
|
||||
Result map[string]interface{} // Result when completed
|
||||
Error string // Error text when error
|
||||
CreatedAt time.Time
|
||||
DoneAt *time.Time
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage Example (Backend)
|
||||
|
||||
```go
|
||||
taskID := h.taskManager.Submit(tasks.TaskTypeStockImport,
|
||||
func(ctx context.Context, progressCb func(int, string)) (map[string]interface{}, error) {
|
||||
progressCb(25, "Reading file")
|
||||
// ... work ...
|
||||
progressCb(75, "Saving to DB")
|
||||
return map[string]interface{}{
|
||||
"rows_total": 100,
|
||||
"inserted": 95,
|
||||
}, nil
|
||||
},
|
||||
)
|
||||
c.JSON(http.StatusOK, gin.H{"task_id": taskID})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
| Method | URL | Description |
|
||||
|--------|-----|-------------|
|
||||
| GET | `/api/tasks/:id` | Task status and result |
|
||||
|
||||
---
|
||||
|
||||
## Implementation
|
||||
|
||||
`internal/tasks/` — Task Manager: Submit, track, poll.
|
||||
Reference in New Issue
Block a user