ODOO数据文件（XML、CSV、SQL）是如何转换并加载到 Odoo 数据库

本文档详细解释 Odoo 的 odoo/tools/convert.py 文件，这是 Odoo 数据导入和转换的核心模块。

🎯 文件的作用是什么？

想象一下，你开发了一个 Odoo 模块，里面有一些初始数据（比如菜单、视图、演示数据等）。这些数据都保存在 XML 或 CSV 文件中。当模块安装时，Odoo 需要把这些文件中的数据读取出来，并保存到数据库里。

convert.py****就是负责这个转换工作的核心文件！

它就像一个"翻译官"，把人类可读的 XML/CSV 文件翻译成数据库能理解的格式。

📊 完整功能总结表

表1：核心类和方法

|------------------------------|---------|-------------|----------|
| 类/方法 | 行号 | 作用 | 重要程度 |
| ParseError | 38-39 | 解析异常类 | ⭐ |
| _get_eval_context() | 42-55 | 创建安全执行环境 | ⭐⭐⭐ |
| _fix_multiple_roots() | 57-73 | 修复多根 XML | ⭐⭐ |
| _eval_xml() | 75-203 | 核心解析器 | ⭐⭐⭐⭐⭐ |
| str2bool() | 205-206 | 字符串转布尔 | ⭐ |
| nodeattr2bool() | 208-214 | 节点属性转布尔 | ⭐ |
| xml_import | 216-617 | XML 导入器类 | ⭐⭐⭐⭐⭐ |
| xml_import.__init__() | 596-612 | 初始化导入器 | ⭐⭐⭐ |
| xml_import.make_xml_id() | 233-236 | 生成完整 XML ID | ⭐⭐⭐ |
| xml_import._test_xml_id() | 238-246 | 验证 XML ID | ⭐⭐ |
| xml_import.get_env() | 217-231 | 获取特定环境 | ⭐⭐ |
| xml_import._tag_delete() | 248-267 | 删除记录 | ⭐⭐⭐ |
| xml_import._tag_function() | 269-273 | 调用函数 | ⭐⭐⭐ |
| xml_import._tag_menuitem() | 275-334 | 创建菜单 | ⭐⭐⭐⭐ |
| xml_import._tag_record() | 336-467 | 创建/更新记录 | ⭐⭐⭐⭐⭐ |
| xml_import._tag_template() | 469-537 | 处理 QWeb 模板 | ⭐⭐⭐⭐⭐ |
| xml_import._tag_root() | 549-580 | 处理根标签 | ⭐⭐⭐⭐ |
| xml_import.id_get() | 539-543 | 获取记录 ID | ⭐⭐⭐ |
| xml_import.model_id_get() | 545-547 | 获取模型和 ID | ⭐⭐ |
| convert_file() | 620-650 | 主入口函数 | ⭐⭐⭐⭐⭐ |
| convert_xml_import() | 715-746 | XML 导入 | ⭐⭐⭐⭐⭐ |
| convert_csv_import() | 657-712 | CSV 导入 | ⭐⭐⭐⭐ |
| convert_sql_import() | 653-654 | SQL 导入 | ⭐⭐ |

表2：支持的 XML 标签

|--------------|-------------------|------------|----------|
| 标签 | 处理器 | 作用 | 常用程度 |
| <record> | _tag_record() | 创建/更新记录 | ⭐⭐⭐⭐⭐ |
| <template> | _tag_template() | 定义 QWeb 模板 | ⭐⭐⭐⭐⭐ |
| <menuitem> | _tag_menuitem() | 创建菜单 | ⭐⭐⭐⭐⭐ |
| <field> | _eval_xml() | 定义字段值 | ⭐⭐⭐⭐⭐ |
| <delete> | _tag_delete() | 删除记录 | ⭐⭐⭐ |
| <function> | _tag_function() | 调用方法 | ⭐⭐⭐ |
| <odoo> | _tag_root() | 根标签 | ⭐⭐⭐⭐⭐ |
| <data> | _tag_root() | 数据容器 | ⭐⭐⭐⭐⭐ |
| <value> | _eval_xml() | 列表/元组元素 | ⭐⭐ |

表3：字段属性和类型

|-----------------|------------|------------------------------------------------|----------|
| 属性/类型 | 说明 | 示例 | 使用频率 |
| name | 字段名（必需） | <field name="email"> | ⭐⭐⭐⭐⭐ |
| ref | 引用 XML ID | ref="base.cn" | ⭐⭐⭐⭐⭐ |
| eval | Python 表达式 | eval="datetime.now()" | ⭐⭐⭐⭐ |
| search | 搜索记录 | search="[('code', '=', 'CN')]" | ⭐⭐⭐ |
| type | 字段类型 | type="xml" | ⭐⭐⭐⭐ |
| model | 关联模型 | model="res.country" | ⭐⭐⭐ |
| file | 文件路径 | file="static/img/logo.png" | ⭐⭐ |
| use | 返回字段 | use="name" | ⭐ |
| type="char" | 字符串（默认） | - | ⭐⭐⭐⭐⭐ |
| type="int" | 整数 | - | ⭐⭐⭐⭐ |
| type="float" | 浮点数 | - | ⭐⭐⭐ |
| type="xml" | XML 内容 | 用于视图 | ⭐⭐⭐⭐⭐ |
| type="html" | HTML 内容 | 用于邮件模板 | ⭐⭐⭐ |
| type="base64" | Base64 编码 | 用于文件 | ⭐⭐⭐ |
| type="file" | 文件路径 | - | ⭐⭐ |
| type="list" | 列表 | - | ⭐ |
| type="tuple" | 元组 | - | ⭐ |

