Mine Action AI System - Backend Implementation Guide

# Mine Action AI System - Backend Implementation Guide
## Hono.js + Cloudflare Workers

## Vue d'ensemble du Backend

Ce guide implémente la partie backend du système d'IA pour l'action humanitaire contre les mines, utilisant Hono.js sur Cloudflare Workers selon le plan stratégique HumaniTech Phase 1.

## Architecture Backend

### Stack technologique Backend
- **Framework**: Hono.js (ultra-rapide, type-safe)
- **Runtime**: Cloudflare Workers
- **Base de données**: Cloudflare D1 (SQLite distribuée)
- **Stockage fichiers**: Cloudflare R2
- **IA**: Anthropic Claude API
- **Authentification**: JWT + Cloudflare Access
- **Build**: Wrangler

## Structure du projet Backend

```
mine-action-ai-backend/
├── README.md
├── package.json
├── wrangler.toml
├── schema.sql
├── src/
│   ├── index.ts              # Point d'entrée principal Hono
│   ├── routes/
│   │   ├── auth.ts           # Authentification
│   │   ├── documents.ts      # Gestion documents
│   │   ├── reports.ts        # Génération rapports
│   │   ├── chat.ts           # Assistant IA
│   │   ├── risk-analysis.ts  # Analyse risques
│   │   └── sop.ts           # Génération SOPs
│   ├── middleware/
│   │   ├── auth.ts           # Middleware JWT
│   │   ├── cors.ts           # Configuration CORS
│   │   └── validation.ts     # Validation des données
│   ├── services/
│   │   ├── claude.ts         # Service Claude AI
│   │   ├── database.ts       # Gestionnaire D1
│   │   ├── storage.ts        # Gestionnaire R2
│   │   └── parsers.ts        # Parseurs documents
│   ├── types/
│   │   ├── bindings.ts       # Types Cloudflare
│   │   ├── api.ts           # Types API
│   │   └── database.ts      # Types base de données
│   └── utils/
│       ├── crypto.ts         # Utilitaires crypto
│       ├── validation.ts     # Schémas Zod
│       └── constants.ts      # Constantes
└── migrations/
    └── 001_initial.sql
```

## Installation et configuration

### 1. Initialisation du projet Backend

```bash
# Créer le projet avec Hono template
npm create hono@latest mine-action-ai-backend
cd mine-action-ai-backend

# Installer les dépendances spécifiques
npm install @anthropic-ai/sdk
npm install jose # JWT
npm install zod @hono/zod-validator
npm install mammoth pdf-parse xlsx papaparse
npm install @types/pdf-parse

# Outils de développement
npm install -D @cloudflare/workers-types
npm install -D miniflare
```

### 2. Configuration Cloudflare (wrangler.toml)

```toml
# wrangler.toml
name = "mine-action-ai-backend"
main = "src/index.ts"
compatibility_date = "2024-06-01"
compatibility_flags = ["nodejs_compat"]

[env.production.vars]
ENVIRONMENT = "production"

[env.development.vars]
ENVIRONMENT = "development"

# Base de données D1
[[d1_databases]]
binding = "DB"
database_name = "mine-action-db"
database_id = "your-d1-database-id"

# Stockage R2
[[r2_buckets]]
binding = "STORAGE"
bucket_name = "mine-action-files"

# Variables d'environnement (utiliser wrangler secret pour les valeurs sensibles)
[vars]
JWT_SECRET = "your_jwt_secret_here"
CORS_ORIGINS = "http://localhost:5173,https://your-frontend.workers.dev"
```

### 3. Schéma base de données D1

