# Template Functional Requirements Document

> **Usage:** Template for 3-functional-specification.md
> **Loaded in:** step-03-specify.md

---

```markdown
# Specification fonctionnelle - {FEAT-XXX} {Feature Name}

> **Module:** business/{application}/{module}
> **Version:** 1.0
> **Based on:** 2-brd.md v1.0
> **Permission path:** {application}.{module}.*

## 1. Overview

### 1.1 Functional Objective
{Description of what the system must do}

### 1.2 Actors

| Actor | Description | Required Permissions |
|--------|-------------|---------------------|
| {Role} | {description} | `{app}.{module}.{action}` |

## 2. Use Cases

### UC-001: {Use Case Name}

| Attribute | Value |
|----------|--------|
| **ID** | UC-001 |
| **Name** | {Name} |
| **Primary Actor** | {Role} |
| **Preconditions** | {required conditions} |
| **Postconditions** | {final state} |
| **Permission** | `{app}.{module}.{action}` |

**Main Scenario:**
1. The user {action}
2. The system {response}
3. The user {action}
4. The system {response}

**Alternative Scenarios:**

| # | Condition | Steps |
|---|-----------|-------|
| 3a | {condition} | 3a.1 {action}, 3a.2 {action} |

**Error Scenarios:**

| # | Error | Message | Action |
|---|-------|---------|--------|
| E1 | {error} | {user message} | {behavior} |

## 3. Functional Requirements

| ID | Requirement | Related UC | Priority |
|----|-------------|------------|----------|
| FR-001 | {The system MUST...} | UC-001 | Must |
| FR-002 | {The system SHOULD...} | UC-001 | Should |

### 3.1 Detail FR-001

**Statement:** The system MUST {specific action}

**Acceptance Criteria:**
- [ ] {Measurable criterion 1}
- [ ] {Measurable criterion 2}

**Associated Rules:** BR-001, BR-002

## 4. User Interface

### 4.1 Wireframe - Main Screen

```
┌─────────────────────────────────────────────────────────────┐
│  [Logo]    {Module Name}                      [User] [Menu] │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐   │
│  │ FILTER                                               │   │
│  │ [Field 1 ▼] [Field 2 ▼] [Search]                   │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ TABLE                                                │   │
│  │ ┌────────┬────────┬────────┬─────────┐              │   │
│  │ │ Col 1  │ Col 2  │ Col 3  │ Actions │              │   │
│  │ ├────────┼────────┼────────┼─────────┤              │   │
│  │ │ data   │ data   │ data   │ [E] [D] │              │   │
│  │ └────────┴────────┴────────┴─────────┘              │   │
│  └─────────────────────────────────────────────────────┘   │
│  [+ New]                                 [< Prev] [Next >]  │
└─────────────────────────────────────────────────────────────┘
```

### 4.2 UI Element Description

| Element | Type | Behavior | Permission |
|---------|------|----------|------------|
| [+ New] | Button | Navigates to `/create` page | `{module}.create` |
| [E] | Icon | Navigates to `/:id/edit` page | `{module}.update` |
| [D] | Icon | Confirmation + delete | `{module}.delete` |

## 5. Validation and Messages

### 5.1 Validations

| Field | Rule | Error Message |
|-------|------|----------------|
| {field} | {validation rule} | {message i18n key} |

### 5.2 System Messages

| Code | Type | Message (i18n key) |
|------|------|-------------------|
| MSG-001 | Success | `{module}.messages.created` |
| MSG-002 | Error | `{module}.errors.notFound` |

## 6. Detailed Permissions

### 6.1 Role-Permission Matrix

| Permission | Admin | Manager | User | ReadOnly |
|------------|-------|---------|------|----------|
| `{app}.{module}.read` | ✅ | ✅ | ✅ | ✅ |
| `{app}.{module}.create` | ✅ | ✅ | ❌ | ❌ |
| `{app}.{module}.update` | ✅ | ✅ | ❌ | ❌ |
| `{app}.{module}.delete` | ✅ | ❌ | ❌ | ❌ |

### 6.2 Endpoint-Permission Mapping

| Endpoint | Method | Required Permission |
|----------|--------|-------------------|
| `/api/{module}` | GET | `{module}.read` |
| `/api/{module}` | POST | `{module}.create` |
| `/api/{module}/{id}` | PUT | `{module}.update` |
| `/api/{module}/{id}` | DELETE | `{module}.delete` |

## 7. Gherkin Scenarios

```gherkin
Feature: {FEAT-XXX} {Feature Name}

  @permission @403
  Scenario: User without permission cannot create
    Given I am logged in as "user@test.com" with role "ReadOnly"
    When I send POST to "/api/{module}"
    Then the response status should be 403

  @happy-path
  Scenario: Admin creates new item
    Given I am logged in as "admin@test.com" with role "Admin"
    When I send POST to "/api/{module}" with:
      | field1 | value1 |
    Then the response status should be 201
```

---

## Version History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | {date} | BA | Initial creation |
```
