Migration Guide: Flat to Hierarchical Taxonomies¶

Tags: Medical, Receipt, Tax-Deductible
Document Type: Medical Receipt

Path: HealthManagement/MedicalCare/Consultations/MedicalReceipt
Tags: Function:HealthManagement, Service:MedicalCare, Activity:Consultations, DocumentType:MedicalReceipt
Storage Path: Health_Management/Medical_Care/Consultations/Medical_Receipt

# Docker deployment
docker exec paperless_db pg_dump -U paperless paperless > paperless_backup_$(date +%Y%m%d).sql

# Manual deployment
pg_dump -U paperless paperless > paperless_backup_$(date +%Y%m%d).sql

# Check current country setting
echo $MADEINOZ_RECORDMANAGER_COUNTRY

# Verify hierarchical taxonomy is available
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts taxonomy functions --domain household

# Export current document list
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search --domain household --query "*" > pre_migration_docs.txt

# Count documents by domain
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts stats --domain household

import { TaxonomyInstaller } from '~/src/lib/TaxonomyInstaller';
import { PaperlessClient } from '~/src/lib/PaperlessClient';

const client = new PaperlessClient(
  process.env.MADEINOZ_RECORDMANAGER_PAPERLESS_URL,
  process.env.MADEINOZ_RECORDMANAGER_PAPERLESS_API_TOKEN
);

const installer = new TaxonomyInstaller(
  client,
  'AUS',  // Your country code
  '/tmp/migration-logs'
);

// Load migration mappings
const mappings = await installer.loadMappingTable('household');
console.log(`Loaded ${mappings.length} migration mappings`);

// Check how many of your documents can be auto-mapped
const documents = await client.getDocuments();
const coverage = mappings.filter(m =>
  documents.some(d => d.document_type === m.flatDocumentType)
).length;

console.log(`Mapping coverage: ${coverage}/${documents.length} (${(coverage/documents.length*100).toFixed(1)}%)`);

// Migrate all documents in domain
const result = await installer.migrateAllDocuments();

console.log('Migration Results:');
console.log(`Total Documents: ${result.totalDocuments}`);
console.log(`Auto-Mapped: ${result.autoMapped}`);
console.log(`Manual Review Needed: ${result.manualReview}`);
console.log(`Failed: ${result.failed}`);

// View detailed migration log
result.mappingLog.forEach(entry => {
  console.log(`Doc ${entry.documentId}: ${entry.originalType} → ${entry.hierarchicalPath} (${entry.method})`);
});

Doc 1234: Medical Receipt → HealthManagement/MedicalCare/Consultations/MedicalReceipt (automatic)
Doc 1235: Tax Return → FinanceManagement/Taxation/Returns/TaxReturn (automatic)
Doc 1236: Utility Bill → PropertyManagement/Utilities/Bills/ElectricityBill (automatic)
Doc 1237: Unknown Type → null (manual)

const reviewDocs = await installer.getDocumentsForManualReview();

console.log(`${reviewDocs.length} documents need manual review`);

for (const doc of reviewDocs) {
  console.log(`\nDocument ${doc.id}: "${doc.title}"`);
  console.log(`Original type: ${doc.document_type}`);
  console.log(`Alternatives:`);
  doc.alternatives.forEach((alt, i) => {
    console.log(`  ${i + 1}. ${alt.path} (score: ${alt.score})`);
  });

  // Prompt user to select correct path
  const selection = await promptUser('Select path (1-N): ');
  const selectedPath = doc.alternatives[selection - 1].path;

  // Apply selected mapping
  await installer.applyManualMapping(doc.id, selectedPath);
}

// Verify all documents now have hierarchical paths
const unmapped = await installer.getUnmappedDocuments();
console.log(`Remaining unmapped: ${unmapped.length}`);

# Check all documents have hierarchical tags
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts migration verify --domain household

✓ Migration Verification Results:
  Total Documents: 1000
  With Hierarchical Tags: 1000 (100%)
  With Storage Paths: 1000 (100%)
  Missing Mappings: 0 (0%)

✓ All documents successfully migrated

// Sample 10 random migrated documents
const docs = await client.getDocuments();
const sample = docs.sort(() => Math.random() - 0.5).slice(0, 10);

for (const doc of sample) {
  console.log(`\nDocument ${doc.id}: ${doc.title}`);
  console.log(`Tags:`, doc.tags);
  console.log(`Custom Fields:`, doc.custom_fields);

  // Verify hierarchical tags exist
  const hasFunction = doc.tags.some(t => t.startsWith('Function:'));
  const hasService = doc.tags.some(t => t.startsWith('Service:'));
  const hasActivity = doc.tags.some(t => t.startsWith('Activity:'));
  const hasDocType = doc.tags.some(t => t.startsWith('DocumentType:'));

  if (hasFunction && hasService && hasActivity && hasDocType) {
    console.log('✓ Hierarchical tags present');
  } else {
    console.log('✗ Missing hierarchical tags');
  }
}

# Test hierarchical path search
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search \
  --domain household \
  --path "HealthManagement/MedicalCare/Consultations"

# Test tag search
bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search \
  --domain household \
  --tags "Function:HealthManagement"

const expert = new TaxonomyExpert('AUS', 'household');
const mode = expert.getTaxonomyMode();
console.log(`Current mode: ${mode}`);  // Should return 'hierarchical' or 'dual-mode'

// Legacy flat query (still works)
const flatResults = expert.getDocumentTypes('household');

// New hierarchical query (preferred)
const hierarchicalResults = expert.getFunctions('household');

docker-compose down  # or systemctl stop paperless

docker exec -i paperless_db psql -U paperless paperless < paperless_backup_20260122.sql

docker-compose up -d  # or systemctl start paperless

bun run ~/.claude/skills/RecordsManager/Tools/RecordManager.ts search --domain household --query "*" > post_rollback_docs.txt

diff pre_migration_docs.txt post_rollback_docs.txt