# Templates Specification - Business Analysis

> **Usage:** Templates for functional specification documents
> **Context:** Business > Application > Module > Section

---

## Template 1-discovery.md

```markdown
# Discovery - {FEAT-XXX} {Feature Name}

> **Module:** business/{application}/{module}
> **Version:** 1.0
> **Date:** {YYYY-MM-DD}
> **Author:** Business Analyst

## 1. Business Context

### 1.1 Need Description
{Clear description of the business need expressed by the stakeholder}

### 1.2 Current Problem
{Current situation and its limitations}

### 1.3 Expected Value
{Measurable business benefits}

## 2. Stakeholders

| Role | Name/Function | Involvement | Decision Level |
|------|--------------|-------------|-----------------|
| Sponsor | {name} | {description} | Approver |
| Product Owner | {name} | {description} | Decision Maker |
| Key User | {name} | {description} | Consulted |

## 3. Scope

### 3.1 In Scope
- [ ] {Included feature 1}
- [ ] {Included feature 2}

### 3.2 Out of Scope
- {Explicit exclusion 1}
- {Explicit exclusion 2}

## 4. Open Questions

| # | Question | Answer | Status |
|---|----------|---------|--------|
| Q1 | {Question} | {Answer or "Pending"} | ⏳/✅ |

## 5. Identified Constraints

| Type | Constraint | Impact |
|------|------------|--------|
| Technical | {constraint} | {impact} |
| Budget | {constraint} | {impact} |
| Schedule | {constraint} | {impact} |
| Regulatory | {constraint} | {impact} |

## 6. Dependencies

| Dependency | Type | Module/System | Criticality |
|------------|------|----------------|-----------|
| {dep} | Internal/External | {module} | High/Medium/Low |

---

## Version History

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

---

## Template 2-brd.md (Exigences metier)

```markdown
# Exigences metier - {FEAT-XXX} {Feature Name}

> **Module:** business/{application}/{module}
> **Version:** 1.0
> **Based on:** 1-discovery.md v1.0

## 1. Executive Summary

{3-5 sentence summary of the business need and proposed solution}

## 2. Business Objectives

| ID | Objective | Metric | Target |
|----|----------|--------|--------|
| OBJ-001 | {objective} | {Measurable KPI} | {target value} |

## 3. Business Rules

| ID | Rule | Category | Priority |
|----|------|----------|----------|
| BR-001 | {Business rule description} | Validation/Calculation/Workflow | Must/Should/Could |
| BR-002 | {Description} | {category} | {priority} |

### 3.1 Critical Rules Detail

#### BR-001: {Rule Name}

**Statement:** {Precise rule formulation}

**Conditions:**
- IF {condition A}
- AND {condition B}
- THEN {result}
- ELSE {alternative result}

**Examples:**
| Input | Expected Output |
|--------|-----------------|
| {example 1} | {result 1} |
| {example 2} | {result 2} |

## 4. Business Process

### 4.1 Main Process

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Step 1    │────►│   Step 2    │────►│   Step 3    │
│  {action}   │     │  {action}   │     │  {action}   │
└─────────────┘     └─────────────┘     └─────────────┘
      │                   │                   │
      ▼                   ▼                   ▼
   {actor}            {actor}            {actor}
