F-002 fix: Remove secrets and externalize config

spec/acceptance.md

@@ -1,9 +1,36 @@
-# Acceptance Criteria
+# Acceptance Spec
 
-Define criterios verificables por feature.
+## F-001 — Document and move legacy PHP app into ARNES project layout
 
-Formato recomendado:
-- Feature ID:
-- Escenario:
-- Given / When / Then:
-- Evidencia esperada (test/comando):
+### Acceptance criteria
+- Legacy PHP app structure is documented in SDD files.
+- Repo layout decision is recorded in one ADR.
+- Legacy code moves from `project/new` to `project/web/index/new` with no file loss.
+- SQL dump moves from `project/db-25052026.sql` to `project/sql/db-25052026.sql`.
+- `./scripts/verify.sh` stays green after the move.
+
+### Evidence targets
+- `spec/sdd/architecture.md`
+- `spec/sdd/components/*.md`
+- `spec/sdd/decisions/001-store-legacy-app-under-project-web.md`
+- `spec/bdd/features/layout/legacy-app-layout.feature`
+- `work/artifacts/F-001/architect.md`
+
+## F-002 — Remove secrets and externalize config
+
+### Acceptance criteria
+- No hard-coded API or DB secrets stay in versioned PHP files.
+- Config values load from one local config source for the legacy module.
+- Production URLs and external endpoints are configurable.
+- Legacy PHP entry points use config helper keys instead of inline values.
+- `./scripts/verify.sh` stays green after the change.
+
+### Evidence targets
+- `project/web/index/new/bootstrap.php`
+- `project/web/index/new/config/local.example.php`
+- `project/web/index/new/config/README.md`
+- `spec/sdd/components/legacy-config-loader.md`
+- `spec/sdd/decisions/002-use-local-config-loader-for-legacy-module.md`
+- `spec/bdd/features/config/legacy-config.feature`
+- `work/artifacts/F-002/architect.md`
+- `work/artifacts/F-002/implementer.md`

spec/bdd/features/config/legacy-config.feature

@@ -0,0 +1,20 @@
+@F-002 @smoke @security @regression
+Feature: Legacy module reads config from one local source
+
+  As a maintainer
+  I want secrets and URLs outside tracked PHP files
+  So I can run the legacy module without storing sensitive values in source
+
+  Scenario: Entry points use shared config helper
+    Given the legacy PHP module has multiple web and CLI entry points
+    When feature F-002 is applied
+    Then tracked PHP files do not contain hard-coded DB credentials
+    And tracked PHP files do not contain hard-coded OpenAI credentials
+    And DB and route values are loaded through a shared config helper
+
+  Scenario: Local config shape is documented
+    Given a maintainer needs to set local credentials
+    When feature F-002 is applied
+    Then the repo contains a versioned local config example
+    And the repo ignores the real local config file
+    And setup notes explain how to create the local config

spec/bdd/features/layout/legacy-app-layout.feature

@@ -0,0 +1,25 @@
+@F-001 @smoke @regression
+Feature: Legacy app lives in stable ARNES layout
+
+  As a maintainer
+  I want the copied legacy PHP app in a stable repo path
+  So I can trace design and change code safely
+
+  Scenario: Web module path is explicit
+    Given the repo contains legacy PHP product module files
+    When feature F-001 is applied
+    Then the module lives under "project/web/index/new"
+    And the old temporary path "project/new" is removed
+
+  Scenario: Development SQL baseline is explicit
+    Given the repo contains one SQL dump for local development
+    When feature F-001 is applied
+    Then the dump lives under "project/sql/db-25052026.sql"
+    And the dump is referenced by SDD docs as development baseline only
+
+  Scenario: Design trace exists for the move
+    Given feature F-001 is in progress
+    When the design stage is complete
+    Then SDD architecture docs exist for the legacy app
+    And one ADR records the repo layout move
+    And architect evidence exists under "work/artifacts/F-001/architect.md"

spec/product.md

@@ -1,15 +1,49 @@
 # Product Spec
 
-## Problema
-Describe el problema de negocio.
+## Problem
+Legacy PHP app lives in temporary path `project/new`.
+SQL dump lives mixed with app code.
+There is no ARNES design record for this code.
+This makes next change work risky and hard to trace.
 
-## Objetivo
-Define el resultado esperado del producto.
+## Objective
+Put legacy app in stable ARNES project layout.
+Keep same code and same behavior for now.
+Make next work easy to trace, review, and test.
 
-## Usuarios
-- Usuario principal:
-- Usuario secundario:
+## Users
+- Primary user: maintainer of legacy PHP app
+- Secondary user: architect, implementer, reviewer, qa
 
-## Alcance v1
+## Scope v1
 - In scope:
+  - document current legacy app structure
+  - define target repo layout
+  - move app code to `project/web/index/new`
+  - move SQL dump to `project/sql/db-25052026.sql`
 - Out of scope:
+  - auth rewrite
+  - OpenAI secret cleanup
+  - production deploy
+  - feature refactor
+
+## F-002 — Remove secrets and externalize config
+
+### Problem
+Legacy PHP files still contain API keys, DB credentials, and production URLs.
+This blocks security approval and makes local setup unsafe.
+
+### Objective
+Load config from one local source outside versioned code.
+Keep page behavior the same while removing hard-coded secrets from tracked PHP files.
+
+### Scope
+- In scope:
+  - one config loader for legacy module
+  - one local config file shape for DB, OpenAI, URLs, and endpoints
+  - replace hard-coded values in tracked PHP files
+  - setup notes for local config
+- Out of scope:
+  - auth redesign
+  - worker refactor beyond config use
+  - deploy automation

spec/sdd/architecture.md

@@ -0,0 +1,47 @@
+# Architecture Overview — Legacy PHP Product Module
+
+## Context
+This repo holds one legacy PHP module copied from production.
+The module helps product staff create products and generate SEO text.
+The module also runs one batch worker that updates OpenCart product descriptions.
+
+Current raw source path was `project/new`.
+Target stable path is `project/web/index/new`.
+SQL dump target path is `project/sql/db-25052026.sql`.
+
+## Main flows
+1. User opens product form.
+2. Form reads OpenCart data from MariaDB.
+3. User can open AI helper page for one product text.
+4. Bulk page writes product ids into `oc_product_queue`.
+5. CLI worker reads queue, calls OpenAI, updates `oc_product_description`.
+
+## Constraints
+- Keep legacy behavior unchanged in layout and config features.
+- Preserve file contents during move unless config externalization requires value lookup changes.
+- Keep evidence in repo for each design change.
+- Do not redesign auth or deploy in these features.
+
+## System view
+```mermaid
+graph TD
+    U[Backoffice user] --> F[Legacy PHP web module]
+    F --> DB[(MariaDB / OpenCart)]
+    F --> Q[oc_product_queue]
+    W[worker_bulk.php CLI worker] --> Q
+    W --> AI[OpenAI API]
+    W --> DB
+```
+
+## Files and responsibilities
+- `bootstrap.php`: shared local config loader and DB helper
+- `config/local.example.php`: versioned config shape
+- `config/local.php`: ignored local values file
+- `index.php`: manual product create form
+- `describe.php`: one-shot AI description helper
+- `productos_bulk_update.php`: queue intake and worker log viewer
+- `productos_modificados.php`: review processed items
+- `worker_bulk.php`: batch generator and DB updater
+- `inc/*`: shared layout, prompts, AJAX helpers
+- `db/conn.php`: shared DB connection for web pages
+- `logs/*`: runtime debug output from worker and AI calls

spec/sdd/components/bulk-seo-worker.md

@@ -0,0 +1,33 @@
+# Component: Bulk SEO worker
+
+## Responsibility
+Read product ids from queue.
+Call OpenAI with EN and ES prompts.
+Clean output.
+Update OpenCart product description fields.
+Write processing logs.
+
+## Interfaces
+- Input:
+  - CLI run of `worker_bulk.php`
+  - rows from `oc_product_queue`
+  - prompt files `inc/prompt_en.md` and `inc/prompt_es.md`
+- Output:
+  - updates in `oc_product_description`
+  - status fields in `oc_product_queue`
+  - log files under `logs/`
+
+## Dependencies
+- MariaDB/MySQL
+- OpenAI Chat Completions API
+- local prompt markdown files
+
+## Limits
+- No secret management yet.
+- No retry queue store outside DB.
+- No metrics or structured logs.
+
+## Success criteria
+- [ ] Worker path is documented
+- [ ] Queue and DB side effects are known
+- [ ] Log location is explicit in design docs

spec/sdd/components/development-data-baseline.md

@@ -0,0 +1,24 @@
+# Component: Development data baseline
+
+## Responsibility
+Provide one local SQL dump so maintainers can inspect schema and seed dev database.
+
+## Interfaces
+- Input:
+  - SQL import command run by maintainer
+- Output:
+  - local MariaDB database with OpenCart and custom tables
+
+## Dependencies
+- `project/sql/db-25052026.sql`
+- local MariaDB/MySQL server
+
+## Limits
+- Dump may contain production-like data.
+- Dump is large.
+- Dump is not safe for public sharing without review.
+
+## Success criteria
+- [ ] Dump path is stable and explicit
+- [ ] Design docs call it dev baseline only
+- [ ] Move does not alter dump content

spec/sdd/components/legacy-config-loader.md

@@ -0,0 +1,30 @@
+# Component: Legacy config loader
+
+## Responsibility
+Load local configuration for the legacy PHP module.
+Expose helper access for DB, OpenAI, URLs, endpoints, and path values.
+Provide one DB connection factory used by web pages and worker.
+
+## Interfaces
+- Input:
+  - `config/local.php` if present
+  - fallback `config/local.example.php` for shape and safe defaults
+- Output:
+  - config access helpers
+  - mysqli connection helper
+  - normalized path values for logs and routes
+
+## Dependencies
+- PHP array config files
+- `mysqli`
+- module root path
+
+## Limits
+- Does not manage secret rotation.
+- Does not validate remote credentials.
+- Does not redesign auth or downstream business logic.
+
+## Success criteria
+- [ ] No tracked PHP file contains hard-coded DB or OpenAI secrets
+- [ ] Entry points use shared config helper
+- [ ] Local setup path is documented

