odoo 之结构化应用数据

一.模型深入了解

模型是 Odoo 框架的核心，它们描述应用的数据结构，是应用服务和数据库存储之间的桥梁

模型类型：普通(regular)、临时(transient)和抽象(abstract)类型。

模型属性

### 常用属性
_name    #  是我们创建的 Odoo 模型的内部标识符，在创建新模型时为必填。
_description #是对用户友好的模块记录标题，在用户界面中查看模型时显示。可选但推荐添加。
_order　　　# 设置浏览模型记录时或列表视图的默认排序。其值为 SQL 语句中 order by 使用的字符串，所以可以传入符合 SQL 语法的任意值，它有智能模式并支持可翻译及many-to-one字段名。


如:
    class Book(models.Model):
    _name = 'library.book'
    _description = 'Book'
    _order = 'name, date_published desc'
    
    
### 高级属性
_rec_name   #　在从关联字段（如many-to-one关联）中引用时作为记录描述。默认使用模型中常用的 name字段，但可以指定任意其它字段。

_table　　　# 是模型对应的数据表名。默认表名由 ORM 通过替换模块名中的点为下划线来自动定义，但是可通过该属性指定表名。

_log_access=False   #  用于设置不自动创建审计追踪字段：create_uid, create_date, write_uid和write_date。

_auto=False  #  用于设置不自动创建模型对应的数据表。如有需要，可通过重载init()方法来创建数据库对象：数据表或视图。

模型和 Python 类

Odoo的模型保存在中央注册表(central registry)中，可通过 env 环境对象(老 API 中称为 pool)获取

它是一个数据库保存所有可用模型类引用的字典，其中的词条可通过模型名引用。

具体来说，模型方法中的代码可使用self.env[‘library.book’]来获取表示 library.book模型的模型类

# 模型名非常重要,因为它是访问该注册表的关键。模型名的规则是以点号连接的小写单词 . 如library.book或library.book.category

# 由于历史原因，有些内核模型没有遵循这一规则，如res.users。

# 1.　模型名必须全局唯一，因此第一个单词应使用模块关联的主应用对应．以图书应用来说，模型的前缀名使用library. 其它内核模块如 project,crm和sale

# 2. 另一方面 Python 类仅为所声明文件本地内容，名称仅需在代码文件中唯一即可。因为类名不会与其它模块中的类产生冲突，也就不需为其添加主应用相关的前缀

# 3. 类的命名遵守驼峰原则CamelCase,与pep8规范一致

临时(Transient)模型和抽象模型

# 临时模型继承models.TransientModel类 
	1. 作用: 用于向导式的用户交互 , 数据会临时性的存储
	2. 清理: 定期运行清空job来清楚这些表中的老数据.
        
        
# 抽象模型继承models.AbstractModel类
	1. 不带有数据存储, 抽象模型可用于功能集,配合odoo继承功能的其它模型使用
    2. 比如:mail.thread是Discuss应用种的一个抽象模型,用于为其它模型添加消息和follower功能

检查已有模型

python类创建的模型和字段,在用户界面中有自己的元标签

Settings > Technical > Database Structure > Models，这里有数据库中的所有模型。点击列表中的模型会打开详情表单

# 上图中在右上角 In Apps字段中可以看到library.book模型的定义来自library_app和library_member两个模块。


# 下方区域中还有几个包含附加信息的标签
    Fields可快速查看模型字段
    Access Rights是授予不同权限组的访问控制规则
    Views显示模型所带的视图列表
    
    
# 开发者可通过 View Metadata选项查看模型的外部标识符。  
	如: library.book模型的外部标识符为model_library_book
	在定义安全访问控制列表经常在 CSV 文件中使用到这些XML ID。

二.模型字段深入了解

基本字段类型

#####
Char(string)  # 是一个单行文本，唯一位置参数是string字段标签。

Text(string)  # 是一个多行文本，唯一位置参数是string字段标签。

Selection(selection, string)  # 是一个下拉选择列表。选项位置参数是一个[(‘value’, ‘Title’),]元组列表。元组第一个元素是存储在数据库中的值，第二个元素是展示在用户界面中的描述。该列表可由其它模块使用selection_add关键字参数扩展。

Html(string)  # 存储为文本字段，但有针对用户界面 HTML 内容展示的特殊处理。出于安全考虑，该字段会被清洗，但清洗行为可被重载。

Integer(string)  # 仅需字段标题字符串参数。

Float(string, digits)  # 带有第二个可选参数digits，该字段是一个指定字段精度的(x,y)元组，x 是数字总长，y 是小数位。

Monetary(string, currency_field)  # 与浮点字段类似，但带有货币的特殊处理。第二个参数currency_field用于存储所使用货币，默认应传入currency_id字段。

