# TED XML Parser - Complete Model

This package provides comprehensive Go structures for parsing all TED (Tenders Electronic Daily) XML documents, supporting the complete range of eForms notice types and legacy TED XML formats.

## 🚀 Features

- ✅ **Complete TED XML Support**: All notice subtypes from eForms SDK 1.3 to 1.13
- ✅ **Automatic Document Detection**: Intelligent parsing with type detection
- ✅ **Full Field Coverage**: Comprehensive mapping of all TED XML fields
- ✅ **eForms Compliance**: Full support for eForms extensions and organizations
- ✅ **Legacy Compatibility**: Backward compatibility with old TED XML formats
- ✅ **Validation & Utility Methods**: Built-in validation and data extraction helpers
- ✅ **Award Results**: Complete lot tender and award information
- ✅ **Multi-language Support**: Proper handling of multilingual content
- ✅ **High Performance**: Optimized parsing with 50MB file support

## 📋 Supported Document Types

### Core Notice Types
- **ContractNotice** - Standard tender notices for procurement opportunities
- **ContractAwardNotice** - Award notices announcing procurement results
- **PriorInformationNotice** - Early market engagement and planning notices
- **ResultNotice** - eForms-specific result notices

### Specialized Notice Types
- **DesignContest** - Design competition notices with jury and reward information
- **QualificationSystemNotice** - Qualification system establishment notices
- **ConcessionNotice** - Concession contract notices with revenue terms
- **PlanningNotice** - Procurement planning and budget notices
- **CompetitionNotice** - Competition procedure notices
- **ChangeNotice** - Notice modifications and corrections (eForms)
- **SubcontractNotice** - Subcontracting opportunity notices

### Legacy Document Types
- **Corrigendum** - Corrections (parsed as ContractNotice)
- **ModificationNotice** - Modifications (parsed as ContractNotice)

## 🏗️ Complete Data Model

### Business Groups Covered

#### **BG-1: Notice**
- Complete notice metadata (ID, version, dates, language)
- Notice type codes and regulatory domains
- Publication information and gazette references
- UBL extensions with eForms data

#### **BG-2: Competition**
- Procedure codes and submission methods
- Tender submission deadlines and periods
- Open tender events and auction terms
- Process justification and government agreements

#### **BG-3: Tender**
- Tender reference and identification
- Tender variants and ranking information
- Legal monetary totals and payable amounts
- Subcontracting terms and descriptions

#### **BG-4: Lot**
- Lot identification and titles
- Procurement project details per lot
- Tendering terms and processes per lot
- Award criteria and selection requirements

#### **BG-5: Part**
- Part identification and classification
- Place of performance and location details
- Contract duration and planned periods
- Additional commodity classifications

#### **BG-6: Contracting Entity**
- Contracting party identification
- Buyer profile URIs and contact information
- Contracting party types and activities
- Service provider party details

#### **BG-7: Procedure**
- Procurement procedures and frameworks
- Procedure identifiers (UUID v4)
- Framework agreement terms
- Cross-border procurement indicators

#### **BG-8: Organization**
- Complete organization details and contacts
- Party identification and legal entities
- Postal addresses with country codes
- Natural person indicators

#### **BG-9: Document**
- Document references and attachments
- External references with URIs and hashes
- Document types and status codes
- Validity periods and language specifications

#### **BG-10: Lot Result**
- Tender result codes and award decisions
- Received submission statistics
- Winner identification and tender details
- Contract references and settlement information

#### **BG-11: Winner**
- Winning tenderer identification
- Winner organization details
- SME indicator and natural person flags
- Country of origin information

#### **BG-12: Settled Contract**
- Contract identification and titles
- Issue dates and signatory parties
- Contract values and currency information
- Performance period details

#### **BG-13: Subcontracting**
- Subcontracting terms and percentages
- Subcontractor identification
- Value thresholds and descriptions
- Unknown price indicators

### Extended Structures

#### **Design Contest Specific**
- **ContestDesignJury**: Jury decisions and member information
- **ContestDesignReward**: Reward structures and benefit values
- **JudgingCriteria**: Evaluation criteria and descriptions

#### **Qualification System Specific**
- **QualificationApplication**: Application procedures and periods
- **TendererQualificationRequest**: Qualification requirements
- **ApplicationPeriod**: Application start/end dates and times

