docs: add Odoo 17 mail template, body field, and test isolation gotchas

Capture lessons from driving the K8s suite to 69/69 green:
- mail.template Mako → inline_template/qweb migration
- _render_field vs _generate_template
- data-XML staleness in primed template DBs (-u to refresh)
- blog.post.content (body_arch removed in Odoo 17)
- mock-attr-stringification isolation failures

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -853,6 +853,11 @@ post = self.env['blog.post'].sudo().create({
 | Odoo 17: `mail.template` has no `generate_email()` | Method removed in Odoo 17; API changed entirely | Use `template._generate_template([res_id], ['subject', 'body_html'])` — positional args only, returns `{res_id: {field: value}}`. Never use `generate_email(res_id)` (old Odoo 16 API) |
 | conftest.py inside addon dir causes `Invalid import` | pytest adds addon dir to sys.path, bypassing `odoo.addons.*` namespace | Never put conftest.py inside the addon package. Place at repo root or at `/mnt/extra-addons/conftest.py` (parent of addon dir) |
 | BDD test: `fixture 'env' not found` (pytest-odoo 2.x) | pytest-odoo 2.x does NOT provide an `env` pytest fixture — env only exists as `self.env` inside TransactionCase | In BDD step fixtures, build env directly: `registry = odoo.registry(request.config.getoption('--odoo-database')); with registry.cursor() as cr: env = Environment(cr, odoo.SUPERUSER_ID, {}); yield env; cr.rollback()` |
+| Odoo 17: `mail.template` body uses `${}`/`% for` Mako and renders literally | Pre-Odoo-14 Mako syntax is dead in Odoo 17 | subject/email_from use inline_template `{{ }}`; body_html uses `type="html"` with qweb `<t t-out=""/>`, `<t t-foreach t-as>`, `<t t-if>`. NOT `type="qweb"` (invalid RNG type → "Element odoo has extra content: data") |
+| Odoo 17: `mail.template._render_field('subject', [id])` returns `{id: rendered_str}` | This is the real synchronous render method | Use `_render_field(field, res_ids)` to assert on rendered output; `_generate_template` returns UNrendered template text |
+| Data-XML change (e.g. mail.template) not reflected after image rebuild | Template DB was primed once; clones inherit stale records | Re-prime or run `odoo -u <module> -d odoo_template --stop-after-init`. Translatable fields (subject) DO update on `-u` once the XML is valid |
+| Test passes alone but fails in full suite | Stale image at pod startup, or mock attr mismatch | Re-run fresh in the pod to confirm; a MagicMock attr the code reads but the test never set stringifies to ~66 chars (e.g. body_html vs text) |
+| Odoo 17: `blog.post` has no `body_arch`/`body` | Renamed in Odoo 17 | The HTML body field is `content`. Auto-generation MUST write `'content': llm_response.body_html` or posts publish empty |
 | Test: `IndexError: tuple index out of range` when accessing `mock.call_args[0][0]` | Mock method called with keyword-only args; `call_args[0]` is empty tuple `()` | Use `mock.call_args[1].get('key')` for kwargs; or check `mock.called` before accessing `call_args` |
 | Test: TransactionCase gets `InFailedSqlTransaction` in subsequent tests | Previous test called `self.env.cr.commit()` breaking savepoint chain | Replace `commit()` with `flush_all()` in code being tested; `commit()` is only allowed in non-test code in production |
 | Test: Mock response returns HTML but code expects JSON | Mock return values must match the data format expected by code under test | Create helper function to generate mocks with correct structure (e.g., JSON string in `.text` field for LLM routers) |