newspaper_wedding/.aidlc/knowledge/aidlc-product-agent/functional-design-guide.md

# Functional Design Guide

## Business Logic Modeling

### Logic Decomposition Approach
Break complex business logic into composable layers:

1. **Input Validation Layer**: Verify data format, ranges, required fields
2. **Business Rule Layer**: Apply domain rules, constraints, and calculations
3. **State Transition Layer**: Manage entity lifecycle and valid state changes
4. **Side Effect Layer**: Trigger notifications, audit logs, integrations

### Business Rule Specification Format
For each rule, document (the `BR{group}.{seq}` ID format the traceability sensor recognizes, e.g. `BR1.1`):
```
Rule ID: BRx.y
Name: [descriptive name]
Trigger: [when this rule is evaluated]
Condition: [the logical expression]
Action: [what happens when condition is true]
Exception: [what happens when condition is false or invalid]
Priority: [execution order when multiple rules apply]
Source: [requirement ID or stakeholder that defined this rule]
```

### Rule Conflict Resolution
When multiple rules apply to the same operation:
- **Priority ordering**: Higher-priority rules execute first
- **First-match wins**: Stop evaluating after the first matching rule
- **All-match accumulate**: Apply all matching rules (must be non-contradictory)
- Always document the chosen strategy per rule group

## Domain Entity Design

### Entity Identification Checklist
An entity should be modeled when:
- It has a unique identity that persists over time
- It has a lifecycle with distinct states
- Multiple parts of the system reference it
- It has business rules governing its behavior
- It participates in relationships with other entities

### Entity Specification Template

| Attribute | Type | Required | Constraints | Default | Notes |
|-----------|------|----------|-------------|---------|-------|
| id | UUID | Yes | System-generated | Auto | Primary identifier |
| status | Enum | Yes | [valid values] | Initial | See state machine |
| ... | ... | ... | ... | ... | ... |

### Relationship Types and Design Rules
- **One-to-One**: Embed or separate based on access patterns (always queried together = embed)
- **One-to-Many**: Parent owns the collection; child references parent by ID
- **Many-to-Many**: Use a junction entity with its own attributes (timestamps, status)
- Always define cascade behavior: what happens to children when parent is deleted?
- Document referential integrity constraints explicitly

## Business Rule Specification Patterns

### Calculation Rules
For computed values, specify:
- **Formula**: The calculation expression with variable definitions
- **Precision**: Rounding rules, decimal places, currency handling
- **Edge cases**: Division by zero, overflow, null inputs
- **Examples**: At least 3 worked examples with inputs and expected output

### Validation Rules
For each input field:
| Field | Type | Required | Min | Max | Pattern | Custom Rule |
|-------|------|----------|-----|-----|---------|-------------|
| email | string | Yes | 5 | 254 | RFC 5322 | Must be unique |
| amount | decimal | Yes | 0.01 | 999999.99 | 2 decimal places | Must not exceed account balance |

### Authorization Rules
Document access control per operation:
```
Operation: [Create/Read/Update/Delete] [Entity]
Allowed Roles: [role list]
Additional Conditions: [ownership check, status check, time window]
Denied Response: [error code and message]
Audit: [whether to log access attempts]
```

## Workflow Design Methodology

### Workflow Specification Template
For each business workflow:

1. **Trigger**: What initiates the workflow (user action, scheduled event, external signal)
2. **Preconditions**: What must be true before the workflow can start
3. **Steps**: Ordered list of actions with decision points
4. **Actors**: Who or what performs each step (user, system, external service)
5. **Postconditions**: What must be true when the workflow completes successfully
6. **Error Paths**: What happens when each step fails
7. **Timeout Behavior**: What happens if the workflow stalls at any step

### State Machine Design
For entities with complex lifecycles:

| Current State | Event | Guard Condition | Next State | Actions |
|--------------|-------|-----------------|------------|---------|
| Draft | Submit | All required fields populated | Pending Review | Notify reviewer, log event |
| Pending Review | Approve | Reviewer has authority | Approved | Notify submitter, update timestamps |
| Pending Review | Reject | Rejection reason provided | Draft | Notify submitter with reason |
| Approved | Activate | Start date reached | Active | Enable functionality |
| Active | Expire | End date reached | Expired | Disable functionality, notify owner |
| Any | Cancel | Cancellation policy met | Cancelled | Notify stakeholders, release resources |

### State Machine Validation Rules
- Every state must be reachable from the initial state
- Every non-terminal state must have at least one outgoing transition
- Terminal states (Cancelled, Expired, Completed) have no outgoing transitions
- No implicit transitions -- every state change requires an explicit event
- Guard conditions must be testable (no subjective criteria)

## Functional Design Document Structure

Organize each functional design specification as:
1. **Overview**: Purpose and scope of the function
2. **Entities**: Data model with attributes and relationships
3. **Business Rules**: Complete rule set with priorities
4. **Workflows**: Step-by-step processes with decision points
5. **State Machines**: Lifecycle diagrams for stateful entities
6. **Interfaces**: Input/output specifications for each operation
7. **Validation**: Field-level and cross-field validation rules
8. **Error Catalog**: All error conditions with codes and messages
9. **Traceability**: Mapping back to requirements (FR-NNN references)