Docs: Taxonomy cache refresh logic — middle-tier anchor, client re-pull, and triggers #14

New Issue

2026-09-01T23:09:50Z

Ty commented

2026-09-01 23:09:50 +00:00

Docs: Taxonomy cache refresh logic — middle-tier anchor, client re-pull, and triggers

Summary

WooCommerce's REST API exposes no last-modified timestamp on categories, attributes, or tags — only products carry date_modified. The middle tier (FastAPI) must therefore manufacture its own freshness anchor, since the client never talks to Woo directly and reads taxonomy exclusively from the middle tier's SQLite cache.

This issue captures the agreed refresh model so the docs state it explicitly rather than leaving it implied.

Current plan of record (gap)

CONTENT-WOO defines POST /api/admin/taxonomy/sync, which pulls categories, attributes, and tags, rebuilds the cache tables in a single transaction, and on failure returns 502 while keeping the previous cache. The only documented freshness rule is opportunistic: before product create, re-sync "if cache older than one hour." There is no stated anchor, no client-visible freshness signal, and no defined set of refresh triggers.

Agreed model

Anchor

The middle tier owns a single last-modified timestamp for the taxonomy cache.
The anchor bumps only when a row-level change is detected in the stored subset of fields across the cache tables (categories, attributes, tags) after a sync write — i.e., the diff is against what the middle tier actually persists, not the full Woo payload.
A no-op sync (nothing in the stored subset changed) does not bump the anchor, so the client does not churn its cache for nothing.
Scope is schema-driven: any column present in the cache tables counts. Adding a field later (e.g. menu_order) automatically brings that field's changes into scope without touching the refresh logic. Reorder is currently a no-op only because the schema does not store it — not because reorder is semantically excluded.
Spelling/name edits, additions, and deletions in the stored subset all bump the anchor. The diff must catch missing rows (deletions) as well as changed rows.

Client behavior

The client reads the anchor timestamp from the middle tier.
If the anchor is newer than the client's last known value, the client re-pulls the full taxonomy cache; otherwise it uses its local copy.
One timestamp, one re-pull decision — applies uniformly to categories, attributes, and tags.

Triggers

Test connection — a successful connection test always performs a category and attribute resync (already agreed; DOR). This is the gate that unlocks the species list, so the user always sees current taxonomy right after proving the connection.
Product submission — the middle tier checks the one-hour threshold at publish time, reconciles against its internal cache, and bumps the anchor only if the stored subset actually changed. This is the opportunistic refresh already partially documented; this issue makes the anchor semantics explicit.
App launch (optional, cheap) — check the anchor; sync only if stale. Not required for POC but noted as a natural fit.
Manual refresh in Settings — optional affordance; not required for POC.

Avoid syncing on every screen navigation — that hammers the Woo API for no benefit.

Required doc changes

CONTENT-WOO.md — state the manufactured anchor, the stored-subset diff rule, the no-op-doesn't-bump rule, and the trigger set (test connection, submission, optional launch/manual).
ARCHITECTURE.md — the middle-tier cache + anchor as the sole freshness source; client reads anchor, never queries Woo.
IMPL-PLAN.md — acceptance criteria covering: anchor bumps on real stored-subset change, stays put on no-op sync, client re-pulls only on bump, test-connection always resyncs, submission respects the one-hour threshold with reconciliation.
AGENTS.md — precedence note so agents don't invent a Woo-side timestamp or a per-table anchor.
OPENAPI.md — the sync and settings endpoints expose the anchor timestamp to the client.

Acceptance criteria

Docs state that Woo provides no taxonomy timestamp and the middle tier manufactures one.
Anchor bumps only on row-level change in the stored subset of cache fields, across categories, attributes, and tags.
No-op sync does not bump the anchor.
Client re-pulls the full cache iff the anchor advanced; one timestamp governs all metadata types.
Test connection always triggers a resync.
Product submission triggers a reconciled refresh subject to the one-hour threshold.
Scope is schema-driven: future cache columns are automatically in scope.
No doc implies a Woo-side last_modified exists for categories, attributes, or tags.

Labels / priority

Non-blocking for POC (the one-hour opportunistic rule already works), but required before the taxonomy flow is considered complete. Linked to docs/refactor-v2.