```

### 4.2 Alternative Flows

| Trigger | Flow | Result |
|---------|------|--------|
| {condition} | {flow description} | {final state} |

## 5. Business Data

### 5.1 Main Entities

| Entity | Description | Cardinality |
|--------|-------------|-------------|
| {Entity} | {description} | 1:N with {other entity} |

### 5.2 Key Attributes (NO technical types)

| Entity | Attribute | Description | Required |
|--------|-----------|-------------|----------|
| {Entity} | {attribute} | {business description} | Yes/No |

## 6. Integrations

| System | Direction | Data | Frequency |
|--------|-----------|------|-----------|
| {system} | Input/Output/Bidirectional | {data} | Real-time/Batch |

---

## Version History

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

---

## Template 3-frd.md (Specification fonctionnelle)

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

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

## 1. Overview

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

### 1.2 Actors

| Actor | Description | Required Permissions |
|--------|-------------|---------------------|
| {Role} | {description} | `business.{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** | `business.{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 |
|------------|-------|---------|------|----------|
| `business.{app}.{module}.read` | ✅ | ✅ | ✅ | ✅ |
| `business.{app}.{module}.create` | ✅ | ✅ | ❌ | ❌ |
| `business.{app}.{module}.update` | ✅ | ✅ | ❌ | ❌ |
| `business.{app}.{module}.delete` | ✅ | ❌ | ❌ | ❌ |

### 6.2 Endpoint-Permission Mapping

| Endpoint | Method | Required Permission |
|----------|--------|-------------------|
| `/api/business/{module}` | GET | `{module}.read` |
| `/api/business/{module}` | POST | `{module}.create` |
| `/api/business/{module}/{id}` | PUT | `{module}.update` |
| `/api/business/{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/business/{module}"
    Then the response status should be 403
    And the response should contain "Permission denied"

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

---

## Version History

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

---

## Template 4-handoff.md

```markdown
# Development Handoff - {FEAT-XXX} {Feature Name}

> **Module:** business/{application}/{module}
> **Version:** 1.0
> **Validated Specs:** Specification v1.0 (validation.json)
> **Implementation:** `/ralph-loop`

## DEVELOPER INSTRUCTIONS

This document is a self-contained prompt for Claude Code.

**Lancement:**
```
/ralph-loop
```
> Ralph-loop auto-detects BA artifacts and derives PRD task breakdowns.
> Use `/ralph-loop -r` only to resume an interrupted loop.

---

## 1. QUICK CONTEXT

| Attribute | Value |
|----------|--------|
| Feature ID | FEAT-XXX |
| Module | business/{application}/{module} |
| Base Permission | `business.{app}.{module}` |
| Complexity | {Simple/Medium/Complex} |

## 2. [EXPLORE] EXISTING PATTERNS

BEFORE coding, explore these files to understand the patterns:

```
BACKEND:
- src/SmartStack.Domain/Entities/ → Entity structure
- src/SmartStack.Application/Features/ → CQRS pattern
- src/SmartStack.Infrastructure/Persistence/Configurations/ → EF Core

FRONTEND:
- web/smartstack-web/src/pages/business/ → Existing pages
- web/smartstack-web/src/components/ → Reusable components
- web/smartstack-web/src/services/api/ → API calls
```

## 3. FILES TO CREATE

### 3.1 Backend

| File | Template | Description |
|------|----------|-------------|
| `Domain/Entities/{Entity}.cs` | Domain Entity | Properties + business rules |
| `Application/Features/{Module}/` | CQRS Commands/Queries | MediatR handlers |
| `Infrastructure/.../Configurations/` | EF Core Config | Config + HasData |
| `Api/Controllers/Business/` | API Controller | REST endpoints |

### 3.2 Frontend

| File | Template | Description |
|------|----------|-------------|
| `pages/business/{app}/{module}/` | React Page | List + detail |
| `services/api/{module}Api.ts` | API Service | Axios calls |
| `i18n/locales/{lang}/{module}.json` | Translations | FR, EN, IT, DE |

## 4. DETAILED SPECIFICATIONS

### 4.1 Entity (business attributes, not C# types)

| Attribute | Description | Required | Rules |
|-----------|-------------|----------|-------|
| Id | Unique identifier | Yes | Random GUID |
| {attr} | {description} | {Yes/No} | {validation} |

### 4.2 API Endpoints

| Endpoint | Method | Permission | Body | Response |
|----------|--------|------------|------|----------|
| `/api/business/{module}` | GET | `.read` | - | Paginated list |
| `/api/business/{module}` | POST | `.create` | CreateDto | 201 + entity |
| `/api/business/{module}/{id}` | GET | `.read` | - | Entity |
| `/api/business/{module}/{id}` | PUT | `.update` | UpdateDto | 200 + entity |
| `/api/business/{module}/{id}` | DELETE | `.delete` | - | 204 |

### 4.3 Business Rules to Implement

| BR-ID | Rule | Implementation |
|-------|------|----------------|
| BR-001 | {rule} | {where to implement} |

## 5. REQUIRED TESTS

- [ ] Unit test: Entity validation
- [ ] Integration test: API endpoints (200, 201, 400, 403, 404)
- [ ] Permission test: 403 denial without permission
- [ ] Postman test: Collection generated

## 6. POST-IMPLEMENTATION CHECKLIST

- [ ] Backend build OK
- [ ] Frontend build OK
- [ ] Tests passing
- [ ] EF Core migration created if entity
- [ ] Permissions added in PermissionConfiguration.cs
- [ ] i18n complete (4 languages)
- [ ] Documentation generated: `/documentation user {module_name}`

---

## EXECUTION

**Lancement:**
```bash
/ralph-loop
```
```

---

## Template Validation

Each template MUST:
- [ ] Be pure Markdown (no technical code)
- [ ] Use tables for structured data
- [ ] Include permissions with full path
- [ ] Have version history
- [ ] Reference BR/FR/UC with unique IDs