Date(string)和Datetime(string)  # 字段只需一个字符串文本位置参数。

Boolean(string)  # 的值为True 或False，可传入一个字符串文本位置参数。

Binary(string)  # 存储文件类二进制文件，只需一个字符串文本位置参数。它可由Python使用 base64编码字符串进行处理。

##### 文本字符串 Char Text Html的特有属性
	size  #  (Char)设置最大允许尺寸。无特殊原因建议不要使用，例如可用于带有最大允许长度的社保账号。
	
    translate  #  使用得字段内容可翻译，带有针对不同语言的不同值。

    trim默认值为 True，  #  启动在网络客户端中自动去除周围的空格。可通过设置trim=false来取消。

常用字段属性

tring  #  是字段的默认标签，在用户界面中使用。除Selection和关联字段外，它都是第一个位置参数，所以大多数情况下它用作关键字参数。如未传入，将由字段名自动生成。

default   #   设置字段默认值。可以是具体值（如 active字段中的default=True），或是可调用引用，有名函数或匿名函数均可。

help  #  提供 UI 中鼠标悬停字段向用户显示的提示文本。

readonly=True  #  
会使用户界面中的字段默认不可编辑。在 API 层面并没有强制，模型方法中的代码仍然可以向其写入。仅针对用户界面设置。

required=True  #  使得用户界面中字段默认必填。这通过在数据库层面为列添加NOT NULL 约束来实现。

index=True  #  为字段添加数据库索引，让搜索更快速，但同时也会部分降低写操作速度。

copy=False  #  让字段在使用 ORM copy()方法复制字段时忽略该字段。除 to-many 关联字段外，其它字段值默认会被复制。

groups  #  可限制字段仅对一些组可访问并可见。值为逗号分隔的安全组XML ID列表，如groups=’base.group_user,base.group_system’。

states  #  传入依赖 state字段值的 UI 属性的字典映射值。可用属性有readonly, required和invisible，例如states={‘done’:[(‘readonly’,True)]}。


##注意
	states 字段等价于视图中的 attrs 属性。同时注意视图也支持 states 属性，但用途不同，传入逗号分隔的状态列表来控制元素什么时候可见。
    
    
    
# 例子
name = fields.Char(
        'Title',
        default=None,
        index=True,
        help='Book cover title',
        readonly=False,
        required=True,
        translate=False,
    )

# default属性 是固定值, 或者引用函数来计算默认值. 对于简单的运算,使用lambda即可. 如下:

last_borrow_date = fields.Datetime(
        'Last Borrowed On',
        default=lambda self: fields.Datetime.now(),
    )

# 默认值也可以是一个函数引用,或者待定义函数名字符串
    last_borrow_date = fields.Datetime(
        'Last Borrowed On',
        default='_default_last_borrow_date',
    )

    def _default_last_borrow_date(self):
        return fields.Datetime.now()
    
    
### 当模块数据结构在不同版本种,下列两个属性非常重要
	deprecated=True  # 在字段被使用时记录一条 warning 日志
    oldname=’field’  # 是在新版本中重命名字段时使用，可在升级模块时将老字段中的数据自动拷贝到新字段中

特殊字段名

出于特殊目的作为 ORM 保留字,也是默认字段

# 只要模型中没有设置  _log_access=False , 都会在新模型中自动创建

create_uid为创建记录的用户
create_date是记录创建的日期和时间
write_uid是最后写入记录的用户
write_date是最后修改记录的日期和时间

### 一些内置 API 功能默认需要一些指定字段名。避免在不必要的场合使用这些字段名会让开发更轻松。其中有些字段名被保留并且不能在其它地方使用

name #  (通常为 Char)默认作为记录的显示名称。通过是一个 Char，但也可以是 Text 或Many2one字段类型。用作显示名的字段可修改为_rec_name模型属性。

active   #  (Boolean型)允许我们关闭记录。带有active=False的记录会自动从查询中排除掉。可在当前上下文中添加{‘active_test’: False} 来关闭这一自动过滤。可用作记录存档或假删除（soft delete）。

state    #   (Selection类型) 表示记录生命周期的基本状态。它允许使用states字段属性来根据记录状态以具备不同的 UI 行为。动态修改视图：字段可在特定记录状态下变为readonly, required或invisible。

parent_id和parent_path Integer和Char型)  #  对于父子层级关系具有特殊意义。本文后续会进行讨论。

三.模型关系深入了解

具体的用例就是层级关联，即一个模型中的记录与同模型中的其它记录关联。

Odoo 框架还支持弹性关系，即一个字段可指向其它表中的字段，这称为引用字段。

Many-to-one关联

多对一

