Aller au contenu principal

Client Document Management System - Brownfield User Story

Story Overview​

Epic: Client Management Enhancement
Story: Story 1 - Client Document Management System
Story Type: Enhancement (Brownfield)
Priority: High
Estimated Effort: 5 story points

User Story​

As a client manager
I want to manage client documents with upload/download capabilities, validation tracking, and status integration
So that I can efficiently handle client documentation requirements while maintaining compliance and audit trails

Context & Integration​

Current System Integration Points:

  • Extends existing ClientService (/Users/ayoub/projects/emtb/apps/api/src/client/client.service.ts)
  • Leverages existing Client Prisma model with convention/mandat fields
  • Integrates with existing status workflow (EN_ATTENTE_DOCUMENTS)
  • Maintains compatibility with existing Client-Contact-Site-ApporteurAffaire relationships

Existing Functionality to Preserve:

  • All CRUD operations (GET /clients, POST /clients, PATCH /clients/:id, DELETE /clients/:id)
  • Reference generation (generateReference() method)
  • Client statistics endpoint (GET /clients/stats)
  • Client lookup by reference (GET /clients/reference/:reference)
  • Status update functionality (PATCH /clients/:id/status)
  • Relationship loading (contact, apporteursAffaires, sites, facturesPartenaires, users)

Acceptance Criteria​

AC1: Document Upload & Management​

Given I am a client manager
When I upload documents for a client
Then the system should:

  • Accept PDF, DOC, DOCX, JPG, PNG file formats
  • Store documents securely with proper file naming convention
  • Update client record with document paths
  • Generate document metadata (filename, size, upload date, uploaded by)
  • Validate file types and size limits (max 10MB per file)

AC2: Document Categories & Validation​

Given a client requires specific documents
When I manage client documents
Then the system should:

  • Support document categories: Convention, Mandat, Identity, Financial, Legal, Other
  • Track document validation status (PENDING, VALIDATED, REJECTED, EXPIRED)
  • Allow document version management with history tracking
  • Automatically update client status to EN_ATTENTE_DOCUMENTS when required docs are missing
  • Provide document requirement checklist based on client type

AC3: Document Access & Download​

Given documents are uploaded for a client
When I need to access client documents
Then the system should:

  • Provide secure download links with proper authorization
  • Display document preview when possible
  • Show document metadata (size, upload date, validation status)
  • Log all document access attempts for audit purposes
  • Support bulk download of all client documents as ZIP archive

AC4: Integration with Client Status Workflow​

Given the existing client status system
When document operations occur
Then the system should:

  • Automatically update client status based on document completeness
  • Maintain existing status enum values (ACTIF, EN_ATTENTE_DOCUMENTS, ARCHIVE)
  • Preserve existing status update API (PATCH /clients/:id/status)
  • Trigger status change notifications when documents are validated
  • Update client statistics to reflect document-based status changes

AC5: Evolution Tracking & Audit Trail​

Given document management operations
When any document action occurs
Then the system should:

  • Log all document uploads, deletions, validations, and downloads
  • Track user responsible for each action with timestamp
  • Maintain document version history with change reasons
  • Provide audit report generation for compliance
  • Store audit data in separate audit table for performance

AC6: Backward Compatibility​

Given existing client functionality
When the document management system is implemented
Then it should:

  • Maintain all existing API endpoints without breaking changes
  • Preserve existing client creation/update workflows
  • Keep existing convention/mandat field functionality
  • Maintain performance of existing queries with proper indexing
  • Support existing Swagger documentation patterns

Technical Requirements​

Database Schema Changes (Additive Only)​

