คู่มือการอัปเกรด¶

การอัปเกรด HEMMS มาในสามขนาด:

1. ดึงโค้ดใหม่ รัน install-private ใหม่ — ทุกการอัปเวอร์ชันโมดูล roots_hemms_* target ใน Makefile ใช้ -i ซึ่งหมายถึง "install or upgrade" ดังนั้นคำสั่งเดียวนี้จัดการได้ทั้งสองกรณี
2. อัปเกรดโมดูลใดโมดูลหนึ่งเฉพาะเจาะจง — เมื่อคุณต้องการรับการแก้ไขใน roots_hemms_workflow โดยไม่แตะต้องสิ่งอื่น
3. การอัปเกรด Odoo รุ่นใหญ่ (18 → 19) — โครงการย้ายข้อมูลที่วางแผน ไว้หลายสัปดาห์ ซึ่งกล่าวถึงในเชิงแนวคิดที่ท้ายหน้านี้

ทุกอย่างเหล่านี้เริ่มต้นด้วยขั้นเดียวกัน: สำรองข้อมูล ดูที่ การสำรองข้อมูลและการกู้คืน

ก่อนเริ่ม — เช็กลิสต์ความปลอดภัย¶

การอ่านฟิลด์ version¶

โมดูล HEMMS ทุกตัวมี version ใน __manifest__.py ของมัน การ ประชุมปัจจุบันคือ semver-ish 5 ส่วน ที่ยึดกับเวอร์ชันใหญ่ของ Odoo:

"version": "18.0.1.0.0"
#          │   │ │ │ │
#          │   │ │ │ └─ Patch     — bug fix, no schema change
#          │   │ │ └─── Minor     — backward-compat feature
#          │   │ └───── Major     — breaking change for downstream
#          │   └─────── Module-local feature bump
#          └─────────── Odoo major version (18.x)

ส่วนแรก ตรงกับเวอร์ชันใหญ่ของ Odoo เสมอ เมื่อเรา ย้ายไปยัง Odoo 19 manifest ทุกตัวจะถูกตั้งเวอร์ชันใหม่เป็น 19.0.x.y.z

ตัวโหลดโมดูลของ Odoo ตรวจสอบเวอร์ชันนี้เทียบกับค่าที่จัดเก็บใน ir.module.module หาก manifest ใหม่กว่า Odoo จะรัน upgrade hook สำหรับโมดูลนั้น หากคุณอัปเวอร์ชันใน source แต่ลืม -u <module> หรือ -i <leaf> instance ที่กำลังรันจะคงพฤติกรรมเดิม ไว้จนกว่าจะเริ่มใหม่ครั้งถัดไปด้วย --update

รูปแบบที่ 1 — ดึงและติดตั้งใหม่ (กรณีทั่วไป)¶

# 1. Make sure nothing is in flight, then back up
make backup-private

# 2. Pull the new code
git pull origin main

# 3. Rebuild the image if the Dockerfile or requirements changed
#    (most upgrades don't need this)
docker compose -f docker-compose.private.yml build

# 4. Install/upgrade all four leaf modules — this transitively
#    upgrades every roots_hemms_* module that bumped its version
make install-private

# 5. Restart Odoo so the new code is loaded by the running process
make down-private && make up-private

make install-private รัน odoo -i <leaf modules> --stop-after-init แฟล็ก -i ของ Odoo ติดตั้งโมดูลที่ขาดหายไป และ อัปเกรดโมดูลที่ เวอร์ชัน manifest ใหม่กว่าค่าที่จัดเก็บใน ir.module.module คำสั่งเดียวนั้นจัดการได้ทั้งการติดตั้งใหม่และการอัปเกรดแบบเพิ่มขึ้น ซึ่งเป็นเหตุผลที่ target เดียวกันปรากฏใน การติดตั้ง

รูปแบบที่ 2 — อัปเกรดโมดูลใดโมดูลหนึ่งเฉพาะเจาะจง¶