表4：record 标签属性

|---------------|--------|-------------------------------|--------|
| 属性 | 说明 | 示例 | 必需 |
| id | XML ID | id="partner_demo" | ✓ |
| model | 模型名 | model="res.partner" | ✓ |
| forcecreate | 强制创建 | forcecreate="True" | ✗ |
| context | 上下文 | context="{'lang': 'zh_CN'}" | ✗ |
| uid | 执行用户 | uid="base.user_admin" | ✗ |

表5：template 标签属性

|------------------|---------|---------------------------------|--------|
| 属性 | 说明 | 示例 | 常用 |
| id | 模板 ID | id="my_page" | ⭐⭐⭐⭐⭐ |
| name | 模板名称 | name="My Page" | ⭐⭐⭐ |
| inherit_id | 继承模板 | inherit_id="website.layout" | ⭐⭐⭐⭐⭐ |
| priority | 优先级 | priority="20" | ⭐⭐⭐ |
| groups | 权限组 | groups="base.group_user" | ⭐⭐ |
| active | 是否激活 | active="False" | ⭐⭐ |
| customize_show | 显示在定制菜单 | customize_show="True" | ⭐ |
| track | 跟踪修改 | track="True" | ⭐ |
| website_id | 限定网站 | website_id="website.website1" | ⭐ |
| primary | 主模板模式 | primary="True" | ⭐ |

表6：menuitem 标签属性

|------------|--------|-----------------------------------|--------|
| 属性 | 说明 | 示例 | 常用 |
| id | 菜单 ID | id="menu_sale" | ⭐⭐⭐⭐⭐ |
| name | 菜单名称 | name="销售" | ⭐⭐⭐⭐⭐ |
| parent | 父菜单 | parent="base.menu_main" | ⭐⭐⭐⭐⭐ |
| action | 关联动作 | action="action_sale_order" | ⭐⭐⭐⭐⭐ |
| sequence | 排序 | sequence="10" | ⭐⭐⭐⭐ |
| groups | 权限组 | groups="base.group_user" | ⭐⭐⭐⭐ |
| web_icon | 图标 | web_icon="sale,static/icon.png" | ⭐⭐⭐ |
| active | 是否激活 | active="True" | ⭐⭐ |

表7：data 标签属性

|-----------------|--------|-------------------------------|------------------|
| 属性 | 说明 | 示例 | 作用 |
| noupdate | 升级时不更新 | noupdate="1" | 保护用户修改的数据 |
| auto_sequence | 自动序列号 | auto_sequence="True" | 自动设置 sequence 字段 |
| uid | 执行用户 | uid="base.user_admin" | 以特定用户执行 |
| context | 上下文 | context="{'lang': 'zh_CN'}" | 设置上下文 |

表8：转换模式对比

|------------------|-------------|---------------|
| 特性 | init 模式 | update 模式 |
| 触发时机 | 模块安装 | 模块升级 |
| noupdate="1" 的行为 | 创建记录 | 跳过更新 |
| noupdate="0" 的行为 | 创建记录 | 更新记录 |
| CSV 文件 id 列 | 可选 | 必需 |
| 典型用途 | 首次安装 | 版本升级 |

表9：文件类型处理

|------------|---------|------------------------|----------|--------|
| 文件类型 | 扩展名 | 处理器 | 用途 | 性能 |
| XML | .xml | convert_xml_import() | 视图、数据、菜单 | 中等 |
| CSV | .csv | convert_csv_import() | 批量数据 | 快速 |
| SQL | .sql | convert_sql_import() | 直接 SQL | 最快 |
| JavaScript | .js | 无（忽略） | 前端代码 | - |

表10：常用字段命令（Command）

|-----------------------------|---------|--------------------------------------|---------------------|
| 命令 | 说明 | 示例 | 用于 |
| Command.create({...}) | 创建关联记录 | [Command.create({'name': 'A'})] | One2many, Many2many |
| Command.link(id) | 关联已存在记录 | [Command.link(5)] | Many2many |
| Command.unlink(id) | 取消关联 | [Command.unlink(5)] | Many2many |
| Command.delete(id) | 删除关联记录 | [Command.delete(5)] | One2many |
| Command.set([ids]) | 替换全部关联 | [Command.set([1,2,3])] | Many2many |
| Command.clear() | 清空全部关联 | [Command.clear()] | One2many, Many2many |
| Command.update(id, {...}) | 更新关联记录 | [Command.update(5, {'name': 'B'})] | One2many |

📦 第一部分：导入和基础定义（第 1-40 行）

1.1 导入的库

复制代码

import base64      # 处理 base64 编码（比如图片）
import csv         # 处理 CSV 文件
import io          # 输入输出操作
import logging     # 日志记录
import os.path     # 文件路径操作
import pprint      # 漂亮地打印数据
import re          # 正则表达式
import subprocess  # 运行外部命令
import warnings    # 警告信息
from datetime import datetime, timedelta  # 日期时间处理

通俗解释：这些都是 Python 的工具包，就像工具箱里的不同工具，每个都有特定的用途。

1.2 类型定义

复制代码

ConvertMode = Literal['init', 'update']
IdRef = dict[str, int | Literal[False]]

通俗解释：

ConvertMode：定义了两种转换模式
- init（初始化模式）：第一次安装模块时使用，所有数据都会被创建
- update（更新模式）：模块升级时使用，会根据设置决定是否更新数据
IdRef：一个字典，用来记住"XML ID" 和 "数据库 ID" 的对应关系
- XML ID ：比如 base.partner_admin（人类可读）
- 数据库 ID ：比如 3（数据库中的实际 ID）

