# Use Case: UC-[nn] [Verb phrase goal, for example Withdraw cash]

> Fully dressed use case specification following the format described by
> Alistair Cockburn in *Writing Effective Use Cases*. It records one
> actor's goal, every stakeholder's interest, the main success scenario and
> all extensions. Replace every `[bracketed]` value and every line marked
> *Example*.

<!--
Guidance: How to use this template
- Name the use case as the primary actor's goal, in active voice: "Withdraw
  cash", not "Cash withdrawal function".
- Write the main success scenario first, 3 to 9 steps, then brainstorm
  every way each step can fail or branch and record them as extensions.
- Each step is "who does what": actor or system as subject, one action,
  no user interface detail ("Customer enters amount", not "clicks the
  green button").
- Keep one use case per file. Link related use cases by ID.
-->

| Field | Value |
|---|---|
| Use case ID | UC-[nn] |
| Version | [0.1] |
| Status | [Draft / Reviewed / Approved] |
| Author | [@name] |
| Last updated | YYYY-MM-DD |
| Related use cases | [UC-nn includes / extends UC-nn] |
| Source requirements | [BR-nnn, STK-UR-nnn] |

## 1. Goal in context

<!-- Guidance: One or two sentences: what the primary actor wants and why it matters. -->

[Longer statement of the goal and the situation in which it arises.]

*Example:* A bank customer wants to withdraw cash from their current
account at an ATM, quickly and without errors, and leave with the right
amount, their card and a correct balance.

## 2. Scope and level

<!-- Guidance: Scope is the system under design (the black box). Level is user goal (sea level), summary (cloud or kite) or subfunction (fish). Most use cases should be user goal level. -->

| Attribute | Value |
|---|---|
| Scope | [System under design, for example ATM network system, black box] |
| Level | [User goal / Summary / Subfunction] |
| Primary actor | [Actor with the goal, for example Account holder] |
| Supporting actors | [Bank core system, card network] |

## 3. Stakeholders and interests

<!-- Guidance: List everyone whose interests the system must protect, even if they never touch it. Each interest should be visible in a step, guarantee or extension. -->

| Stakeholder | Interest |
|---|---|
| *Example:* Account holder | Gets the requested cash quickly; account debited exactly once and only if cash is dispensed |
| *Example:* Bank | Withdrawal is authorised, limits enforced, every transaction is auditable |
| *Example:* Card network | Message formats followed; fees recorded |
| *Example:* Regulator | Customer data protected; disputes can be resolved from records |
| [Stakeholder] | [Interest] |

## 4. Conditions and trigger

<!-- Guidance: Preconditions are what the system guarantees is already true; they are not checked again. Minimal guarantee holds however the use case ends. Success guarantee holds when the goal is met. -->

| Item | Statement |
|---|---|
| Preconditions | *Example:* ATM is in service and has a connection to the bank. |
| Minimal guarantee | *Example:* Every attempt is logged; the account is never debited for cash not dispensed; the card is returned or retained with a record. |
| Success guarantee | *Example:* Customer has cash, card and receipt; account debited by the amount; ATM cash balance reduced. |
| Trigger | *Example:* Customer inserts a card. |

## 5. Main success scenario

<!-- Guidance: Number each step. Show the goal succeeding by the simplest route. Avoid "if" in this section; branches belong in extensions. -->

1. Customer inserts card.
2. System reads the card and asks for the PIN.
3. Customer enters the PIN.
4. System validates the PIN with the bank and presents transaction options.
5. Customer selects "Withdraw" and enters an amount.
6. System checks the amount against the account balance, daily limit and
   cash available, and requests authorisation from the bank.
7. Bank authorises and debits the account.
8. System returns the card, dispenses the cash and prints a receipt.
9. Customer takes card, cash and receipt.
10. System logs the transaction and returns to the welcome screen.

## 6. Extensions

<!-- Guidance: Label each extension with the step number and a letter: "4a". Write the condition the system can detect, then the handling steps, then where it rejoins or ends. "*a" applies at any step. -->

| ID | Condition | Handling |
|---|---|---|
| *a | Customer cancels at any step before 7 | 1. System returns the card. 2. Use case ends; nothing debited. |
| *b | Power failure | 1. System completes or reverses any in-flight bank transaction on restart. 2. Use case ends with minimal guarantee. |
| 2a | Card unreadable | 1. System returns card and shows "Card could not be read". 2. Use case ends. |
| 2b | Card reported stolen | 1. System retains card and logs event. 2. Use case ends. |
| 4a | Wrong PIN, fewer than 3 attempts | 1. System shows remaining attempts. 2. Return to step 3. |
| 4b | Wrong PIN, third attempt | 1. System retains card and notifies the bank. 2. Use case ends. |
| 5a | Amount not a multiple of available notes | 1. System suggests nearest valid amounts. 2. Return to step 5. |
| 6a | Amount exceeds balance or daily limit | 1. System shows the maximum allowed. 2. Return to step 5. |
| 6b | Bank does not respond within 30 s | 1. System returns card with "Service unavailable". 2. Use case ends; nothing debited. |
| 8a | Dispenser jams after debit | 1. System reverses the debit with the bank. 2. ATM goes out of service and alerts operations. 3. Use case ends with minimal guarantee. |
| 9a | Customer does not take cash within 30 s | 1. System retracts cash and reverses the debit. 2. Use case ends. |
| [n][x] | [Condition] | [Handling steps and rejoin point] |

## 7. Technology and data variations

<!-- Guidance: Variations in how a step is done that do not change the flow: input devices, formats, channels. -->

| Step | Variation |
|---|---|
| 1 | *Example:* Contactless card or mobile wallet instead of inserted card |
| 3 | *Example:* Biometric verification where the bank supports it |
| 8 | *Example:* Receipt sent to the banking app instead of printed |
| [n] | [Variation] |

## 8. Related information

<!-- Guidance: Non-functional notes, frequency and links that help designers size and prioritise the use case. -->

| Item | Value |
|---|---|
| Frequency of occurrence | *Example:* About 400 per ATM per day; peaks Friday 17:00 to 19:00 |
| Priority | [Must / Should / Could] |
| Performance target | *Example:* Steps 6 to 8 complete within 10 s at p95 |
| Channels | [ATM, branch kiosk] |
| Superordinate use case | [UC-nn, summary level] |
| Subordinate use cases | [UC-nn Validate PIN, UC-nn Print receipt] |

## 9. Use case diagram

<!-- Guidance: Optional. Show the actors and the use cases around this one. Keep it small; the text is the specification. -->

The diagram shows this use case with its actors and the related use cases
it includes or is extended by.

```mermaid
flowchart LR
  cust([Account holder])
  bank([Bank core system])
  subgraph ATM["ATM network system"]
    uc1((Withdraw cash))
    uc2((Validate PIN))
    uc3((Print receipt))
    uc4((Check balance))
  end
  cust --> uc1
  cust --> uc4
  uc1 -.->|includes| uc2
  uc1 -.->|includes| uc3
  uc1 --> bank
```

## 10. Open issues

<!-- Guidance: Questions that must be answered before the use case is approved. -->

| ID | Issue | Owner | Due | Resolution |
|---|---|---|---|---|
| OI-01 | *Example:* Should the daily limit be shown before the amount is entered? | [@product-owner] | YYYY-MM-DD | [Open] |
| OI-02 | *Example:* Confirm retraction rules with the cash handling vendor | [@ops-lead] | YYYY-MM-DD | [Open] |
| [OI-nn] | [Issue] | [@name] | YYYY-MM-DD | [Resolution] |

## 11. Review checklist

- The name is an active verb phrase stating the primary actor's goal.
- Every stakeholder interest is protected by a step, guarantee or
  extension.
- The main success scenario has 3 to 9 steps without "if".
- Every step can fail; failures are listed as extensions or justified as
  impossible.
- No user interface detail appears in steps.
- Preconditions are not re-checked in the scenario.

## Standard and licence note

Based on the fully dressed use case format described by Alistair Cockburn
in *Writing Effective Use Cases* (Addison-Wesley, 2001). The structure is a
widely used convention; this template is original text written for this
collection and reproduces no text from the book. Template licence: MIT.