# Functional Specification: [Product or feature name]

> Complete functional specification document (FSD). It describes exactly
> how the product behaves from the user's point of view: roles and
> permissions, each feature's flows, business rules, screens, validation,
> messages and data. Based on common industry practice for functional
> specifications. Replace every `[bracketed]` value and every row marked
> *Example*.

<!--
Guidance: How to use this template
- The FSD sits between the business or product requirements (why and
  what) and the technical design (how it is built). Developers and testers
  should be able to build and test each feature from section 5 alone.
- Write one sub-section per feature using the same layout. Copy the
  feature block in 5.1 for each additional feature.
- Be exact about validation rules and error messages. Vague wording here
  becomes inconsistent behaviour in the product.
- Every feature ends with acceptance criteria that a tester can execute.
  Section 10 collects them for sign-off.
-->

## Document control

<!-- Guidance: Identify the document so every copy can be traced to one version. -->

| Field | Value |
|---|---|
| Document ID | [FSD-PRODUCT-001] |
| Product / feature | [Name] [release] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Author | [@business-analyst] |
| Product owner | [@product-owner] |
| Classification | [Internal / Confidential] |
| Last updated | YYYY-MM-DD |
| Related documents | [BRS / PRD], [SRS], [UX designs], [Technical design], [Test plan] |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Product owner | [@name] | [Approved / Rejected / Approved with comments] | YYYY-MM-DD |
| Engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| QA lead | [@name] | [Decision] | YYYY-MM-DD |
| UX lead | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: One row per published version; name the features and rules changed. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft of features F-01 to F-03 |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Added refund approval rule BR-07; updated error messages after UX review |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Approved for development of release 2 |

## Contents

<!-- Guidance: Keep this list in sync with the headings. -->

