Odoo 19 模块结构概述

Odoo 是一款高效且功能强大的 ERP 软件，包含各类应用与模块，可助力不同行业顺畅运行各类业务流程。它在一个模块化、易用的平台内，提供了客户关系管理（CRM）、企业资源计划（ERP）、会计、库存、人力资源（HR）、电子商务等解决方案。

Odoo 以灵活性和可扩展性著称，适用于各类规模的企业，能帮助企业自定义并自动化业务流程，提升运营效率。凭借强大的全球社区支持与持续的功能迭代，Odoo 已成为传统企业级解决方案之外的高性价比之选。

模块（Module）是 Odoo 的核心组成单元，因此创建新模块时需遵循特定规范。本文将概述 Odoo 19 的模块结构。

一、核心配置文件

Odoo 模块的正常加载与运行依赖两个关键文件：__init__.py 和 __manifest__.py，二者缺一不可。

1. __init__.py 文件

该文件的核心作用是导入模块内的 Python 文件（如模型文件、控制器文件、向导文件等），若缺少此文件，Python 将无法把该目录识别为模块的一部分。

示例代码：

from . import models  # 导入模型目录下的Python文件
from . import controllers  # 导入控制器目录下的Python文件

若模块包含向导（wizard）或其他 Python 组件，可在此处补充导入，如：

from . import wizard

2. __manifest__.py 文件

该文件是模块的元数据配置文件，用于定义模块的名称、版本、分类、功能摘要等关键信息，是 Odoo 识别并正确加载模块的核心依据。

以下是一个标准的 __manifest__.py 文件示例，后续将逐一解析各参数含义：

{
    "name": "模块名称",  # 模块名称
    "version": "1.0",  # 模块版本
    "summary": "模块功能摘要",  # 模块核心作用的简要描述（一行）
    "description": "模块详细描述",  # 模块功能、使用场景等详细说明
    "category": "product",  # 模块所属分类（如product表示“产品”类）
    "author": "苏州远鼎信息技术有限公司",  # 模块作者
    "company": "苏州远鼎信息技术有限公司",  # 开发模块的公司
    "maintainer": "苏州远鼎信息技术有限公司",  # 模块维护者（个人或团队）
    "website": "https://www.chinaodoo.com/",  # 模块或维护者的官网地址
    "depends": ["base"],  # 模块依赖的其他模块列表（base为Odoo核心基础模块，多数模块需依赖）
    "data": [  # 模块安装/更新时需加载的XML/CSV文件列表
        "security/ir.model.access.csv",  # 权限控制文件（定义用户对模型的访问权限）
        "data/filename.xml",  # 初始化数据文件（如基础数据、演示数据）
        "views/filename.xml",  # 视图文件（定义用户界面，如表单、列表）
    ],
    "assets": {  # 定义模块需加载的静态资源（CSS、JavaScript、图片等）
        "web.assets_backend": [  # 后端界面（如Odoo后台管理页）需加载的资源
            "module_name/static/src/js/*.js",  # 所有JS文件
            "module_name/static/src/css/*.css",  # 所有CSS文件
            "module_name/static/src/img/*",  # 所有图片文件
        ],
    },
    "images": [],  # 模块关联的图片路径列表（如模块图标）
    "license": "AGPL-3",  # 模块分发所遵循的协议（AGPL-3为Odoo常用开源协议）
    "installable": True,  # 布尔值，指定模块是否可在Odoo中安装
    "auto_install": False,  # 布尔值，指定是否在依赖模块满足时自动安装
    "application": False,  # 布尔值，指定模块是否为独立应用（True表示可在Odoo首页显示为独立应用图标）
}

__manifest__.py 关键参数解析：

• name：模块的显示名称（将在 Odoo“应用”模块中显示，需简洁明了，如“学生管理”）。
• version：模块版本号（通常遵循“主版本。次版本”格式，如 1.0、2.1，用于版本管理与更新）。
• summary：模块功能的一行简要描述（如“实现销售订单自动生成发票”），帮助用户快速了解模块用途。
• description：模块的详细描述，可包含功能细节、使用场景、操作步骤等（支持换行与格式化文本）。
• category：模块所属分类（Odoo 预设分类如 “Sales”“Inventory”“Accounting”，自定义分类需符合命名规范）。
• depends：模块依赖的其他模块列表（如开发销售相关模块需依赖 “sale”，会计相关模块需依赖 “account”）；依赖模块必须先安装，当前模块才能正常运行。
• data：模块安装或更新时需加载的配置文件列表，核心包含三类文件：
  • 视图文件（views 目录下，定义界面）；
  • 权限文件（security 目录下，控制访问权限）；
  • 数据文件（data 目录下，初始化基础数据）。
• assets：定义模块所需的静态资源，按“前端场景”分类（如 web.assets_backend 对应后端管理界面，web.assets_frontend 对应前端网站界面），支持通配符（*）批量加载文件。
• license：模块的开源协议（Odoo 社区版常用 AGPL-3，企业版需遵循商业协议）。
• installable：若设为 False，模块将无法在 Odoo 中安装（通常用于 “开发中未完成” 的模块）。
• auto_install：若设为 True，当 depends 列表中的所有依赖模块都已安装时，当前模块将自动安装（适用于 “基础功能补充类” 模块）。
• application：若设为 True，模块将在 Odoo 首页显示为独立应用图标（如 “Sales”“Inventory” 等核心模块）；设为 False 则仅作为功能扩展，不单独显示图标。