# 格式:
publisher_id = fields.Many2one(
        'res.partner', string='Publisher')



# 参数:
    ondelete #  定义关联记录删除时执行的操作：
    set null  # (默认值): 关联字段删除时会置为空值
    restricted　# 　：抛出错误阻止删除
    cascade：# 　 在关联记录删除时同时删除当前记录
    context  # 是一个数据字典，可在浏览关联时为网页客户端传递信息，比如设置默认值
    domain  # 是一个域表达式：使用一个元组列表过滤记录来作为关联记录选项
    auto_join=True  #  允许ORM在使用关联进行搜索时使用SQL连接。使用时会跳过访问安全规则，用户可以访问安全规则不允许其访问的关联记录，但这样 SQL 的查询会更有效率且更快。
	delegate=True   #　创建一个关联记录的代理继承。使用时必须设置required=True和ondelete=’cascade’。

One-to-many反向关联

one-to-many关联是many-to-one的反向关联

在图书模型中,publisher_id和parnter是 many-to-one. 同样说明在partner模型中是有一个one-to-many的反向模型

# 在partner 模型中添加　library_app/models/res_partner.py下代码：
from odoo import fields, models

class Partner(models.Model):
    _inherit = 'res.partner'
    published_book_ids = fields.One2many(
        'library.book', # related model
        'publisher_id', # fields for "this" on related model
        string='Published Books')
    
# One2many字段接收三个位置参数说明
	关联模型 (comodel_name关键字参数) # 关联的模型
	引用该记录的模型字段 (inverse_name关键字参数) # 引用关联模型的字段
	字段标签 (string关键字参数) # 提示
    
# 其它可用的关键字参数与many-to-one字段相同：context, domain和ondelete

Many-to-many关联

书和作者之间是many-to-many关联：一本书可以有多个作者，一个作者可以有多本书

# 图书
class Book(models.Model):
    _name = 'library.book'
...
    author_ids = fields.Many2many(
        'res.partner', string='Authors')
        
# 作者端
class Partner(models.Model):
    _inherit = 'res.partner'
    book_ids = fields.Many2many(
        'library.book', string='Authored Books')
    
    
# 格式:
author_ids = fields.Many2many(
    'res.partner', # 关联模型（尾款）
    'library_book_res_partner_rel', # 要使用的关联表名
    'a_id', # 本记录关联表字段
    'p_id', # 关联记录关联表字段
    'Authors') # string标签文本

# many2many 默认自动生成第三张表
	# 1.模型名称过程,psql默认是63个字符,需要手动指定关联名
    # 2.手动创建时,避免冲突

# 参数 和one-to-many类似,还可以使用context, domain和auto_join这些关键字参数

#　在创建抽象模型时，many-to-many中不要使用column1和column2属性。在 ORM 设计中对抽象模型有一个限制，如果指定关联表列名，就无法再被正常继承。

层级关联

父子树状关联使用同一模型中many-to-one关联表示，来将每条记录引用其父级。反向的one-to-many关联对应记录的子级。Odoo 通过域表达式附加的child_of和parent_of操作符改良了对这些层级数据结构的支持。只要这些模型有parent_id字段（或_parent_name有效模型定义）就可以使用这些操作符。

通过设置_parent_store=True和添加parent_path帮助字段可加快层级树的查询速度。该字段存储用于加速查询速度的层级树结构信息。

from odoo import api, fields, models

class BookCategory(models.Model):
    _name = 'library.book.category'
    _description = 'Book Category'
    _parent_store = True

    name = fields.Char(translate=True, required=True)
    # Hierarchy fields
    parent_id = fields.Many2one(
        'library.book.category',
        'Parent Category',
        ondelete='restrict')
    parent_path = fields.Char(index=True)

    # Optional but good to have:
    child_ids = fields.One2many(
        'library.book.category',
        'parent_id',
        'Subcategories')
    
    
### 这里定义了一个基本模型，包含引用父级记录的parent_id字段。为启用层级索引来加快树级搜索，添加了一个_parent_store=True 模型属性。使用该属性必须要添加且必须要索引parent_path字段。引用父级的字段名应为parent_id，但如果声明了可选的_parent_name模型属性，则可以使用任意其它字段名。

引用字段的弹性关联

普通关联字段指定固定的引用co-model模型,但是Reference字段类型不受这一点限制,支持弹性关联

因此相同字段不用限制只指向相同的目标模型。

# 图书分类模型来添加引用重点图书或者作者,因此该字段可引用图书或 partner：

class BookCategory(models.Model):
...   
    highlighted_id = fields.Reference(
        [('library.book', 'Book'), ('res.partner', 'Author')],
        'Category Highlight'
    )