1.3 异常类

复制代码

class ParseError(Exception):
    ...

通俗解释：当解析 XML 文件出错时，会抛出这个异常。就像你看不懂一本书时说"我读不懂"。

🔧 第二部分：辅助函数

2.1 `_get_eval_context()` - 创建安全的执行环境（第 42-55 行）

作用：当 XML 文件中需要执行 Python 代码时，提供一个安全的环境。

复制代码

def _get_eval_context(self, env, model_str):
    context = dict(
        Command=fields.Command,     # 用于操作关系字段
        time=time,                  # 时间模块
        DateTime=datetime,          # 日期时间类
        datetime=datetime,          # 日期时间类
        timedelta=timedelta,        # 时间差
        relativedelta=relativedelta,# 相对时间差
        version=release.major_version,  # Odoo 版本
        ref=self.id_get,           # 引用其他记录的函数
        pytz=pytz                  # 时区处理
    )
    if model_str:
        context['obj'] = env[model_str].browse
    return context

通俗例子：

假设你在 XML 中写了这样的代码：

复制代码

<field name="date" eval="datetime.now()"/>

这个函数就确保 datetime.now() 能够正确执行，并且只能使用安全的函数（不能执行危险操作）。

为什么需要这个？

安全性：防止 XML 文件中执行恶意代码
方便性：提供常用的工具函数

2.2 `_fix_multiple_roots()` - 修复多根节点（第 57-73 行）

作用：确保 XML 只有一个根节点。

复制代码

def _fix_multiple_roots(node):
    real_nodes = [x for x in node if not isinstance(x, SKIPPED_ELEMENT_TYPES)]
    if len(real_nodes) > 1:
        data_node = etree.Element("data")
        for child in node:
            data_node.append(child)
        node.append(data_node)

通俗例子：

错误的 XML（两个根）：

复制代码

<field name="arch">
    <div>第一个元素</div>
    <div>第二个元素</div>
</field>

自动修复后：

复制代码

<field name="arch">
    <data>
        <div>第一个元素</div>
        <div>第二个元素</div>
    </data>
</field>

为什么需要？ XML 规范要求一个文档只能有一个根元素，这个函数自动修复不规范的 XML。

2.3 `_eval_xml()` - 核心解析器（第 75-203 行）

作用：这是整个文件最核心的函数！它负责解析 XML 节点并返回对应的 Python 值。

支持的节点类型：

A. `<field>` 和 `<value>` 节点

1) search 属性 - 搜索记录

复制代码

<field name="country_id" model="res.country" search="[('code', '=', 'CN')]"/>

解释：在 res.country 模型中搜索代码为 'CN' 的国家，返回中国的记录 ID。

2) eval 属性 - 执行 Python 表达式

复制代码

<field name="date" eval="datetime.now()"/>
<field name="price" eval="100 * 1.13"/>

解释：执行 Python 代码，第一个得到当前时间，第二个计算价格。

3) ref 属性 - 引用其他记录

复制代码

<field name="partner_id" ref="base.partner_admin"/>

解释：引用 XML ID 为 base.partner_admin 的记录。

4) file 属性 - 读取文件

复制代码

<field name="image" type="base64" file="static/img/logo.png"/>

解释：读取图片文件并转换为 base64 编码。

B. 支持的字段类型

|----------|-----------|--------------------------------------------------|
| 类型 | 说明 | 例子 |
| char | 字符串（默认） | <field name="name">张三</field> |
| int | 整数 | <field name="age" type="int">25</field> |
| float | 浮点数 | <field name="price" type="float">99.99</field> |
| xml | XML 内容 | 视图定义 |
| html | HTML 内容 | 邮件模板 |
| base64 | Base64 编码 | 图片、文件 |
| list | 列表 | 多个 <value> 元素 |
| tuple | 元组 | 多个 <value> 元素 |
| file | 文件路径 | 指向模块内的文件 |

C. `<function>` 节点 - 调用方法

复制代码

<function model="ir.module.module" name="update_list"/>

解释：调用 ir.module.module 模型的 update_list() 方法（更新模块列表）。

带参数的例子：

复制代码

<function model="res.partner" name="write" eval="[[1, 2, 3], {'name': '新名字'}]"/>

解释：对 ID 为 1, 2, 3 的伙伴记录，将名字改为"新名字"。

2.4 `str2bool()` 和 `nodeattr2bool()` - 字符串转布尔值（第 205-214 行）

复制代码

def str2bool(value):
    return value.lower() not in ('0', 'false', 'off')

def nodeattr2bool(node, attr, default=False):
    if not node.get(attr):
        return default
    val = node.get(attr).strip()
    if not val:
        return default
    return str2bool(val)

通俗解释：

把字符串转换为 True 或 False。

|------------------------------|-----------|
| 输入字符串 | 结果 |
| "True", "true", "1", "on" | True |
| "False", "false", "0", "off" | False |
| 空字符串或不存在 | default 值 |

例子：

复制代码

<record id="view_1" active="true">
<record id="view_2" active="false">
<record id="view_3" active="1">

🏗️ 第三部分：xml_import 类（第 216-617 行）

这是整个文件的核心类！它负责解析 XML 文件并将数据导入数据库。

3.1 初始化方法 `init()` （第 596-612 行）

复制代码