# Docs: Taxonomy cache refresh logic — middle-tier anchor, client re-pull, and triggers ## Summary WooCommerce's REST API exposes **no last-modified timestamp** on categories, attributes, or tags — only products carry `date_modified`. The middle tier (FastAPI) must therefore manufacture its own freshness anchor, since the client never talks to Woo directly and reads taxonomy exclusively from the middle tier's SQLite cache. This issue captures the agreed refresh model so the docs state it explicitly rather than leaving it implied. ## Current plan of record (gap) CONTENT-WOO defines `POST /api/admin/taxonomy/sync`, which pulls categories, attributes, and tags, rebuilds the cache tables in a single transaction, and on failure returns 502 while keeping the previous cache. The only documented freshness rule is opportunistic: before product create, re-sync "if cache older than one hour." There is no stated anchor, no client-visible freshness signal, and no defined set of refresh triggers. ## Agreed model ### Anchor - The middle tier owns a single **last-modified timestamp** for the taxonomy cache. - The anchor bumps **only** when a row-level change is detected in the stored subset of fields across the cache tables (categories, attributes, tags) after a sync write — i.e., the diff is against what the middle tier actually persists, not the full Woo payload. - A no-op sync (nothing in the stored subset changed) does **not** bump the anchor, so the client does not churn its cache for nothing. - Scope is schema-driven: any column present in the cache tables counts. Adding a field later (e.g. `menu_order`) automatically brings that field's changes into scope without touching the refresh logic. Reorder is currently a no-op only because the schema does not store it — not because reorder is semantically excluded. - Spelling/name edits, additions, and deletions in the stored subset all bump the anchor. The diff must catch missing rows (deletions) as well as changed rows. ### Client behavior - The client reads the anchor timestamp from the middle tier. - If the anchor is newer than the client's last known value, the client re-pulls the full taxonomy cache; otherwise it uses its local copy. - One timestamp, one re-pull decision — applies uniformly to categories, attributes, and tags. ### Triggers 1. **Test connection** — a successful connection test always performs a category and attribute resync (already agreed; DOR). This is the gate that unlocks the species list, so the user always sees current taxonomy right after proving the connection. 2. **Product submission** — the middle tier checks the one-hour threshold at publish time, reconciles against its internal cache, and bumps the anchor only if the stored subset actually changed. This is the opportunistic refresh already partially documented; this issue makes the anchor semantics explicit. 3. **App launch (optional, cheap)** — check the anchor; sync only if stale. Not required for POC but noted as a natural fit. 4. **Manual refresh in Settings** — optional affordance; not required for POC. Avoid syncing on every screen navigation — that hammers the Woo API for no benefit. ## Required doc changes - **CONTENT-WOO.md** — state the manufactured anchor, the stored-subset diff rule, the no-op-doesn't-bump rule, and the trigger set (test connection, submission, optional launch/manual). - **ARCHITECTURE.md** — the middle-tier cache + anchor as the sole freshness source; client reads anchor, never queries Woo. - **IMPL-PLAN.md** — acceptance criteria covering: anchor bumps on real stored-subset change, stays put on no-op sync, client re-pulls only on bump, test-connection always resyncs, submission respects the one-hour threshold with reconciliation. - **AGENTS.md** — precedence note so agents don't invent a Woo-side timestamp or a per-table anchor. - **OPENAPI.md** — the sync and settings endpoints expose the anchor timestamp to the client. ## Acceptance criteria - [ ] Docs state that Woo provides no taxonomy timestamp and the middle tier manufactures one. - [ ] Anchor bumps only on row-level change in the **stored subset** of cache fields, across categories, attributes, and tags. - [ ] No-op sync does not bump the anchor. - [ ] Client re-pulls the full cache iff the anchor advanced; one timestamp governs all metadata types. - [ ] Test connection always triggers a resync. - [ ] Product submission triggers a reconciled refresh subject to the one-hour threshold. - [ ] Scope is schema-driven: future cache columns are automatically in scope. - [ ] No doc implies a Woo-side `last_modified` exists for categories, attributes, or tags. ## Labels / priority Non-blocking for POC (the one-hour opportunistic rule already works), but required before the taxonomy flow is considered complete. Linked to `docs/refactor-v2`.

Ty added this to the POC milestone 2026-09-01 23:49:46 +00:00

grokbot_ty referenced this issue from a commit

2026-09-02 00:34:50 +00:00

docs: pair locks for #14 #2 #17 #18 (PPM product OK)

Ty referenced this issue

2026-09-03 02:36:57 +00:00

Test plan: POC acceptance test cases for all milestone issues #19

Ty closed this issue

2026-09-03 03:28:03 +00:00

Sign in to join this conversation.