#### **Concession Specific**
- **ConcessionRevenue**: Revenue types and amounts
- **ConcessionTerm**: Concession values and duration
- **FrameworkAgreement**: Framework terms and participants

#### **Planning Specific**
- **BudgetAccountLine**: Budget codes and amounts
- **BudgetAccount**: Account classification schemes
- **PlannedPeriod**: Planning timeline information

#### **Award Results Enhanced**
- **EnhancedTenderResult**: Comprehensive award information
- **AwardedTenderedProject**: Project award details
- **WinningTenderLot**: Lot-specific winners
- **WinningTender**: Individual tender results
- **ReceivedSubmissionsStatistics**: Submission counts and statistics

## 🔧 Usage Examples

### Basic Document Parsing

```go
package main

import (
    "fmt"
    "io/ioutil"
    "log"
    
    "tm/ted"
)

func main() {
    // Create comprehensive TED parser
    parser := ted.NewTEDParser()
    
    // Read any TED XML file
    xmlData, err := ioutil.ReadFile("ted_document.xml")
    if err != nil {
        log.Fatal(err)
    }

    // Automatic detection and parsing
    parsedDoc, err := parser.ParseXML(xmlData)
    if err != nil {
        log.Fatal(err)
    }

    // Get document information
    document := parsedDoc.GetDocument()
    fmt.Printf("Document Type: %s\n", parsedDoc.Type)
    fmt.Printf("Document ID: %s\n", document.GetID())
    fmt.Printf("Notice Type: %s\n", document.GetNoticeType())
    fmt.Printf("Language: %s\n", document.GetLanguage())
    
    // Validate document
    if err := document.Validate(); err != nil {
        log.Printf("Validation error: %v", err)
    }
}
```

### Advanced Usage by Document Type

```go
// Handle specific document types
switch parsedDoc.Type {
case ted.DocumentTypeContractNotice:
    cn := parsedDoc.ContractNotice
    fmt.Printf("Tender Deadline: %s\n", cn.GetTenderDeadline())
    amount, currency := cn.GetBudget()
    fmt.Printf("Estimated Value: %s %s\n", amount, currency)
    
case ted.DocumentTypeContractAwardNotice:
    can := parsedDoc.ContractAwardNotice
    fmt.Printf("Award Date: %s\n", can.GetAwardDate())
    amount, currency := can.GetTotalAwardValue()
    fmt.Printf("Total Award: %s %s\n", amount, currency)
    
case ted.DocumentTypePriorInformationNotice:
    pin := parsedDoc.PriorInformationNotice
    fmt.Printf("Prior Information ID: %s\n", pin.GetID())
    
case ted.DocumentTypeDesignContest:
    dc := parsedDoc.DesignContest
    fmt.Printf("Design Contest ID: %s\n", dc.GetID())
    if dc.ContestDesignJury != nil {
        fmt.Printf("Jury Decision: %s\n", dc.ContestDesignJury.JuryDecision)
    }
    
case ted.DocumentTypeQualificationSystemNotice:
    qsn := parsedDoc.QualificationSystemNotice
    fmt.Printf("Qualification System ID: %s\n", qsn.GetID())
    
case ted.DocumentTypeConcessionNotice:
    cn := parsedDoc.ConcessionNotice
    fmt.Printf("Concession ID: %s\n", cn.GetID())
    if cn.ConcessionRevenue != nil {
        fmt.Printf("Revenue Type: %s\n", cn.ConcessionRevenue.RevenueType)
    }
    
case ted.DocumentTypePlanningNotice:
    pn := parsedDoc.PlanningNotice
    fmt.Printf("Planning ID: %s\n", pn.GetID())
    fmt.Printf("Budget Lines: %d\n", len(pn.BudgetAccountLine))
    
case ted.DocumentTypeResultNotice:
    rn := parsedDoc.ResultNotice
    fmt.Printf("Result ID: %s\n", rn.GetID())
    fmt.Printf("Tender Results: %d\n", len(rn.TenderResult))
    
case ted.DocumentTypeChangeNotice:
    cn := parsedDoc.ChangeNotice
    fmt.Printf("Change ID: %s\n", cn.GetID())
    fmt.Printf("Change Reasons: %d\n", len(cn.ChangeReason))
    
case ted.DocumentTypeSubcontractNotice:
    sn := parsedDoc.SubcontractNotice
    fmt.Printf("Subcontract ID: %s\n", sn.GetID())
    fmt.Printf("Subcontract Calls: %d\n", len(sn.SubcontractCall))
}
```

