Troubleshoot Doc Engine

Troubleshoot Doc Engine

Common errors + fixes cho Admin / Sales rep khi Doc Engine không hoạt động.

Symptom 1: Template render báo UndefinedError

Error message: UndefinedError: 'X' is undefined

Nguyên nhân: Placeholder tham chiếu field không tồn tại trên record.

Fix:

Field misspell

• {{ record.customer_name }} — sai
• {{ record.customer_id.name }} — đúng

Verify field name trong Odoo record form.

Related field empty

• {{ record.warehouse_id.name }} — nếu HĐ không có warehouse (chỉ có lot), field is False → .name fail

Fix trong template:

{% if record.warehouse_id %}
  Kho: {{ record.warehouse_id.name }}
{% endif %}

Hoặc:

Kho: {{ record.warehouse_id.name or 'N/A' }}

Field trên custom model

• Custom field x_special_field thêm qua Studio → có thể chưa được include trong _record_to_dict()

Fix: Dev mode → Cấu hình → Doc Engine → Depth → increase từ 3 → 4 để include deeper fields.

Symptom 2: .docx render giữ nguyên {{ ... }} literal

Error: File output vẫn có {{ record.name }} thay vì “ZC-2026-042”.

Nguyên nhân: Jinja syntax lỗi (Word tự “smart quote” → {{ biến "{{).

Fix:

1. Mở .docx trong Word / LibreOffice
2. Verify {{ record.name }} — không có nghiêng, quote khác nhau (" vs ")
3. Word autocorrect có thể đổi:
   • "{{ ... }}" (straight) → "{{ ... }}" (curly) — SAI
   • {{ ... }} (plain) → {{ ... }} (italic) — OK vẫn work
4. Tắt Word autocorrect: File → Options → Proofing → AutoCorrect Options → uncheck “Smart quotes”
5. Re-type placeholder → save → re-upload

Symptom 3: OnlyOffice iframe blank / infinite loading

Symptom: Click Edit inline → iframe show white screen, không render editor.

Nguyên nhân + Fix:

1. Check JWT secret mismatch

docker exec parkone-odoo bash -c 'echo $OO_JWT_SECRET'
docker exec zonepro-onlyoffice cat /etc/onlyoffice/documentserver/local.json | grep secret

Cả 2 phải same secret. Nếu khác:

• Sửa docker-compose.yml: OO_JWT_SECRET=<same_value>
• Restart cả 2 containers

2. Check network connectivity

docker exec zonepro-onlyoffice curl http://odoo:8069/parkone/doc/test-endpoint

Return 200 → network OK. Timeout / connection refused → check docker network config.

3. Check browser console

DevTools → Console → look for:

• 403 Forbidden → JWT wrong
• Mixed content blocked → protocol mismatch (http vs https)
• CORS blocked → OnlyOffice config AllowMetaTag: true

4. Check OnlyOffice healthy

curl https://oo.parkone.vn/healthcheck
# → "true" nếu OK

Symptom 4: Save trong OnlyOffice fail

Symptom: Editor OK, edit content, click Save → error “Save failed”.

Nguyên nhân: Callback URL wrong hoặc Odoo callback endpoint error.

Fix:

1. Verify callback URL config trong Odoo:

   • Env OO_CALLBACK_URL = http://parkone.bsdinsights.com:8069 (docker network alias)
   • Hoặc http://odoo:8069 nếu cùng compose

2. Test callback endpoint:

   docker exec zonepro-onlyoffice curl -X POST \
     http://parkone.bsdinsights.com:8069/parkone/doc/<template_id>/callback \
     -H "Content-Type: application/json" \
     -d '{"status": 2, "url": "test"}'

   Expect {"error": 0} return.

3. Check Odoo log: docker logs parkone-odoo --tail 100 | grep callback

Symptom 5: PDF convert fail

Symptom: Click “Convert to PDF” → error “libreoffice: command not found” hoặc timeout.

Fix:

LibreOffice không installed

• Add vào Dockerfile:

  RUN apt-get install -y libreoffice

• Rebuild image

Chi tiết: Auto-convert PDF → Setup

Font missing

• Convert PDF ra dấu hỏi chấm thay tiếng Việt
• Install font: apt-get install fonts-noto-cjk fonts-liberation

Timeout

• Doc quá lớn → convert > 60s → timeout
• Increase env LIBREOFFICE_CONVERT_TIMEOUT=180
• Hoặc dùng async convert

Symptom 6: Field picker sidebar không hiện

Symptom: Mở template trong OnlyOffice → sidebar bên phải trống hoặc missing.

Fix:

1. Verify plugin sidecar loaded:

   • DevTools → Network → filter oo-plugin
   • Should see code.js load with 200 status

2. Verify plugin path exists:

   docker exec parkone-odoo ls addons/parkone/static/src/oo_plugin/
   # Should see code.js, config.json

3. Cache issue — force reload:

   • Cache-buster ?v=random phải work
   • Nếu vẫn stale — clear browser cache (Ctrl+Shift+Del)

4. JWT mismatch — plugin không load nếu JWT invalid. Xem Symptom 3.

Symptom 7: Click field không insert

Symptom: Click field trong sidebar → no reaction, snippet không xuất hiện.

Fix:

1. Verify hello-ACK completed:

   • DevTools → Console → filter [Parkone]
   • Should see Plugin ACK received
   • Nếu không → plugin không load, quay lại Symptom 6

2. Verify cursor active trong editor:

   • Click vào doc content trước khi click field
   • Không click từ sidebar mà editor không focus

3. Verify insert command dispatched:

   • Console: Insert command dispatched: <snippet>
   • Nếu không → sidebar handler broken, contact BSD support

Symptom 8: Placeholder render Vietnamese sai encoding

Symptom: {{ record.customer_id.name }} render “Cong ty TNHH Hoa Biet” (không dấu) hoặc “Cty ??? Hoa Bi???t” (mojibake).

Nguyên nhân: docxtpl encoding issue hoặc font missing.

Fix:

1. Verify template .docx encoding UTF-8:

   • Word default UTF-8, không cần fix
   • LibreOffice save as .docx: File → Save As → chọn “Word 2007-365 (.docx)”

2. Verify Odoo Python encoding:

   • Container should have LANG=C.UTF-8 env
   • docker exec parkone-odoo locale | grep LANG

3. Verify record data có dấu:

   • SELECT name FROM res_partner WHERE id = 42;
   • Nếu DB show “Cong ty” without dấu → data nhập sai, sửa data không phải template

Symptom 9: Multiple placeholders render same value

Symptom: Template có 2 placeholders khác nhau {{ record.name }} và {{ record.customer_id.name }} — render ra cùng value.

Nguyên nhân: docxtpl context confused hoặc Word autoformat merged placeholders.

Fix:

1. Verify template raw XML:

   • Unzip .docx → open word/document.xml
   • Search record.name — should appear đúng 1 lần
   • Nếu appear 2 lần → Word merged placeholders, need re-type

2. Recreate placeholder từng cái:

   • Delete existing placeholder
   • Ctrl+Enter (paragraph break)
   • Type new: {{ record.customer_id.name }}

Symptom 10: Wizard render batch fail giữa chừng

Symptom: Bulk render 20 HĐ → render được 5 → error → abort.

Fix:

1. Xem log Odoo — identify record thứ 6 fail
2. Xem lỗi cụ thể:
   • Missing field → fix record data
   • Template invalid → fix template
   • Timeout → docsx quá phức tạp
3. Skip record đó, re-run batch:
   • Menu Action → Bulk Render → uncheck failed record
   • Continue

Debug tools

1. Test render standalone

docker exec parkone-odoo python3 << 'EOF'
from docxtpl import DocxTemplate
import io

tpl = DocxTemplate('/mnt/extra-addons/parkone/data/templates/hd_thue_dat.docx')
context = {
    'record': {
        'name': 'ZC-TEST-001',
        'customer_id': {'name': 'Test KH', 'vat': '123'},
    },
    'company': {'name': 'Test Co'},
}
tpl.render(context)
out = io.BytesIO()
tpl.save(out)
print("OK, output size:", len(out.getvalue()))
EOF

Nếu OK → template + docxtpl work. Vấn đề ở Odoo integration.

2. Enable verbose logging

docker exec parkone-odoo bash -c \
  'echo "log_level = debug_rpc" >> /etc/odoo/odoo.conf'
docker restart parkone-odoo

Log verbose: mọi WOPI request, JWT verify, callback log full. Tắt sau khi debug xong (log spam).

3. Postman test WOPI endpoints

• GET /parkone/doc/<template_id>/download?token=<jwt> — should return .docx binary
• POST /parkone/doc/<template_id>/callback — should accept JSON with {status, url}

Verify endpoints reachable từ OnlyOffice container network.

Emergency fallback

Nếu OnlyOffice hoàn toàn broken:

1. Sales rep vẫn có thể download template từ Parkone → mở Word manual → edit → upload lại
2. Skip OnlyOffice hoàn toàn → dùng Doc Engine v1 flow (render → download → upload signed)
3. Follow-up với BSD support để fix OnlyOffice

Contact support

Nếu debug không ra:

• Email: support@bsdinsight.com
• Attach: screenshot error + container logs (docker logs parkone-odoo --tail 200)
• Response time: 24h business hours

Liên kết liên quan

• Setup OnlyOffice
• Field picker
• Snippet insert
• Wizard render
• PDF convert