```sql
-- schema.sql
PRAGMA foreign_keys = ON;

-- Table utilisateurs
CREATE TABLE IF NOT EXISTS users (
  id TEXT PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  name TEXT,
  role TEXT DEFAULT 'USER' CHECK (role IN ('USER', 'IM_OFFICER', 'PROGRAM_MANAGER', 'ADMIN')),
  password_hash TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Table documents
CREATE TABLE IF NOT EXISTS documents (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  type TEXT NOT NULL CHECK (type IN ('FIELD_REPORT', 'SURVEY_FORM', 'SOP_MANUAL', 'DONOR_REPORT', 'TRAINING_MATERIAL', 'HAZARD_SURVEY', 'INCIDENT_LOG')),
  file_url TEXT,
  file_size INTEGER,
  file_type TEXT,
  extracted_data TEXT, -- JSON as TEXT
  status TEXT DEFAULT 'PENDING' CHECK (status IN ('PENDING', 'PROCESSING', 'COMPLETED', 'FAILED')),
  user_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Table rapports
CREATE TABLE IF NOT EXISTS reports (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  type TEXT NOT NULL CHECK (type IN ('DONOR_REPORT', 'PROGRESS_REPORT', 'RISK_ASSESSMENT', 'OPERATIONAL_PLAN')),
  metadata TEXT, -- JSON as TEXT
  user_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Table conversations chat
CREATE TABLE IF NOT EXISTS chats (
  id TEXT PRIMARY KEY,
  title TEXT,
  messages TEXT NOT NULL, -- JSON as TEXT
  user_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Table évaluations de risques
CREATE TABLE IF NOT EXISTS risk_assessments (
  id TEXT PRIMARY KEY,
  area TEXT NOT NULL,
  risk_level TEXT NOT NULL CHECK (risk_level IN ('LOW', 'MEDIUM', 'HIGH', 'CRITICAL')),
  factors TEXT, -- JSON as TEXT
  predictions TEXT, -- JSON as TEXT
  confidence_score REAL,
  user_id TEXT,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE SET NULL
);

-- Table SOPs générées
CREATE TABLE IF NOT EXISTS sops (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT NOT NULL,
  imas_standards TEXT, -- JSON array as TEXT
  category TEXT NOT NULL,
  version TEXT DEFAULT '1.0',
  user_id TEXT NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

-- Index pour améliorer les performances
CREATE INDEX IF NOT EXISTS idx_documents_user_id ON documents(user_id);
CREATE INDEX IF NOT EXISTS idx_documents_type ON documents(type);
CREATE INDEX IF NOT EXISTS idx_documents_status ON documents(status);
CREATE INDEX IF NOT EXISTS idx_reports_user_id ON reports(user_id);
CREATE INDEX IF NOT EXISTS idx_reports_type ON reports(type);
CREATE INDEX IF NOT EXISTS idx_chats_user_id ON chats(user_id);
CREATE INDEX IF NOT EXISTS idx_risk_assessments_area ON risk_assessments(area);
CREATE INDEX IF NOT EXISTS idx_risk_assessments_risk_level ON risk_assessments(risk_level);
CREATE INDEX IF NOT EXISTS idx_sops_user_id ON sops(user_id);
CREATE INDEX IF NOT EXISTS idx_sops_category ON sops(category);
```

## Implémentation Backend

### 1. Point d'entrée principal (src/index.ts)

```typescript
// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';
import { prettyJSON } from 'hono/pretty-json';
import { secureHeaders } from 'hono/secure-headers';

import { authRoutes } from './routes/auth';
import { documentRoutes } from './routes/documents';
import { reportRoutes } from './routes/reports';
import { chatRoutes } from './routes/chat';
import { riskAnalysisRoutes } from './routes/risk-analysis';
import { sopRoutes } from './routes/sop';

import { authMiddleware } from './middleware/auth';
import type { Bindings, Variables } from './types/bindings';

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();

// Middleware global
app.use('*', logger());
app.use('*', prettyJSON());
app.use('*', secureHeaders());

app.use('/api/*', cors({
  origin: (origin) => {
    const allowedOrigins = ['http://localhost:5173', 'https://your-frontend.workers.dev'];
    return allowedOrigins.includes(origin) || origin?.endsWith('.workers.dev');
  },
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  allowHeaders: ['Content-Type', 'Authorization'],
  credentials: true,
}));

// Routes publiques
app.route('/api/auth', authRoutes);

// Health check
app.get('/api/health', (c) => {
  return c.json({ 
    status: 'healthy', 
    timestamp: new Date().toISOString(),
    environment: c.env.ENVIRONMENT 
  });
});

// Routes protégées
app.use('/api/*', authMiddleware);
app.route('/api/documents', documentRoutes);
app.route('/api/reports', reportRoutes);
app.route('/api/chat', chatRoutes);
app.route('/api/risk-analysis', riskAnalysisRoutes);
app.route('/api/sop', sopRoutes);

// Route 404
app.notFound((c) => {
  return c.json({ error: 'Endpoint not found' }, 404);
});

// Gestionnaire d'erreurs global
app.onError((err, c) => {
  console.error(`${err}`);
  return c.json({ 
    error: 'Internal Server Error',
    message: c.env.ENVIRONMENT === 'development' ? err.message : undefined
  }, 500);
});

export default app;
```

### 2. Types et interfaces (src/types/bindings.ts)

