简介面向Odoo 17开发者、实施顾问及二次开发人员这份中文版数据字典以PDF形式完整梳理了系统核心数据库结构。资源内容基于Navicat生成报告系统罗列了public模式下各业务模块的数据表、字段类型、键值关系与索引信息涵盖account_account等财务与供应链相关表方便快速定位模型间关联。全文共1个PDF文件压缩包总大小约8.07MB轻量易携带适合作为日常开发查阅的手边手册。目前已有133人学习使用尤其适合正在入门Odoo或需要为定制模块梳理数据模型的读者。借助这份字典可减少逐张翻表的时间在继承扩展、编写domain表达式或分析数据流时提供清晰参照。1. 为什么需要 Odoo 17 数据字典中文版从一次报表事故说起我有一次给某公司做 Odoo 17 的经营分析报表开发同事对着数据库翻了一个下午最后发现「销售订单状态」在这张表里是 Selection 类型值存的是英文代码而客户要的是中文显示。更麻烦的是销售订单主表里一个叫「伙伴」的字段实际对应的是客户和供应商共用的伙伴主数据报表里的过滤条件一开始就建错了。折腾了两天最后翻到一份 Odoo 17 数据字典的中文版才把表结构、字段类型、中文标签一次对齐。所谓数据字典就是把 Odoo 数据库里每张表、每个字段、每个类型、每个约束整理成文档而中文版则把英文技术字段和标签翻译成中文让开发、运维、实施顾问不用再对着源码猜字段含义。这篇笔记面向的是正在做 Odoo 17 二次开发、报表取数、数据迁移或系统对接的人目标是让你拿到字典后知道先看什么、怎么用、坑在哪。2. 数据字典到底装了什么模型、表、字段与中文映射2.1 从模型到表名先弄懂 Odoo 的命名链数据字典里最常见的一列叫「模型」比如sale.order、account.move、res.partner。这一列和你真正去 PostgreSQL 里查的表名并不一样中间隔着一条固定的转换规则模型名里的点号换成下划线sale.order变成sale_orderaccount.move变成account_moveres.partner变成res_partner。字典里一般会同时列出「模型」和「对应表名」两列方便你直接跳转到数据库工具里去查。这里有个值得注意的细节Odoo 17 的表名不全是模型名直接转换。像mail.message对应mail_message但一些继承了mail.thread的模型字段并不是分散在多个表里而是全部落在主表那一张上字典里会把这些继承来的字段也一并列出并在「来源」列标注来自哪个 mixin。你在数据库里看不到所谓的「继承子表」这是和 Java 系 ORM 很不一样的地方。还有一类「瞬态模型」也就是向导类模型比如各种导出向导、报表向导。它们在数据库里确实有表但数据是临时的会话结束或者定期清理后会被清掉。字典一般会给这类模型单独分组或用「类型」列标出来。我一般建议新手拿到字典后先看两处一是「模型与表名对照」这个说明段落二是每个模块开头对模块用途的中文简介这两处能避免你拿着点号去数据库里查表的尴尬。2.2 字段类型在数据字典里的表达方式数据字典的字段类型列通常直接用 Odoo 里的字段类型名称比如Char、Text、Integer、Float、Monetary、Boolean、Date、Datetime、Many2one、One2many、Many2many、Selection、Reference、Binary、Json。这些类型名对应到数据库里的物理结构是有规律可循的我整理了一个常用对照关系字典字段类型数据库里的物理表现备注Char / Textvarchar/text列长度由模型里的size决定Integer / Floatint/numeric列Float 在库里可能是numeric或double precisionMonetarynumeric列金额字段必须搭配currency_id使用否则金额单位不明Booleanboolean列默认值一般是falseDate / Datetimedate/timestamp列注意时区只影响显示库里存 UTCMany2one字段名_id的 int 列存的是关联表主键名字自动带_id后缀One2many不产生列存在对方表里字典里通常会提示「反查关系」Many2many不产生列会自动建中间表表名一般是模型a_模型b_relSelectionvarchar或int列取决于选项定义时用的是字符串还是数字Referencevarchar列存的是「模型名,ID」的组合字符串Binarybytea列文件内容一般也存这里注意占用空间Jsonjsonb列动态结构字典里往往只说明用途这个对照表是数据字典里最值得反复看的部分因为很多翻车事故都出在「把 Selection 字段当字符串处理」「把 Monetary 字段直接求和却不理会币种」上。字典里的中文标签只是给人看的字段类型才是决定你查询和写入逻辑的最终依据。2.3 中文翻译带来的便利与歧义数据字典「已翻译为中文」真正值钱的是「字段中文标签」这一列。像invoice_origin这类字段英文名直译是「发票来源」但业务上它可能是「源单据号」partner_id在不同模块里分别表示「客户」「供应商」「联系人」「承运商」翻译成中文标签后业务人员一眼就能看懂。这也是实施顾问和业务需求方沟通时最省事的部分拿着字典中文标签核对需求比对着英文模型名讲半天高效得多。但中文翻译也会引入新的歧义我不能不提醒。第一「备注」这个标签在十几张表里都有备注对应的技术字段可能是name、note、comment字段类型也可能完全不同。第二人工翻译偶尔会把「名称」和「姓名」混用比如res.partner里的name在中文语境下更接近「单位名称」但有的字典版本直接翻译成「姓名」。第三所有中文标签都不能当「唯一键」用真正稳定的标识永远是技术字段名。所以我的习惯是看字典时以「技术字段名 中文标签」成对看写 SQL 时只引用技术字段名中文标签只用于沟通和理解。3. 用数据字典做实际查询拿到手后先做这三件事3.1 用 SQL 验证一张业务表的字段定义数据字典是二手资料严谨的做法是先拿它去数据库里验证一遍。假设你想确认销售订单相关的表结构先翻字典里sale.order那一节记下它对应的表名sale_order然后在 PostgreSQL 里执行下面这条 SQLSELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name sale_order ORDER BY ordinal_position;这段查询从数据库系统表里读出sale_order的所有物理列名、类型和是否可空。拿着这份结果和字典里的字段清单逐一对能快速发现三类差异字典里有但库表里没有的列、库表里有但字典里没记录的列、以及类型对不上的列。做完这张表建议再顺手验证一下account_move和res_partner这两张表是财务和客户主数据里被引用最多的表字段也最多。如果字典在这三张表上都能对得上说明你手里这份字典可信度相当高可以放心往下用如果连基础表都对不上要么是版本对错了要么是字典本身有删改后面所有查询都要留个心眼。验证期间我先不着急写报表逻辑而是把发现的差异记录下来每一条都标注「字典缺失」还是「多余的列」后面字段核对时这份记录就是我的核对底稿。3.2 从字典反查模型写一个字段检查脚本很多时候你不是从数据库出发而是从需求出发业务说「我要查订单的客户名称」你翻字典找到了partner_id但不确定它到底能不能直接拉到客户名。最常见的做法是在 Odoo shell 里直接检查模型字段定义确认字段是否真实存在、是不是 related 字段# 在 odoo-bin shell 中执行确认字段来源 env[sale.order]._fields[partner_id] # 查看字段的完整定义包含 type、related、store 等属性 env[sale.order]._fields[partner_id].__dict__ # 快速列出模型里所有不落库的字段辅助判断查询计划 for name, field in env[sale.order]._fields.items(): if not field.store and field.compute: print(name, -, field.compute)这段脚本的价值在于Odoo 17 里很多字段是「计算字段」默认不存数据库比如销售订单的amount_total在旧版本是存库的但某些自定义字段或新版模型可能是实时计算的。store属性为False时你在 PostgreSQL 表里看不到这个字段直接用 SQL 去查就查不到必须走 ORM 或在 SQL 里自己写表达式。compute属性则告诉你这个值是怎么算出来的方便你在 SQL 里复刻算法。字段检查脚本是数据字典的「运行时补充」。字典是静态文档可能滞后于线上环境但模型里的_fields永远是当前代码的真实状态。我一般把字典当成索引把_fields当成最终裁决者两边不一致时以线上代码为准。3.3 用它设计报表查询的字段清单数据字典最日常的用法是设计报表取数清单。假设你要做一个「客户回款分析表」涉及客户主数据和财务凭证两张核心表。正确步骤是先翻字典里res.partner和account.move两节把需要的字段按「模型 / 表名 / 字段名 / 中文标签 / 类型 / 是否必填 / 备注」整理成一张清单再拿去和业务确认。我给一个字段清单模板模型表名字段名中文标签类型用途说明res.partnerres_partnername名称Char客户显示名res.partnerres_partnercustomer_rank客户等级Integer判断是否客户account.moveaccount_movepartner_id业务伙伴Many2one关联客户account.moveaccount_moveinvoice_date发票日期Date回款统计时间account.moveaccount_moveamount_total总额Monetary金额汇总account.moveaccount_movepayment_state付款状态Selection按状态过滤字段清单列好以后再去数据库里用information_schema核对一遍金额字段所在的表有没有对应的currency_id列这一点做跨国业务时特别容易漏。清单可以直接写成 Markdown 表格放在项目文档里也可以导入到在线表格里共享给团队。我在做这类报表时还会额外加一列「字典页码或章节位置」这样后续有人对字段语义有疑问时能快速溯源到字典原文。4. Odoo 17 数据字典避坑指南版本、翻译与字段纠纷4.1 现象字段在字典里有但数据库表里没有对应列我遇到过字典里明明写了sale.order有个字段叫x_remark类型是Text但sale_order表里怎么都查不到x_remark这一列。原因通常是两种第一种这个字段是计算字段或 related 字段默认不落库第二种这个字段来自某个未安装的模块字典在整理时把模块内全部模型都列进去了但实际环境没装那个模块所以表里自然没有。解决方法是先看字典「类型」列是compute/related还是普通类型再在 Odoo 界面「设置-技术-模型」里查这个字段是否存在以及它属于哪个模块。如果是 related 字段去它引用的源字段所在表查如果属于未安装模块确认是否需要安装。判断依据是字典描述的是「标准 Odoo 17 全模块」理论结构而你的环境是「已安装子集」两者全等才正常否则一切以当前环境数据库为准。4.2 现象系统表里多出一批字典没记录的列和上面相反的情况我也踩过数据库里出现了字典里完全没写的列比如res_partner里多了x_studio_custom_field之类的字段后缀。这类列大部分是「开发者模式」里用「自定义字段」功能加出来的也可能是某个第三方模块升级时自动加列。字典因为是整理时的快照不会包含后续的现场改动。这种情况不算字典错误但要提醒自己字典的用途是理解标准结构现场环境的真实结构必须用information_schema或模型定义来勘定。我一般会定期把现场表结构和字典做一次 diff记录成一份「现场差异清单」每次 Odoo 升级后重新跑一遍避免查报表时报错。4.3 现象中文标签翻译和代码里的 Selection 值对不上某个「状态」字段字典中文标签写的是「草稿 / 已确认 / 已完成」但你在数据库里查出来的是draft、done、cancel或者更隐蔽的数字1、2、3。原因很简单Selection 字段在库里存的是选项「值」而不是「标签」数据结构里(draft, 草稿)这种对数据库只存draft。解决方式是对照字典里的「存储值」列如果有的话或模型源码里的 Selection 定义把值到中文标签的映射关系单独存成一张翻译表报表查询里用CASE WHEN做转换或者在 Odoo 里用display_name字段直接取翻译后的显示值。这个坑我见过最离谱的版本是有人把整个 Selection 字段当成字符串拼接进报表结果所有状态都是 ARRAY 形式。字典给你的是「人和机器」之间的桥不是让你直接拿中文标签去数据库里比对。4.4 现象表名在 Odoo 16 和 17 之间对不上数据字典如果标题写的是 Odoo 17但实际内容是照着 16 的老结构整理的查表名时会发现很多差异。Odoo 官方在 17 里调整过不少模型的命名和字段归属比如某些原先挂在sale.order上的字段被移动或重构。你按 16 的sale_order去查可能没问题但按 16 的字段去找 17 的列可能就扑空了。最稳妥的方法是先翻字典的「版本说明」章节看它有没有标注「基于 Odoo 17.0 官方源码整理」再拿一个你确定的新版本特有字段去验证。验证不通过就不要继续用了直接在 Odoo 里打开「设置-技术-数据库结构-模型」逐个查。数据字典是工具不是权威版本对不上就果断换版本不要硬拿旧字典去套新库。4.5 现象用 Excel 打开字典 CSV 文件时中文乱码数据字典的常见分发格式是 CSV 或 Excel而 CSV 文件如果没有带 UTF-8 BOM 头用 Windows 上的 Excel 直接双击打开时经常乱码。这个现象和字典内容本身无关纯粹是文件编码问题。原因是 Excel 默认按 ANSI 编码读取 CSV而现代工具导出时一般用 UTF-8。解决方式是用文本编辑器或 Python 读取后再另存为 Excel 能识别的编码。一行 Python 就可以import pandas as pd df pd.read_csv(odoo17_data_dictionary.csv, encodingutf-8-sig) df.to_excel(odoo17_data_dictionary.xlsx, indexFalse)utf-8-sig编码会在文件开头写入 BOMExcel 打开时就能正确识别为 UTF-8。转成 xlsx 后中文标签、字段名、表名都能正常显示。注意读 CSV 前先确认分隔符是逗号还是制表符read_csv默认按逗号处理制表符分隔则要加sep\t。这类转换脚本不涉及业务逻辑但每次拿到新版本字典我都要先跑一遍已经成了标准动作。5. 把数据字典变成团队内部工具的两个进阶做法先讲第一个进阶做法用字典做字段级权限审核。Odoo 的权限配置只控制到「模型级」也就是一个模型下能不能读、写、删不能直接控制某个字段谁能看。但字典能帮你列出哪些字段是敏感字段比如成本价、工资、银行账号这类字段分散在product.template、hr.employee、res.partner里英文名不直观。我的做法是把字典按「敏感字段」过一遍筛凡是类型为Monetary、Binary或标签带有「成本、工资、银行、身份证」的字段全部抽出来整理成一张敏感字段清单再把清单交给负责权限配置的同事让他们借用「字段级访问权限」的机制对指定群体做隐藏。这一步看起来简单但每次新版本升级时新旧字典字段差异会导致权限漏配提前筛一遍能省很多事后补漏的时间。第二个进阶做法用字典生成表关系清单辅助排查 JOIN 写错的问题。数据字典里Many2one字段会明确标注关联目标模型比如partner_id指向res.partner你能直接从字典里整理出「sale_order.partner_id→res_partner.id」这类关系对。把这些关系对收集起来放在 Markdown 表格里写 SQL 时就不会 JOIN 错表也不需要每次打开数据库图形工具去数外键。我习惯把关系清单按模块拆成小表格接到需求时只翻对应模块的清单不用每次翻全量字典。用熟了以后连新同事上手 Odoo 报表取数都不用再啃源码看关系清单就能写对第一个 JOIN。最后说一个我自己的习惯拿到版本号对应的字典后我一定要在安装好的 Odoo 17 里抽查三张表分别是res_partner、sale_order、account_move把字典字段数、表实际列数、模型_fields数量三者做一次差额统计。只要这三个数在合理误差内我就认定这份字典能用于后续工作。有一次正是因为没做这步拿旧版字典建报表 JOIN 错了表白费了一天。这个版本核对的动作不复杂但能在第一天就把翻车概率压到最低。希望帮到你。本文还有配套的精品资源点击获取