Odoo Custom Module: Vòng Đời An Toàn Từ A–Z

Một Odoo custom module tốt không chỉ là code chạy được — nó phải cài được, nâng cấp được và gỡ được mà không làm hỏng dữ liệu thật của khách hàng. Bài này là bản đồ tổng quan toàn bộ vòng đời của một Odoo custom module: từ cấu trúc thư mục, thiết kế model, phân quyền, đến cài/nâng cấp/gỡ an toàn và những lỗi production hay gặp nhất. Mỗi phần sẽ dẫn bạn tới một bài chuyên sâu để đào tiếp khi cần.

Đây là kiến thức mình rút ra sau nhiều năm triển khai Odoo cho khách hàng thật — nơi một lệnh -u sai có thể xoá một cột dữ liệu trong vài giây.

Custom module là gì và khi nào bạn cần

Trong Odoo, gần như mọi tính năng đều đóng gói dưới dạng module. Một custom module là module bạn tự viết để mở rộng hành vi sẵn có: thêm field, thêm model, sửa view, hoặc nối nghiệp vụ riêng của doanh nghiệp.

Bạn cần custom module khi: cấu hình sẵn không đủ, cần tự động hoá một quy trình đặc thù, hoặc tích hợp với hệ thống bên ngoài. Ngược lại, đừng viết module nếu chỉ cần thay đổi nhỏ mà Studio hoặc cấu hình đã làm được.

Mới bắt đầu? Đọc nền tảng trước: Custom module trong Odoo là gì.

Cấu trúc một Odoo custom module

Mọi module đều theo một bố cục thư mục quen thuộc:

my_module/
├── __init__.py
├── __manifest__.py
├── models/
│   ├── __init__.py
│   └── my_model.py
├── views/
│   └── my_model_views.xml
├── security/
│   └── ir.model.access.csv
└── data/

Trái tim là __manifest__.py — khai báo tên, version, phụ thuộc và danh sách file dữ liệu được nạp:

{
    'name': 'My Module',
    'version': '18.0.1.0.0',
    'depends': ['base', 'sale'],
    'data': [
        'security/ir.model.access.csv',
        'views/my_model_views.xml',
    ],
    'license': 'LGPL-3',
    'installable': True,
    'application': False,
}

Lưu ý version: đặt theo 18.0.x.y.z. Tăng số version mỗi lần đổi schema để biết chính xác bản nào đang chạy trên production.

Vòng đời module: 4 giai đoạn

Một module đi qua đúng 4 trạng thái — và mỗi trạng thái có rủi ro riêng:

• Phát triển: viết code trên môi trường dev, bật --dev=all để reload nhanh.

• Cài đặt (-i): Odoo tạo bảng, cột và quyền lần đầu.

• Nâng cấp (-u): Odoo so sánh code mới với schema cũ và áp thay đổi.

• Gỡ (uninstall): Odoo xoá bảng, cột và dữ liệu liên quan — không thể undo.

Hiểu rõ ranh giới giữa "nâng cấp" và "gỡ" là điều quan trọng nhất để không mất dữ liệu.

Thiết kế model và dữ liệu

Model là nơi định nghĩa bảng dữ liệu của bạn:

from odoo import models, fields

class MyModel(models.Model):
    _name = 'my.model'
    _description = 'My Custom Record'

    name = fields.Char(required=True)
    partner_id = fields.Many2one('res.partner', string='Khách hàng')
    amount = fields.Float()

Mỗi model my.model map thành một bảng SQL my_model. Trước khi viết, hãy phác thảo quan hệ giữa các bảng để tránh thiết kế sai từ gốc — bạn có thể dán các câu CREATE TABLE tương ứng vào công cụ SQL → ERD để nhìn quan hệ Many2one/One2many bằng sơ đồ trực quan.

Phân quyền: phần dev hay quên nhất

Tạo model mà quên khai báo quyền là lỗi kinh điển — model sẽ "tàng hình" với mọi user thường. Tối thiểu bạn cần một dòng trong ir.model.access.csv:

id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
access_my_model,my.model.user,model_my_model,base.group_user,1,1,1,0

Dòng trên cho nhóm user cơ bản quyền đọc/sửa/tạo, nhưng không cho xoá (perm_unlink=0). Với dữ liệu nhạy cảm, hãy siết quyền xoá và cân nhắc thêm record rules.

Cài và nâng cấp an toàn

Lệnh cơ bản:

# Cài lần đầu
odoo-bin -c odoo.conf -d mydb -i my_module --stop-after-init

# Nâng cấp sau khi đổi code
odoo-bin -c odoo.conf -d mydb -u my_module --stop-after-init

Quy tắc vàng cho production:

• Luôn backup database trước khi chạy -u.

• Thử trên staging (bản sao DB thật) trước, rồi mới lên production.

• Tránh -u all trên hệ thống lớn nếu chỉ đổi một module.

Gỡ module: nơi dễ mất dữ liệu nhất

Đây là cạm bẫy nguy hiểm nhất. Gỡ một module sẽ kéo theo việc xoá bảng và cột mà nó tạo ra — kể cả dữ liệu khách hàng đã nhập. Trước khi bấm Uninstall, hãy đọc kỹ:

Uninstall module trong Odoo và rủi ro mất dữ liệu — vì sao thao tác này không thể hoàn tác và cách phòng tránh.

Hiệu năng và lỗi production hay gặp

Module chạy ngon trên dev vẫn có thể gây lỗi khi tải thật. Hai tình huống mình gặp nhiều nhất:

• Giật lag khi nhập liệu (đặc biệt màn POS): xem Fix lỗi lag màn payment POS Odoo 18.

• WebSocket timeout sau khi deploy sau proxy: xem Fix WebSocket timeout trong Odoo.

Phát triển an toàn cùng AI

AI giúp viết module nhanh hơn, nhưng cũng dễ tạo code xoá nhầm dữ liệu nếu prompt cẩu thả. Mình tổng hợp bộ prompt an toàn ở đây: Prompt phát triển Odoo custom module an toàn.

Checklist trước khi lên production

• Đã tăng số version trong manifest.

• Đã khai báo quyền trong ir.model.access.csv.

• Đã backup DB và thử -u trên staging.

• Đã kiểm tra hiệu năng với dữ liệu lớn.

• Đã xác nhận hành vi khi gỡ module (không xoá nhầm dữ liệu cần giữ).

Kết luận

Một Odoo custom module an toàn là module bạn kiểm soát được suốt cả vòng đời — không chỉ lúc viết. Nắm vững 4 giai đoạn cài/nâng cấp/gỡ, không bao giờ bỏ qua phân quyền, và luôn backup trước khi đụng vào schema production.

Bước tiếp theo: phác thảo data model của bạn bằng công cụ SQL → ERD, rồi đi sâu vào từng chủ đề qua các bài liên kết ở trên.