```typescript
// src/types/bindings.ts
export interface Bindings {
  DB: D1Database;
  STORAGE: R2Bucket;
  ANTHROPIC_API_KEY: string;
  JWT_SECRET: string;
  ENVIRONMENT: 'development' | 'production';
  CORS_ORIGINS: string;
}

export interface Variables {
  user: {
    id: string;
    email: string;
    role: string;
  };
}

export interface ClaudeMessage {
  role: 'user' | 'assistant';
  content: string;
}

export interface ParsedDocument {
  raw: string;
  structured?: any;
  metadata?: {
    pageCount?: number;
    wordCount?: number;
    extractedAt: string;
  };
}
```

### 3. Service Claude AI (src/services/claude.ts)

```typescript
// src/services/claude.ts
import type { ClaudeMessage } from '../types/bindings';

export class ClaudeService {
  constructor(private apiKey: string) {}

  async generateResponse(
    messages: ClaudeMessage[], 
    systemPrompt?: string
  ): Promise<string> {
    try {
      const response = await fetch('https://api.anthropic.com/v1/messages', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': this.apiKey,
          'anthropic-version': '2023-06-01',
        },
        body: JSON.stringify({
          model: 'claude-3-sonnet-20240229',
          max_tokens: 4000,
          system: systemPrompt,
          messages,
        }),
      });

      if (!response.ok) {
        throw new Error(`Claude API error: ${response.status}`);
      }

      const data = await response.json();
      return data.content[0]?.text || '';
    } catch (error) {
      console.error('Claude API error:', error);
      throw new Error('Failed to generate response from Claude');
    }
  }

  async parseDocument(content: string, documentType: string): Promise<any> {
    const systemPrompt = `You are an expert in mine action operations. Extract structured data from the following ${documentType} document and format it as JSON. Include key information such as:
    - Location/coordinates
    - Date/time
    - Personnel involved
    - Activities performed
    - Hazards identified
    - Safety measures
    - Equipment used
    - Results/outcomes
    
    Respond with valid JSON only.`;
    
    const response = await this.generateResponse([
      { 
        role: 'user', 
        content: `Parse this ${documentType} document and extract key information:\n\n${content.slice(0, 4000)}` 
      }
    ], systemPrompt);

    try {
      return JSON.parse(response);
    } catch {
      return { 
        raw: response,
        error: 'Failed to parse as JSON',
        extractedText: content.slice(0, 1000)
      };
    }
  }

  async generateReport(
    data: any[], 
    reportType: string, 
    donorSpecific?: string,
    dateRange?: { start: string; end: string }
  ): Promise<string> {
    const systemPrompt = `You are a mine action specialist creating ${reportType} reports. Generate professional, donor-appropriate content based on the provided data. 
    
    Include:
    - Executive summary
    - Key metrics and achievements
    - Challenges and mitigation strategies
    - Future recommendations
    - Compliance with IMAS standards
    
    Format as professional markdown document.`;
    
    const contextInfo = donorSpecific ? `for ${donorSpecific}` : 'for general stakeholders';
    const periodInfo = dateRange ? `covering period ${dateRange.start} to ${dateRange.end}` : '';
    
    const prompt = `Generate a comprehensive ${reportType} report ${contextInfo} ${periodInfo} based on this data:
    
    Data Summary:
    - Total documents processed: ${data.length}
    - Document types: ${[...new Set(data.map(d => d.type))].join(', ')}
    
    Detailed Data: ${JSON.stringify(data.slice(0, 10), null, 2)}
    
    Ensure the report follows international mine action reporting standards.`;

    return await this.generateResponse([
      { role: 'user', content: prompt }
    ], systemPrompt);
  }

  async assessRisk(
    surveyData: any[], 
    incidentLogs: any[],
    area: string
  ): Promise<{ level: string; analysis: string; recommendations: string[] }> {
    const systemPrompt = `You are a mine action risk assessment expert. Analyze survey data and incident logs to predict risk levels and priority areas according to IMAS standards.
    
    Risk levels: LOW, MEDIUM, HIGH, CRITICAL
    
    Consider:
    - Historical incident patterns
    - Hazard density and types
    - Population proximity
    - Infrastructure importance
    - Environmental factors
    
    Respond with JSON containing: level, analysis, recommendations array.`;
    
    const prompt = `Analyze risk for area "${area}" based on:
    
    Survey Data: ${JSON.stringify(surveyData)}
    Incident Logs: ${JSON.stringify(incidentLogs)}
    
    Provide comprehensive risk assessment with actionable recommendations.`;

    const response = await this.generateResponse([
      { role: 'user', content: prompt }
    ], systemPrompt);

    try {
      return JSON.parse(response);
    } catch {
      // Fallback parsing
      const level = response.includes('CRITICAL') ? 'CRITICAL' :
                   response.includes('HIGH') ? 'HIGH' :
                   response.includes('MEDIUM') ? 'MEDIUM' : 'LOW';
      
      return {
        level,
        analysis: response,
        recommendations: ['Review assessment manually', 'Consult field specialists']
      };
    }
  }

  async generateSOP(
    topic: string, 
    imasStandards: string[], 
    category: string
  ): Promise<string> {
    const systemPrompt = `You are a mine action technical expert. Generate Standard Operating Procedure (SOP) content based on IMAS standards and international best practices.
    
    Include:
    - Purpose and scope
    - References to IMAS standards
    - Responsibilities
    - Procedures (step-by-step)
    - Safety requirements
    - Quality assurance
    - Documentation requirements
    
    Format as professional SOP document with clear sections and numbering.`;
    
    const prompt = `Generate a comprehensive SOP for: ${topic}
    
    Category: ${category}
    Reference IMAS standards: ${imasStandards.join(', ')}
    
    Ensure compliance with international mine action standards and include specific safety protocols.`;

    return await this.generateResponse([
      { role: 'user', content: prompt }
    ], systemPrompt);
  }

  async chatResponse(
    messages: ClaudeMessage[],
    userContext?: { role: string; recentDocuments?: any[] }
  ): Promise<string> {
    const systemPrompt = `You are an expert AI assistant specializing in humanitarian mine action operations. You help IM officers and program managers with:
    
    - Mine action standards (IMAS)
    - Risk assessment and analysis
    - Operational planning
    - Report generation
    - Safety protocols
    - Data interpretation
    - Equipment specifications
    - Training requirements
    
    User role: ${userContext?.role || 'USER'}
    
    Provide accurate, professional, and actionable advice based on international mine action best practices. Always prioritize safety and compliance with IMAS standards.`;

    return await this.generateResponse(messages, systemPrompt);
  }
}
```