เมื่อคุณต้องการรับการแก้ไขในโมดูลเดียว — โดยทั่วไประหว่างการ พัฒนาหรือเมื่อใช้ hotfix:

docker compose -f docker-compose.private.yml exec odoo_private \
    odoo -c /etc/odoo/odoo.conf \
    -d hemms_private \
    -u roots_hemms_workflow \
    --stop-after-init

-u (ความหมายตัวพิมพ์ใหญ่: upgrade) จะรันไฟล์ข้อมูลของโมดูลใหม่ (security/, views/, data/) และสคริปต์ migration ใด ๆ (ดูส่วน ถัดไป) มัน ไม่ ติดตั้ง dependency ที่ขาดหายไป — หากคุณอัปเวอร์ชัน โมดูลที่ได้ depends ใหม่ ให้ใช้ -i แทน

หลังจากคำสั่งออก ให้เริ่ม Odoo ที่รันยาว ๆ ใหม่:

make down-private && make up-private

ไฟล์ migration¶

เมื่อการอัปเกรดของโมดูลต้องทำมากกว่าแค่โหลด XML ใหม่ — เช่น เปลี่ยนชื่อ ฟิลด์ เติมค่าย้อนหลัง หรือ merge เรกคอร์ดสองรายการ — มันจะเพิ่มสคริปต์ migration แบบ Python ภายใต้ migrations/<version>/ Odoo จะรันตามลำดับระหว่าง การอัปเวอร์ชัน manifest กับการโหลด XML ใหม่

สถานะปัจจุบันของ migration ใน HEMMS:

find addons/roots -path '*/migrations/*'
# (no results — none of the roots_hemms_* modules has needed a migration
# script yet because they were all added at 18.0.1.0.0)

เมื่อต้องการ migration ครั้งแรก (น่าจะเป็น Q3 → Q3.x ที่มีการเปลี่ยน schema ของ coverage-line) โครงสร้างจะเป็น:

addons/roots/roots_hemms_service_contracts/
└── migrations/
    └── 18.0.1.1.0/
        ├── pre-migrate.py    # runs before module load
        └── post-migrate.py   # runs after module load

repo OCA/server-tools ของ OCA มี playbook สำหรับ migration และยูทิลิตีช่วยเหลือ — ให้ใช้สิ่งเหล่านั้นแทนที่จะ เขียน SQL ด้วยมือเมื่อ migration จริงครั้งแรกมาถึง

CI ตรวจจับสิ่งที่พังอย่างชัดเจน¶

ก่อนทุก PR merge เข้า main เวิร์กโฟลว์ Tests จะติดตั้ง leaf module ทุกตัวบนสแต็ก Postgres 15 + Odoo 18 ใหม่ และรัน ทดสอบ unit ของ HEMMS ทั้ง 177 รายการ หาก main เป็นสีเขียว เส้นทางติดตั้ง / อัปเกรดได้รับการ พิสูจน์บนฐานข้อมูลใหม่แล้ว

สิ่งที่ CI ไม่ ตรวจจับ:

• migration จากรูปทรงข้อมูลเก่าที่ไม่มีอยู่ใน test fixture
• การถดถอยด้านประสิทธิภาพบนฐานข้อมูลขนาดใหญ่
• การถดถอยฝั่งเบราว์เซอร์ (ยังไม่มีการทดสอบ JS)

สำหรับการอัปเกรดที่มีความเสี่ยงสูง ให้ติดตั้งโค้ดใหม่ลงใน staging DB ที่กู้คืนจากการสำรองข้อมูล production ล่าสุด คลิกผ่าน flow ที่สำคัญ แล้วจึงค่อยอัปเกรด production นี่คือการซ้อมกู้คืนจากภัยพิบัติ จาก การสำรองข้อมูลและการกู้คืน ที่นำมาใช้สองวัตถุประสงค์

รูปแบบที่ 3 — การอัปเกรด Odoo รุ่นใหญ่ (18 → 19)¶

นี่เป็นโครงการ ไม่ใช่คำสั่ง ลำดับเต็ม:

1. รอความพร้อมของ OCA 19.0 ติดตามสาขา 19.0 ของ OCA repo maintenance — HEMMS ขึ้นอยู่กับ maintenance_plan, maintenance_stock, maintenance_partner และ sign_oca ไม่มีทั้งสี่ตัวที่จะนำหน้า release 19.0 ของพวกมันได้
2. ตรวจสอบ API ที่เลิกใช้ release notes 19.0 ของ Odoo แสดงรายการทุก API ที่ถูกนำออก Grep addons/roots/ หาแต่ละตัว การรัน CI ของ Q7 จะตรวจจับส่วนใหญ่ บน base image 19.0 แต่บางสิ่งที่พังจะปรากฏเฉพาะตอน runtime
3. Rebase ชั้น OCA vendor ไปยังสาขา 19.0
4. อัปเวอร์ชัน manifest ของ roots_hemms_* ทุกตัว จาก 18.0.x.y.z เป็น 19.0.x.y.z
5. เขียนสคริปต์ migration สำหรับการเปลี่ยนชื่อฟิลด์หรือเปลี่ยนชื่อโมเดลใด ๆ
6. รัน playbook migration ของ OCA บน staging DB: https://github.com/OCA/openupgrade เป็นเครื่องมือของชุมชนสำหรับงานนี้
7. Stage, dry-run, บันทึก แล้วอัปเกรด production ระหว่างหน้าต่าง downtime ที่วางแผนไว้

วางแผนโครงการหลายสัปดาห์ README ของ openupgrade ของ OCA เป็นแหล่งข้อมูล เดียวที่ดีที่สุด

การตรวจสอบหลังอัปเกรด¶

หลังการอัปเกรดทุกครั้ง — ระดับโมดูลหรือรุ่นใหญ่ — ให้ตรวจสอบ:

1. log การบูตสะอาด make logs-private ควรจบที่ Modules loaded. โดยไม่มี traceback อยู่เหนือมัน
2. รายการโมดูลอัปเดตแล้ว Settings → Apps แสดงเวอร์ชันใหม่ใน Installed
3. smoke test flow ที่สำคัญ:
   • สร้างและปิดคำขอบำรุงรักษา
   • เปิดรายงาน HA ของปีที่แล้ว — PDF render ได้
   • เปิดสัญญาบริการที่ลงนามแล้ว — สิ่งแนบดาวน์โหลดได้
   • รัน mass-import dry-run และ commit บนตัวอย่างขนาดเล็ก
4. audit log ครบถ้วน สุ่มตรวจแถว hemms.stage.transition.log จากก่อนและหลังการอัปเกรด

หากมีอะไรล้มเหลว ให้กู้คืนจากการสำรองข้อมูลที่ทำในขั้นที่ 1 ของเช็กลิสต์ ความปลอดภัย ดูที่ การสำรองข้อมูลและการกู้คืน

การ rollback¶

หากมีอะไรผิดพลาดกลางการอัปเกรด:

# 1. Stop Odoo
docker stop hemms_odoo_private

# 2. Roll the code back
git checkout <previous-good-sha>
docker compose -f docker-compose.private.yml build

# 3. Restore the pre-upgrade DB + filestore
#    (full procedure in Backup & Restore)

# 4. Restart
make up-private

อย่า พยายาม "fix forward" บน production DB ให้ roll back ทำการ ล้มเหลวซ้ำบน staging แก้ที่นั่น ส่งผ่าน PR ผ่าน CI แล้วลอง อีกครั้ง

หน้าที่เกี่ยวข้อง¶

• การสำรองข้อมูลและการกู้คืน — ข้อกำหนดเบื้องต้นสำหรับการ อัปเกรดทุกครั้ง
• CI/CD — สิ่งที่ CI พิสูจน์ก่อนคุณอัปเกรด
• การพัฒนาโมดูล — วิธีอัปเวอร์ชัน ของโมดูลเมื่อคุณเปลี่ยนมัน