1. [Introduction](#1-introduction)
2. [User roles and permissions](#2-user-roles-and-permissions)
3. [Functional overview](#3-functional-overview)
4. [Global rules and conventions](#4-global-rules-and-conventions)
5. [Feature specifications](#5-feature-specifications)
6. [Reporting](#6-reporting)
7. [Notifications](#7-notifications)
8. [Integrations](#8-integrations)
9. [Non-functional summary](#9-non-functional-summary)
10. [Acceptance criteria summary](#10-acceptance-criteria-summary)
11. [Open issues and decisions](#11-open-issues-and-decisions)
12. [Appendices](#12-appendices)

## 1. Introduction

<!-- Guidance: Tell the reader what the product is, which release this covers, and what this document does not cover. -->

### 1.1 Purpose

This document specifies the functional behaviour of [Product name]
[release]. It is the reference for design, development, testing,
documentation and user acceptance.

### 1.2 Scope

- **In scope**: [feature F-01], [feature F-02], [feature F-03].
- **Out of scope**: [feature excluded], [feature in a later release].
- **Assumptions**: [assumption that affects behaviour, for example
  "users are already signed in through single sign-on"].

### 1.3 Audience and how to read

[Who reads which sections. Example: developers and testers read 4 and 5;
operations reads 7 and 8; sponsors read 1, 3 and 10.]

### 1.4 Source requirements

| Source | ID range | Location |
|---|---|---|
| *Example:* Business requirements | BR-001 to BR-012 | BRS 1.0 |
| *Example:* User stories | ORD-101 to ORD-140 | Backlog |
| [Source] | [IDs] | [Location] |

## 2. User roles and permissions

<!-- Guidance: List every role and what it may do. A permissions matrix prevents the "who can delete this?" argument during testing. -->

### 2.1 Roles

| Role | Description | Typical users | Number |
|---|---|---|---|
| *Example:* Customer | Places and tracks orders | Registered shoppers | 50,000 |
| *Example:* Support agent | Handles order queries and refunds up to a limit | Contact centre staff | 40 |
| *Example:* Support supervisor | Approves refunds above the agent limit | Team leads | 6 |
| *Example:* Administrator | Configures products, prices and roles | Operations | 3 |
| [Role] | [Description] | [Users] | [n] |

### 2.2 Permissions matrix

C = create, R = read, U = update, D = delete, A = approve, dash = no access.

| Function | Customer | Support agent | Support supervisor | Administrator |
|---|---|---|---|---|
| Orders (own) | C R U | R | R | R |
| Orders (all) | - | R U | R U | R |
| Refunds up to [limit] | - | C | C A | - |
| Refunds above [limit] | - | C | A | - |
| Product catalogue | R | R | R | C R U D |
| User roles | - | - | - | C R U D |
| Reports | - | R (own team) | R | R |

## 3. Functional overview

<!-- Guidance: A one-page picture of all features and how they connect. -->

[Short narrative of what the product does and the main user journeys.]

The feature map below shows how the main features relate.

```mermaid
flowchart LR
  F01["F-01 Browse and search"] --> F02["F-02 Cart and checkout"]
  F02 --> F03["F-03 Order tracking"]
  F03 --> F04["F-04 Returns and refunds"]
  F05["F-05 Catalogue admin"] --> F01
```

| ID | Feature | Primary role | Priority | Source |
|---|---|---|---|---|
| F-01 | *Example:* Browse and search | Customer | Must | BR-001 |
| F-02 | *Example:* Cart and checkout | Customer | Must | BR-002 |
| F-03 | *Example:* Order tracking | Customer, agent | Must | BR-004 |
| F-04 | *Example:* Returns and refunds | Customer, agent, supervisor | Should | BR-007 |
| F-05 | [Feature] | [Role] | [MoSCoW] | [Source] |

## 4. Global rules and conventions

<!-- Guidance: Rules that apply to every feature, so they are not repeated in each section. -->

- **Dates and times**: shown in the user's time zone as [YYYY-MM-DD HH:mm];
  stored in UTC.
- **Currency**: [ISO 4217 code], two decimal places, rounding half-up.
- **Required fields**: marked with an asterisk and announced to screen
  readers.
- **Validation timing**: on leaving the field and again on submit.
- **Error message style**: say what is wrong and how to fix it, in plain
  language, next to the field. No error codes in user-facing text.
- **Audit**: every create, update and delete stores user, time and old and
  new values.
- **Accessibility**: [WCAG 2.2 level AA].
- **Languages**: [list]; all user-facing text comes from translation files.

## 5. Feature specifications

<!-- Guidance: One sub-section per feature, same layout. Keep each flow numbered so test cases can reference steps. -->

### 5.1 F-04 Returns and refunds

#### 5.1.1 Description

*Example:* Lets a customer request a return for delivered items within the
return window, and lets support staff approve and refund it. Supports full
and partial refunds to the original payment method.

#### 5.1.2 Actors and preconditions

- **Actors**: Customer, Support agent, Support supervisor.
- **Preconditions**: The order exists, has status Delivered, and the
  delivery date is within [30] days.
- **Trigger**: Customer selects "Return items" on an order, or an agent
  opens a return on the customer's behalf.

#### 5.1.3 Main flow

1. Customer opens a delivered order and selects "Return items".
2. System lists the returnable items with quantity selectors.
3. Customer selects items and quantities and chooses a reason.
4. System validates the request (5.1.6) and shows the refund amount.
5. Customer confirms.
6. System creates a return with status Requested, emails a return label
   and shows the return number.
7. Warehouse scans the returned parcel; system sets status Received.
8. Support agent inspects and selects "Approve refund".
9. System refunds to the original payment method and sets status Refunded.
10. System notifies the customer (N-03).

#### 5.1.4 Alternate and exception flows

| ID | At step | Condition | Behaviour |
|---|---|---|---|
| A1 | 2 | Some items are not returnable (final sale) | Items shown greyed with reason "Final sale items cannot be returned" |
| A2 | 4 | Return window has passed | Request blocked; message E-RET-02; link to contact support |
| A3 | 8 | Refund above agent limit | Status Awaiting approval; supervisor notified (N-04) |
| A4 | 9 | Payment provider declines refund | Status Refund failed; agent alerted; retry or store credit offered |
| A5 | 8 | Item damaged by customer | Agent selects "Reject" with reason; customer notified (N-05) |

#### 5.1.5 Business rules

| ID | Rule |
|---|---|
| BR-RET-01 | *Example:* Returns are accepted up to 30 days after delivery date. |
| BR-RET-02 | *Example:* Original shipping is refunded only when the whole order is returned. |
| BR-RET-03 | *Example:* Agents may approve refunds up to 200; above that a supervisor must approve. |
| BR-RET-04 | *Example:* One open return per order line at a time. |

#### 5.1.6 Validation rules

| Field | Rule | Error message ID |
|---|---|---|
| Quantity | Integer, 1 to quantity delivered minus quantity already returned | E-RET-01 |
| Reason | Required; one of the configured reasons | E-RET-03 |
| Comment | Optional; up to 500 characters | E-RET-04 |
| Delivery date | Within 30 days of today | E-RET-02 |

#### 5.1.7 User interface elements

| Element | Type | Behaviour |
|---|---|---|
| Return items | Button | Visible only for Delivered orders inside the window |
| Item quantity | Number stepper | Range from validation rules |
| Return reason | Select | Values from configuration table RET_REASON |
| Refund summary | Read-only panel | Updates as items are selected |
| Confirm return | Primary button | Disabled until at least one item and a reason are chosen |

Wireframe or design reference: [link to design file, frame name].

#### 5.1.8 Error and information messages

| ID | Text shown to the user | Shown when |
|---|---|---|
| E-RET-01 | "Choose a quantity between 1 and [n]." | Quantity outside range |
| E-RET-02 | "This order is past the 30-day return window. Contact us if you need help." | Window expired |
| E-RET-03 | "Choose a reason for the return." | No reason selected |
| E-RET-04 | "Comments can be up to 500 characters." | Comment too long |
| I-RET-01 | "Return [number] created. We have emailed your return label." | Return created |

#### 5.1.9 Data fields

| Field | Type | Length / format | Required | Default | Source / notes |
|---|---|---|---|---|---|
| return_id | String | RET-YYYYMMDD-nnnn | Yes | Generated | System |
| order_id | String | ORD-nnnnnnnn | Yes | From order | Orders |
| line_items | List | 1 to 50 items | Yes | None | Customer selection |
| reason_code | Enum | RET_REASON values | Yes | None | Configuration |
| status | Enum | Requested, Received, Awaiting approval, Refunded, Rejected, Refund failed | Yes | Requested | System |
| refund_amount | Decimal | 10,2 | Yes | Calculated | BR-RET-02 |

#### 5.1.10 Acceptance criteria

- AC-RET-01: Given a delivered order within 30 days, when the customer
  returns one item with a reason, then a return is created with status
  Requested and a label email is sent.
- AC-RET-02: Given a delivered order 31 days old, when the customer opens
  it, then "Return items" is not available and E-RET-02 is explained.
- AC-RET-03: Given a refund of 250, when an agent approves, then the
  status becomes Awaiting approval and a supervisor is notified.

### 5.2 [F-nn Feature name]

[Repeat the structure of 5.1 for each feature: description, actors and
preconditions, main flow, alternate flows, business rules, validation
rules, UI elements, messages, data fields, acceptance criteria.]

## 6. Reporting

<!-- Guidance: List each report with its audience, filters, columns and refresh. -->

| ID | Report | Audience | Filters | Columns | Refresh |
|---|---|---|---|---|---|
| RPT-01 | *Example:* Returns by reason | Operations | Date range, category | Reason, count, refund value, % of orders | Daily |
| RPT-02 | *Example:* Refunds pending approval | Supervisors | Team | Return ID, age, amount, agent | Real time |
| [RPT-nn] | [Report] | [Audience] | [Filters] | [Columns] | [Refresh] |

## 7. Notifications

<!-- Guidance: Every message the system sends, its trigger, channel and recipients. -->

| ID | Trigger | Recipient | Channel | Content summary | Opt-out |
|---|---|---|---|---|---|
| N-03 | *Example:* Refund completed | Customer | Email | Amount, method, expected days to appear | No (transactional) |
| N-04 | *Example:* Refund above agent limit | Supervisor | In-app, email | Return ID, amount, agent | No |
| N-05 | *Example:* Return rejected | Customer | Email | Reason, next steps | No |
| [N-nn] | [Trigger] | [Recipient] | [Channel] | [Content] | [Yes / No] |

## 8. Integrations

<!-- Guidance: External systems this functionality depends on, from a functional view. Technical contracts go in the interface specification. -->

| ID | System | Purpose | Direction | Trigger | Failure behaviour |
|---|---|---|---|---|---|
| INT-01 | *Example:* Payment provider | Issue refunds | Out | Refund approved | Status Refund failed; retry up to 3 times |
| INT-02 | *Example:* Warehouse system | Confirm parcel receipt | In | Parcel scanned | Manual receipt by agent |
| [INT-nn] | [System] | [Purpose] | [In / Out] | [Trigger] | [Behaviour] |

## 9. Non-functional summary

<!-- Guidance: Summarise the quality requirements that shape functional behaviour; the full list lives in the SRS or NFR document. -->

| Area | Requirement | Reference |
|---|---|---|
| Performance | *Example:* Return request confirmation within 2 s at p95 | [NFR-PERF-03] |
| Availability | *Example:* 99.9% monthly for customer-facing functions | [NFR-AV-01] |
| Security | *Example:* Refund approval requires re-authentication within the last 15 min | [NFR-SEC-07] |
| Accessibility | WCAG 2.2 level AA | [NFR-ACC-01] |
| Privacy | *Example:* Return comments are deleted after 2 years | [NFR-PRIV-02] |

## 10. Acceptance criteria summary

<!-- Guidance: Collect all acceptance criteria for sign-off and link each to its test case. -->

| Feature | Acceptance criteria | Test cases | Status |
|---|---|---|---|
| F-04 | AC-RET-01, AC-RET-02, AC-RET-03 | TC-RET-001 to TC-RET-012 | [Not run / Passed / Failed] |
| [F-nn] | [AC IDs] | [TC IDs] | [Status] |

## 11. Open issues and decisions

<!-- Guidance: Track what is still undecided and record decisions with date and owner. -->

| ID | Issue or decision | Owner | Due | Status / outcome |
|---|---|---|---|---|
| OI-01 | *Example:* Should store credit be offered when card refund fails? | Product owner | YYYY-MM-DD | [Open] |
| DEC-01 | *Example:* Partial refunds allowed per line, not per unit | Product owner | YYYY-MM-DD | Decided |
| [ID] | [Issue] | [@name] | YYYY-MM-DD | [Status] |

## 12. Appendices

<!-- Guidance: Glossary, configuration tables and references. -->

### 12.1 Glossary

| Term | Definition |
|---|---|
| Return window | Number of days after delivery during which a return can be requested |
| Store credit | Balance usable for future orders instead of a card refund |
| [Term] | [Definition] |

### 12.2 Configuration tables

| Table | Values | Maintained by |
|---|---|---|
| RET_REASON | Damaged, Wrong item, No longer needed, Size or fit, Other | Administrator |
| [Table] | [Values] | [Role] |

## Standard and licence note

Based on common industry practice for functional specification documents
in business analysis and software delivery. Original text written for this
collection; examples are illustrative. Template licence: MIT.