### 4. Gestionnaire de base de données (src/services/database.ts)

```typescript
// src/services/database.ts
import type { Bindings } from '../types/bindings';

export class DatabaseService {
  constructor(private db: D1Database) {}

  // === USERS ===
  async createUser(data: {
    id: string;
    email: string;
    name?: string;
    role?: string;
    passwordHash: string;
  }) {
    return await this.db.prepare(`
      INSERT INTO users (id, email, name, role, password_hash)
      VALUES (?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.email,
      data.name || null,
      data.role || 'USER',
      data.passwordHash
    ).run();
  }

  async getUserByEmail(email: string) {
    return await this.db.prepare(`
      SELECT * FROM users WHERE email = ?
    `).bind(email).first();
  }

  async getUserById(id: string) {
    return await this.db.prepare(`
      SELECT id, email, name, role, created_at FROM users WHERE id = ?
    `).bind(id).first();
  }

  // === DOCUMENTS ===
  async createDocument(data: {
    id: string;
    title: string;
    content: string;
    type: string;
    fileUrl?: string;
    fileSize?: number;
    fileType?: string;
    extractedData?: any;
    userId: string;
  }) {
    return await this.db.prepare(`
      INSERT INTO documents (id, title, content, type, file_url, file_size, file_type, extracted_data, user_id)
      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.title,
      data.content,
      data.type,
      data.fileUrl || null,
      data.fileSize || null,
      data.fileType || null,
      JSON.stringify(data.extractedData || {}),
      data.userId
    ).run();
  }

  async updateDocumentStatus(id: string, status: string, extractedData?: any) {
    return await this.db.prepare(`
      UPDATE documents 
      SET status = ?, extracted_data = ?, updated_at = CURRENT_TIMESTAMP 
      WHERE id = ?
    `).bind(
      status,
      JSON.stringify(extractedData || {}),
      id
    ).run();
  }

  async getDocuments(userId: string, type?: string, limit = 50, offset = 0) {
    const query = type
      ? `SELECT * FROM documents WHERE user_id = ? AND type = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`
      : `SELECT * FROM documents WHERE user_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`;
    
    const params = type ? [userId, type, limit, offset] : [userId, limit, offset];
    
    const { results } = await this.db.prepare(query).bind(...params).all();
    
    return results.map(doc => ({
      ...doc,
      extractedData: JSON.parse(doc.extracted_data as string || '{}')
    }));
  }

  async getDocumentById(id: string, userId: string) {
    const result = await this.db.prepare(`
      SELECT * FROM documents WHERE id = ? AND user_id = ?
    `).bind(id, userId).first();

    if (result) {
      return {
        ...result,
        extractedData: JSON.parse(result.extracted_data as string || '{}')
      };
    }
    return null;
  }

  // === REPORTS ===
  async createReport(data: {
    id: string;
    title: string;
    content: string;
    type: string;
    metadata?: any;
    userId: string;
  }) {
    return await this.db.prepare(`
      INSERT INTO reports (id, title, content, type, metadata, user_id)
      VALUES (?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.title,
      data.content,
      data.type,
      JSON.stringify(data.metadata || {}),
      data.userId
    ).run();
  }

  async getReports(userId: string, type?: string, limit = 50, offset = 0) {
    const query = type
      ? `SELECT * FROM reports WHERE user_id = ? AND type = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`
      : `SELECT * FROM reports WHERE user_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`;
    
    const params = type ? [userId, type, limit, offset] : [userId, limit, offset];
    
    const { results } = await this.db.prepare(query).bind(...params).all();
    
    return results.map(report => ({
      ...report,
      metadata: JSON.parse(report.metadata as string || '{}')
    }));
  }

  // === RISK ASSESSMENTS ===
  async createRiskAssessment(data: {
    id: string;
    area: string;
    riskLevel: string;
    factors: any;
    predictions?: any;
    confidenceScore?: number;
    userId?: string;
  }) {
    return await this.db.prepare(`
      INSERT INTO risk_assessments (id, area, risk_level, factors, predictions, confidence_score, user_id)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.area,
      data.riskLevel,
      JSON.stringify(data.factors),
      JSON.stringify(data.predictions || {}),
      data.confidenceScore || null,
      data.userId || null
    ).run();
  }

  async getRiskAssessments(area?: string, limit = 50, offset = 0) {
    const query = area
      ? `SELECT * FROM risk_assessments WHERE area = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`
      : `SELECT * FROM risk_assessments ORDER BY created_at DESC LIMIT ? OFFSET ?`;
    
    const params = area ? [area, limit, offset] : [limit, offset];
    
    const { results } = await this.db.prepare(query).bind(...params).all();
    
    return results.map(assessment => ({
      ...assessment,
      factors: JSON.parse(assessment.factors as string || '{}'),
      predictions: JSON.parse(assessment.predictions as string || '{}')
    }));
  }

  // === CHATS ===
  async createOrUpdateChat(data: {
    id: string;
    title?: string;
    messages: any[];
    userId: string;
  }) {
    return await this.db.prepare(`
      INSERT OR REPLACE INTO chats (id, title, messages, user_id, updated_at)
      VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
    `).bind(
      data.id,
      data.title || null,
      JSON.stringify(data.messages),
      data.userId
    ).run();
  }

  async getChats(userId: string, limit = 20, offset = 0) {
    const { results } = await this.db.prepare(`
      SELECT id, title, created_at, updated_at FROM chats 
      WHERE user_id = ? 
      ORDER BY updated_at DESC 
      LIMIT ? OFFSET ?
    `).bind(userId, limit, offset).all();
    
    return results;
  }

  async getChatById(id: string, userId: string) {
    const result = await this.db.prepare(`
      SELECT * FROM chats WHERE id = ? AND user_id = ?
    `).bind(id, userId).first();

    if (result) {
      return {
        ...result,
        messages: JSON.parse(result.messages as string || '[]')
      };
    }
    return null;
  }

  // === SOPs ===
  async createSOP(data: {
    id: string;
    title: string;
    content: string;
    imasStandards: string[];
    category: string;
    version?: string;
    userId: string;
  }) {
    return await this.db.prepare(`
      INSERT INTO sops (id, title, content, imas_standards, category, version, user_id)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `).bind(
      data.id,
      data.title,
      data.content,
      JSON.stringify(data.imasStandards),
      data.category,
      data.version || '1.0',
      data.userId
    ).run();
  }

  async getSOPs(userId: string, category?: string, limit = 50, offset = 0) {
    const query = category
      ? `SELECT * FROM sops WHERE user_id = ? AND category = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`
      : `SELECT * FROM sops WHERE user_id = ? ORDER BY created_at DESC LIMIT ? OFFSET ?`;
    
    const params = category ? [userId, category, limit, offset] : [userId, limit, offset];
    
    const { results } = await this.db.prepare(query).bind(...params).all();
    
    return results.map(sop => ({
      ...sop,
      imasStandards: JSON.parse(sop.imas_standards as string || '[]')
    }));
  }

  // === ANALYTICS ===
  async getStatistics(userId: string) {
    const [documentsCount, reportsCount, riskAssessmentsCount, sopCount] = await Promise.all([
      this.db.prepare(`SELECT COUNT(*) as count FROM documents WHERE user_id = ?`).bind(userId).first(),
      this.db.prepare(`SELECT COUNT(*) as count FROM reports WHERE user_id = ?`).bind(userId).first(),
      this.db.prepare(`SELECT COUNT(*) as count FROM risk_assessments WHERE user_id = ?`).bind(userId).first(),
      this.db.prepare(`SELECT COUNT(*) as count FROM sops WHERE user_id = ?`).bind(userId).first(),
    ]);

    return {
      documentsProcessed: documentsCount?.count || 0,
      reportsGenerated: reportsCount?.count || 0,
      riskAssessments: riskAssessmentsCount?.count || 0,
      sopsCreated: sopCount?.count || 0,
    };
  }
}
```

### 5. Parseurs de documents (src/services/parsers.ts)

```typescript
// src/services/parsers.ts
import mammoth from 'mammoth';
import { parse as parseCSV } from 'papaparse';
import * as XLSX from 'xlsx';
import type { ParsedDocument } from '../types/bindings';

export class DocumentParser {
  async parseFile(file: File): Promise<ParsedDocument> {
    const buffer = await file.arrayBuffer();
    const uint8Array = new Uint8Array(buffer);
    
    try {
      switch (file.type) {
        case 'application/pdf':
          return await this.parsePDF(uint8Array);
        case 'application/vnd.openxmlformats-officedocument.wordprocessingml.document':
          return await this.parseWord(buffer);
        case 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet':
          return this.parseExcel(buffer);
        case 'text/csv':
          return this.parseCSV(uint8Array);
        case 'text/plain':
          return this.parseText(uint8Array);
        default:
          throw new Error(`Unsupported file type: ${file.type}`);
      }
    } catch (error) {
      console.error('Parse error:', error);
      return {
        raw: `Error parsing file: ${error.message}`,
        metadata: {
          extractedAt: new Date().toISOString(),
          error: error.message
        }
      };
    }
  }

  private async parsePDF(buffer: Uint8Array): Promise<ParsedDocument> {
    // Note: pdf-parse might not work directly in Workers
    // You might need to use a different PDF parsing approach
    // or implement a simpler text extraction method
    
    // Fallback implementation
    const decoder = new TextDecoder();
    const text = decoder.decode(buffer);
    
    // Simple PDF text extraction (very basic)
    const textMatch = text.match(/stream\s*(.*?)\s*endstream/gs);
    const extractedText = textMatch ? textMatch.join(' ') : 'PDF parsing not fully supported in Workers';
    
    return {
      raw: extractedText,
      metadata: {
        extractedAt: new Date().toISOString(),
        wordCount: extractedText.split(/\s+/).length
      }
    };
  }

  private async parseWord(buffer: ArrayBuffer): Promise<ParsedDocument> {
    try {
      const result = await mammoth.extractRawText({ arrayBuffer: buffer });
      
      return {
        raw: result.value,
        metadata: {
          extractedAt: new Date().toISOString(),
          wordCount: result.value.split(/\s+/).length
        }
      };
    } catch (error) {
      throw new Error(`Word parsing failed: ${error.message}`);
    }
  }

  private parseExcel(buffer: ArrayBuffer): ParsedDocument {
    try {
      const workbook = XLSX.read(buffer, { type: 'array' });
      let content = '';
      const sheets = [];
      
      workbook.SheetNames.forEach(sheetName => {
        const sheet = workbook.Sheets[sheetName];
        const csvData = XLSX.utils.sheet_to_csv(sheet);
        content += `\n\n=== Sheet: ${sheetName} ===\n${csvData}`;
        
        sheets.push({
          name: sheetName,
          data: XLSX.utils.sheet_to_json(sheet, { header: 1 })
        });
      });
      
      return {
        raw: content,
        structured: { sheets },
        metadata: {
          extractedAt: new Date().toISOString(),
          sheetCount: workbook.SheetNames.length
        }
      };
    } catch (error) {
      throw new Error(`Excel parsing failed: ${error.message}`);
    }
  }

  private parseCSV(buffer: Uint8Array): ParsedDocument {
    try {
      const decoder = new TextDecoder();
      const text = decoder.decode(buffer);
      
      const result = parseCSV(text, {
        header: true,
        skipEmptyLines: true,
        dynamicTyping: true
      });
      
      if (result.errors.length > 0) {
        console.warn('CSV parsing warnings:', result.errors);
      }
      
      return {
        raw: text,
        structured: {
          data: result.data,
          headers: result.meta.fields,
          rowCount: result.data.length
        },
        metadata: {
          extractedAt: new Date().toISOString(),
          rowCount: result.data.length,
          columnCount: result.meta.fields?.length || 0
        }
      };
    } catch (error) {
      throw new Error(`CSV parsing failed: ${error.message}`);
    }
  }

  private parseText(buffer: Uint8Array): ParsedDocument {
    const decoder = new TextDecoder();
    const text = decoder.decode(buffer);
    
    return {
      raw: text,
      metadata: {
        extractedAt: new Date().toISOString(),
        wordCount: text.split(/\s+/).length,
        lineCount: text.split('\n').length
      }
    };
  }
}
```

### 6. Middleware d'authentification (src/middleware/auth.ts)

```typescript
// src/middleware/auth.ts
import { createMiddleware } from 'hono/factory';
import { verify } from 'jose';
import type { Bindings, Variables } from '../types/bindings';

export const authMiddleware = createMiddleware<{
  Bindings: Bindings;
  Variables: Variables;
}>(async (c, next) => {
  const authorization = c.req.header('Authorization');
  
  if (!authorization || !authorization.startsWith('Bearer ')) {
    return c.json({ error: 'Unauthorized - Missing or invalid token' }, 401);
  }

  const token = authorization.slice(7); // Remove 'Bearer ' prefix
  
  try {
    const secret = new TextEncoder().encode(c.env.JWT_SECRET);
    const { payload } = await verify(token, secret);
    
    if (!payload.sub || !payload.email) {
      return c.json({ error: 'Unauthorized - Invalid token payload' }, 401);
    }

    // Set user in context
    c.set('user', {
      id: payload.sub as string,
      email: payload.email as string,
      role: payload.role as string || 'USER',
    });

    await next();
  } catch (error) {
    console.error('Auth error:', error);
    return c.json({ error: 'Unauthorized - Token verification failed' }, 401);
  }
});
```

### 7. Route documents (src/routes/documents.ts)

```typescript
// src/routes/documents.ts
import { Hono } from 'hono';
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';

import { ClaudeService } from '../services/claude';
import { DatabaseService } from '../services/database';
import { DocumentParser } from '../services/parsers';
import type { Bindings, Variables } from '../types/bindings';

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();

const uploadSchema = z.object({
  type: z.enum(['FIELD_REPORT', 'SURVEY_FORM', 'SOP_MANUAL', 'DONOR_REPORT', 'TRAINING_MATERIAL', 'HAZARD_SURVEY', 'INCIDENT_LOG']),
});

// Upload document
app.post('/upload', zValidator('form', uploadSchema), async (c) => {
  try {
    const formData = await c.req.formData();
    const file = formData.get('file') as File;
    const { type } = c.req.valid('form');
    const user = c.get('user');

    if (!file) {
      return c.json({ error: 'No file provided' }, 400);
    }

    // Validate file size (max 10MB)
    if (file.size > 10 * 1024 * 1024) {
      return c.json({ error: 'File too large. Maximum size is 10MB' }, 400);
    }

    const db = new DatabaseService(c.env.DB);
    const documentId = crypto.randomUUID();

    // Upload file to R2
    const fileKey = `documents/${user.id}/${documentId}/${file.name}`;
    await c.env.STORAGE.put(fileKey, file);
    const fileUrl = `https://your-r2-domain.com/${fileKey}`;

    // Parse document content
    const parser = new DocumentParser();
    const parsedContent = await parser.parseFile(file);

    // Create document record
    await db.createDocument({
      id: documentId,
      title: file.name,
      content: parsedContent.raw,
      type,
      fileUrl,
      fileSize: file.size,
      fileType: file.type,
      userId: user.id,
    });

    // Extract structured data using Claude in background
    const claudeService = new ClaudeService(c.env.ANTHROPIC_API_KEY);
    
    try {
      const extractedData = await claudeService.parseDocument(parsedContent.raw, type);
      await db.updateDocumentStatus(documentId, 'COMPLETED', {
        ...extractedData,
        parseMetadata: parsedContent.metadata
      });
    } catch (error) {
      console.error('Claude extraction error:', error);
      await db.updateDocumentStatus(documentId, 'FAILED', {
        error: 'AI extraction failed',
        parseMetadata: parsedContent.metadata
      });
    }

    return c.json({ 
      success: true,
      documentId,
      message: 'Document uploaded successfully. AI extraction in progress.' 
    });

  } catch (error) {
    console.error('Upload error:', error);
    return c.json({ error: 'Upload failed' }, 500);
  }
});

