[DOC] all: Reorganize and consolidate project documentation
- Create .github/copilot-instructions.md with global development guidelines - Add comprehensive README.md at project root with quick start guide - Create docs/ directory for technical documentation - Move installation and linter docs to docs/ - Add docs/TRANSLATIONS.md with complete translation system guide - Create README.md for OCA modified addons (product_origin, product_get_price_helper, product_main_seller) - Document translation best practices (no _() in field definitions) - Add references between all documentation files - Clean up project root by moving technical docs to docs/ All documentation now properly references addon-specific READMEs for detailed architecture and implementation.
This commit is contained in:
snt
parent
2a480b74bb
commit
b10ba1fc15
12 changed files with 1327 additions and 0 deletions
414
.github/copilot-instructions.md
vendored
Normal file
414
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,414 @@
|
|||
# GitHub Copilot Instructions - Kidekoop Addons Custom
|
||||
|
||||
## Project Overview
|
||||
|
||||
Este repositorio contiene addons personalizados y modificados de Odoo 18.0. El proyecto combina:
|
||||
|
||||
- **OCB (Odoo Community Backports)**: Base de Odoo 18.0 community en `/ocb`
|
||||
- **Addons OCA**: Módulos de la comunidad OCA modificados para necesidades específicas
|
||||
- **Addons Custom**: Módulos desarrollados específicamente para este proyecto
|
||||
|
||||
## Architecture & Stack
|
||||
|
||||
- **Odoo Version**: 18.0
|
||||
- **Python Version**: 3.10+
|
||||
- **Framework**: Odoo ORM
|
||||
- **Deployment**: Docker Compose
|
||||
- **DB**: PostgreSQL
|
||||
- **Languages**: Python, XML, JavaScript, QWeb
|
||||
|
||||
## Code Standards
|
||||
|
||||
### Python Style
|
||||
|
||||
- Seguir **OCA guidelines** estrictamente
|
||||
- Usar **black** para formateo (configurado en `pyproject.toml`)
|
||||
- **isort** para ordenar imports (perfil black)
|
||||
- **flake8** para linting
|
||||
- **pylint** con pylint-odoo para verificaciones específicas de Odoo
|
||||
- Pre-commit hooks activos (ver `.pre-commit-config.yaml`)
|
||||
|
||||
### Odoo Conventions
|
||||
|
||||
- **Model names**: snake_case con punto (`product.price.category`)
|
||||
- **Class names**: PascalCase (`ProductPriceCategory`)
|
||||
- **File names**: snake_case (`product_price_category.py`)
|
||||
- **XML IDs**: módulo.nombre_descriptivo (`product_price_category.view_form`)
|
||||
- **Manifest**: Siempre `__manifest__.py`, nunca `__openerp__.py`
|
||||
|
||||
### XML/View Standards
|
||||
|
||||
- **Indent**: 4 espacios (no tabs)
|
||||
- **XPath**: Usar `position` explícito (`before`, `after`, `inside`, `replace`, `attributes`)
|
||||
- **Groups**: Referenciar grupos con módulo.xml_id (`sales_team.group_sale_manager`)
|
||||
- **Sequence**: Usar `sequence` attribute para ordenar campos en vistas
|
||||
|
||||
### Translation System
|
||||
|
||||
**IMPORTANTE**: El sistema de traducciones está funcionando correctamente. Seguir estas reglas:
|
||||
|
||||
1. **Estructura de carpeta i18n/**:
|
||||
|
||||
```
|
||||
addon_name/
|
||||
├── i18n/
|
||||
│ ├── es.po # Español (obligatorio)
|
||||
│ ├── eu.po # Euskera (obligatorio)
|
||||
│ └── addon_name.pot # Template (generado)
|
||||
```
|
||||
|
||||
2. **NO usar `_()` en definiciones de campos a nivel de módulo**:
|
||||
|
||||
```python
|
||||
# ❌ INCORRECTO - causa warnings
|
||||
from odoo import _
|
||||
name = fields.Char(string=_("Name"))
|
||||
|
||||
# ✅ CORRECTO - traducción se maneja por .po files
|
||||
name = fields.Char(string="Name")
|
||||
```
|
||||
|
||||
3. **Usar `_()` solo en métodos y código ejecutable**:
|
||||
|
||||
```python
|
||||
def action_confirm(self):
|
||||
message = _("Confirmed successfully")
|
||||
return {'warning': {'message': message}}
|
||||
```
|
||||
|
||||
4. **Generar/actualizar traducciones**:
|
||||
|
||||
```bash
|
||||
# Exportar términos a traducir
|
||||
docker-compose exec odoo odoo \
|
||||
--addons-path=/mnt/extra-addons \
|
||||
--i18n-export=/tmp/addon_name.pot \
|
||||
--modules=addon_name \
|
||||
--db=odoo
|
||||
|
||||
# Copiar y renombrar
|
||||
cd addon_name/i18n
|
||||
msgmerge --update es.po addon_name.pot
|
||||
msgmerge --update eu.po addon_name.pot
|
||||
```
|
||||
|
||||
5. **Formato de archivos .po**:
|
||||
- Encoding: UTF-8
|
||||
- Content-Type: text/plain; charset=UTF-8
|
||||
- Language codes: `es`, `eu`, `ca`, `gl`, `pt`, `fr`, `it`
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
addons-cm/
|
||||
├── .github/ # GitHub configs
|
||||
│ └── copilot-instructions.md # Este archivo
|
||||
├── ocb/ # Odoo Community Backports (18.0)
|
||||
│ └── addons/ # Addons core de Odoo
|
||||
├── oca_dependencies.txt # Dependencias OCA
|
||||
├── requirements.txt # Dependencias Python
|
||||
├── docker-compose.yml # Configuración Docker
|
||||
├── Makefile # Comandos útiles
|
||||
│
|
||||
├── # === ADDONS OCA MODIFICADOS ===
|
||||
├── account_invoice_triple_discount/ # Triple descuento en facturas (OCA)
|
||||
├── purchase_triple_discount/ # Triple descuento en compras (OCA)
|
||||
├── product_origin/ # Origen del producto (OCA)
|
||||
├── product_get_price_helper/ # Helper de precios (OCA)
|
||||
├── product_main_seller/ # Proveedor principal (OCA)
|
||||
├── product_price_category/ # Categorías de precio (OCA)
|
||||
│
|
||||
├── # === ADDONS CUSTOM ===
|
||||
├── account_invoice_triple_discount_readonly/ # Fix para triple descuento
|
||||
├── product_price_category_supplier/ # Extensión categorías precio
|
||||
├── product_sale_price_from_pricelist/ # Auto-cálculo precio venta
|
||||
└── website_sale_aplicoop/ # Sistema eskaera (compras grupo)
|
||||
```
|
||||
|
||||
## Addon References
|
||||
|
||||
**Para arquitectura, detalles de implementación y uso específico de cada addon, consultar su `README.md` individual.**
|
||||
|
||||
### Addons OCA Modificados
|
||||
|
||||
- [account_invoice_triple_discount](../account_invoice_triple_discount/README.rst)
|
||||
- [purchase_triple_discount](../purchase_triple_discount/README.rst)
|
||||
- [product_origin](../product_origin/README.rst)
|
||||
- [product_get_price_helper](../product_get_price_helper/README.rst)
|
||||
- [product_main_seller](../product_main_seller/README.rst)
|
||||
- [product_price_category](../product_price_category/README.rst)
|
||||
|
||||
### Addons Custom Propios
|
||||
|
||||
- [account_invoice_triple_discount_readonly](../account_invoice_triple_discount_readonly/README.md) - Fix bug descuentos
|
||||
- [product_price_category_supplier](../product_price_category_supplier/README.md) - Gestión categorías por proveedor
|
||||
- [product_sale_price_from_pricelist](../product_sale_price_from_pricelist/README.md) - Auto-precio basado en compra
|
||||
- [website_sale_aplicoop](../website_sale_aplicoop/README.md) - Sistema eskaera completo
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Iniciar entorno
|
||||
docker-compose up -d
|
||||
|
||||
# Actualizar addon
|
||||
docker-compose exec odoo odoo -d odoo -u addon_name --stop-after-init
|
||||
|
||||
# Ver logs
|
||||
docker-compose logs -f odoo
|
||||
|
||||
# Ejecutar tests
|
||||
docker-compose exec odoo odoo -d odoo --test-enable --stop-after-init -u addon_name
|
||||
```
|
||||
|
||||
### Quality Checks
|
||||
|
||||
```bash
|
||||
# Ejecutar todos los checks
|
||||
pre-commit run --all-files
|
||||
|
||||
# O usar Makefile
|
||||
make lint # Solo linting
|
||||
make format # Formatear código
|
||||
make check-addon # Verificar addon específico
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
- Tests en `tests/` de cada addon
|
||||
- Naming: `test_*.py`
|
||||
- Herencia: `odoo.tests.common.TransactionCase`
|
||||
- Ejecutar: `--test-enable` flag
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Extending Models
|
||||
|
||||
```python
|
||||
from odoo import models, fields, api
|
||||
|
||||
class ResPartner(models.Model):
|
||||
_inherit = 'res.partner'
|
||||
|
||||
custom_field = fields.Char(string="Custom Field")
|
||||
|
||||
@api.depends('field1', 'field2')
|
||||
def _compute_custom(self):
|
||||
for record in self:
|
||||
record.custom_computed = record.field1 + record.field2
|
||||
```
|
||||
|
||||
### Creating Wizards (Transient Models)
|
||||
|
||||
```python
|
||||
class WizardModel(models.TransientModel):
|
||||
_name = 'wizard.model.name'
|
||||
_description = "Wizard Description"
|
||||
|
||||
def action_confirm(self):
|
||||
# Business logic
|
||||
return {'type': 'ir.actions.act_window_close'}
|
||||
```
|
||||
|
||||
### Bulk Updates
|
||||
|
||||
```python
|
||||
# Prefer SQL-level updates for performance
|
||||
self.env['product.template'].search([
|
||||
('default_supplier_id', '=', partner_id)
|
||||
]).write({'price_category_id': category_id})
|
||||
```
|
||||
|
||||
### Notifications
|
||||
|
||||
```python
|
||||
return {
|
||||
'type': 'ir.actions.client',
|
||||
'tag': 'display_notification',
|
||||
'params': {
|
||||
'title': _('Success'),
|
||||
'message': _('Operation completed'),
|
||||
'type': 'success', # or 'warning', 'danger', 'info'
|
||||
'sticky': False,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies Management
|
||||
|
||||
### OCA Dependencies (`oca_dependencies.txt`)
|
||||
|
||||
```
|
||||
account-invoicing
|
||||
product-attribute
|
||||
purchase-workflow
|
||||
sale-workflow
|
||||
```
|
||||
|
||||
### Python Dependencies (`requirements.txt`)
|
||||
|
||||
- Versiones específicas para evitar breaking changes
|
||||
- Incluir herramientas de desarrollo (linters, etc)
|
||||
|
||||
## Security & Access Rights
|
||||
|
||||
### Grupos Comunes
|
||||
|
||||
- `base.group_user` - Usuario interno
|
||||
- `base.group_system` - Administrador
|
||||
- `sales_team.group_sale_manager` - Manager de ventas
|
||||
- `sales_team.group_sale_salesman` - Vendedor
|
||||
- `purchase.group_purchase_manager` - Manager de compras
|
||||
|
||||
### Security Files
|
||||
|
||||
```xml
|
||||
<!-- security/ir.model.access.csv -->
|
||||
id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
|
||||
access_model_user,model.name.user,model_model_name,base.group_user,1,1,1,0
|
||||
```
|
||||
|
||||
## Common Issues & Solutions
|
||||
|
||||
### Translation Warnings
|
||||
|
||||
**Problem**: `WARNING: _() called at import time at module...`
|
||||
**Solution**: Remove `_()` from field definitions, use only in methods
|
||||
|
||||
### XPath Not Found
|
||||
|
||||
**Problem**: `Element ... not found in parent view`
|
||||
**Solution**: Check view inheritance chain, verify XML IDs are correct
|
||||
|
||||
### Discount Reset Issue
|
||||
|
||||
**Problem**: Multiple discounts being accumulated in discount1
|
||||
**Solution**: Use `account_invoice_triple_discount_readonly` addon
|
||||
|
||||
### Price Calculation
|
||||
|
||||
**Problem**: Prices not updating from pricelist
|
||||
**Solution**: Use `product_sale_price_from_pricelist` with proper configuration
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Test business logic in isolation
|
||||
- Mock external dependencies
|
||||
- Use `TransactionCase` for DB tests
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Test workflow end-to-end
|
||||
- Verify computed fields
|
||||
- Check access rights
|
||||
|
||||
### UI Tests (Tours)
|
||||
|
||||
```javascript
|
||||
odoo.define("module.tour", function (require) {
|
||||
"use strict";
|
||||
var tour = require("web_tour.tour");
|
||||
tour.register(
|
||||
"tour_name",
|
||||
{
|
||||
test: true,
|
||||
url: "/web",
|
||||
},
|
||||
[
|
||||
// Tour steps
|
||||
],
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### Enable Developer Mode
|
||||
|
||||
```
|
||||
Settings > Activate Developer Mode
|
||||
```
|
||||
|
||||
### Check Logs
|
||||
|
||||
```bash
|
||||
docker-compose logs -f odoo | grep ERROR
|
||||
docker-compose logs -f odoo | grep addon_name
|
||||
```
|
||||
|
||||
### Python Debugger
|
||||
|
||||
```python
|
||||
import pdb; pdb.set_trace() # Set breakpoint
|
||||
```
|
||||
|
||||
### Performance Profiling
|
||||
|
||||
```bash
|
||||
--log-level=debug_sql # Show SQL queries
|
||||
```
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
### README.md Structure
|
||||
|
||||
Cada addon debe tener un README.md con:
|
||||
|
||||
1. **Title & Summary**: Qué hace el addon
|
||||
2. **Features**: Lista de funcionalidades
|
||||
3. **Dependencies**: Addons requeridos
|
||||
4. **Installation**: Comandos de instalación
|
||||
5. **Configuration**: Settings necesarios
|
||||
6. **Usage**: Flujo de trabajo típico
|
||||
7. **Technical Details**: Modelos, campos, métodos
|
||||
8. **Translations**: Estado de traducciones (si aplica)
|
||||
|
||||
### Code Comments
|
||||
|
||||
- Docstrings en clases y métodos públicos
|
||||
- Comentarios inline para lógica compleja
|
||||
- TODOs con contexto completo
|
||||
|
||||
## Version Control
|
||||
|
||||
### Commit Messages
|
||||
|
||||
```
|
||||
[TAG] module: Brief description
|
||||
|
||||
Longer explanation if needed
|
||||
```
|
||||
|
||||
Tags: `[ADD]`, `[FIX]`, `[IMP]`, `[REF]`, `[REM]`, `[I18N]`, `[DOC]`
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
- `main` - Production ready
|
||||
- `dev` - Development
|
||||
- `feature/*` - New features
|
||||
- `fix/*` - Bug fixes
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Use `@api.depends` correctamente para computed fields
|
||||
- Prefer `search()` + `write()` sobre loops con `write()`
|
||||
- Use `create()` con lista de vals para bulk creates
|
||||
- Indexes en campos frecuentemente buscados
|
||||
- Avoid N+1 queries con `prefetch`
|
||||
|
||||
## Resources
|
||||
|
||||
- **OCA Guidelines**: https://github.com/OCA/odoo-community.org/blob/master/website/Contribution/CONTRIBUTING.rst
|
||||
- **Odoo Documentation**: https://www.odoo.com/documentation/18.0/
|
||||
- **OCB Repository**: https://github.com/OCA/OCB
|
||||
- **OCA Repositories**: https://github.com/OCA/
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2026-02-12
|
||||
**Odoo Version**: 18.0
|
||||
**Python Version**: 3.10+
|
||||
Loading…
Add table
Add a link
Reference in a new issue