Full catalog of AFM's features with our current status (have/partial/ missing), a concrete first-phase plan (quality-aware pricing, price history + EMV, arbitrage flipper, Black Market flipper), a prioritized backlog toward fuller parity, and reference notes on how AFM is built. Planning doc only — no code changes yet. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Заид Омар Медхат
parent
b12a9d1821
commit
38c7ff5e56
1 changed files with 175 additions and 0 deletions
175
docs/AFM-PARITY-ROADMAP.md
Normal file
175
docs/AFM-PARITY-ROADMAP.md
Normal file
|
|
@ -0,0 +1,175 @@
|
||||||
|
# Albion Free Market parity — roadmap + first build phase
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
We like [albionfreemarket.com](https://albionfreemarket.com) (AFM) and want our app to reach **as
|
||||||
|
much feature parity as possible over time**. This document is the durable roadmap: a complete
|
||||||
|
catalog of AFM's features (what each does, how it's built, what data it needs, our current
|
||||||
|
status), plus a concrete implementation plan for the **first phase** — the trading/pricing
|
||||||
|
cluster (quality-aware pricing → price history/EMV → arbitrage flipper → Black Market flipper).
|
||||||
|
|
||||||
|
Keep this file updated as features land (flip the status markers).
|
||||||
|
|
||||||
|
AFM and our app share the same data backbone: the **Albion Data Project (AODP)** — crowdsourced
|
||||||
|
sniffer clients upload market orders (and price history). So almost everything AFM does is
|
||||||
|
achievable for us; the gaps are breadth of tools, price **history**, **EMV** (a fair-value
|
||||||
|
baseline from history), **Black Market flipping**, and account/portfolio features.
|
||||||
|
|
||||||
|
Legend — **Us:** ✅ have · 🟡 partial · ❌ missing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Complete AFM feature catalog + our status
|
||||||
|
|
||||||
|
### 1. Market data & analysis
|
||||||
|
- **Price Check** — live prices per item across cities/servers. Data: AODP prices. **Us: ✅** (Market Data).
|
||||||
|
- **Price History Charts** — trend up to 180 days, daily points. Data: AODP `/history`. **Us: ❌**.
|
||||||
|
- **EMV (Estimated Market Value)** — statistical fair-value baseline from history to judge over/under-pricing (their "AI" = smoothed/median of historical avg price). Data: history. **Us: ❌**.
|
||||||
|
- **Top Traded Items** — most-traded by volume/silver, filterable. Data: history `item_count`. **Us: ❌**.
|
||||||
|
- **Quality-aware pricing** — prices per quality 1–5. **Us: 🟡** (storage, AODP fetch, sniffer, overrides, watch rules, Market page all q1–5; **only the economy engine hardcodes q1** — `service.ts` `WHERE quality = 1`).
|
||||||
|
- **CSV export** of market data. **Us: ❌**.
|
||||||
|
|
||||||
|
### 2. Crafting & production
|
||||||
|
- **Full Craft/Refine calculator** — RRR + focus + journals + food + quality rerolls, auto-loads prices, per-material breakdown. **Us: 🟡** (we have RRR, focus, taxes, station fees, recursive buy-vs-craft, and rank *all* recipes at once; missing journals, food/nutrition modeling, quality-reroll odds, single-item deep-dive view).
|
||||||
|
- **Simple Craft calculator** + shareable link. **Us: 🟡** (Opportunities ranker + URL-synced filters; no dedicated single-item quick view).
|
||||||
|
- **RRR calculator** — return rate by city/spec. **Us: ✅** (engine + Character page).
|
||||||
|
- **Farm & Breed calculator** — crops/animals/island yield + profit. Data: farm/seed/offspring tables. **Us: ❌**.
|
||||||
|
- **Journals calculator** — fame→journal fill happiness + profit. Data: journal items + fame values. **Us: ❌**.
|
||||||
|
- **Transmutation** — cost to convert tier/enchant. Data: transmutation recipes. **Us: ❌**.
|
||||||
|
|
||||||
|
### 3. Trading & flipping
|
||||||
|
- **Market Flipper** — buy-order vs sell-order arbitrage within/between cities. Data: AODP buy+sell + freshness. **Us: ❌**.
|
||||||
|
- **Black Market Flipper** — royal sell order → Black Market buy order, minus tax + transport (Smuggler's Network distance fee); includes **upgrade flips** (buy low-enchant + runes to match a higher-enchant BM buy order) and **private flips** (use only your own sniffed orders). Data: AODP incl. BM buy orders (we already fetch these). **Us: ❌** (BM is a tracked city already; no flip logic).
|
||||||
|
- **EMV Flipper** — orders priced far from EMV (bargains / overpriced). Data: EMV. **Us: ❌**.
|
||||||
|
- **Trade Routes finder** — profitable multi-hop trading sequences. **Us: 🟡** (2-city Haul Advisor exists; no multi-hop).
|
||||||
|
- **Trade Calculator** — transport route profit given weight/fees. **Us: 🟡** (haul by weight; no fee/teleport model).
|
||||||
|
- **Upgrade Calculator** — buy-ready vs buy-low+upgrade. Data: upgrade recipes (we parse them). **Us: 🟡** (engine has upgrade recipes; no dedicated UI).
|
||||||
|
|
||||||
|
### 4. Character & knowledge
|
||||||
|
- **Your Specs** — Destiny Board spec tracker, uploaded by the data client. **Us: 🟡** (manual Character page; sniffer auto-fill of specs not wired — event codes TBD from a live capture).
|
||||||
|
- **Item Power (IP)** — gear IP from tier/enchant/quality/masteries + price-by-IP. Data: IP formula + item stats (not in our current dump). **Us: ❌**.
|
||||||
|
- **Repair Cost calculator** — repair silver by item/quality. Data: item value + repair formula. **Us: ❌**.
|
||||||
|
- **Teleport Calculator** — fast-travel silver cost between cities by weight. Data: teleport fee formula. **Us: 🟡** (routes exist; no silver cost).
|
||||||
|
- **Mounts** — mount stats/spells/pricing browser. **Us: ❌**.
|
||||||
|
- **Albion Journal** — achievements browser. **Us: ❌**.
|
||||||
|
- **Articles & Tutorials** — guides. **Us: ❌** (out of scope).
|
||||||
|
|
||||||
|
### 5. Maps & navigation
|
||||||
|
- **World Map / Albion Maps** — interactive zone map, markers, resources, POIs. **Us: 🟡** (zone graph + text routing/directions; no visual map).
|
||||||
|
- **Pathfinder / Routes** — travel time with waypoints + mount speeds. **Us: 🟡** (hop-count routing; no time/mount-speed).
|
||||||
|
- **Roads of Avalon** — ROA network routing with exit tracking (time-limited portals). **Us: ❌** (deliberately excluded from routing today).
|
||||||
|
- **Teleport routes** — see Teleport Calculator above.
|
||||||
|
|
||||||
|
### 6. PvP / meta (separate domain — needs kill/loot data, lowest priority)
|
||||||
|
- **Builds / Build Bundles** — create/share gear+skill builds. **Us: ❌**.
|
||||||
|
- **Meta Items** — item popularity from PvP kill data. **Us: ❌**.
|
||||||
|
- **Meta Builds** — full gear sets from recorded fights. **Us: ❌**.
|
||||||
|
- **Loot Logger** — record PvE/PvP loot, value with EMV. **Us: ❌**.
|
||||||
|
- **Awakened Items marketplace + Awakened Calculator** — awakened weapon trait/cost modeling. **Us: ❌**.
|
||||||
|
|
||||||
|
### 7. Portfolio / accounts / QoL
|
||||||
|
- **Portfolio Tracker** — holdings, transactions, FIFO stock pricing, P&L. Data: user-recorded trades. **Us: ❌**.
|
||||||
|
- **Your Flips / Your Crafts history** — historical flip/craft tracking with charts. **Us: ❌**.
|
||||||
|
- **Accounts + subscription** (Patreon) gating premium features. **Us: ❌** (we have single API key, no multi-user accounts).
|
||||||
|
- **Menu favorites, themes, i18n (localized item names), URL sharing.** **Us: 🟡** (URL sharing via routing done; favorites/themes/i18n missing).
|
||||||
|
- **Data Client** (desktop app uploading prices + specs + loot). **Us: 🟡** (our agent uploads prices + world map; no spec/loot upload yet).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Approved first phase — trading & pricing cluster
|
||||||
|
|
||||||
|
Build order below is dependency-ordered. Reuse existing patterns: AODP client chunk/throttle
|
||||||
|
(`market/client.ts` `fetchPrices`), `upsertPriceRows` bulk-upsert, backend cache + cooldown
|
||||||
|
(`cache.ts`, `market/service.ts`), freshness ages, `economy/config.ts` for editable fees/taxes,
|
||||||
|
and the pure engine in `economy/engine.ts`.
|
||||||
|
|
||||||
|
### Part A — Quality-aware pricing (foundation)
|
||||||
|
- `economy/service.ts` `buildProvider(city)` → `buildProvider(city, quality)`: load the chosen
|
||||||
|
quality's price map with **fallback to q1** (resources have no quality; equipment output does).
|
||||||
|
Drop the hardcoded `WHERE quality = 1`.
|
||||||
|
- `RankRequest` gains `quality?` (default 1); thread through `rankOpportunities`.
|
||||||
|
- `OpportunitiesPage.tsx`: quality selector (1–5), URL-synced like other filters.
|
||||||
|
- Files: `server/src/economy/service.ts`, `server/src/routes/economy.ts`, `web/src/pages/OpportunitiesPage.tsx`.
|
||||||
|
|
||||||
|
### Part B — Price history + EMV + Top Traded
|
||||||
|
- `market/client.ts`: add `fetchHistory` → AODP `GET /api/v2/stats/history/{items}?date&locations&qualities&time-scale=24`
|
||||||
|
(daily). Same chunk/throttle/proxy/`AodpUnreachableError` handling. **Confirm response shape
|
||||||
|
defensively on first run** (`[{location,item_id,quality,data:[{item_count,avg_price,timestamp}]}]`).
|
||||||
|
- DB: new `price_history(item, city, quality, ts, avg_price, item_count)` PK(item,city,quality,ts);
|
||||||
|
new `market_emv(item, city, quality, emv, updated_at)`. Add to schema + `ALTER … IF NOT EXISTS`.
|
||||||
|
- `market/service.ts`: history refresh job (mirrors price refresh + cooldown); EMV compute =
|
||||||
|
item_count-weighted median/avg of last N days' `avg_price`; store to `market_emv`. Merge `emv`
|
||||||
|
into `getPricesForItem`.
|
||||||
|
- Endpoints (`routes/market.ts`): `POST /api/market/history/refresh`, `GET /api/market/history/:item`
|
||||||
|
(series for charts), `GET /api/market/top-traded?days=` (sum item_count).
|
||||||
|
- UI: inline **SVG** line chart on the Market Data item view (no external libs — CSP), with an EMV
|
||||||
|
reference line; a "Top Traded" section/tab.
|
||||||
|
|
||||||
|
### Part C — Arbitrage flipper (general)
|
||||||
|
- New `economy/flip.ts` (pure): given prices for item×city×quality, find buy-low/sell-high:
|
||||||
|
within-city (sell_min→buy_max) and cross-city (buy_min city A → sell to buy_max city B), minus
|
||||||
|
sales tax (premium-aware) and transport (weight-based). **False-positive guards:** only orders
|
||||||
|
within a freshness window (reuse cooldown/age), and an optional **EMV sanity filter** (skip when
|
||||||
|
a price deviates from EMV beyond a configurable %).
|
||||||
|
- `routes/market.ts`: `POST /api/market/flips` (cities, tiers, minProfit, useEmvFilter) → rows
|
||||||
|
{item, buyCity, buyPrice, sellCity, sellPrice, tax, transport, profit, roi, profitPer100kg, ages}.
|
||||||
|
- UI: new **Flipper** tab (route `/flipper`, URL-synced filters), sortable table.
|
||||||
|
|
||||||
|
### Part D — Black Market flipper
|
||||||
|
- Specialize Part C: sell side = Black Market `buy_price_max`; buy side = royal/Caerleon
|
||||||
|
`sell_price_min`; net = `bmBuy*(1-salesTax) - buyPrice - transportToBM` (BM instant-sell = sales
|
||||||
|
tax only, no listing fee). Uses existing `market_prices` — **no new fetch**.
|
||||||
|
- Transport model: add editable `transportFees` to `economy/config.ts` (per source city →
|
||||||
|
Caerleon/BM, silver per 100kg or flat; approximate, user-tunable — Smuggler's Network fees shift).
|
||||||
|
- **Upgrade flips:** reuse engine upgrade recipes + `acquisitionCost` to compare buy-low+runes vs a
|
||||||
|
higher-enchant BM buy order.
|
||||||
|
- UI: "Black Market" mode in the Flipper tab (transport-fee column, upgrade-flip toggle).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Backlog (later phases, toward fuller parity)
|
||||||
|
|
||||||
|
Ordered roughly by value for a solo economy player:
|
||||||
|
1. Single-item **Craft deep-dive** view (food/nutrition, journals, quality-reroll odds).
|
||||||
|
2. **Trade Routes** (multi-hop) + **Teleport/transport fee** model + travel time & mount speed.
|
||||||
|
3. **Portfolio / Your Flips / Your Crafts** history (record user trades; needs a light user model).
|
||||||
|
4. **Farm & Breed**, **Journals**, **Transmutation** calculators (need extra game-data tables).
|
||||||
|
5. **Item Power / Repair cost** (need item stat + formulas; may require a richer data dump).
|
||||||
|
6. **Sniffer spec auto-fill** (finish destiny-board event mapping) + agent **loot upload**.
|
||||||
|
7. **Visual world map**, **Roads of Avalon** routing.
|
||||||
|
8. QoL: favorites, themes, i18n item names, CSV export.
|
||||||
|
9. PvP/meta (Builds, Meta Items/Builds, Loot Logger, Awakened) — only if we expand beyond economy.
|
||||||
|
10. Multi-user **accounts** (only if this is ever shared beyond a single user).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification (for the first phase)
|
||||||
|
|
||||||
|
- **Unit tests** (vitest, pure funcs): flip math (tax/transport/ROI/profit-per-100kg), EMV
|
||||||
|
computation, quality-aware provider fallback. Add to `server/src/economy/*.test.ts`.
|
||||||
|
- **End-to-end** against a throwaway Postgres: seed prices incl. Black Market buy orders + a few
|
||||||
|
history rows; verify quality-aware ranking, `/history` series, EMV values, `/flips` and Black
|
||||||
|
Market flips, and cache invalidation on price writes.
|
||||||
|
- **Manual** (needs VPN): refresh history for a few items → view chart + EMV; run the Black Market
|
||||||
|
flipper and cross-check one flip's numbers against AFM/albiononline2d.
|
||||||
|
|
||||||
|
## Notes / unknowns
|
||||||
|
- AODP `/history` response shape parsed defensively; adjust on first live run.
|
||||||
|
- Smuggler's/transport fees are approximate → keep in editable config, show freshness so users
|
||||||
|
sanity-check.
|
||||||
|
- Black Market buy orders depend on community scans and can be sparse/stale → always surface age.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How AFM is built (reference notes)
|
||||||
|
|
||||||
|
- **Data client**: desktop/mobile apps that sniff network traffic and upload market orders (and
|
||||||
|
specs/loot) to AODP + AFM. Directly analogous to our `agent/`.
|
||||||
|
- **Order freshness**: AFM treats sell orders as valid ~60 min, buy orders ~30 min, to reduce
|
||||||
|
false positives from already-consumed orders. We have `fetched_at` + a cooldown we can reuse.
|
||||||
|
- **Black Market**: has **buy orders** scanned by players into AODP under location "Black Market"
|
||||||
|
(id 3003). We already fetch it as a tracked city — the flip finder just needs to use it.
|
||||||
|
- **EMV**: presented as "AI fair value"; functionally a smoothed/median baseline over historical
|
||||||
|
average prices, used to flag over/under-priced orders and filter fake/stale flips.
|
||||||
|
- **Homepage scale (for context)**: ≈106k users; 212.8B flipper profit + 37.8B craft profit
|
||||||
|
reported generated; 4% sales-tax figure referenced in their impact numbers.
|
||||||
Loading…
Reference in a new issue