# Tabriz Soghat — Master Implementation Spec

## Mission

Improve the existing Laravel e-commerce application for Tabriz Soghat without breaking current production behavior.

The implementation target is LOCAL first, using a copy of the LIVE database. No direct changes to production.

The work is divided into:
1. Technical and On-page SEO
2. Blog / content system
3. Category hierarchy
4. Wholesale carton rules
5. Menu builder
6. Bug fixing / regression hardening
7. Local environment and production-safe deployment preparation

## Non-negotiable rules

- First inspect the existing repository, migrations, models, routes, controllers, services, resources, Blade views, Vue/JS if present, policies, tests, jobs, commands, config, and existing blog/menu/category code.
- Do not rewrite working systems just because a cleaner architecture is possible.
- Prefer incremental changes and reuse existing services/components.
- Do not rename database columns or routes unless necessary; when changing public URLs, preserve compatibility with 301 redirects.
- Do not delete production data.
- Add migrations for schema changes.
- Add/extend automated tests for every behavior change.
- Keep SEO output server-rendered where possible.
- Preserve Persian RTL behavior.
- Preserve existing authentication, cart, checkout, payment, order, inventory, coupon, shipping, and admin behavior.
- Never hardcode business rules in Blade/JS when they belong in domain/service logic.
- All business rules must be testable independently from UI.

## Required workflow

### Phase A — Audit before coding

Produce:
- architecture map
- database/entity map
- route map
- current category/product/menu/blog inventory
- current SEO implementation
- list of existing bugs found
- list of current migrations relevant to these features
- list of existing tests
- list of potentially reusable code

Do not make feature changes before this audit.

### Phase B — Safe local clone

Document:
- local Laravel setup
- `.env` values required
- database import procedure
- storage/link setup
- queue/cron/local scheduler requirements
- cache/session requirements
- payment gateway sandbox/mock behavior
- image/file storage strategy

Never copy production secrets into the repository.

### Phase C — Implement

Implement the separate specs in this repository:
- `01-SEO-SPEC.md`
- `02-BLOG-SPEC.md`
- `03-CATEGORY-HIERARCHY-SPEC.md`
- `04-WHOLESALE-CARTON-RULE-SPEC.md`
- `05-MENU-BUILDER-SPEC.md`
- `06-BUG-AND-QA-SPEC.md`

### Phase D — Verification

Before declaring done:
- run migrations from clean DB
- run full test suite
- run feature-specific tests
- check Laravel logs
- check browser console
- crawl local site with a crawler if available
- validate important JSON-LD
- validate canonical URLs
- validate sitemap
- test desktop/mobile
- test guest/authenticated cart flows
- test checkout unaffected
- test admin CRUD

## Definition of done

A feature is not done when the code compiles. It is done when:
- migration is safe
- validation exists
- authorization exists
- tests exist
- UI works
- API/AJAX behavior works if applicable
- SEO output is correct where applicable
- no existing critical flow regresses
- logs contain no new errors
- documentation is updated

## Priority

P0 = production-blocking or data/order/cart/security issue
P1 = important SEO/core feature/regression
P2 = usability or non-critical enhancement
P3 = polish

## Final deliverables from the AI developer

At the end, produce:
1. Changed files list
2. New migrations
3. New routes
4. New env/config requirements
5. Tests added
6. Remaining known issues
7. Manual QA checklist
8. Deployment steps
9. Any required data backfill command