def __init__(self, env, module, idref, mode, noupdate=False, xml_filename=''):
    self.mode = mode              # 'init' 或 'update'
    self.module = module          # 当前模块名，如 'sale'
    self.envs = [env(...)]        # 环境栈
    self.idref = {} if idref is None else idref  # XML ID 映射
    self._noupdate = [noupdate]   # 是否跳过更新
    self._sequences = []          # 序列号栈
    self.xml_filename = xml_filename  # 当前文件名
    self._tags = {                # 标签处理器映射
        'record': self._tag_record,
        'delete': self._tag_delete,
        'function': self._tag_function,
        'menuitem': self._tag_menuitem,
        'template': self._tag_template,
        **dict.fromkeys(self.DATA_ROOTS, self._tag_root)
    }

通俗解释：

创建一个 XML 导入器对象，设置好所有必要的配置。就像开始工作前，先准备好所有工具。

参数说明：

env：Odoo 环境，可以访问数据库
module：当前模块名（如 sale, purchase 等）
idref：记住哪些记录已经创建了
mode：'init'（安装）或 'update'（升级）
noupdate：如果是 True，升级时不更新数据
xml_filename：当前处理的文件名

3.2 工具方法

A. `make_xml_id()` - 生成完整 XML ID（第 233-236 行）

复制代码

def make_xml_id(self, xml_id):
    if not xml_id or '.' in xml_id:
        return xml_id
    return "%s.%s" % (self.module, xml_id)

通俗例子：

复制代码

# 当前模块是 'sale'
make_xml_id('order_form')           # 返回 'sale.order_form'
make_xml_id('base.partner_form')    # 返回 'base.partner_form'（已经有模块前缀）

为什么需要？ 确保每个 XML ID 都是唯一的，不会和其他模块冲突。

B. `_test_xml_id()` - 验证 XML ID（第 238-246 行）

作用：检查 XML ID 格式是否正确，引用的模块是否已安装。

规则：

最多只能有一个点 .
引用其他模块时，该模块必须已安装

例子：

复制代码

_test_xml_id('sale.order_form')        # ✓ 正确
_test_xml_id('base.res.partner.form')  # ✗ 错误（两个点）
_test_xml_id('uninstalled.record')     # ✗ 错误（模块未安装）

C. `get_env()` - 获取特定环境（第 217-231 行）

作用：根据 XML 节点的属性创建特定的 Odoo 环境。

复制代码

<record id="partner_1" model="res.partner" uid="base.user_admin" context="{'lang': 'zh_CN'}">

解释：

uid="base.user_admin"：以管理员身份创建记录
context="{'lang': 'zh_CN'}"：设置语言为简体中文

3.3 标签处理方法

A. `_tag_delete()` - 删除记录（第 248-267 行）

作用：从数据库中删除记录。

方式 1：通过搜索条件删除

复制代码

<delete model="res.partner" search="[('is_demo', '=', True)]"/>

解释：删除所有演示伙伴记录。

方式 2：通过 XML ID 删除

复制代码

<delete model="res.partner" id="partner_demo"/>

解释：删除 XML ID 为 partner_demo 的记录。

方式 3：两者结合

复制代码

<delete model="res.partner" search="[('type', '=', 'temp')]" id="partner_temp_1"/>

解释：删除搜索到的记录 + 指定 ID 的记录。

安全机制：

如果搜索失败，只记录警告，不会中断
如果 ID 不存在，也只记录警告

B. `_tag_function()` - 调用函数（第 269-273 行）

作用：执行模型的方法。

例子 1：无参数方法

复制代码

<function model="ir.module.module" name="update_list"/>

解释：更新可用模块列表。

例子 2：带参数方法

复制代码

<function model="res.partner" name="create" eval="[{'name': '张三', 'email': 'zhang@example.com'}]"/>

解释：创建一个新的伙伴记录。

例子 3：使用子节点传参

复制代码

<function model="res.partner" name="write">
    <value eval="[1, 2, 3]"/>  <!-- 第一个参数：记录 IDs -->
    <value name="name">新名字</value>  <!-- kwargs 参数 -->
</function>

noupdate 检查：

如果 noupdate=True 且 mode='update'，这个函数调用会被跳过。

C. `_tag_menuitem()` - 创建菜单（第 275-334 行）

作用：创建或更新 Odoo 菜单项。

基础例子：

复制代码

<menuitem id="menu_sale" 
          name="销售" 
          sequence="10"/>

完整例子：

复制代码

<menuitem id="menu_sale_orders"
          name="销售订单"
          parent="menu_sale"
          action="action_sale_order"
          sequence="20"
          groups="sales_team.group_sale_user"
          web_icon="sale,static/description/icon.png"/>

属性说明：

|------------|-------------|----------------------------------------------|
| 属性 | 说明 | 例子 |
| id | XML ID（必需） | menu_sale |
| name | 菜单名称 | 销售 |
| parent | 父菜单 XML ID | base.menu_main |
| action | 关联的动作 | action_sale_order |
| sequence | 排序（数字越小越靠前） | 10 |
| groups | 权限组（逗号分隔） | sales_team.group_sale_user,base.group_user |
| web_icon | 图标 | sale,static/description/icon.png |
| active | 是否激活 | True 或 False |

嵌套菜单：

复制代码

<menuitem id="menu_sale" name="销售">
    <menuitem id="menu_sale_orders" name="订单"/>
    <menuitem id="menu_sale_customers" name="客户"/>
</menuitem>

权限组的特殊用法：

复制代码

<!-- 添加权限组 -->
<menuitem id="menu_1" groups="base.group_user"/>

<!-- 移除权限组（注意前面的减号）-->
<menuitem id="menu_2" groups="-base.group_user,sales_team.group_sale_manager"/>

