ios-dev-agent / rules

---
description: iOS development rule
globs: "**/*.swift"
alwaysApply: true
---

# Currency Handling Rules

Use these rules for any iOS app that stores, calculates, or displays money.

## Non-Negotiables

### Store Money As Decimal

Use `Decimal` for monetary amounts. Never use `Double` or `Float` for stored money, model money, or totals.

```swift
// BANNED
let price: Double = 9.99

// CORRECT
let price: Decimal = Decimal(string: "9.99")!
```

### Pair Amount With Currency

An amount without a currency is incomplete. Keep `amount` and `currencyCode` together in models, DTOs, storage, and view state. Validate currency codes against `Locale.commonISOCurrencyCodes` or an app-owned wrapper.

### Format With Foundation

Never concatenate currency symbols or force two decimal places.

```swift
// BANNED
Text("$\(amount)")
String(format: "%.2f", amount)

// CORRECT
Text(amount.formatted(.currency(code: currencyCode)))
```

Foundation formatting handles symbol position, separators, minor-unit counts, right-to-left layout, and localized digits.

### Do Not Sum Across Currencies

Aggregate money per currency unless the product has an explicit, user-visible FX conversion feature. Cross-currency totals must show the conversion source, timestamp, and any unconverted currencies.

### User-Entered Prices

For prices entered by the user or extracted from OCR/imports:

- Store `Decimal`.
- Store ISO 4217 currency code.
- Mark uncertain or invalid parsed currencies for user review.
- Default new entries to `Locale.current.currency?.identifier` when appropriate.

## Banned Patterns

```swift
"$\(amount)"
"\(currency)\(amount)"
String(format: "$%.2f", amount)
Double(amountString)
totals.values.reduce(0, +) // when totals include mixed currencies
```

## Preferred Shape

```swift
struct Money: Hashable, Codable {
    var amount: Decimal
    var currencyCode: String
}
```

Expose a single formatting helper, such as `money.formatted(locale:)`, and use it from SwiftUI views instead of formatting inline.