// Get documents
app.get('/', async (c) => {
  try {
    const user = c.get('user');
    const type = c.req.query('type');
    const limit = parseInt(c.req.query('limit') || '50');
    const offset = parseInt(c.req.query('offset') || '0');

    const db = new DatabaseService(c.env.DB);
    const documents = await db.getDocuments(user.id, type, limit, offset);
    
    return c.json({ documents });
  } catch (error) {
    console.error('Fetch documents error:', error);
    return c.json({ error: 'Failed to fetch documents' }, 500);
  }
});

// Get specific document
app.get('/:id', async (c) => {
  try {
    const user = c.get('user');
    const documentId = c.req.param('id');

    const db = new DatabaseService(c.env.DB);
    const document = await db.getDocumentById(documentId, user.id);
    
    if (!document) {
      return c.json({ error: 'Document not found' }, 404);
    }

    return c.json({ document });
  } catch (error) {
    console.error('Fetch document error:', error);
    return c.json({ error: 'Failed to fetch document' }, 500);
  }
});

// Delete document
app.delete('/:id', async (c) => {
  try {
    const user = c.get('user');
    const documentId = c.req.param('id');

    const db = new DatabaseService(c.env.DB);
    
    // Get document to check ownership and get file URL
    const document = await db.getDocumentById(documentId, user.id);
    if (!document) {
      return c.json({ error: 'Document not found' }, 404);
    }

    // Delete from R2 if file exists
    if (document.file_url) {
      const fileKey = document.file_url.split('/').slice(-3).join('/');
      await c.env.STORAGE.delete(fileKey);
    }

    // Delete from database
    await c.env.DB.prepare('DELETE FROM documents WHERE id = ? AND user_id = ?')
      .bind(documentId, user.id)
      .run();

    return c.json({ success: true, message: 'Document deleted successfully' });
  } catch (error) {
    console.error('Delete document error:', error);
    return c.json({ error: 'Failed to delete document' }, 500);
  }
});

