addons-cm/website_sale_aplicoop/README_DEV.md

# Website Sale - Aplicoop

**Author:** Criptomart
**License:** AGPL-3
**Maintainer:** Criptomart SL

## Summary

Modern replacement for legacy Aplicoop - Cooperative group ordering system with separate carts and multi-language support.

## Description

Website Sale Aplicoop provides a complete group ordering system designed for cooperative consumption groups. It replaces the legacy Aplicoop system with a modern, scalable solution where customers organize collaborative orders, manage group memberships, and handle separate shopping carts. Perfect for food cooperatives, buying groups, and collective purchasing organizations.

## Features

- ✅ Group order management with full lifecycle (draft → confirmed → completed)
- ✅ Separate shopping carts per order group
- ✅ Group membership tracking with active/inactive states
- ✅ Order collection and cutoff dates with validation
- ✅ Pickup day configuration and fulfillment tracking
- ✅ Multi-language support (ES, PT, GL, CA, EU, FR, IT)
- ✅ Partner location management for group coordination
- ✅ Product ecosystem integration (ribbons, pricing, margins)
- ✅ Order state transitions with email notifications
- ✅ Delivery tracking and group order fulfillment
- ✅ Financial tracking per group member
- ✅ Automatic translation of UI elements
- ✅ **Lazy Loading**: Configurable product pagination for fast page loads

## Installation

1. Place addon in Odoo addons folder: `/addons/website_sale_aplicoop`
2. Activate developer mode
3. Go to **Apps** → **Update Apps List**
4. Search for "Website Sale - Aplicoop"
5. Click **Install**

### Requirements

- Odoo 18.0+
- Website module
- Sale module
- Product module
- Account module

### Dependencies

```
- base
- web
- website
- sale
- product
- account
```

## Usage

### Administrator Setup

#### 1. Create a Group Order

1. Go to **Website Sale** → **Group Orders** (or **Coops** → **Órdenes de Grupo**)
2. Click **Create**
3. Fill in:
   - **Name**: e.g., "Weekly Cooperative Order #5"
   - **Group**: Select the cooperative group
   - **Collection Date**: When orders will be collected
   - **Cutoff Date**: Last moment to add items
   - **Pickup Date**: When group members collect their orders
4. Save

#### 2. Configure Pickup Dates

1. Go to **Settings** → **Website** → **Shop Settings**
2. Configure **Pickup Days**: Define which days are available
3. Set **Group Settings**: Default locations, delivery partners

#### 3. Add Group Members

1. Open a Group Order
2. In the **Members** tab, click **Add**
3. Select partner(s)
4. Set active/inactive status
5. Save

### Customer Experience

#### For Group Members on Website

1. **Browse Products**: Members see products with eco-ribbons, pricing, margin info
2. **Add to Cart**: Select items (cart is separate per group order)
3. **Review Cart**: See order summary before cutoff date
4. **Submit Order**: Confirm before cutoff time
5. **Receive Notification**: Get email with pickup details
6. **Pickup**: Collect order on designated pickup date

#### Order Workflow

```
Draft → Confirmed → Collected → Invoiced → Completed
  ↓
Cancelled (if member opts out)
```

## Configuration

### Basic Configuration

**Required:**
1. Create group orders with collection/cutoff/pickup dates
2. Assign group members to orders
3. Set available pickup dates

**Optional:**
1. Configure custom email templates
2. Set up product-specific group restrictions
3. Customize group order report

### Multi-Language Setup

The addon automatically translates:
- Interface elements
- Form labels
- Report headers
- Email notifications

**Supported Languages:** ES, PT, GL, CA, EU, FR, IT

**Translations are managed in:**
- `i18n/[language].po` files
- Auto-extracted from templates
- See `docs/TRANSLATION_CONVENTIONS.md` for translation patterns

### Website Customization

Edit templates in: `views/website_templates.xml`

Key customizable sections:
- `eskaera_page`: Main group order display
- `eskaera_details`: Order details view
- `member_cart`: Individual member cart interface

## Technical Details

### Core Models

**`group.order`** (Main group order)
- `name` (Char): Order identifier
- `group_id` (Many2one): Link to group
- `state` (Selection): draft/confirmed/collected/invoiced/completed/cancelled
- `collection_date` (Date): When group collects
- `cutoff_date` (Datetime): Last moment to order
- `pickup_date` (Date): Member pickup day
- `line_ids` (One2many): Order lines
- `member_ids` (One2many): Group members
- `active` (Boolean): Soft delete

**`group.order.line`** (Order items per member)
- `order_id` (Many2one): Parent group order
- `member_id` (Many2one): Which group member
- `product_id` (Many2one): Ordered product
- `quantity` (Float): Amount ordered
- `unit_price` (Float): Price per unit
- `subtotal` (Float): Computed (qty × price)

**`group.partner`** (Group member tracking)
- `partner_id` (Many2one): Odoo partner
- `group_id` (Many2one): Which group
- `active` (Boolean): Active member status
- `role` (Selection): admin/member

### Extended Models

**`product.template`**
- `group_order_allowed` (Boolean): Can be in group orders
- `eco_ribbon_id` (Many2one): Environmental ribbon
- `margin_type_id` (Many2one): Pricing margin

**`sale.order`**
- `group_order_id` (Many2one): Parent group order (if applicable)

### Views & Templates

**Backend Views:**
- `group.order` list/form views
- `group.order.line` inline form
- `group.partner` configuration view

**Frontend Templates:**
- `eskaera_page`: Main group order display
- `eskaera_details`: Order details/summary
- `member_cart`: Individual cart interface
- `group_members`: Member list view

## Integration Points

This addon integrates with:

