# PHASE 01: PLUGIN FOUNDATION, STATUSES, META AND INSTALLER

Read `docs/06-DATA-MODEL.md` in full and `docs/07-DECISION-LOG.md` entries D-02, D-04, D-05, D-09.

## Scope

The data layer. Order statuses, the typed meta accessor, the two custom tables, settings, roles and the audit trail. No admin UI yet, no checkout changes yet.

## Build

1. `BC_Installer`: `dbDelta` for `bc_order_stats`, `bc_order_stat_items` and `bc_settlements` exactly as specified in the data model, with the indexes named. A `bc_db_version` option, not autoloaded, and an upgrade routine that runs on version mismatch.
2. `BC_Activator`: creates tables, registers the custom capabilities on Administrator and Shop Manager, seeds `bc_settings` with the defaults from data model section 5, flushes rewrite and status registration.
3. `BC_Order_Statuses`: registers `wc-bc-verify`, `wc-bc-shipped`, `wc-bc-rto` on `init`. Labels all eight statuses on `wc_order_statuses`, including relabelling `wc-processing` to Confirmed and `wc-completed` to Delivered. Each custom status gets a distinct colour in the order list.
   **Paid and reporting statuses, read the data model section 1 carefully.** Add only `wc-completed` to `woocommerce_order_is_paid_statuses`, never `wc-bc-shipped`: on a COD order no money exists until the rider collects it. And WooCommerce Analytics does not read `woocommerce_reports_order_statuses`, which only drives the deprecated legacy reports. Set the `woocommerce_excluded_report_order_statuses` and `woocommerce_actionable_order_statuses` **options** on activation instead, or the dashboard in phase 10 will never reconcile with Analytics.
4. `BC_Order_Meta`: a typed accessor over the CRUD API. One getter and one setter per meta key in data model section 2, each with the right cast and an allowed-values guard on enum fields. **This class is the only place in the codebase that touches order meta directly.** Everything else calls it.
5. `BC_Order_Timeline`: subscribes to `woocommerce_order_status_changed`, plus the custom actions `bc_verification_changed`, `bc_fulfilment_changed`, `bc_cod_changed` and `bc_settlement_changed`. Every one of these must be **fired** by the class that owns it in phase 9. An action with a listener and no emitter is a hole in the audit trail. Writes a structured order note for each, naming the acting user and the old and new value. This is the single audit trail, there is no separate log table.
6. `BC_Stats_Writer`: upserts the `bc_order_stats` row on the same events. Idempotent.
7. `BC_Settings`: a settings API page under WooCommerce, tabbed, writing to the single `bc_settings` option. Fields for every key in data model section 5.
8. `BC_CLI`: `wp bc rebuild-stats` that truncates and rebuilds `bc_order_stats` and `bc_order_stat_items` from orders in batches of 200, and `wp bc seed-demo` that creates 20 demo products and 30 demo orders across the statuses.
9. `BC_Tools`: an admin page exposing the same rebuild through Action Scheduler in batches of 200, with a progress readout. **Namecheap shared plans usually have no SSH, so a CLI-only rebuild path does not exist on the launch host.** The CLI command is developer convenience; this button is the one that has to work in production.
9. `uninstall.php`: drops the tables and the options only when a `bc_delete_data_on_uninstall` setting is on. Default off.

## Acceptance criteria

- [ ] Activating on a clean install creates both tables with the specified columns and indexes, verified in the database
- [ ] Deactivating and reactivating does not duplicate or error
- [ ] All eight statuses appear in the order list status filter with the correct labels
- [ ] Changing an order to Confirmed reduces stock, exactly as `wc-processing` normally does
- [ ] `wp bc seed-demo` creates orders across all statuses
- [ ] Every status change writes an order note naming the user
- [ ] `bc_order_stats` has one correct row per seeded order, and `bc_order_stat_items` one row per line
- [ ] Only `wc-completed` is in `woocommerce_order_is_paid_statuses`, verified by dumping the filter output
- [ ] The admin rebuild button completes on 1,000 seeded orders without a timeout
- [ ] `wp bc rebuild-stats` reproduces identical rows after a truncate
- [ ] `grep -rn "get_post_meta\|update_post_meta" wp-content/plugins/brand-commerce` returns nothing that touches an order
- [ ] `composer run lint` passes

## Stop

No admin metabox, no checkout fields, no COD logic, no front end. Those are phases 8 and 9.