D. `_tag_record()` - 创建/更新记录（第 336-467 行）

这是最重要、最复杂的方法！ 它负责创建或更新数据库记录。

基础结构：

复制代码

<record id="partner_demo" model="res.partner">
    <field name="name">演示伙伴</field>
    <field name="email">demo@example.com</field>
</record>

工作流程：

复制代码

1. 读取 model 和 id 属性
2. 检查 noupdate 标志
3. 遍历所有 <field> 子节点
4. 解析每个字段的值
5. 处理关系字段（many2one, one2many, many2many）
6. 调用 model._load_records() 保存
7. 更新 idref 映射
8. 处理嵌套记录（one2many）

字段值的设置方式：

1) 直接文本

复制代码

<field name="name">张三</field>

2) 引用其他记录

复制代码

<field name="country_id" ref="base.cn"/>

3) 搜索记录

复制代码

<field name="country_id" model="res.country" search="[('code', '=', 'CN')]"/>

4) 执行 Python 代码

复制代码

<field name="date" eval="datetime.now()"/>
<field name="price" eval="100 * 1.13"/>

5) Many2many 字段（多对多）

复制代码

<field name="category_id" eval="[Command.set([ref('category_1'), ref('category_2')])]"/>

解释：设置分类为 category_1 和 category_2。

6) One2many 字段（一对多）- 嵌套记录

复制代码

<record id="partner_1" model="res.partner">
    <field name="name">公司A</field>
    <field name="child_ids">
        <record id="partner_1_contact_1" model="res.partner">
            <field name="name">联系人1</field>
            <field name="type">contact</field>
        </record>
        <record id="partner_1_contact_2" model="res.partner">
            <field name="name">联系人2</field>
            <field name="type">contact</field>
        </record>
    </field>
</record>

解释：创建一个公司，同时创建两个联系人。

7) Reference 字段（引用字段）

复制代码

<field name="res_id" ref="sale.order_1"/>

解释：Reference 字段存储的格式是 model,id，如 sale.order,5。

noupdate 机制：

复制代码

<data noupdate="1">
    <record id="demo_data" model="res.partner">
        <field name="name">演示数据</field>
    </record>
</data>

行为：

init 模式（安装）：创建记录
update 模式（升级） ：
- 如果 noupdate="1"：跳过，不更新
- 如果 noupdate="0"：更新记录

为什么需要 noupdate？

用户可能修改了演示数据，升级模块时不希望被覆盖。

forcecreate 属性：

复制代码

<record id="other_module.record_1" model="res.partner" forcecreate="True">

解释：允许在当前模块中创建/修改其他模块的记录。

E. `_tag_template()` - 处理 QWeb 模板（第 469-537 行）

作用：将 <template> 标签转换为 ir.ui.view 记录。

为什么要转换？

QWeb 模板本质上就是特殊的视图
存储在 ir.ui.view 表中，类型为 'qweb'
统一管理所有视图和模板

基础例子：

复制代码

<template id="my_page">
    <div class="container">
        <h1>欢迎</h1>
    </div>
</template>

转换后的等价形式：

复制代码

<record id="my_page" model="ir.ui.view">
    <field name="name">my_page</field>
    <field name="key">module_name.my_page</field>
    <field name="type">qweb</field>
    <field name="arch" type="xml">
        <t t-name="module_name.my_page">
            <div class="container">
                <h1>欢迎</h1>
            </div>
        </t>
    </field>
</record>

转换过程详解：

复制代码

1. 提取 template 的 id 属性
2. 生成完整的模板名称（module.template_id）
3. 将 <template> 标签改为 <t> 标签
4. 添加 t-name 属性
5. 创建 <record> 元素
6. 设置字段：name, key, type='qweb', arch
7. 处理其他属性（inherit_id, priority 等）
8. 调用 _tag_record() 保存

模板继承：

复制代码

<template id="my_page_extended" inherit_id="module.my_page">
    <xpath expr="//h1" position="replace">
        <h1>新标题</h1>
    </xpath>
</template>

支持的属性：

|------------------|----------------|---------------------|
| 属性 | 说明 | 例子 |
| id | 模板 XML ID | my_template |
| name | 模板名称 | My Template |
| inherit_id | 继承的模板 | website.layout |
| priority | 优先级（数字越小优先级越高） | 16 |
| groups | 访问权限组 | base.group_user |
| active | 是否激活 | True 或 False |
| customize_show | 是否在定制菜单显示 | True 或 False |
| track | 是否跟踪修改 | True 或 False |
| website_id | 限定网站 | website.website_1 |
| primary | 主模板模式 | True |

主题模块特殊处理：

复制代码

if self.module.startswith('theme_'):
    model = 'theme.ir.ui.view'
else:
    model = 'ir.ui.view'

解释：主题模块的模板存储在 theme.ir.ui.view 表中。

F. `_tag_root()` - 处理根标签（第 549-580 行）

作用：处理 <odoo>, <data>, <openerp> 根标签，遍历所有子标签。

支持的根标签：

复制代码

<odoo>...</odoo>
<data>...</data>
<openerp>...</openerp>  <!-- 旧版本兼容 -->

noupdate 属性：

复制代码

<odoo>
    <data noupdate="1">
        <!-- 这里的数据在升级时不会更新 -->
    </data>
    <data noupdate="0">
        <!-- 这里的数据在升级时会更新 -->
    </data>
</odoo>

auto_sequence 属性：

复制代码

<data auto_sequence="True">
    <record id="view_1" model="ir.ui.view">...</record>
    <record id="view_2" model="ir.ui.view">...</record>
    <record id="view_3" model="ir.ui.view">...</record>