- **Product Modules**
  - `product_eco_ribbon` - Eco-friendly product indicators
  - `product_margin_type` - Dynamic product pricing
  - `product_pricing_margins` - Cost management

- **Website/E-commerce**
  - `elika_bilbo_website_theme` - Custom website theme
  - `website_sale` - Core shop functionality
  - `website_legal_es` - Legal compliance (Spanish)

- **Sales/Accounting**
  - `sale` - Sales order generation
  - `account` - Invoicing

## Testing

Run tests with:

```bash
cd /home/snt/Documentos/lab/odoo/kidekoop/odoo-addons
python -m pytest website_sale_aplicoop/tests/ -v
```

**Test Coverage:**
- ✅ Group order creation/deletion
- ✅ Member management
- ✅ Order line addition/removal
- ✅ State transitions
- ✅ Cutoff date validation
- ✅ Pickup date assignment
- ✅ Translation extraction (7 languages)
- ✅ Website template rendering

## Known Limitations

- Group orders are company-specific
- Cannot change pickup date after order is confirmed
- Members cannot modify orders after cutoff
- Automatic invoicing must be triggered manually

## Changelog

### 18.0.1.3.1 (2026-02-18)
- **Date Calculation Fixes (Critical)**:
  - Fixed `_compute_cutoff_date` logic: Changed `days_ahead <= 0` to `days_ahead < 0` to allow cutoff_date to be the same day as today
  - Enabled `store=True` for `delivery_date` field to persist calculated values and enable database filtering
  - Added constraint `_check_cutoff_before_pickup` to validate that pickup_day >= cutoff_day in weekly orders
  - Added `@api.onchange` methods for immediate UI feedback when changing cutoff_day or pickup_day
- **Automatic Date Updates**:
  - Created daily cron job `_cron_update_dates` to automatically recalculate dates for active orders
  - Ensures computed dates stay current as time passes
- **UI Improvements**:
  - Added "Calculated Dates" section in form view showing readonly cutoff_date, pickup_date, and delivery_date
  - Improved visibility of automatically calculated dates for administrators
- **Testing**:
  - Added 6 regression tests with `@tagged('post_install', 'date_calculations')`:
    - `test_cutoff_same_day_as_today_bug_fix`: Validates cutoff can be today
    - `test_delivery_date_stored_correctly`: Ensures delivery_date persistence
    - `test_constraint_cutoff_before_pickup_invalid`: Tests invalid configurations are rejected
    - `test_constraint_cutoff_before_pickup_valid`: Tests valid configurations work
    - `test_all_weekday_combinations_consistency`: Tests all 49 date combinations
    - `test_cron_update_dates_executes`: Validates cron job execution
- **Documentation**:
  - Documented that this is a more robust fix than v18.0.1.2.0, addressing edge cases in date calculations

### 18.0.1.3.0 (2026-02-16)
- **Performance**: Lazy loading of products for faster page loads
  - Configurable product pagination (default: 20 per page)
  - New Settings: Enable Lazy Loading, Products Per Page
  - Page 1: 500-800ms load time (vs 10-20s before)
  - Subsequent pages: 200-400ms via AJAX
  - New endpoint: `GET /eskaera/<order_id>/load-page?page=N`
- **Templates**: Split product rendering into reusable template
  - New: `eskaera_shop_products` template
  - Backend: `_get_products_paginated()` in group_order model
- **JavaScript**: Load More button with event handling
  - `_attachLoadMoreListener()` for AJAX pagination
  - Spinner during load (button disabled + "Loading..." text)
  - Re-attach event listeners for new products
  - Auto-hide button when no more products
- Documentation: Added `docs/LAZY_LOADING.md` with full technical details

### 18.0.1.2.0 (2026-02-02)
- UI Improvements:
  - Increased cart text size (2x) for better readability
  - Increased cart icon sizes (1.2rem) with proper button proportions
  - Enlarged "Save as Draft" button in checkout (2x text and icon)
- Date Calculation Fixes:
  - Fixed pickup_date calculation (was adding extra week incorrectly)
  - Simplified pickup_date computation logic
- Display Enhancements:
  - Added delivery_date display to all order pages
  - Improved date field visibility on order cards and product pages

### 18.0.1.0.0 (2024-12-20)
- Initial release
- Core group order functionality
- Multi-language translation support
- Complete member management
- Order state machine implementation

### 18.0.1.1.0 (2025-01-10)
- Fixed translation extraction for "Pickup day" and "Cutoff day"
- Improved QWeb template for better performance
- Added comprehensive documentation

## Support

For issues, feature requests, or contributions:
- **Repository**: https://git.criptomart.net/KideKoop/kidekoop/odoo-addons
- **Main Documentation**: `/docs/` folder (transversal docs)
- **Addon Documentation**: This README + `/docs/ODOO18_TRANSLATIONS_LEARNINGS.md`
- **Maintainer**: Criptomart SL

## Documentation References

- **Translation Patterns**: See `docs/TRANSLATION_CONVENTIONS.md`
- **Translation Examples**: See `docs/TRANSLATION_EXAMPLES.md`
- **Odoo 18 Translation Guide**: See `docs/ODOO18_TRANSLATIONS_LEARNINGS.md`
- **Project Architecture**: See `docs/ARCHITECTURE.md`

## Related Modules

- `product_eco_ribbon` - Product environmental classification
- `product_margin_type` - Dynamic product pricing
- `product_pricing_margins` - Complete pricing system
- `elika_bilbo_website_theme` - Custom website theme
- `website_legal_es` - Legal compliance

---

**Version:** 18.0.1.3.1
**Odoo:** 18.0+
**License:** AGPL-3
**Maintainer:** Criptomart
**Repository:** https://git.criptomart.net/criptomart/addons-cm