### Working with Organizations and Extensions

```go
// Extract organization information (works for all notice types)
if doc := parsedDoc.GetDocument(); doc != nil {
    // Type assertion for specific methods
    if notice, ok := doc.(*ted.ContractNotice); ok {
        orgs := notice.GetOrganizations()
        if orgs != nil {
            fmt.Printf("Organizations: %d\n", len(orgs.Organization))
            for _, org := range orgs.Organization {
                if org.Company != nil && org.Company.PartyName != nil {
                    fmt.Printf("- %s\n", org.Company.PartyName.Name)
                }
            }
        }
        
        // Get publication information
        pub := notice.GetPublicationInfo()
        if pub != nil {
            fmt.Printf("Publication ID: %s\n", pub.NoticePublicationID)
            fmt.Printf("OJS ID: %s\n", pub.GazetteID)
            fmt.Printf("Publication Date: %s\n", pub.PublicationDate)
        }
    }
}
```

## 🔍 Document Type Detection

The parser includes intelligent document type detection:

```go
// Detect document type without parsing
docType, err := parser.DetectDocumentType(xmlData)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Detected document type: %s\n", docType)

// Parse specific type if known
switch docType {
case ted.DocumentTypeContractNotice:
    notice, err := parser.ParseXMLAsContractNotice(xmlData)
case ted.DocumentTypePriorInformationNotice:
    notice, err := parser.ParseXMLAsPriorInformationNotice(xmlData)
case ted.DocumentTypeDesignContest:
    notice, err := parser.ParseXMLAsDesignContest(xmlData)
// ... other specific parsers available
}
```

## ✅ Comprehensive Validation

All notice types include thorough validation:

```go
// Validate any notice type
err := notice.Validate()
if err != nil {
    log.Printf("Validation failed: %v", err)
}
```

### Validation Coverage
- Required fields (ID, ContractFolderID, IssueDate)
- Date format validation (multiple ISO 8601 formats)
- Notice type code validation
- Language code validation (3-letter ISO codes)
- Currency code validation (3-letter ISO codes)  
- Duration unit code validation
- Business rule validation per notice type

## 🎯 Complete Field Coverage

### Core Metadata Fields
- UBLVersionID, CustomizationID, ID, ContractFolderID
- IssueDate, IssueTime, VersionID, RegulatoryDomain
- NoticeTypeCode, NoticeLanguageCode
- All namespace declarations and XML attributes

### Business Information
- Contracting party details and buyer profiles
- Tendering terms, processes, and submission requirements
- Procurement projects with lots and parts
- Award criteria and selection requirements
- Legal monetary totals with currency support
- Duration measures with unit codes

### eForms Extensions
- Complete eForms extension support
- Organizations with party identification
- Publication information and gazette details
- Notice results with lot awards
- Selection criteria and official languages
- Award criterion parameters

### Enhanced Structures
- Subcontracting terms with enhanced details
- Framework agreements and parent contracts
- Document references with validity periods
- Address information with country codes
- Contact details and electronic communication

## 🧪 Tested Compatibility

This comprehensive parser has been tested with:
- ✅ All eForms SDK versions 1.3 to 1.13
- ✅ Legacy TED XML formats (R2.0.8, R2.0.9)
- ✅ Multiple notice subtypes (20+ tested)
- ✅ Complex organization structures (10+ organizations)
- ✅ Large procurement lots (50+ lots tested)
- ✅ Multiple currencies and value formats
- ✅ Multilingual content and character encoding
- ✅ Large XML files (up to 50MB)
- ✅ Real TED database documents

## 📊 Performance Characteristics

- **Memory Efficient**: Streaming XML parsing with configurable limits
- **Fast Detection**: String-based detection with XML fallback
- **Scalable**: Handles large files and complex structures
- **Concurrent Safe**: Thread-safe parser instances
- **Error Resilient**: Graceful handling of malformed or incomplete XML

## 🔗 Dependencies

- Go 1.19+
- Standard library: `encoding/xml`, `time`, `fmt`
- Custom XML parser: `tm/pkg/xmlparser`

## 📈 Future Extensions

This model is designed to be forward-compatible with:
- New eForms SDK versions
- Additional notice subtypes
- Extended business groups
- Enhanced validation rules
- Performance optimizations

The comprehensive nature of this TED XML model ensures complete coverage of all procurement notice types and supports the full lifecycle of European public procurement processes.