# Data Directory Migration Guide

This migration unifies the user data directory structure from a fragmented layout to a consistent nested format.

## Before (Old Structure)

```
data/
├── files/
│   └── alice/              # WebDAV files
│       └── documents/
│           └── file.txt
├── alice/
│   ├── cal-personal/       # CalDAV calendar
│   │   └── event1.ics
│   └── card-contacts/      # CardDAV address book
│       └── contact1.vcf
└── bob/
    ├── cal-work/
    │   └── meeting.ics
    └── card-addressbook/
        └── address.vcf
```

## After (New Unified Structure)

```
data/
├── alice/
│   ├── files/              # WebDAV files
│   │   └── documents/
│   │       └── file.txt
│   ├── calendars/          # CalDAV calendars
│   │   └── personal/
│   │       └── event1.ics
│   └── addressbooks/       # CardDAV address books
│       └── contacts/
│           └── contact1.vcf
└── bob/
    ├── files/
    ├── calendars/
    │   └── work/
    └── addressbooks/
        └── addressbook/
```

## Migration Details

### What Changed

1. **WebDAV files**: `data/files/<username>/` → `data/<username>/files/`
2. **CalDAV calendars**: `data/<username>/cal-<name>/` → `data/<username>/calendars/<name>/`
3. **CardDAV address books**: `data/<username>/card-<name>/` → `data/<username>/addressbooks/<name>/`

### Migration Tool

A migration tool is provided that automatically restructures the data directory. It is **idempotent** and can be run multiple times safely.

#### Using nidusctl (Recommended)

```bash
go run ./tools/nidusctl -config config.yaml migrate
```

#### Using standalone migrate tool

```bash
go run ./tools/migrate -config config.yaml
```

#### Verbose output

```bash
go run ./tools/nidusctl -config config.yaml migrate --verbose
```

### What the Migration Does

1. For each user directory in the data directory:
   - Creates `<username>/` if it doesn't exist
   - Moves `files/<username>/` → `<username>/files/` (if exists)
   - Moves `cal-<name>/` → `<username>/calendars/<name>/`
   - Moves `card-<name>/` → `<username>/addressbooks/<name>/`

2. The old `files/` directory is left in place (can be manually removed after verification)

### Backward Compatibility

The migration is **fully backward compatible**:
- The migration tool handles both old and new structures
- If files are already in the new location, they are not moved
- Running migration multiple times is safe (idempotent)

### Server Integration

The server automatically runs migration on startup (if enabled in config). No manual migration is required for new installations.

### Testing

After migration, verify:

```bash
# Check data structure
ls -la data/

# Run tests
go test ./...

# Start server to verify WebDAV, CalDAV, CardDAV work correctly
go run ./cmd/server -config config.yaml
```

### Manual Verification

After migration, you should see:

```bash
$ ls -la data/alice/
calendars/
addressbooks/
files/
```

Each calendar should be in `data/<user>/calendars/<name>/` format, not `cal-<name>/`.

### Rollback (if needed)

If you need to rollback:
1. Stop the server
2. Restore the data directory from backup
3. Re-run the migration after fixing any issues

### Common Issues

**Q: Migration reports "directory already exists" warnings**
A: These are normal if files were already migrated. The migration is idempotent.

**Q: Old `files/` directory still exists**
A: This is expected. You can manually remove it after verifying migration success.

**Q: Some calendars/address books not visible after migration**
A: Check the migration logs and verify directory structure. Run `find data/ -type d -name "cal-*"` to find unmigrated calendars.

### Support

If you encounter issues:
1. Check logs for detailed error messages
2. Run migration with `--verbose` flag
3. Ensure no server processes are running during migration
4. Make backup before migrating in production