odoo-17.0

Odoo 17.0 开发技能

一套全面的技能指南，用于构建生产级 Odoo 17.0 自定义模块。涵盖完整的开发生命周期：模块结构、ORM、视图、操作、性能和测试，并遵循 Odoo 官方编码指南。

适用场景

在以下情况下，请参考这些规则：

• 创建或扩展自定义 Odoo 17.0 模块
• 定义模型、字段或计算方法
• 编写 @api 装饰器、约束或 onchange 处理程序
• 构建 XML 视图、菜单和操作
• 优化查询或处理大型记录集
• 编写单元测试、集成测试或 UI tour
• 为模型添加 chatter、序列、评分或门户访问权限

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模块清单	高	manifest-
2	ORM 模型	高	models-
3	ORM 字段	高	fields-
4	API 装饰器	高	decorators-
5	记录集与域	中	recordsets-
6	操作	中	actions-
7	性能	中	performance-
8	测试	中	testing-
9	混入	低	mixins-

快速参考

1. 模块清单（高）

• manifest-required-keys — 每个模块都必须包含 name、version、depends、license、installable
• manifest-data-order — data 中始终将安全 CSV 文件放在最前，菜单放在最后
• manifest-assets-bundle — 在 assets.web.assets_backend 下注册 JS/OWL/SCSS 文件
• manifest-version-format — 使用 {odoo}.{major}.{minor}.{patch}，例如 17.0.1.0.0
• manifest-dependencies — 缺少 depends 或其中配置错误会导致模块无法安装

2. ORM 模型（高）

• models-class-order — 按照规范顺序组织属性 → 字段 → 约束 → 计算方法 → CRUD → 操作 → 辅助方法
• models-type-selection — 持久化使用 Model，向导使用 TransientModel，混入使用 AbstractModel
• models-inherit-modes — 了解 _inherit 的 4 种模式：扩展、复制、组合、委派
• models-sql-constraints — 唯一性检查优先使用 _sql_constraints，而非 Python
• models-required-attributes — 每个新模型都必须定义 _name 和 _description

3. ORM 字段（高）

• fields-monetary-currency — Monetary 字段始终需要配套的 currency_field
• fields-many2one-index — 对用于搜索的 Many2one 字段始终设置 index=True
• fields-store-decision — 仅当字段需要用于搜索或排序时才使用 store=True
• fields-m2m-commands — 关系字段写入使用 ORM 命令 (0,0,v) (4,id) (6,0,ids)
• fields-selection-add — 扩展 Selection 时，始终为新增键定义 ondelete

4. API 装饰器（高）

• decorators-depends-completeness — 列出所有会影响计算结果的字段
• decorators-depends-assign-all-branches — 确保在每个代码分支中都为计算字段赋值
• decorators-constrains-exception — @api.constrains 必须引发 ValidationError，不能引发 UserError
• decorators-constrains-loop — 在 @api.constrains 中始终使用 for rec in self 循环
• decorators-onchange-not-enforced — 程序化执行 create/write 时不会触发 @api.onchange
• decorators-onchange-newid — @api.onchange 中的 self.id 是 NewId，不是整数
• decorators-create-multi — 在 17.0 中重写 create() 时始终使用 @api.model_create_multi
• decorators-depends-context-no-store — 带有 @api.depends_context 的字段不能设置 store=True

5. 记录集与域（中）

• recordsets-search-count — 计数时使用 search_count()，不要使用 len(search())
• recordsets-batch-write — 对整个记录集调用 write()，不要在循环内调用
• recordsets-batch-create — 将列表传给 create([...])，不要在循环中调用
• recordsets-domain-operators — | 和 & 是前缀运算符，作用于接下来的两个条件
• recordsets-sudo-comment — 使用 sudo() 时务必添加注释，说明使用原因
• recordsets-raw-sql-params — 不要格式化 SQL 字符串；始终使用 %s 参数化查询
• recordsets-no-commit — 业务代码中绝不要调用 cr.commit()；事务由框架管理
• recordsets-savepoint — 使用 cr.savepoint() 实现隔离回滚；执行原生 SQL 写入后调用 invalidate_all()

6. 操作（中）

• actions-window-menu — 始终将叶级 <menuitem> 绑定到一个 ir.actions.act_window 记录
• actions-data-order — 在视图 XML 中声明操作，在单独的 menus.xml 中声明菜单，并将其最后加载
• actions-python-return — 从 Python 方法返回操作字典，以打开视图或向导
• actions-cron-method — Cron 方法必须使用 @api.model 装饰，并自行处理错误
• actions-server-binding — 使用 binding_model_id 将服务器操作添加到“操作”下拉菜单

7. 性能（中）

• performance-prefetch — 利用 ORM 预取；使用 mapped() 提取跨记录字段值
• performance-no-loop-write — 绝不要在 for 循环内调用 write() 或 create()
• performance-index-searched-fields — 对用于 search() 域或 ORDER BY 的字段添加 index=True
• performance-read-group — 使用 read_group() 进行聚合，而不是加载完整记录集
• performance-invalidate-after-sql — 执行任何原生 SQL 写入后调用 invalidate_model()

8. 测试（中）

• testing-setup-class — 使用 setUpClass 设置共享测试装置；仅在需要完全隔离时使用 setUp
• testing-post-install-tag — 使用 @tagged('post_install', '-at_install') 标记测试
• testing-constrains-coverage — 每个 @api.constrains 方法都必须有一个能够触发它的测试
• testing-wizard-pattern — 通过创建带上下文的向导，然后调用其操作方法来测试向导
• testing-tour-js — UI tour 必须注册到 web_tour.tours 注册表，并通过 HttpCase 测试
• testing-bugfix-first — 修复 Bug 时必须附带一个在修复前会失败的测试
• testing-no-flaky — 在测试中构建数据，固定日期（freezegun），模拟外部服务，并以权限最低的用户身份进行测试
• testing-no-stale-env — 绝不要在子测试之间通过类属性缓存记录；使用 with_env() 重新绑定

9. 混入（低）

• mixins-mail-thread — 添加 _inherit = ['mail.thread', 'mail.activity.mixin'] 以启用消息讨论区和活动
• mixins-tracking — 在字段上使用 tracking=True，自动在消息讨论区中记录变更
• mixins-sequence — 在字段的 default= 中使用 ir.sequence + next_by_code() 实现自动编号
• mixins-portal — 使用 portal.mixin 时，实现 _compute_access_url
• mixins-message-post — 使用 message_post() 以编程方式发布消息讨论区消息

使用方法

阅读各个技能文件，了解详细说明、正确和错误的代码示例及注意事项：

odoo-manifest.md
odoo-orm-models.md
odoo-orm-fields.md
odoo-orm-decorators.md
odoo-orm-recordsets.md
odoo-actions.md
odoo-performance.md
odoo-testing.md
odoo-mixins.md

每个文件都包含：

• 其在 Odoo 17.0 中的重要性
• 附带说明的错误代码示例（# ❌ WRONG）
• 附带说明的正确代码示例（# ✅ CORRECT）
• 决策树和边缘情况

完整汇编文档

如需查看包含所有规则、模式和扩展示例的完整指南，包括全局编码规范和技能路由表，请参阅：AGENTS.md