spec/sdd/components/legacy-web-module.md

@@ -0,0 +1,32 @@
+# Component: Legacy web module
+
+## Responsibility
+Serve old PHP pages for product create and product SEO work.
+Render HTML.
+Read OpenCart data.
+Write queue rows for batch processing.
+
+## Interfaces
+- Input:
+  - browser GET and POST requests
+  - session state from external login flow
+- Output:
+  - HTML pages
+  - inserts into `oc_product_queue`
+  - writes brand rows and URL alias rows
+
+## Dependencies
+- `db/conn.php`
+- `inc/header.php`, `inc/footer.php`
+- OpenCart tables
+- external `success.php` and `login.php` outside repo
+
+## Limits
+- Does not own authentication.
+- Does not own final product creation endpoint.
+- Uses hard-coded config today.
+
+## Success criteria
+- [ ] Module files live under stable repo path
+- [ ] Relative module structure stays intact
+- [ ] Pages can still be reviewed as one legacy unit

spec/sdd/decisions/001-store-legacy-app-under-project-web.md

@@ -0,0 +1,33 @@
+# ADR-001: Store legacy app under project web path
+
+## Status
+Accepted
+
+## Context
+Legacy PHP code was copied into `project/new`.
+That path does not explain app role.
+SQL dump also sits beside code in `project/` root.
+We need stable layout before deeper refactor.
+
+## Decision
+Store legacy web code under `project/web/index/new`.
+Store SQL dump under `project/sql/db-25052026.sql`.
+Keep internal legacy file tree unchanged inside module.
+Do not refactor code in same step.
+
+## Consequences
+- Good:
+  - repo layout shows what is web code and what is data
+  - ARNES design docs can point to stable paths
+  - future config and secret cleanup gets easier
+- Bad:
+  - move may require path-aware follow-up in later features
+  - repo still contains legacy secrets until later cleanup
+
+## Alternatives considered
+1. Keep code in `project/new` - rejected because path is temporary and vague.
+2. Move code to `project/app` - rejected because this is web module, not service code.
+3. Refactor layout and code now - rejected because scope would grow too much.
+
+## Date
+2026-05-25

spec/sdd/decisions/002-use-local-config-loader-for-legacy-module.md

@@ -0,0 +1,33 @@
+# ADR-002: Use local config loader for legacy module
+
+## Status
+Accepted
+
+## Context
+Security gate for F-001 failed.
+Legacy PHP files still hold DB credentials, OpenAI keys, and production-coupled URLs.
+The module needs one small config mechanism without large refactor.
+
+## Decision
+Add `bootstrap.php` to the legacy module root.
+Load config from `config/local.php` with fallback to `config/local.example.php`.
+Expose shared helper functions for config lookup and DB connection.
+Update web pages and worker to read DB, OpenAI, route, and URL values through this helper.
+Ignore `config/local.php` in git.
+
+## Consequences
+- Good:
+  - secrets leave tracked PHP source files
+  - one config shape is reused by web pages and worker
+  - local setup becomes explicit
+- Bad:
+  - module still depends on local file management
+  - fallback example config can still fail at runtime until maintainer fills real values
+
+## Alternatives considered
+1. Use environment variables only - rejected because this legacy module already expects file-based setup.
+2. Keep secrets in PHP constants - rejected because tracked source would still hold sensitive values.
+3. Full framework migration - rejected because scope is too large for this fix.
+
+## Date
+2026-05-25

spec/tech.md

@@ -1,19 +1,37 @@
 # Technical Spec
 
 ## Stack
-- Lenguaje:
-- Framework:
-- Runtime:
+- Language: PHP, JavaScript, CSS
+- Framework: legacy custom PHP + OpenCart database schema
+- Runtime: Apache/Nginx + PHP, MariaDB/MySQL, CLI worker for batch jobs
 
-## Restricciones
-- Seguridad:
-- Rendimiento:
-- Compatibilidad:
+## Restrictions
+- Security:
+  - do not expose secrets in new docs
+  - keep real dump as local dev input only
+- Performance:
+  - file move must not change app code behavior
+- Compatibility:
+  - preserve relative file structure inside legacy module
+  - preserve SQL dump file content
 
-## Dependencias
-Lista y justificación de dependencias externas.
+## Dependencies
+- MariaDB/MySQL dump from `project/sql/db-25052026.sql`
+- OpenCart tables like `oc_product`, `oc_product_description`, `oc_product_queue`
+- OpenAI API used by legacy scripts
+- External login and success endpoints exist outside this repo
 
-## Observabilidad
+## Observability
 - Logging:
-- Métricas:
-- Alertas:
+  - current legacy logs live under module `logs/`
+- Metrics:
+  - none in repo now
+- Alerts:
+  - none in repo now
+
+## F-002 technical notes
+- Add `bootstrap.php` in legacy module root.
+- Add config files under `project/web/index/new/config/`.
+- Versioned file stores example values only.
+- Ignored local file stores real local secrets and URLs.
+- All PHP entry points must read DB, OpenAI, and route values through config helper.