代码结构与组织

1. 模块结构

Odoo 模块必须遵循统一的文件和目录结构：

your_module/
│
├── __init__.py            # 初始化文件
├── __manifest__.py        # 模块描述文件
├── models/                # 模型文件目录
│   ├── __init__.py
│   ├── model.py
│   └── ...
├── views/                 # XML 视图文件目录
│   ├── views.xml
│   └── ...
├── static/                # 静态文件
│   ├── src/
│   ├── description/
│   └── ...
├── security/              # 权限控制文件
│   ├── ir.model.access.csv
│   └── ...
└── data/                  # 数据文件
    ├── data.xml
    └── ...

避免每次新增模块，都去更改Odoo配置文件，导致配置文件维护难度增大。

2. 模块命名

• 模块名使用 小写字母加下划线，如 santic_sale_order_custom,前缀必须带上santic
• 避免使用冗长的模块名，保持简洁、可读。

代码书写规范

1. Python 代码规范

1.1 遵循 PEP8

• 使用 4 个空格缩进，不使用制表符。
• 行长度限制为 79 个字符（可以适当放宽，但应避免过长的行）。

1.2 类与方法命名

• 模型类名使用大驼峰（CamelCase），如 SaleOrderLine.
• 字段名和方法名使用下划线小写（snake_case），如 compute_total.
• 类命令必须为驼峰式，如：SanticCustomerDemandDevelopment，开通Santic后续可以用功能对应的英文名称进行命名
• 一个models文件里可以书写一个或多个数据表，但建议按表名来做区分,或者一个菜单对应的model可以放在一个文件里
• model命名一定要全英文，string和help都必须写英文的提示，然后要带上一定量中文注释，具体的汉化规则后面会对大家进行培训

1.3 注释与文档

• 在文件开头提供模块或脚本的简要说明。

• 类和方法必须有 docstring 注释，简要说明功能。

  class SanticSaleOrder(models.Model):
    """
    中文注释
    """
    _inherit = 'sale.order'
  
    def compute_discount(self):
        """
        Compute the discount for the sale order based on custom logic.
        """
        pass

1.4 避免硬编码

• 使用 Odoo 提供的配置参数或 XML 文件动态加载数据，避免直接在代码中写死数值。

2. 模型开发规范

2.1 字段定义

• 按需指定字段的 string 描述、required 、tracking和 help 属性，增加字段的可读性和易用性,tracking=True是开启字段修改记录到日志里的开关，odoo默认不开启，需要手动开启。
• string表示字段名称，help表示字段解释，这些全部要用英文去写，后面加中文注释是在弄汉化文件的时候需要用到

name = fields.Char(string="Customer Name", required=True, help="Enter the name of the customer.", tracking=True) # 客户名称

2.2 计算字段

• 对计算字段使用装饰器 @api.depends 声明依赖字段，避免遗漏依赖项。

  total_price = fields.Float(string="Total Price", compute="_compute_total_price")
  
  @api.depends('unit_price', 'quantity')
  def _compute_total_price(self):
    for record in self:
        record.total_price = record.unit_price * record.quantity

2.3 避免使用魔法方法

• 避免直接覆盖 _init_ 或 _new_ 方法，使用 Odoo 提供的生命周期方法（如 create、write 等）。

3. 视图开发规范

3.1 XML 规范

• XML 文件必须严格按照格式书写，并包含注释以说明内容。
• 使用缩进清晰的层次结构，通常为 2 个空格。
• 定义 id 唯一标识，不使用随机生成的 ID。

<record id="view_form_sale_order_custom" model="ir.ui.view">
    <field name="name">sale.order.form.custom</field>
    <field name="model">sale.order</field>
    <field name="arch" type="xml">
        <form string="Sale Order">
            <sheet>
                <group>
                    <field name="name"/>
                    <field name="customer_id"/>
                </group>
            </sheet>
        </form>
    </field>
</record>

3.2 模板命名

• XML 文件命名采用以下方式：

  • 视图文件: views.xml
  • 数据文件: data.xml
  • 安全文件: security.xml

3.3 标签顺序

• 确保 form, tree, kanban 等标签的内容按照业务逻辑和 Odoo 的标准排列。

4. 权限与安全

4.1 数据访问控制

• 为模型定义访问权限，使用 ir.model.access.csv。

  id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
  access_sale_order_custom,sale.order.custom,model_sale_order_custom,base.group_user,1,1,1,0

4.2 记录规则

• 定义必要的记录规则（record rules），避免用户访问未经授权的数据。

<record id="sale_order_rule" model="ir.rule">
    <field name="name">Sale Order Rule</field>
    <field name="model_id" ref="model_sale_order"/>
    <field name="domain_force">[('user_id', '=', user.id)]</field>
    <field name="groups" eval="[(4, ref('base.group_user'))]"/>
</record>

5. 元数据清单文件

__manifest__.py 文件，是 Odoo 模块的描述文件，包含该模块的元数据。使用 Python 字典格式，定义了模块的基本信息和依赖关系。

5.1 配置项的顺序

list 类型的配置项，有区分先后顺序。如顺序不一致，可能会导致莫名其妙的错误。
如下所示：'security/ir.model.access.csv', 条目，必须写第一行，否则前端菜单会显示不出来。

     'data': [
         'security/ir.model.access.csv',
         'views/menu.xml'
         ],

推荐使用官方自带的 odoo-bin scaffold 命令，生成新模块，避免出现不可预知问题。

性能优化

1. 避免循环中多次执行 SQL 查询:

   • 合理使用 Odoo 的 ORM 方法，如 search 和 filtered，尽量避免使用循环查询。

2. 计算字段优化:

   • 设置计算字段为 store=True，让字段值被存储，以减少计算开销。

     total_price = fields.Float(string="Total Price", compute="_compute_total_price", store=True)

3. 使用预加载:

   • 在操作较大数据集时，使用 read_group 或 search_read 提高性能。

代码审查

1. 代码审查:

   • 代码必须经过团队成员的审查，确保遵守规范和最佳实践。