Phase A: Lock the Skeleton (the core of the first 1–2 sprints)

Purpose: Freeze the parts that would be costly to change later so that subsequent work only adds implementation.

Freeze the API spec

• Deliverable: OpenAPI 3.1 (the YAML already provided) finalized as /openapi/openapi.yaml.
• DoD: Visible under /docs; all base paths enumerated (mock implementation acceptable).

Finalize DDL & migration foundation

• Deliverables:
  sql/000_extensions.sql, 010_portal_core.sql, 020_portal_translate.sql, 030_portal_chroma_doc.sql
  Change already applied: portal_view’s calendar_*_field columns set to text.
• DoD: “Initialize → re-apply” is idempotent in local and CI.

Project skeleton + health endpoints

• Deliverables: /app/main.py (healthz/livez/startupz), /app/config.py, /app/db.py, /app/repos/* skeletons.
• DoD: GET /healthz = 200; logging and config loading both work.

---

Phase B: Complete the Repo Layer (core DB I/O)

Purpose: Make it so that every router only needs to call this layer.

Portal Repos (with writes)

• Files: portal_model_repo.py, portal_field_repo.py, portal_view_common_repo.py, portal_view_repo.py
• Common behaviors: UPSERT / paging / natural-key generation; automatic updated_at touch.
• DoD: CRUD and uniqueness constraints pass unit tests.

IR Source Repos (read-only)

• Files: ir_model_src_repo.py, ir_field_src_repo.py, ir_view_src_repo.py (action-centric)
• DoD: SELECT queries return the expected counts (stubs acceptable initially).

---

Phase C: Make the Odoo Mirror (action-centric) “Queryable”

Purpose: Enable trying Portal imports against production-like data.

• Deliverable: A script (both local and Cron-friendly) that rebuilds public.ir_*_src with the SQL you provided.
• DoD: You can obtain counts for ir_model_src, ir_field_src, ir_view_src.
  Note: K8s CronJobs come later—here we only validate the SQL execution and Repo behavior.

---

Phase D: Implement the Portal “Import APIs” First

Purpose: Stand up the backbone of the Portal as quickly as possible.

• /portal/view_common/import (selective UPSERT by action_xmlid)
• /portal/view_common/bootstrap_view (expand view_types[] → create portal_view skeletons)
• /portal/field/import (selective UPSERT by model/field)
• (4) (if needed) /portal/model/import

DoD: Manual invocation uniquely UPSERTs portal_view_common / portal_view / portal_fields.

---

Phase E: Extraction (enqueue to translate)

Purpose: Idempotently UPSERT translation targets into translate.

• Finalize state machine / natural keys / source_hash for the translate table (spec remains as is).
• /extract/view_common (targets: ai_purpose / help_ja_text — only where JA exists & EN is empty)
• /extract/field (from JA label/notes)

DoD: Repeating the same request aggregates into a single pending (no duplicates).

---

Phase F: Translation (job)

Purpose: Operate a reliable pending → translated pipeline.

• Pluggable translation adapter (provider-swappable).
• /translate/run (limit / target entity / failures marked failed)
• Rule: do not re-translate the same source_hash.

DoD: E2E validation of normal, failed, and re-run cases.

---

Phase G: Packaging (Japanese doc + strict metadata)

Purpose: Produce the final shape to send to Chroma.

• /chroma/package: take only translated → UPSERT into portal_chroma_doc with status queued.
• Doc template (Japanese): format for Field/View + strict metadata (model, model_table, field_name or action_xmlid, etc.)

DoD: doc_id = natural_key::lang is unique; identical source_hash is skipped.

---

Phase H: Chroma Upsert

Purpose: Make content searchable.

• Chroma Client (connectivity / collection creation / embeddings).
• /chroma/upsert (targets queued only; supports dry_run)

DoD: upserted increases by the expected count; simple Japanese queries return hits.

---

Phase I: Write-back (optional) & Status

Purpose: Align with the UI and make operations observable.

• /writeback/view_common & /writeback/field (default mode: skip_if_exists)
• /status/summary, /samples/trace

DoD: For each natural key, you can see the end-to-end status: extract → translate → package → upsert.

---

Phase J: “Development Optimization” for Kubernetes

Purpose: Make development/verification smooth on K8s.

• Health checks (readiness/liveness/startup) implemented for real.
• Bearer auth / audit logging / Request-ID middleware.
• Idempotency-Key (prevent duplicate POST/PUT; backward-compatible).
• Config separation (dev/prod via ConfigMap/Secret switching).

DoD: Rolling updates / re-runs on K8s do not cause double execution or downtime.

---

Phase K: Cron Layer (K8s-oriented)

Purpose: Run the pipeline without human intervention.

• Wire extract → translate → package → upsert as API-call steps using the existing CronJob template.

DoD: The Cron chain naturally moves items from queued → upserted (with retry policy verified for failures).

---

Dependency Summary (shortest path)

• The shortest line to “search working” is: D → E → F → G → H.
• C (Odoo mirror) only needs to be queryable before D.
• I / J / K are quality & operations layers; implement them after the shortest line is working.