</data>

解释：自动为每条记录设置递增的 sequence 值（10, 20, 30...）。

错误处理：

捕获所有异常
提供详细的错误信息（文件名、行号、上下文）
使用 ParseError 包装原始异常

3.4 ID 管理方法

`id_get()` - 获取记录 ID（第 539-543 行）

复制代码

def id_get(self, id_str, raise_if_not_found=True):
    id_str = self.make_xml_id(id_str)
    if id_str in self.idref:
        return self.idref[id_str]
    return self.model_id_get(id_str, raise_if_not_found)[1]

工作流程：

复制代码

1. 将相对 ID 转换为完整 ID
2. 先查缓存（idref）
3. 缓存没有则查数据库（model_id_get）
4. 返回数据库 ID

例子：

复制代码

# 在 sale 模块中
id_get('order_1')              # 查找 sale.order_1，返回如 42
id_get('base.partner_admin')   # 查找 base.partner_admin，返回如 3

`model_id_get()` - 获取模型和记录 ID（第 545-547 行）

复制代码

def model_id_get(self, id_str, raise_if_not_found=True):
    id_str = self.make_xml_id(id_str)
    return self.env['ir.model.data']._xmlid_to_res_model_res_id(id_str, raise_if_not_found=raise_if_not_found)

返回值 ：(model_name, record_id)

例子：

复制代码

model_id_get('base.partner_admin')
# 返回：('res.partner', 3)

3.5 属性方法

`env` 属性（第 582-584 行）

复制代码

@property
def env(self):
    return self.envs[-1]

解释：返回当前环境。支持嵌套环境栈（可以临时切换用户或上下文）。

`noupdate` 属性（第 586-588 行）

复制代码

@property
def noupdate(self):
    return self._noupdate[-1]

解释：返回当前的 noupdate 状态。支持嵌套（<data> 标签可以嵌套）。

`next_sequence()` 方法（第 590-594 行）

复制代码

def next_sequence(self):
    value = self._sequences[-1]
    if value is not None:
        value = self._sequences[-1] = value + 10
    return value

解释：

如果启用了 auto_sequence，返回递增的序列号（10, 20, 30...）
否则返回 None

📄 第四部分：文件转换函数

4.1 `convert_file()` - 主入口函数（第 620-650 行）

作用：根据文件扩展名，调用相应的转换器。

复制代码

def convert_file(env, module, filename, idref, mode='update', noupdate=False, kind=None, pathname=None):
    ext = os.path.splitext(filename)[1].lower()
    
    with file_open(pathname, 'rb', env=env) as fp:
        if ext == '.csv':
            convert_csv_import(...)
        elif ext == '.sql':
            convert_sql_import(...)
        elif ext == '.xml':
            convert_xml_import(...)
        elif ext == '.js':
            pass  # 忽略
        else:
            raise ValueError("Can't load unknown file type %s.", filename)

支持的文件类型：

|---------|------------------------|---------------|
| 扩展名 | 处理器 | 用途 |
| .xml | convert_xml_import() | 视图、数据、菜单等 |
| .csv | convert_csv_import() | 批量数据导入 |
| .sql | convert_sql_import() | 直接执行 SQL |
| .js | 无（忽略） | JavaScript 文件 |

使用场景：

复制代码

# 在模块安装时，Odoo 会自动调用
convert_file(env, 'sale', 'views/sale_views.xml', {}, mode='init')
convert_file(env, 'sale', 'data/demo.csv', {}, mode='init')

4.2 `convert_xml_import()` - XML 导入（第 715-746 行）

作用：导入 XML 文件数据。

复制代码

def convert_xml_import(env, module, xmlfile, idref=None, mode='init', noupdate=False, report=None):
    # 1. 解析 XML 文件
    doc = etree.parse(xmlfile)
    
    # 2. 验证 XML 格式（使用 RelaxNG schema）
    schema = os.path.join(config.root_path, 'import_xml.rng')
    relaxng = etree.RelaxNG(etree.parse(schema))
    relaxng.assert_(doc)
    
    # 3. 创建 xml_import 对象并解析
    obj = xml_import(env, module, idref, mode, noupdate=noupdate, xml_filename=xmlfile.name)
    obj.parse(doc.getroot())

工作流程：

复制代码

1. 解析 XML 文件
2. 使用 Schema 验证格式
3. 创建 xml_import 实例
4. 调用 parse() 处理
5. 遍历所有标签并调用相应处理器

Schema 验证：

使用 import_xml.rng 文件定义 XML 格式规范
检查标签名、属性是否合法
如果格式错误，提供详细的错误信息

错误处理：

复制代码

try:
    relaxng.assert_(doc)
except Exception:
    # 使用 jingtrang 工具提供更友好的错误信息
    if jingtrang:
        subprocess.run(['pyjing', schema, xmlfile.name])
    else:
        # 显示 RelaxNG 错误日志
        for e in relaxng.error_log:
            _logger.warning(e)

4.3 `convert_csv_import()` - CSV 导入（第 657-712 行）

作用：批量导入 CSV 数据。

CSV 文件要求：

分隔符 ：逗号 ,
引号：双引号 "
编码：UTF-8
第一行：字段名（必须）
update 模式 ：必须包含 id 列

CSV 文件命名规则：

复制代码

模型名-任意名称.csv
例如：
  res.partner-customers.csv  → 导入到 res.partner 模型
  product.product-demo.csv   → 导入到 product.product 模型

CSV 示例：

res.partner-demo.csv：

复制代码