-- New document table
CREATE TABLE client_documents (
  id SERIAL PRIMARY KEY,
  client_id INTEGER NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
  category VARCHAR(50) NOT NULL, -- Convention, Mandat, Identity, Financial, Legal, Other
  filename VARCHAR(255) NOT NULL,
  original_filename VARCHAR(255) NOT NULL,
  file_path VARCHAR(500) NOT NULL,
  file_size BIGINT NOT NULL,
  mime_type VARCHAR(100) NOT NULL,
  validation_status VARCHAR(20) NOT NULL DEFAULT 'PENDING', -- PENDING, VALIDATED, REJECTED, EXPIRED
  version INTEGER NOT NULL DEFAULT 1,
  uploaded_by INTEGER REFERENCES users(id),
  uploaded_at TIMESTAMP DEFAULT NOW(),
  validated_by INTEGER REFERENCES users(id),
  validated_at TIMESTAMP,
  validation_notes TEXT,
  expires_at TIMESTAMP,
  is_required BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Document audit trail
CREATE TABLE client_document_audit (
  id SERIAL PRIMARY KEY,
  document_id INTEGER REFERENCES client_documents(id) ON DELETE CASCADE,
  action VARCHAR(50) NOT NULL, -- UPLOAD, DOWNLOAD, VALIDATE, REJECT, DELETE, UPDATE
  performed_by INTEGER REFERENCES users(id),
  performed_at TIMESTAMP DEFAULT NOW(),
  details JSONB,
  ip_address INET,
  user_agent TEXT
);

-- Indexes for performance
CREATE INDEX idx_client_documents_client_id ON client_documents(client_id);
CREATE INDEX idx_client_documents_category ON client_documents(category);
CREATE INDEX idx_client_documents_validation_status ON client_documents(validation_status);
CREATE INDEX idx_client_document_audit_document_id ON client_document_audit(document_id);
CREATE INDEX idx_client_document_audit_performed_at ON client_document_audit(performed_at);

New API Endpoints (Additive)​

// Document management endpoints
POST /clients/:id/documents - Upload document
GET /clients/:id/documents - List client documents
GET /clients/:id/documents/:documentId - Get document details
GET /clients/:id/documents/:documentId/download - Download document
PUT /clients/:id/documents/:documentId/validate - Validate document
DELETE /clients/:id/documents/:documentId - Delete document
GET /clients/:id/documents/audit - Get document audit trail
POST /clients/:id/documents/bulk-download - Download all documents as ZIP

// Document validation endpoints
GET /clients/:id/documents/requirements - Get document requirements checklist
POST /clients/:id/documents/validate-all - Validate all pending documents
GET /clients/:id/documents/status - Get document completeness status

Service Extensions​

// Add to existing ClientService
class ClientService {
  // ... existing methods preserved ...
  
  // New document methods
  async uploadDocument(clientId: number, file: Express.Multer.File, category: string, uploadedBy: number): Promise<ClientDocument>
  async getClientDocuments(clientId: number): Promise<ClientDocument[]>
  async downloadDocument(documentId: number): Promise<{ buffer: Buffer, filename: string, mimeType: string }>
  async validateDocument(documentId: number, validatedBy: number, notes?: string): Promise<ClientDocument>
  async deleteDocument(documentId: number, deletedBy: number): Promise<void>
  async getDocumentRequirements(clientId: number): Promise<DocumentRequirement[]>
  async checkDocumentCompleteness(clientId: number): Promise<{ isComplete: boolean, missingDocs: string[] }>
  async getDocumentAuditTrail(clientId: number): Promise<DocumentAudit[]>
  
  // Enhanced status method to consider documents
  async updateStatusWithDocumentCheck(id: number, status: ClientStatus): Promise<Client>
}

File Storage Configuration​

  • Storage location: /uploads/clients/{clientId}/documents/
  • Naming convention: {category}_{timestamp}_{originalName}
  • Security: Files stored outside web root with secure access tokens
  • Backup: Daily backup of document storage with retention policy

Test Automation Requirements​

Unit Tests​

describe('ClientDocumentService', () => {
  // Document upload tests
  it('should upload document and update client record')
  it('should validate file type and size limits')
  it('should generate proper file paths and names')
  it('should create audit trail entry on upload')
  
  // Document validation tests
  it('should validate document and update status')
  it('should update client status when all required docs are validated')
  it('should handle document rejection with notes')
  
  // Integration tests
  it('should preserve existing client functionality after document features')
  it('should maintain client statistics accuracy')
  it('should keep existing API endpoints working')
})

Integration Tests​

describe('Client Document API Integration', () => {
  // Upload/Download flow
  it('should upload, validate, and download documents successfully')
  it('should handle concurrent document operations safely')
  it('should maintain transaction integrity during bulk operations')
  
  // Status integration
  it('should automatically update client status based on document completeness')
  it('should preserve existing status update functionality')
  it('should maintain client-site-apporteur relationships')
  
  // Audit trail
  it('should log all document operations with proper user tracking')
  it('should generate complete audit reports')
})

End-to-End Tests​

describe('Client Document Management E2E', () => {
  it('should complete full client onboarding with document upload')
  it('should handle document validation workflow from upload to approval')
  it('should maintain client status consistency throughout document lifecycle')
  it('should preserve existing client management workflows')
})

Performance Tests​

describe('Document Performance', () => {
  it('should handle multiple file uploads without performance degradation')
  it('should maintain existing client query performance')
  it('should efficiently serve document downloads')
  it('should handle large audit trail queries with pagination')
})

Regression Tests​

describe('Backward Compatibility', () => {
  it('should preserve all existing client CRUD operations')
  it('should maintain existing API response formats')
  it('should keep client statistics calculation unchanged')
  it('should preserve client-contact-site relationship loading')
})

Change Tracking & Evolution​

Version History​

  • v1.0.0: Initial document management implementation
  • Track all schema changes with migration versioning
  • Document API version compatibility matrix

Monitoring & Metrics​

// Key metrics to track
interface DocumentMetrics {
  documentsUploaded: number;
  validationRate: number;
  averageValidationTime: number;
  storageUtilization: number;
  downloadFrequency: number;
  auditTrailSize: number;
}

Configuration Management​

// Document management configuration
interface DocumentConfig {
  maxFileSize: number; // 10MB default
  allowedMimeTypes: string[];
  storageLocation: string;
  retentionPeriod: number; // days
  auditRetention: number; // days
  enableVersioning: boolean;
}

Definition of Done​

Functional Requirements​

  • All document upload/download operations working correctly
  • Document validation workflow integrated with client status
  • Audit trail capturing all document operations
  • Document requirements checklist functional
  • Bulk operations (download, validation) implemented

Technical Requirements​

  • Database migrations applied and tested
  • New API endpoints documented in Swagger
  • File storage security implemented with proper access controls
  • Audit logging configured and tested

Quality Assurance​

  • Unit test coverage ≥ 90% for new document functionality
  • Integration tests verify document-status workflow
  • Performance tests confirm no degradation in existing operations
  • Security audit passed for file upload/download mechanisms

Compatibility Verification​

  • All existing client API endpoints return same response format
  • Client creation/update workflows unchanged
  • Client statistics calculation includes document-based status
  • Existing client-site-apporteur-facture relationships preserved
  • Reference generation and lookup functionality intact

Documentation​

  • API documentation updated in Swagger
  • Technical documentation for document storage architecture
  • Audit trail reporting documentation
  • Configuration guide for document management settings

Risk Mitigation​

Primary Risks & Mitigations​

  1. File Storage Security Risk

    • Mitigation: Implement secure file access tokens, virus scanning, proper file permissions

  2. Performance Impact on Existing Operations

    • Mitigation: Efficient indexing, lazy loading of documents, separate audit table

  3. Breaking Existing Client Workflows

    • Mitigation: Additive-only changes, comprehensive regression testing, feature flags

Rollback Strategy​

  • Database migrations are reversible
  • New endpoints can be disabled via feature flags
  • Document storage can be isolated without affecting client core functionality
  • Existing client operations remain fully functional during rollback

Dependencies​

Internal Dependencies​

  • Existing Client module structure maintained
  • User authentication system for document access control
  • File upload middleware configuration
  • Audit logging infrastructure

External Dependencies​

  • File storage system (local filesystem or cloud storage)
  • Virus scanning service for uploaded documents
  • PDF preview generation library (optional)
  • ZIP archive generation library for bulk downloads

Story Status: Ready for Implementation
Last Updated: 2025-09-09
Reviewed By: Technical Lead
Approved By: Product Owner