Plan → Implement → Verify Pattern

Planning session for CRM crate initialization.

Context:
- Multi-tenant SaaS platform
- Need CRM domain models (Account, Contact, Lead, Opportunity, etc.)
- Must integrate with existing event sourcing infrastructure
- DynamoDB single-table design

Explore the codebase to understand:
1. Existing domain model patterns
2. Event sourcing conventions
3. DynamoDB entity patterns
4. Repository trait patterns

Then design the CRM crate architecture with:
- Domain model structure
- Event integration strategy
- DynamoDB schema design
- Testing approach

Implement DynamoDbEntity derive macro per plan:
.plans/275-crm-initialization.md - Section 3.2

Requirements:
1. Parse struct fields to identify PK, SK, GSI keys
2. Generate impl blocks for DynamoDB attribute conversion
3. Support #[pii] attribute for sensitive fields
4. Follow existing macro patterns from eva-api-macros crate

Create comprehensive tests showing all attribute combinations.

Verify DynamoDB macro implementation for issue #284.

Read:
- Plan: .plans/275-crm-initialization.md - Section 3.2
- Implementation: git diff main...HEAD
- Tests: eva-dynamodb-derive/tests/

Check:
- Does macro handle all PK/SK/GSI patterns from plan?
- Are #[pii] attributes properly propagated?
- Edge cases: optional fields, nested structs, enums?
- Test coverage adequate?

Add API routes for all CRM entities per plan section 5.

Use existing #[eva_api] macro pattern from eva-auth crate.
Wire to handlers with proper permission checks.

Verify API integration for CRM entities.

Check:
- All routes follow RESTful conventions?
- Permissions match authorization design?
- Error handling consistent?
- OpenAPI specs generated correctly?

Create type-safe permission constants in eva-api-common crate.

Follow pattern:
pub const CRM_ACCOUNT_READ: &str = "crm.account.read";
pub const CRM_ACCOUNT_WRITE: &str = "crm.account.write";
...

Then refactor all routes to use constants instead of strings.

// ❌ WRONG - not atomic
pub async fn create_account(&self, account: Account) -> Result<()> {
    // Save to DynamoDB
    self.dynamodb_repo.save(&account).await?;

    // Emit event (might fail after save succeeds)
    self.event_store.append(AccountCreated { ... }).await?;

    Ok(())
}

// ✅ CORRECT - atomic with rollback
pub async fn create_account(&self, account: Account) -> Result<()> {
    // Phase 1: Append event first (source of truth)
    let event_id = self.event_store.append(AccountCreated {
        account_id: account.id,
        ...
    }).await?;

    // Phase 2: Save to DynamoDB with event reference
    let mut entity = AccountEntity::from(account);
    entity.last_event_id = event_id;

    match self.dynamodb_repo.save(&entity).await {
        Ok(_) => Ok(()),
        Err(e) => {
            // Rollback: mark event as failed
            self.event_store.mark_failed(event_id).await?;
            Err(e)
        }
    }
}

pub struct Contact {
    pub id: ContactId,
    pub email: Email,
    pub preferred_name: Option<String>, // ← NOT IN REQUIREMENTS
    ...
}

#[test]
fn test_account_name_validation() {
    let account = Account::new("", "tech");
    assert!(account.is_err()); // ✅ Test passes
}

#[test]
fn test_account_name_validation_per_prd_section_2_1() {
    // Too short
    assert!(Account::new("ab", "tech").is_err());

    // Too long
    assert!(Account::new(&"x".repeat(101), "tech").is_err());

    // Invalid characters
    assert!(Account::new("Acme Corp!", "tech").is_err());

    // Valid cases
    assert!(Account::new("Acme Corp", "tech").is_ok());
    assert!(Account::new("Acme-Corp", "tech").is_ok());
}

// Account
pub struct Account {
    pub id: AccountId(Uuid),  // Format: UUID v4
    ...
}

// Opportunity (WRONG)
pub struct Opportunity {
    pub account_id: String,  // Format: String "ACC-{ulid}"
    ...
}

// Generic domain model with PII and event sourcing
#[derive(DynamoDbEntity, Debug, Clone)]
#[table_name = "platform_data"]
#[pk = "TENANT#{tenant_id}#CONTACT#{id}"]
#[sk = "METADATA"]
pub struct ContactEntity {
    pub id: ContactId,
    pub tenant_id: TenantId,

    #[pii(category = "email")]
    pub email: String,

    #[pii(category = "name")]
    pub first_name: String,

    #[pii(category = "name")]
    pub last_name: String,

    pub phone: Option<String>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,

    // Event sourcing metadata
    pub version: u64,
    pub last_event_id: Option<EventId>,
}

// Macro generates:
// - to_item() / from_item() for DynamoDB conversion
// - Partition key / Sort key builders
// - GSI key builders
// - PII encryption hooks