id,name,email,phone,country_id:id
partner_demo_1,张三,zhang@example.com,13800138000,base.cn
partner_demo_2,李四,li@example.com,13900139000,base.cn
partner_demo_3,王五,wang@example.com,13700137000,base.us

字段名格式：

|------------------|----------------------------|--------------------------------------|
| 格式 | 说明 | 例子 |
| name | 普通字段 | name,email,phone |
| country_id:id | Many2one 引用 XML ID | base.cn |
| country_id | Many2one 引用数据库 ID | 42 |
| category_id:id | Many2many 引用 XML ID（多个用逗号） | category_1,category_2 |
| name@zh_CN | 翻译字段（会被忽略） | 在翻译导入时处理 |

工作流程：

复制代码

1. 从文件名提取模型名
2. 读取 CSV 第一行作为字段名
3. 过滤掉翻译字段（包含 @ 的）
4. 读取所有数据行
5. 调用 model.load() 批量导入
6. 检查错误消息

翻译字段处理：

复制代码

id,name,name@zh_CN,name@en_US
product_1,Product A,产品A,Product A

解释：name@zh_CN 和 name@en_US 在普通导入时会被忽略，在翻译导入时才处理。

错误处理：

复制代码

result = env[model].with_context(**context).load(fields, datas)
if any(msg['type'] == 'error' for msg in result['messages']):
    warning_msg = "\n".join(msg['message'] for msg in result['messages'])
    raise Exception("导入失败：" + warning_msg)

导入上下文：

复制代码

context = {
    'mode': mode,
    'module': module,
    'install_mode': True,
    'install_module': module,
    'install_filename': fname,
    'noupdate': noupdate,
}

4.4 `convert_sql_import()` - SQL 导入（第 653-654 行）

作用：直接执行 SQL 文件中的语句。

复制代码

def convert_sql_import(env, fp):
    env.cr.execute(fp.read())

使用场景：

复杂的数据迁移
性能优化的批量操作
直接操作数据库结构

SQL 文件示例：

data/init.sql：

复制代码

-- 创建索引
CREATE INDEX idx_partner_name ON res_partner(name);

-- 批量更新
UPDATE res_partner SET active = true WHERE type = 'contact';

-- 插入数据
INSERT INTO res_country (code, name) VALUES ('XX', 'Test Country');

注意事项：

⚠️ 危险操作：直接执行 SQL，绕过 ORM
不会触发计算字段、约束检查
不会记录审计日志
需要确保 SQL 兼容不同数据库（PostgreSQL）
建议只用于简单、必要的操作

💡 实际应用示例

示例1：创建演示数据

复制代码

<odoo>
    <data noupdate="1">
        <!-- 创建一个公司 -->
        <record id="company_demo" model="res.partner">
            <field name="name">演示公司</field>
            <field name="company_type">company</field>
            <field name="email">demo@company.com</field>
            <field name="phone">010-12345678</field>
            <field name="country_id" ref="base.cn"/>
            <field name="child_ids">
                <!-- 嵌套创建联系人 -->
                <record id="contact_demo_1" model="res.partner">
                    <field name="name">张经理</field>
                    <field name="type">contact</field>
                    <field name="email">zhang@company.com</field>
                </record>
            </field>
        </record>
    </data>
</odoo>

示例2：创建菜单结构

复制代码

<odoo>
    <data>
        <!-- 顶级菜单 -->
        <menuitem id="menu_sale" 
                  name="销售" 
                  sequence="10"
                  web_icon="sale,static/description/icon.png"/>
        
        <!-- 子菜单 -->
        <menuitem id="menu_sale_orders"
                  name="销售订单"
                  parent="menu_sale"
                  action="sale.action_orders"
                  sequence="10"/>
        
        <menuitem id="menu_sale_customers"
                  name="客户"
                  parent="menu_sale"
                  action="base.action_partner_form"
                  sequence="20"/>
    </data>
</odoo>

示例3：定义网页模板

复制代码

<odoo>
    <data>
        <!-- 基础模板 -->
        <template id="my_website_page" name="My Page">
            <t t-call="website.layout">
                <div class="container">
                    <h1>欢迎来到我的页面</h1>
                    <p>这是内容</p>
                </div>
            </t>
        </template>
        
        <!-- 继承并修改模板 -->
        <template id="my_website_page_extended" inherit_id="my_website_page">
            <xpath expr="//h1" position="replace">
                <h1 class="text-primary">新标题</h1>
            </xpath>
        </template>
    </data>
</odoo>

示例4：批量导入 CSV

res.partner-customers.csv:

复制代码

id,name,email,phone,country_id:id,category_id:id
customer_1,北京公司,beijing@example.com,010-11111111,base.cn,"base.res_partner_category_0,base.res_partner_category_1"
customer_2,上海公司,shanghai@example.com,021-22222222,base.cn,base.res_partner_category_0
customer_3,深圳公司,shenzhen@example.com,0755-33333333,base.cn,base.res_partner_category_1

示例5：调用方法

复制代码

<odoo>
    <data noupdate="1">
        <!-- 更新模块列表 -->
        <function model="ir.module.module" name="update_list"/>
        
        <!-- 创建记录 -->
        <function model="res.partner" name="create">
            <value eval="[{
                'name': '自动创建的伙伴',
                'email': 'auto@example.com'
            }]"/>
        </function>
        
        <!-- 批量更新 -->
        <function model="res.partner" name="write">
            <value eval="[[ref('partner_1'), ref('partner_2')]]"/>
            <value eval="{'active': True}"/>
        </function>
    </data>
</odoo>

🎓 学习建议

对于初学者：

