# Phase 5 — Rollout and acceptance

## Where to verify (matrix)

| Surface | What to check | Expected |
|--------|-----------------|----------|
| **POS** (`pos.html`) | কার্টে লাইনের নিচে **লস ঝুঁকি** ব্যাজ (ক্রয় গড় > বিক্রয় লাইন রেভিনিউ হলে) | ঝুঁকিপূর্ণ লাইনে ব্যাজ; নইলে নেই |
| **POS** | কার্ট ফুটারে **আনুমানিক গ্রস মার্জিন** ও **লস ঝুঁকি** ব্যানার | ক্রয় ডেটা থাকলে শতাংশ/গ্রস প্রফিট; নিচে কস্টে বিক্রয় থাকলে লাল ব্যানার |
| **POS** | চেকআউটে নিচে কস্টে বিক্রয় হলে **confirm** ডায়ালগ | বাতিল করলে অর্ডার সেভ হয় না |
| **Dashboard → Reports** | শর্টকাট থেকে `analytics.html` খোলা | লগইন + `client_id` থাকলে লোড; টোকেন স্বয়ংক্রিয় সেট |
| **Analytics** | খালি/অসম তারিখ ইনপুট পরে **প্রয়োগ** | শেষ ৩০ দিনে নরমালাইজ বা সোয়াপ; চার্ট খালি/ক্র্যাশ নয় |
| **Analytics** | **অ্যাকশন কিউ** ব্লক | সারি না থাকলেও বক্স দৃশ্যমান + কেন খালি তার ব্যাখ্যা |
| **Fixture** | `runPhase5FixtureChecks()` | `ok: true` |

## Preconditions
- Phase 4 live: POS/dashboard write `unitCost` / `costMethod` on sale/refund ledger rows where possible.
- Finance sign-off on [PHASE5_MARGIN.md](PHASE5_MARGIN.md) formula v2 (bill vs line revenue variance expectation documented).

## Shadow period (recommended 2 weeks)
- Run analytics with date filters covering recent weeks; compare **line net revenue** and **COGS** to internal spreadsheet samples.
- Use **Day-close reconciliation** panel for 5 sample days; record `varianceBillVsLine` and investigate outliers (discounts, mixed tax, delivery fees).
- Action queue: triage items without changing prices; validate false-positive rate.

## Acceptance gates
- **Performance**: analytics interactive refresh under target for tenant’s typical dataset (e.g. under 3s on mid laptop) after first load; if not met, narrow default date window.
- **Variance**: median absolute `bill vs line` % below `siteSettings.marginAnalytics.phase5.reconVariancePct` (default 2%) for validated sample days, or documented exceptions list.
- **Data quality**: missing-cost SKU count trending down week over week.

## Go-live
- Enable CSV export for weekly finance email.
- Train ops on global filters (date, channel, category, weighted-only) and drilldown modal.

## Rollback
- Revert `analytics.html` imports and UI blocks; core writers (`pos.html`, `dashboard.js`) unchanged by Phase 5.
- `margin-analytics.js` Phase 5 exports are additive; older callers remain valid.

## Fixture regression
- Run `runMarginAnalyticsFixtureChecks()` and **`runPhase5FixtureChecks()`** from [f:/14/margin-analytics-fixtures.js](f:/14/margin-analytics-fixtures.js) in Node or devtools.

## Troubleshooting

### “Access Denied” on Analytics
- **কারণ**: Firebase এ লগইন নেই, `localStorage.client_id` নেই, অথবা `detective-brain` (Reports) অনুমতি নেই এবং ড্যাশবোর্ডের **Reports** লিঙ্ক দিয়ে প্রবেশ করা হয়নি।
- **সমাধান**: ড্যাশবোর্ড হোমে লগইন করুন → **Reports** টিপুন (এটি `analytics_token` সেট করে) → পেজ খুলবে। **মালিক/অ্যাডমিন** Firebase অনুযায়ী সরাসরি খুলতে পারেন। **স্টাফ** হলে `detective-brain` (Reports) অনুমতি চালু করুন, অথবা শুধু ড্যাশবোর্ডের Reports শর্টকাট ব্যবহার করুন।

### POS এ মার্জিন স্ট্রিপ দেখা যায় না
- **কারণ**: ক্রয় (`purchases`) বা লেজারে কোনো কস্ট ডেটা নেই → গড় ইউনিট কস্ট তৈরি হয় না।
- **সমাধান**: `purchase-add` দিয়ে ক্রয় রেকর্ড যোগ করুন বা ইনভেন্টরি লেজারে purchase ইভেন্ট নিশ্চিত করুন।

### তারিখ বদলালে চার্ট অদ্ভুত
- গ্লোবাল ফিল্টারে **শুধু এক পাশ** খালি থাকলে সিস্টেম স্বয়ংক্রিয়ভাবে মিরর/ডিফল্ট করে; তবুও সমস্যা হলে দুটি ফিল্ডই `YYYY-MM-DD` ফরম্যাটে পূরণ করুন।
