kai/invoice-master-poc-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP

Browse Source
This commit is contained in:
Yaojia Wang
2026-02-01 18:51:54 +01:00
parent 4126196dea
commit a564ac9d70
82 changed files with 13123 additions and 3282 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
docs/product-plan-v2.md
View File

@@ -2,10 +2,16 @@
## Table of Contents
1. [Product Requirements Document (PRD)](#1-product-requirements-document-prd)
- Epic 1-6: Original features
- **Epic 7: Dashboard Enhancement** (NEW)
2. [CSV Format Specification](#2-csv-format-specification)
3. [Database Schema Changes](#3-database-schema-changes)
4. [API Specification](#4-api-specification)
- 4.1-4.2: Original endpoints
- **4.3: Dashboard API Endpoints** (NEW)
5. [UI Wireframes (Text-Based)](#5-ui-wireframes-text-based)
- **5.0: Dashboard Overview** (NEW)
- 5.1-5.5: Original wireframes
6. [Implementation Phases](#6-implementation-phases)
7. [State Machine Diagrams](#7-state-machine-diagrams)
@@ -74,6 +80,23 @@ This enhancement adds batch upload capabilities, document lifecycle management,
| US-6.3 | As a developer, I want to query document status so that I can poll for completion | - GET endpoint with document ID<br>- Returns full status object<br>- Includes annotation summary | P0 |
| US-6.4 | As a developer, I want API-uploaded documents visible in UI so that I can manage all documents centrally | - Same data model for API/UI uploads<br>- Source field distinguishes origin<br>- Full UI functionality available | P0 |
#### Epic 7: Dashboard Enhancement
| ID | User Story | Acceptance Criteria | Priority |
|----|------------|---------------------|----------|
| US-7.1 | As a user, I want to see data quality metrics on the dashboard so that I can monitor annotation completeness | - Annotation completeness rate displayed as percentage ring<br>- Complete/incomplete/pending document counts<br>- Click incomplete count to jump to filtered document list | P0 |
| US-7.2 | As a user, I want to see the active model status on the dashboard so that I can monitor model performance | - Current model version and name displayed<br>- mAP/precision/recall metrics shown<br>- Activation date and training document count displayed<br>- Running training task shown if any | P0 |
| US-7.3 | As a user, I want to see recent activity on the dashboard so that I can track system changes | - Last 10 activities displayed with relative timestamps<br>- Activity types: document upload, annotation change, training complete/failed, model activation<br>- Each activity shows icon, description, and time | P1 |
| US-7.4 | As a user, I want the dashboard stats cards to show meaningful data so that I can quickly assess system state | - Total Documents count<br>- Annotation Complete count (documents with core fields)<br>- Incomplete count (labeled but missing core fields)<br>- Pending count (pending + auto_labeling status) | P0 |
**Annotation Completeness Definition:**
A document is considered "annotation complete" when it has:
- `invoice_number` OR `ocr_number` (at least one identifier)
- `bankgiro` OR `plusgiro` (at least one payment account)
Documents with status=labeled but missing these core fields are considered "incomplete".
---
## 2. CSV Format Specification
@@ -689,10 +712,212 @@ Response (additions):
}
```
### 4.3 Dashboard API Endpoints
#### 4.3.1 Dashboard Statistics
```yaml
GET /api/v1/admin/dashboard/stats
Response:
{
"total_documents": 38,
"annotation_complete": 25,
"annotation_incomplete": 8,
"pending": 5,
"completeness_rate": 75.76
}
```
**Completeness Calculation Logic:**
- `annotation_complete`: Documents where status=labeled AND has (invoice_number OR ocr_number) AND has (bankgiro OR plusgiro)
- `annotation_incomplete`: Documents where status=labeled BUT missing core fields
- `pending`: Documents where status IN (pending, auto_labeling)
- `completeness_rate`: annotation_complete / (annotation_complete + annotation_incomplete) * 100
#### 4.3.2 Active Model Info
```yaml
GET /api/v1/admin/dashboard/active-model
Response:
{
"model": {
"version_id": "uuid",
"version": "1.2.0",
"name": "Invoice Model",
"metrics_mAP": 0.951,
"metrics_precision": 0.94,
"metrics_recall": 0.92,
"document_count": 500,
"activated_at": "2024-01-20T15:00:00Z"
},
"running_training": {
"task_id": "uuid",
"name": "Run-2024-02",
"status": "running",
"started_at": "2024-01-25T10:00:00Z",
"progress": 45
}
}
Response (no active model):
{
"model": null,
"running_training": null
}
```
#### 4.3.3 Recent Activity
```yaml
GET /api/v1/admin/dashboard/activity
Query Parameters:
- limit: 10 (default)
Response:
{
"activities": [
{
"type": "model_activated",
"description": "Activated model v1.2.0",
"timestamp": "2024-01-25T12:00:00Z",
"metadata": {
"version_id": "uuid",
"version": "1.2.0"
}
},
{
"type": "training_completed",
"description": "Training complete: Run-2024-01, mAP 95.1%",
"timestamp": "2024-01-24T18:30:00Z",
"metadata": {
"task_id": "uuid",
"task_name": "Run-2024-01",
"mAP": 0.951
}
},
{
"type": "annotation_modified",
"description": "Modified INV-001.pdf invoice_number",
"timestamp": "2024-01-24T14:20:00Z",
"metadata": {
"document_id": "uuid",
"filename": "INV-001.pdf",
"field_name": "invoice_number"
}
},
{
"type": "document_uploaded",
"description": "Uploaded INV-005.pdf",
"timestamp": "2024-01-23T09:15:00Z",
"metadata": {
"document_id": "uuid",
"filename": "INV-005.pdf"
}
},
{
"type": "training_failed",
"description": "Training failed: Run-2024-00",
"timestamp": "2024-01-22T16:45:00Z",
"metadata": {
"task_id": "uuid",
"task_name": "Run-2024-00",
"error": "GPU memory exceeded"
}
}
]
}
```
**Activity Types:**
| Type | Description Template | Source |
|------|---------------------|--------|
| `document_uploaded` | "Uploaded {filename}" | `admin_documents.created_at` |
| `annotation_modified` | "Modified {filename} {field_name}" | `annotation_history` |
| `training_completed` | "Training complete: {task_name}, mAP {mAP}%" | `training_tasks` (status=completed) |
| `training_failed` | "Training failed: {task_name}" | `training_tasks` (status=failed) |
| `model_activated` | "Activated model {version}" | `model_versions.activated_at` |
---
## 5. UI Wireframes (Text-Based)
### 5.0 Dashboard Overview
```
+------------------------------------------------------------------+
| DOCUMENT ANNOTATION TOOL [User: Admin] [Logout]|
+------------------------------------------------------------------+
| [Dashboard] [Documents] [Training] [Models] [Settings] |
+------------------------------------------------------------------+
| |
| DASHBOARD |
| |
| +-------------+ +-------------+ +-------------+ +-------------+ |
| | Total | | Complete | | Incomplete | | Pending | |
| | Documents | | Annotations | | | | | |
| | 38 | | 25 | | 8 | | 5 | |
| +-------------+ +-------------+ +-------------+ +-------------+ |
| [View List] |
| |
| +---------------------------+ +-------------------------------+ |
| | DATA QUALITY | | ACTIVE MODEL | |
| | +-----------+ | | | |
| | | | | | v1.2.0 - Invoice Model | |
| | | 78% | Annotation | | ----------------------------- | |
| | | | Complete | | | |
| | +-----------+ | | mAP Precision Recall | |
| | | | 95.1% 94% 92% | |
| | Complete: 25 | | | |
| | Incomplete: 8 | | Activated: 2024-01-20 | |
| | Pending: 5 | | Documents: 500 | |
| | | | | |
| | [View Incomplete Docs] | | Training: Run-2024-02 [====] | |
| +---------------------------+ +-------------------------------+ |
| |
| +--------------------------------------------------------------+ |
| | RECENT ACTIVITY | |
| +--------------------------------------------------------------+ |
| | [rocket] Activated model v1.2.0 2 hours ago| |
| | [check] Training complete: Run-2024-01, mAP 95.1% yesterday| |
| | [edit] Modified INV-001.pdf invoice_number yesterday| |
| | [doc] Uploaded INV-005.pdf 2 days ago| |
| | [doc] Uploaded INV-004.pdf 2 days ago| |
| | [x] Training failed: Run-2024-00 3 days ago| |
| +--------------------------------------------------------------+ |
| |
| +--------------------------------------------------------------+ |
| | SYSTEM STATUS | |
| | Backend API: Online Database: Connected GPU: Available | |
| +--------------------------------------------------------------+ |
+------------------------------------------------------------------+
```
**Dashboard Components:**
| Component | Data Source | Update Frequency |
|-----------|-------------|------------------|
| Total Documents | `admin_documents` count | Real-time |
| Complete Annotations | Documents with (invoice_number OR ocr_number) AND (bankgiro OR plusgiro) | Real-time |
| Incomplete | Labeled documents missing core fields | Real-time |
| Pending | Documents with status pending or auto_labeling | Real-time |
| Data Quality Ring | Complete / (Complete + Incomplete) * 100% | Real-time |
| Active Model | `model_versions` where is_active=true | On model activation |
| Recent Activity | Aggregated from multiple tables (see below) | Real-time |
**Recent Activity Sources:**
| Activity Type | Icon | Source Table | Query |
|--------------|------|--------------|-------|
| Document Upload | doc | `admin_documents` | `created_at DESC` |
| Annotation Change | edit | `annotation_history` | `created_at DESC` |
| Training Complete | check | `training_tasks` | `status=completed, completed_at DESC` |
| Training Failed | x | `training_tasks` | `status=failed, completed_at DESC` |
| Model Activated | rocket | `model_versions` | `activated_at DESC` |
### 5.1 Document List View
```