先理解基础概念：XML ID、模型、字段
从简单开始 ：先学习 <record> 标签
多看示例：查看 Odoo 标准模块的数据文件
逐步深入 ：掌握 <record> 后再学习 <template> 和 <menuitem>

关键理解点：

XML ID 系统：理解 XML ID 是如何映射到数据库 ID 的
noupdate 机制：理解为什么需要保护演示数据
eval 表达式：学习如何在 XML 中使用 Python 代码
关系字段：掌握 Many2one、One2many、Many2many 的处理

调试技巧：

查看日志：--log-level=debug
使用 pprint 打印数据
检查 ir.model.data 表了解 XML ID 映射
使用 Schema 验证 XML 格式

📝 总结

convert.py 是 Odoo 数据加载的核心：

统一接口：处理 XML、CSV、SQL 三种格式
安全性：使用 safe_eval 防止恶意代码
灵活性：支持多种数据定义方式
智能转换 ：自动将 <template> 转换为 ir.ui.view 记录
错误处理：提供详细的错误信息

理解这个文件，就理解了 Odoo 模块是如何加载数据的！

ODOO数据文件（XML、CSV、SQL）是如何转换并加载到 Odoo 数据库

🎯 文件的作用是什么？

📊 完整功能总结表

表1：核心类和方法

表2：支持的 XML 标签

表3：字段属性和类型

表4：record 标签属性

表5：template 标签属性

表6：menuitem 标签属性

表7：data 标签属性

表8：转换模式对比

表9：文件类型处理

表10：常用字段命令（Command）

📦 第一部分：导入和基础定义（第 1-40 行）

1.1 导入的库

1.2 类型定义

1.3 异常类

🔧 第二部分：辅助函数

2.1 _get_eval_context() - 创建安全的执行环境（第 42-55 行）

2.2 _fix_multiple_roots() - 修复多根节点（第 57-73 行）

2.3 _eval_xml() - 核心解析器（第 75-203 行）

支持的节点类型：

A. <field> 和 <value> 节点

B. 支持的字段类型

C. <function> 节点 - 调用方法

2.4 str2bool() 和 nodeattr2bool() - 字符串转布尔值（第 205-214 行）

🏗️ 第三部分：xml_import 类（第 216-617 行）

3.1 初始化方法 __init__() （第 596-612 行）

3.2 工具方法

A. make_xml_id() - 生成完整 XML ID（第 233-236 行）

B. _test_xml_id() - 验证 XML ID（第 238-246 行）

C. get_env() - 获取特定环境（第 217-231 行）

3.3 标签处理方法

A. _tag_delete() - 删除记录（第 248-267 行）

B. _tag_function() - 调用函数（第 269-273 行）

C. _tag_menuitem() - 创建菜单（第 275-334 行）

D. _tag_record() - 创建/更新记录（第 336-467 行）

E. _tag_template() - 处理 QWeb 模板（第 469-537 行）

F. _tag_root() - 处理根标签（第 549-580 行）

3.4 ID 管理方法

id_get() - 获取记录 ID（第 539-543 行）

model_id_get() - 获取模型和记录 ID（第 545-547 行）

3.5 属性方法

env 属性（第 582-584 行）

noupdate 属性（第 586-588 行）

next_sequence() 方法（第 590-594 行）

📄 第四部分：文件转换函数

4.1 convert_file() - 主入口函数（第 620-650 行）

4.2 convert_xml_import() - XML 导入（第 715-746 行）

4.3 convert_csv_import() - CSV 导入（第 657-712 行）

4.4 convert_sql_import() - SQL 导入（第 653-654 行）

💡 实际应用示例

示例1：创建演示数据

示例2：创建菜单结构

示例3：定义网页模板

示例4：批量导入 CSV

示例5：调用方法

🎓 学习建议

对于初学者：

关键理解点：

调试技巧：

📝 总结

2.1 `_get_eval_context()` - 创建安全的执行环境（第 42-55 行）

2.2 `_fix_multiple_roots()` - 修复多根节点（第 57-73 行）

2.3 `_eval_xml()` - 核心解析器（第 75-203 行）

A. `<field>` 和 `<value>` 节点

C. `<function>` 节点 - 调用方法

2.4 `str2bool()` 和 `nodeattr2bool()` - 字符串转布尔值（第 205-214 行）

3.1 初始化方法 `init()` （第 596-612 行）

A. `make_xml_id()` - 生成完整 XML ID（第 233-236 行）

B. `_test_xml_id()` - 验证 XML ID（第 238-246 行）

C. `get_env()` - 获取特定环境（第 217-231 行）

A. `_tag_delete()` - 删除记录（第 248-267 行）

B. `_tag_function()` - 调用函数（第 269-273 行）

C. `_tag_menuitem()` - 创建菜单（第 275-334 行）

D. `_tag_record()` - 创建/更新记录（第 336-467 行）

E. `_tag_template()` - 处理 QWeb 模板（第 469-537 行）

F. `_tag_root()` - 处理根标签（第 549-580 行）

`id_get()` - 获取记录 ID（第 539-543 行）

`model_id_get()` - 获取模型和记录 ID（第 545-547 行）

`env` 属性（第 582-584 行）

`noupdate` 属性（第 586-588 行）

`next_sequence()` 方法（第 590-594 行）

4.1 `convert_file()` - 主入口函数（第 620-650 行）

4.2 `convert_xml_import()` - XML 导入（第 715-746 行）

4.3 `convert_csv_import()` - CSV 导入（第 657-712 行）

4.4 `convert_sql_import()` - SQL 导入（第 653-654 行）