###该字段定义与 selection 字段相似，但这里选择项为该字段中可以使用的模型。在用户界面中，用户会先选择列表中的模型，然后选择模型中的指定记录。

# 技术细节:
	# 1. 引用字段在数据库中以model,id字符串形式存储
	# 2. read()方法供外部应用使用，以格式化的(‘model_name’, id)元组返回，而不是常用的many-to-one字段的(id, ‘display_name’)形式

四.计算字段

计算字段声明和普通字段类似, 有一个额外的compute参数来定义计算函数

例如: 添加出版商的国别依赖出版商的 country_id

class Book(models.Model):
...
    publisher_country_id = fields.Many2one(
        'res.country', string='Publisher Country',
        compute='_compute_publisher_country'
    )

    @api.depends('publisher_id.country_id')
    def _compute_publisher_country(self):
        for book in self:
            book.publisher_country_id = book.publisher_id.country_id
            
            
### 注意 
	计算字段必须分配值,如果没有分配值则会报错.

五.模型约束

模型约束的目的是: 通过验证保证数据完整性和正确性.

psql支持多可用验证: 避免重复,检查条件是否符合等. 如若要求更复杂的逻辑,还是用python代码实现约束

SQL模型约束

由PostgreSQL直接执行, 由_sql_constraints类属性来定义.

是由元组组成的列表,格式(name,code,error)

# name 是约束标识名
# code 是约束的PostgreSQL语法
# error 是在约束验证未通过时向用户显示的错误消息
_sql_constraints = [
        ('library_book_name_date_uq', # 约束唯一标识符
        'UNIQUE (name, date_published)', # 约束 SQL 语法
        'Book title and publication date must be unique'), # 消息
    
        ('library_book_check_date',
        'CHECK (date_published <= current_date)',
        'Publication date must not be in the future.'),
    ]

Python模型约束

自定义代码来检查条件,@api.constrains装饰器

from odoo.exceptions import ValidationError

class Book(models.Model):
...
    @api.constrains('isbn') # 约束的字段
    def _constrain_isbn_valid(self):
        for book in self:
            if book.isbn and not book._check_isbn():
                # 抛出异常时,数据自动回滚
                raise ValidationError('%s is an invalid ISBN' % book.isbn)

搜索和写入计算字段

刚计算的字段可读取,但不可以搜索和写入. 默认情况下是实时计算,而不是存储在数据库种的.

# 可以通过特殊方法来开启搜索和写入操作
# 计算字段可与compute方法一起设置,实现搜索逻辑的search方法,以及实现写入逻辑的inverse方法

class Book(models.Model):
...
    publisher_country_id = fields.Many2one(
        'res.country', string='Publisher Country',
        compute='_compute_publisher_country'，
        # store = False, # 默认不在数据库中存储
        inverse='_inverse_publisher_country',
        search='_search_publisher_country',
    )

计算字段的写入是计算的反向逻辑. 因此处理写入的方法成为inverse

# 计算将book.publisher_id.country_id 的值复制给book.publisher_country_id，反向操作是将写入book.publisher_country_id的值拷贝给book.publisher_id.country_id field字段

def _inverse_publisher_country(self):
        for book in self:
            book.publisher_id.country_id = book.publisher_country_id
            
            
# 注意 
	# 1.由于要修改出版商partner记录数据,因此也会修改相同出版商图书的字段.
    # 2.仅对partner模型有写入权限的当前用户才能成功执行此操作

为计算字段开启搜索操作,需要实现search方法. 要将计算字段的搜索转换为使用常规存储字段的搜索域.

def _search_publisher_country(self, opearator, value):
        return [('publisher_id.country_id', operator, value)]

存储计算字段

字段参数添加 store = True

将计算字段值保存到数据库中,在任意依赖变更时值就会重新计算.可以像普通字段一样被搜索,不需要使用search方法了

关联字段

依赖 related参数

publisher_country_id = fields.Many2one(
        'res.country', string='Publisher Country',
        related='publisher_id.country_id',
    )

六.base模型

odoo内置了base插件模块,包含

信息仓库(Information Repository) ir.*模型

资源(Resources) res.*模型

# 信息仓库用于存储 odoo 所需数据, 如:菜单,视图,模型,aciton等
    ir.actions.act_window用于窗口操作
    ir.ui.menu用于菜单项
    ir.ui.view用于视图
    ir.model用于模型
    ir.model.fields用于模型字段
    ir.model.data用于XML ID

# 资源包含基本数据,基本上用于应用
    res.partner用于业务伙伴，如客户、供应商和地址等等
    res.company用于公司数据
    res.currency用于货币
    res.country用于国家
    res.users用于应用用户
    res.groups用于应用安全组