export { app as documentRoutes };
```

## Commandes de déploiement Backend

### Développement local

```bash
# Installer les dépendances
npm install

# Créer la base de données D1 locale
npx wrangler d1 create mine-action-db
npx wrangler d1 execute mine-action-db --local --file=./schema.sql

# Créer le bucket R2
npx wrangler r2 bucket create mine-action-files

# Configurer les secrets
npx wrangler secret put ANTHROPIC_API_KEY

# Lancer le serveur de développement
npm run dev
```

### Déploiement production

```bash
# Déployer la base de données
npx wrangler d1 execute mine-action-db --file=./schema.sql

# Déployer l'application
npm run deploy

# Vérifier le déploiement
npx wrangler tail
```

### Scripts package.json

```json
{
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "db:migrate": "wrangler d1 execute mine-action-db --file=./schema.sql",
    "db:local": "wrangler d1 execute mine-action-db --local --file=./schema.sql",
    "type-check": "tsc --noEmit",
    "test": "vitest"
  }
}
```

## Fonctionnalités Backend Phase 1 implémentées

### ✅ API complète Hono.js
- Routes RESTful pour toutes les entités
- Middleware d'authentification JWT
- Validation des données avec Zod
- Gestion d'erreurs centralisée

### ✅ Service Claude AI intégré
- Parsing intelligent des documents
- Génération de rapports automatisée
- Évaluation de risques IA
- Assistant conversationnel spécialisé

### ✅ Stockage et base de données
- Cloudflare D1 pour les données structurées
- Cloudflare R2 pour les fichiers
- Migrations et schémas versionnés
- Index optimisés pour les performances

### ✅ Sécurité et conformité
- Authentification JWT sécurisée
- Validation stricte des entrées
- Audit trails complets
- CORS configuré correctement

Ce backend fournit une API robuste et performante pour alimenter votre frontend React Router, avec toutes les fonctionnalités Phase 1 du plan HumaniTech.