chore(conductor): Add new track 'Refactor the meal tracking system to decouple 'Journal Logs' from 'Cookbook Recipes''

conductor/tracks.md

@@ -3,3 +3,6 @@
 This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
 
 ---
+
+- [ ] **Track: Refactor the meal tracking system to decouple 'Journal Logs' from 'Cookbook Recipes'**
+*Link: [./tracks/meal_tracker_refactor_20250223/](./tracks/meal_tracker_refactor_20250223/)*

conductor/tracks/meal_tracker_refactor_20250223/index.md

@@ -0,0 +1,5 @@
+# Track meal_tracker_refactor_20250223 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/tracks/meal_tracker_refactor_20250223/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "meal_tracker_refactor_20250223",
+  "type": "refactor",
+  "status": "new",
+  "created_at": "2025-02-23T12:00:00Z",
+  "updated_at": "2025-02-23T12:00:00Z",
+  "description": "Refactor the meal tracking system to decouple 'Journal Logs' from 'Cookbook Recipes', resolving database pollution and improving system structure."
+}

conductor/tracks/meal_tracker_refactor_20250223/plan.md

@@ -0,0 +1,28 @@
+# Implementation Plan - Meal Tracker Refactoring
+
+This plan outlines the steps for refactoring the meal tracking system to decouple "Journal Logs" from "Cookbook Recipes," resolving database pollution and improving system structure.
+
+## Phase 1: Preparation & Schema Updates
+- [ ] Task: Create a new branch for the refactoring track.
+- [ ] Task: Add the 'name' column to the 'TrackedMeal' table and make 'meal_id' nullable in 'app/database.py'.
+- [ ] Task: Create and run an Alembic migration for the schema changes.
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Preparation & Schema Updates' (Protocol in workflow.md)
+
+## Phase 2: Logic & Calculation Updates
+- [ ] Task: Write failing unit tests for 'calculate_tracked_meal_nutrition' with 'meal_id=None'.
+- [ ] Task: Implement support for 'meal_id=None' in 'calculate_tracked_meal_nutrition' within 'app/database.py'.
+- [ ] Task: Write failing unit tests for the refactored 'tracker_add_food' endpoint.
+- [ ] Task: Refactor the 'tracker_add_food' route in 'app/api/routes/tracker.py' to use the new 'TrackedMeal' structure.
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: Logic & Calculation Updates' (Protocol in workflow.md)
+
+## Phase 3: UI & Cookbook Refinement
+- [ ] Task: Update the 'tracker.html' template to display 'TrackedMeal.name' for template-less logs.
+- [ ] Task: Update the Meals page in 'app/api/routes/meals.py' to filter out 'single_food' and 'snapshot' types.
+- [ ] Task: Write failing E2E tests for the new tracking workflow.
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: UI & Cookbook Refinement' (Protocol in workflow.md)
+
+## Phase 4: Database Migration & Cleanup
+- [ ] Task: Create a Python migration script for cleaning up existing 'single_food' entries.
+- [ ] Task: Run the migration script on the development PostgreSQL database.
+- [ ] Task: Verify the database state and ensure no orphans remain.
+- [ ] Task: Conductor - User Manual Verification 'Phase 4: Database Migration & Cleanup' (Protocol in workflow.md)

conductor/tracks/meal_tracker_refactor_20250223/spec.md

@@ -0,0 +1,28 @@
+# Specification - Meal Tracker Refactoring
+
+**Overview:**
+Refactor the meal tracking system to decouple "Journal Logs" from "Cookbook Recipes". Currently, adding a single food item via the tracker incorrectly creates a permanent 'Meal' record of type 'single_food', leading to database pollution and duplicate entries in the Meals library.
+
+**Functional Requirements:**
+- **TrackedMeal Schema Update:** Add a 'name' column to the 'TrackedMeal' model to store the display name of a logged meal or a single food item.
+- **Nullable meal_id:** Modify 'TrackedMeal.meal_id' to be nullable, allowing "template-less" logs.
+- **Refactored Tracker Logic:** Update the 'tracker_add_food' route to log single items directly as a 'TrackedMeal' with 'meal_id=NULL' and the 'name' set to the food item's name.
+- **Nutrition Calculation:** Update nutrition calculation logic to handle 'TrackedMeal' entries without a parent 'Meal' template.
+- **Tracker UI Update:** Ensure the tracker page displays 'TrackedMeal.name' for these logs and maintains the seamless visual style of existing entries.
+- **Cookbook Cleanup (One-time Migration):** Migrate existing 'single_food' meals to the new format and purge the redundant records from the 'meals' and 'meal_foods' tables.
+- **Cookbook Filtering:** Update the Meals page to exclude 'single_food' and 'snapshot' meal types from view.
+
+**Non-Functional Requirements:**
+- **Database Integrity:** Ensure all existing logs remain accurate and correctly linked to their food items during migration.
+- **Performance:** The tracker page should remain fast and responsive with the new logic.
+
+**Acceptance Criteria:**
+- [ ] Adding a single food to the tracker does **not** create a new entry in the 'meals' table.
+- [ ] Existing 'single_food' duplicates are removed from the 'meals' library.
+- [ ] The Meals page only shows "Cookbook Recipes" (e.g., proper combined meals).
+- [ ] The Tracker page correctly displays names and calculates nutrition for all logs (both template-based and template-less).
+- [ ] "Save as New Meal" remains available for all log entries, including single foods.
+
+**Out of Scope:**
+- Refactoring the entire meal planning system beyond the tracker/cookbook separation.
+- Changes to the external Open Food Facts integration.