二、模块核心组件

除上述两个配置文件外，Odoo 模块还包含多个功能组件，分别负责实现 “业务逻辑”“用户界面”“权限控制” 等核心能力，各组件通过固定目录结构组织，确保模块的可维护性。

1. Models（模型目录）

• 作用：包含 Python 类文件（通常以 models/ 为目录名），定义模块的业务逻辑与数据模型（即 “数据库表结构” 与 “数据处理规则”）。
• 示例：销售模块的 sale.order 模型（对应销售订单表）、库存模块的 stock.picking 模型（对应拣货单表），均在此目录下定义。
• 核心功能：实现数据的创建、查询、更新、删除（CRUD）操作，以及业务规则（如订单确认时自动生成发货单）。

2. Views（视图目录）

• 作用：包含 XML 文件（通常以 views/ 为目录名），定义模块的用户界面元素，决定 “数据如何在 Odoo 中显示”。
• 常见视图类型：
  • 表单视图（Form View）：用于创建 / 编辑单条记录（如销售订单详情页）；
  • 列表视图（List View）：用于批量查看 / 筛选记录（如销售订单列表页）；
  • 看板视图（Kanban View）：用于可视化展示记录（如按状态分组的订单看板）；
  • 报表视图（Report View）：用于生成打印报表（如销售订单 PDF）。

3. Security（权限目录）

• 作用：定义模块的访问控制规则，确保只有授权用户才能操作数据，通常包含两类文件：
  • ir.model.access.csv：CSV 文件，定义 “用户组对模型的访问权限”（如 “销售人员” 可创建销售订单，“只读用户” 仅能查看）；
  • ir.rule.xml：XML 文件，定义 “记录级权限”（如 “用户只能查看自己创建的订单”）。
• 示例：ir.model.access.csv 中某一行配置可能为：access_sale_order_user,sale.order.user,model_sale_order,group_sale_user,1,1,1,0（表示 “销售用户组” 对 “销售订单模型” 有创建、读取、更新权限，无删除权限）。

4. Data（数据目录）

• 作用：包含 XML 或 CSV 文件（通常以 data/ 为目录名），用于初始化模块运行所需的基础数据或提供演示数据。
• 示例：
  • 基础数据：产品分类、付款条件、税务规则等（安装模块时自动导入数据库）；
  • 演示数据：测试用的客户、产品、订单等（帮助用户快速了解模块功能）。

5. Static（静态资源目录）

• 作用：存储模块所需的静态资源文件（通常以 static/ 为目录名），不涉及业务逻辑，仅用于界面展示，常见子目录：
  • static/src/js/：JavaScript 文件（实现界面交互逻辑，如按钮点击事件）；
  • static/src/css/：CSS 文件（自定义界面样式，如调整表单布局、字体颜色）；
  • static/src/img/：图片文件（如模块图标、按钮图标、报表 Logo）；
  • static/src/fonts/：字体文件（自定义界面字体）。

6. Wizard（向导目录）

• 作用：包含 Python 与 XML 文件（通常以 wizard/ 为目录名），用于创建向导表单（临时弹窗表单），适用于 “分步操作” 或 “批量处理” 场景。
• 示例：“批量修改产品价格” 向导、“订单状态批量更新” 向导，均通过此组件实现。

7. Controller（控制器目录）

• 作用：包含 Python 文件（通常以 controllers/ 为目录名），定义 HTTP 控制器，用于处理 “外部系统请求” 或 “Odoo 前后端数据交互”。
• 示例：实现 “第三方系统通过 API 创建 Odoo 销售订单”“Odoo 前端页面向后端请求数据” 等功能，均需在此目录下定义控制器。

8. Reports（报表目录）

• 作用：包含 XML 与 Python 文件（通常以 reports/ 为目录名），用于创建自定义报表（如 PDF 报表、Excel 报表）。
• 核心文件：
  • 报表模板 XML：定义报表的格式（如表头、数据列、Logo 位置）；
  • 报表逻辑 Python：处理报表数据（如计算订单总金额、筛选符合条件的记录）。

9. i18n（国际化目录）

• 作用：包含翻译文件（通常以 i18n/ 为目录名），用于实现模块的多语言支持，让模块界面与数据可切换至不同语言。
• 常见文件格式：
  • .po 文件：特定语言的翻译文件（如 en.po 为英文翻译，zh_CN.po 为简体中文翻译）；
  • .pot 文件：翻译模板文件（包含所有需翻译的文本，用于生成各语言的 .po 文件）。

三、总结

理解 Odoo 19 的模块结构是在 Odoo 平台中创建、自定义和维护应用的基础。通过遵循 “核心配置文件 + 固定组件目录” 的规范，开发者可构建出可扩展、可维护、稳定性强的 Odoo 模块，且能与 Odoo 系统整体实现无缝集成。

无论开发新模块还是定制现有模块，清晰掌握模块结构都能为后续的功能实现与项目落地奠定坚实基础。