fix: Awards additional bugs

wiki/Awards.md

@@ -11,28 +11,76 @@ mode.
 
 ## How matching works
 
-An award scans a **QSO field** for a reference, by one of:
+An award scans a **QSO field** (state, QTH, address, notes, …) for a reference,
+using one **Match by** mode:
 
-- **code** — the field value is the reference (e.g. state = `NY`).
-- **description** — the reference's name appears in the field (substring, case-
-  insensitive but **space-sensitive** — "Hongkong" won't match "Hong Kong").
-- **pattern** — a per-reference regex is tested against the field.
+- **code** — the field value *is* the reference (e.g. state = `NY`).
+- **description** — the reference's **name** appears in the field (substring,
+  space-sensitive — "Hongkong" won't match "Hong Kong").
+- **pattern** — the field is tested against a regex.
 
-Plus **OR rules** (also match if any of these hit), a **leading/trailing** strip,
-a **prefix** added to found references, and a **dynamic** mode (any value counts,
-like POTA).
+Plus a **leading/trailing** strip, a **prefix** prepended to found references, a
+**dynamic** mode (any value counts, like POTA), and the **fallback searches**
+described below.
 
-> **Tip — Hong Kong / Macau style mismatches:** if the data says "Hong Kong" but
-> the reference description is "Hongkong", either fix the description to match, or
-> set that OR-search's *Match by* to **pattern** so the reference's own regex
-> (e.g. `\bHong Kong\b`) is used. In *description* mode the per-reference pattern
-> is ignored.
+### The five rules to remember
+
+1. **Every regex is case-insensitive.** Award and per-reference patterns match
+   regardless of case (log fields are typed however the operator felt) — so
+   `\bTok[iy]o\b` catches `TOKYO`, `Tokyo` and even `TOKIO`. Set your own flag
+   group (e.g. `(?s)`) to override.
+
+2. **A reference's own `Pattern` is opt-in extra recognition.** On the
+   *References* tab each reference has a **Pattern (regex)** field. Fill it to
+   recognise a reference by more than its name — spelling variants, or the
+   **cities/terms** that imply it. Leave it empty and the reference is matched by
+   name only. Example — Jiangsu (China) carries the cities in its own regex:
+   `\b(Jiangyin|Wuxi|Suzhou|Nanjing|Changzhou)\b`.
+
+3. **`description` also runs the per-reference regexes** (on the same field).
+   A description search looks for the reference *name* **OR** fires each
+   reference's own Pattern — so a description award over the QTH/address will
+   auto-match your city regexes with no extra rule. (A reference with an empty
+   Pattern stays name-only.)
+
+4. **OR rules are ordered fallbacks (first hit wins).** The **Fallback searches**
+   section adds extra searches tried **in order, only while nothing has matched
+   yet** — the first that finds a reference wins and the rest are skipped
+   (short-circuit, like a chain of *else-if*). So a province already resolved by
+   name isn't also re-tagged, possibly differently, by a later city regex.
+
+5. **Scope is checked first — a manual reference does not bypass it.** DXCC
+   filter, valid bands / modes / emission and the valid-from/to dates gate every
+   QSO before any reference is looked at. A 17 m QSO can't count for an award
+   whose valid bands are 80/40/20/15/10 m, even if you assign the reference by
+   hand. Widen the award's bands if it *should* count.
+
+> **Tip — Hong Kong / Macau style mismatches:** if the log says "Hong Kong" but
+> the reference name is "Hongkong", either fix the name, or give that reference a
+> **Pattern** like `\bHong ?Kong\b`. Thanks to rule 3 the pattern now works even
+> for a *description* award — no separate rule needed.
+
+### Worked example — Worked All Provinces of China (WAPC)
+
+A custom province award where the log rarely spells the province out (it names a
+*city*). The clean setup:
+
+- **Primary:** *Search in* **QTH**, *Match by* **description**.
+- **Fallback search:** *Search in* **address**, *Match by* **description**.
+- On the *References* tab, give each province a Pattern listing its cities.
+
+Now a QSO is resolved by the province **name** if present, else by a **city**
+regex — first in the QTH, then in the address. First hit wins.
 
 ## Live detection & manual refs
 
 - References are detected **live** as you enter a callsign.
-- You can **manually assign** a reference to a QSO (stored in an ADIF extra so it
-  survives export/import — see [[Import and Export ADIF]]).
+- You can **manually assign** a reference to a QSO (the *Award Refs* tab of the
+  QSO editor). It's stored in an ADIF extra (`APP_OPSLOG_AWARDREFS`) so it
+  survives export/import — see [[Import and Export ADIF]] — and is honoured
+  everywhere (award panel, grid columns, totals). For a list-backed award the
+  assigned reference must still be a **valid, listed** reference, and the QSO
+  must be **in scope** (rule 5) for it to count.
 
 ## Reference lists & display