模块结构决定 Odoo 19 安装与升级是否顺利。__manifest__.py 里 depends、data、assets、demo 写错，轻则菜单重复、视图继承失败，重则 --stop-after-init 直接中断。本文按「新库安装 → 小版本升级 → 卸载」三条路径，说明依赖声明、数据文件顺序、noupdate 语义、前端资源挂载，以及怎样避免循环依赖与核心补丁式改法。
depends：只声明真正直接依赖
需要调用 sale.order 就 depends sale；不要为了「环境里反正装着」而 depends 一长串企业应用。过宽依赖会让卸载困难，也会在未购模块的库上安装失败。反向原则：别人 depends 你时，你的对外 XML ID 与模型字段要保持稳定；删除字段前先做迁移脚本。版本号与主版本对齐；私有模块名避免与官方冲突。
data 加载顺序：安全 → 数据 → 视图 → 菜单 → 权限
推荐顺序：
- 安全组 /
ir.model.access.csv - 主数据与序列（
ir.sequence） - 视图与动作
- 菜单
- 邮件模板、自动化、cron
noupdate="1" 的记录在升级时不会覆盖用户改过的数据——适合「初始配置」；若你希望每次升级强制刷新视图，不要对视图乱打 noupdate。演示数据放 demo，生产安装勿默认载入。
assets：挂官方包，不改核心文件
后端 JS/CSS 挂 web.assets_backend；网站挂 web.assets_frontend。用 OWL 组件注册与视图继承扩展，避免直接改 Odoo 源码文件（升级必冲突）。大资源注意懒加载；不要在每个页面打入巨型图表库除非必要。
升级与迁移脚本
结构性变更（字段删除、模型改名）放 migrations/ 脚本，按版本目录执行。升级前在预生产跑：odoo-bin -u your_module --stop-after-init，收集失败视图、缺失 XML ID、访问权限报错。Studio 与手改视图冲突时，以正规模块继承为准，Studio 只保留轻量字段。
常见坑
- 循环 depends：A depends B、B depends A，安装卡死。
- CSV 权限引用了尚未创建的 group xmlid。
- xpath 继承绑在易变结构上，上游一改视图全挂。
- 卸载后残留动作窗口指向已删模型。
验收标准
- 空库
-i your_module一次成功，无告警级视图错误。 - 预生产
-u your_module --stop-after-init成功。 - 卸载模块后菜单与动作不报「模型不存在」。
- 前端资产在无痕浏览器可加载，无 404。
模块拆分与升级友好检查
过大的「万能定制模块」应拆成：主数据扩展、流程自动化、报表、对接。
各自 depends 收紧，避免一张合并请求改爆所有视图。发版前脚本检查：
循环依赖、重名 XML ID、未声明的资产文件、访问权限 CSV 引用缺失 group。
对 noupdate 数据列清单，标明哪些允许客户改、哪些升级会强制刷新。卸载演练在复制库做，
确认菜单与 cron 不残留。
manifest 的 license、author、version 字段保持可读；私有模块 version 跟迭代号走，便于追溯。
仓库结构约定
建议目录：models/、views/、security/、data/、
static/src/、migrations/。视图继承 xpath 优先锚字段 name。
演示数据永不进生产安装。依赖图用工具检查环。发布前在空库 -i 与旧库 -u 双路径验证。
对外 XML ID 变更走废弃期。文档 README 写清模块职责边界，避免万能包。
主题 394 收尾：权限、测试数据清理与 runbook 链接由负责人签字。
预生产勾选表需覆盖文章编号 394 全部验收点后再约生产窗口。
将文章编号 394 的配置变更记入发版说明，便于回滚对照。
中国Odoo网｜对照 Odoo 19 企业版模块工程实践：manifest 依赖收紧，data 顺序固定，升级走预生产验证。