# Data Directory Structure Unification - Summary of Changes

## Overview
This change unifies the user data directory structure from a fragmented layout (with separate top-level `files/` directory) to a consistent nested format under each user's directory.

## Problem Statement

**Before**: Inconsistent directory structure
- WebDAV: `data/files/<username>/`
- CalDAV: `data/<username>/cal-<name>/`
- CardDAV: `data/<username>/card-<name>/`

**After**: Unified structure
- All data: `data/<username>/{files,calendars,addressbooks}/<name>/`

**Benefits**:
1. All user data in a single predictable location
2. Easier backups (single user directory instead of multiple paths)
3. Cleaner directory structure
4. Reduced code complexity in path resolution

## Implementation Details

### Files Modified

1. **`internal/store/store.go`**
   - Updated `collectionPath()` to map collection names to new unified structure:
     - `cal-<name>` → `<username>/calendars/<name>`
     - `card-<name>` → `<username>/addressbooks/<name>`
     - `files` → `<username>/files`
   - Kept `sanitize()` for security

2. **`internal/store/migrate.go`** (new file)
   - Added `Migrate()` method to restructure data directory
   - Idempotent migration that handles both old and new structures
   - Migrates WebDAV, CalDAV, and CardDAV data atomically

3. **`internal/store/migrate_test.go`** (new file)
   - Comprehensive tests for migration functionality
   - Covers migration, idempotency, and edge cases

4. **`internal/webdav/handler.go`**
   - Updated WebDAV handler to use new unified path structure
   - Changed from `dataDir/files/<username>` to `dataDir/<username>/files`

5. **`internal/webdav/handler_test.go`**
   - Updated test assertions to check new path structure
   - Changed from `dataDir/files/alice/` to `dataDir/alice/files/`

6. **`cmd/server/main.go`**
   - Added automatic migration on server startup
   - Ensures data directory is always in correct format

7. **`tools/migrate/main.go`** (new file)
   - Standalone migration tool
   - Can be run independently of server

8. **`tools/nidusctl/main.go`**
   - Added `migrate` subcommand
   - Integrated into existing admin CLI

### Path Mapping

| Old Path | New Path | Collection Type |
|----------|----------|-----------------|
| `files/<user>/<name>` | `<user>/files/<name>` | WebDAV |
| `<user>/cal-<name>/` | `<user>/calendars/<name>/` | CalDAV |
| `<user>/card-<name>/` | `<user>/addressbooks/<name>/` | CardDAV |

## Testing

All existing tests pass with the new structure:
- ✅ Store tests (path resolution, locking)
- ✅ CalDAV backend tests
- ✅ CardDAV backend tests
- ✅ WebDAV handler tests
- ✅ Web UI tests
- ✅ DB tests
- ✅ Migration tests (new)

Run tests:
```bash
go test ./... -v
go test ./internal/store/... -run TestMigrate -v
```

## Migration Process

### For Existing Installations

1. **Stop the server** (optional but recommended)
   ```bash
   # Stop any running server
   ```

2. **Run migration**
   ```bash
   go run ./tools/nidusctl -config config.yaml migrate
   ```

3. **Verify migration**
   ```bash
   ls -la data/
   # Should see user directories with unified structure
   ```

4. **Start the server**
   ```bash
   go run ./cmd/server -config config.yaml
   ```

### For New Deployments

No migration needed - the new structure is used by default:
- Server creates `<username>/files/`, `<username>/calendars/`, etc.
- All data follows the unified structure from the start

## API Compatibility

**URL structure remains unchanged**:
- CalDAV: `/cal/`, `/cal/home/<name>/`, `/cal/home/<name>/<object>`
- CardDAV: `/card/`, `/card/home/<name>/`, `/card/home/<name>/<object>`
- WebDAV: `/files/`

Only the **on-disk path structure** changed. All HTTP endpoints and URL paths remain identical.

## Security

- Path sanitization maintained via `sanitize()` function
- No security-sensitive code changed
- Locking mechanism unchanged (still per-user)
- All same security checks apply

## Performance

No measurable performance impact:
- Same number of filesystem operations
- Same lock granularity (per-user)
- Same cache behavior

## Rollback

If rollback is needed:
1. Restore data directory from backup
2. Restart server (will migrate again on next startup)

## Future Considerations

This unified structure makes future enhancements easier:
- Easier to add per-user quotas
- Simpler backup/restore logic
- Better support for user-specific configuration
- Cleaner codebase with consistent patterns

## Documentation Updates

- `MIGRATION.md` - Detailed migration guide
- `CHANGES_SUMMARY.md` - This file
- Code comments updated to reflect new structure