印刷行业的办公室里最容易失控的不是生产进度而是文件。客户发来的PDF“再改一版”、设计师A和设计师B同时编辑同一个AI源文件、打样稿和签样稿命名成最终版_v3_改、下个月客户投诉印刷色差却根本找不到当时签样存档的是哪一份文件。这些问题表面上是“文件没管好”本质上是文档没有和业务单据绑定也没有版本和权限约束。想靠共享文件夹、网盘、微信文件传输助手解决只会越堆越乱。Odoo 作为开源 ERP很多印刷企业选它做订单、采购、生产、库存管理却往往忽视文档管理模块。我的判断是Odoo 做印刷行业文档管理完全可行但你不能拿原生“附件”功能当文档库直接用而是要根据印刷行业的业务阶段梳理需求后在 Odoo 上做一层轻量的文档管理模型。这篇文章会把概念、需求拆解、环境准备、代码实现、验证和排错完整讲一遍。读完这篇文章你能搞清楚三件事印刷企业的文档管理到底要管什么、Odoo 里和文档相关的机制有哪些坑、以及如何用自定义模块实现一套带版本、签入签出和业务关联的文档管理功能。适合 ERP 实施顾问、Odoo 二开工程师、印刷企业信息化负责人阅读。1. 印刷企业文档管理到底难在哪很多传统 ERP 实施团队一听到“印刷行业”就先看财务、采购、库存、生产排程这些模块文档管理往往放到最后才考虑。但实际上线后最先暴露问题的恰恰是文档管理。1.1 印刷文件本身就有特殊性印刷行业的文档和普通办公文档完全不是一个量级文件体积大。一本画册的印前源文件动辄几百 MB一个 CTP 输出文件甚至能达到 1GB 以上。版本多且频繁。客户改稿是常态从初稿、修改稿、打样稿、签样稿到最终印刷稿一个产品可能产生十几个版本。格式专业且封闭。常见的 PDF/X、AI、InDesign、CorelDRAW 源文件、拼版文件、色卡文件普通网盘根本不能在线预览。业务链条长。从客户来稿到印前处理、打样确认、拼版输出、印刷机台使用、印后加工每个环节都可能产生关联文件。普通办公文档管理办法在印刷场景里很容易失效。1.2 共享文件夹和网盘为什么靠不住很多印刷企业目前用的是共享文件夹或者网盘甚至还在用“文件服务器自动同步”的组合。这种方式有三个绕不开的痛点第一版本无法管理。共享文件夹里最终稿.pdf、最终稿2.pdf、最终稿最终版.pdf并存是常态。谁也不知道哪个才是客户确认过的版本。等到大批量印刷完成后才发现用了旧版本损失已经造成。第二权限难以控制。共享文件夹通常是一个大目录所有人都有读写权限。业务员能看印前文件印前工程师也能看客户报价。离职员工手里可能还保留着大量文件。印刷文件涉及客户商业秘密和工艺参数权限失控的风险远高于普通办公文件。第三文档和业务数据脱节。共享文件夹里只有文件名没有销售订单号、产品编码、工单号。你想追溯“这个文件对应哪个订单”“哪张工单在生产时使用过这份签样稿”完全做不到。即使 Odoo 系统里订单、工单、BOM 管得很好文档一旦脱离业务数据就等于丢失了追溯能力。1.3 核心判断文档必须跟着业务单据走印刷行业的文档管理真正要解决的问题不是“把文件找个地方存起来”而是让每份文件都能和销售订单、产品、工单、工艺路线等业务对象建立关联并控制版本、权限、状态。打个比方共享文件夹像一个大仓库货扔进去就不管了而 ERP 里的文档管理应该像一个有货架编码、有出入库记录、有领用登记的档案室。你不仅要知道“有什么”还要知道“它在哪、谁在用、怎么流转、哪个版本生效”。这也是我建议用 Odoo 而不是单纯上一个 DMS文档管理系统的原因Odoo 里天然有订单、产品、工单、项目等业务对象只要把文档模块和这些对象绑定就能让文件融入业务流而不是孤立存在。2. 认识 Odoo 的文档相关机制在动手开发之前先要把 Odoo 本身和文档相关的几个机制搞清楚否则很容易做出一个“自己造的第二个网盘”而不是 ERP 文档管理模块。2.1 ir.attachmentOdoo 底层的附件表Odoo 中几乎每个业务对象都可以上传附件比如订单、产品、工单、项目任务。这些附件统一存放在ir.attachment表中文件物理上存储在 Odoo 的filestore目录数据库里保存的是文件路径和元数据。任何模型上都默认带附件功能。例如在销售订单表单上系统会自动有一个消息回形针按钮可以上传客户发来的文件、图纸、报价单等。ir.attachment的设计目的是通用的、轻量的它适合“业务对象上挂几个参考文件”这种场景但不适合做正式版的文档管理。它最明显的缺陷有三个没有版本控制。同一份文件上传多次旧的不会自动归档也不会自动生成 v1、v2、v3。没有签入/签出机制。两个人同时下载同一个文件修改改完再传回去互相覆盖。没有业务状态。附件只是“挂在订单下面”但它处于什么状态、是否已被客户签样确认、是否可以用于生产附件表里没有任何信息。因此直接用ir.attachment做文档管理本质上还是在用仓库思维只是把共享文件夹换成了 Odoo 界面。2.2 Documents 模块与外部存储Odoo 从 14 版本开始提供了 Documents 模块它引入了目录、标签、操作规则等概念界面也贴近网盘支持拖拽上传、文档操作、工作流审批等。它还可以对接 Nextcloud 等外部存储实现文件不进入 Odoo 的 filestore而是放到外部存储服务器上。从材料看Documents 模块很适合办公文档、合同、制度文件等场景。它解决的是“文件分类、标签、权限、预览”的问题。但印刷行业要对接的业务流程更强文件必须关联到销售订单行、BOM、工单文件版本必须和打样、签样流程绑定大文件上传后要控制同名的唯一性印前工程师可能要在文件上传时自动计算哈希值以校验文件一致性。这些需求用 Documents 模块也能做但定制成本不低。如果你的项目已经用了 Odoo 的销售、生产、采购模块我更建议在ir.attachment之上做一套轻量的业务文档模型这样关联业务对象更方便二开更直接。2.3 印刷行业文档管理模块的定位在 Odoo 里做印刷行业文档管理合理的定位是不替换ir.attachment而是把它作为底层存储在其上增加一层“文档主记录 版本记录 业务关联 状态控制”的模型。也就是说ir.attachment负责“文件存在哪儿”自定义的print.document和print.document.version模型负责“这份文件属于哪个业务对象、当前是什么版本、谁在修改、是否允许生产使用”。这种设计的好处是底层的文件存储、权限、物理读写依然由 Odoo 原生机制保证稳定可靠。上层的业务语义由自己控制想加签样状态、版本约束、大文件校验都能写进模型逻辑里。未来如果要把文件迁移到外部存储、NAS、MinIO只需要调整ir.attachment的存储后端业务模型不需要大改。3. 印刷行业 ERP 文档管理需求拆解直接写代码之前先把需求拆清楚。这一步不做后面很容易返工。印刷行业的文档管理需求可以从三个维度拆业务阶段、权限角色、文档状态。3.1 按业务阶段拆不同阶段产生不同类型的文档印刷产品的完整业务流程一般分为售前、订单、印前、生产、交付五个阶段每个阶段产生的文档类型差异很大业务阶段典型文档说明售前/报价客户来稿、需求说明、参考文件客户第一次发来的设计文件或样张订单合同扫描件、订单确认函、工艺说明与销售订单绑定具有法务和商务属性印前/工程打样稿、签样稿、色卡、印前拼版文件决定最终印刷效果的关键文件签样稿是生产依据生产CTP 输出文件、印刷机台参数、工艺卡片直接用于机台生产错误代价高交付成品照片、发货单、客户签收单用于质量追溯和售后如果只做一个大而全的“文档列表”文档类型不区分业务阶段那么印前工程师上传的签样稿和业务员上传的合同扫描件会混在一起权限也不好控制。正确做法是在文档主记录上设计doc_type字段用 Selection 类型维护阶段分类不同角色通过视图和权限只能看到自己关心的类型。3.2 按权限拆不同角色对文档的处理能力应该不同印刷企业内部参与文档流转的角色主要包括业务员、印前/工程人员、生产班组、管理层。他们在文档管理系统中应该有不同的权限边界业务员负责客户来稿上传、查看订单相关文档、反馈客户修改意见可以上传和更新客户文件但不能随便改印前生产文件。印前/工程人员负责打样稿、签样稿、拼版文件的管理可以创建新版本、签出签入文件、修改工艺参数但不能更改商务合同。生产班组按工单查看已确认的签样稿、拼版文件通常是只读权限避免误操作。管理层/质量人员可以全库检索、查看操作日志、审查状态变化但不应该直接修改生产文件。在 Odoo 的权限模型里推荐把base.group_user作为基础权限再用“技术标签”或“额外用户组”来控制具体操作的写权限。对于大多数企业做到“业务员和印前分工隔离、生产班组只读”就已经比共享文件夹强很多。3.3 按流程状态拆文档不是永久的“可用”状态印刷文件的流程状态非常重要。很多质量事故不是因为文件丢了而是因为用了还没确认的版本去生产。文档状态至少应该包含待处理文件刚刚上传还没有人处理。审核中印前正在检查文件或已经提交客户确认。已确认已满足生产条件可以作为正式生产依据。已归档生产结束文档冻结不能随意修改。状态控制的意义在于把流程制度固化到系统里。比如“未签样的文档不能关联到生产工单”这条规则如果只写在制度文件里执行靠人盯肯定会漏。但如果在 Odoo 模型里加一个约束工单关联文档时检查状态就能从系统层面杜绝误用。4. 技术方案在 Odoo 中设计文档管理模型需求拆完设计方案就顺理成章了。这套方案的核心思路是文档主记录 版本子表。4.1 为什么使用“主记录 版本子表”假设你是印前工程师客户发来一个 PDF你需要修改三次每次修改都必须保留历史文件以确定最终客户确认的是哪个版本。如果用单个附件字段保存上传新版本时旧文件就会丢失一旦需要回退只能靠运气。因此设计上要分成两层print.document文档主记录一条记录代表一份业务文档。print.document.version文档版本记录维护该文档的所有历史版本。主记录用来存“这份文档的业务属性”它属于哪个订单、哪个产品、哪个工单文档类型是什么当前处于哪个状态当前生效的是哪个版本。版本子表用来存“文件本身”上传的附件、版本号、文件哈希、修改说明、签出人。这样客户每次修改不是“替换”文件而是“追加”一个新版本旧版本永远可追溯。主记录的current_version_id字段指向当前生效的版本生产班组看到的始终是明确的一份文件不会被文件名误导。4.2 核心模型字段建议下面这些字段是一个印刷行业文档管理模块的最小编码模型字段说明print.documentname文档名称print.documentcode文档编号可选便于检索print.documentdoc_type文档类型对应业务阶段print.documentorder_id关联销售订单print.documentproduct_id关联产品print.documentworkorder_id关联生产工单print.documentstate文档状态print.documentversion_ids版本记录列表print.documentcurrent_version_id当前生效版本print.documentchecked_out_by当前签出人print.document.versionsequence版本序号如 1、2、3print.document.versionattachment_id实际文件附件print.document.versionfile_hash文件 SHA256 哈希值print.document.versionnote修改说明4.3 版本自动编号和签入签出设计版本子表在create时自动计算sequence和version_name不需要人工填写。如果有 3 个版本新增第四个版本时自动命名为 v4这样可以避免出现最终版_改1_改2这种命名混乱。签入签出是印刷行业文档管理的关键机制某个人要修改文件时先执行“签出”系统记录checked_out_by为当前用户其他人如果要签出会被系统拒绝防止两个工程师同时修改同一份文件。签出后工程师下载文件并修改改完再上传新版本并“签入”系统自动释放文件锁。这个思路不复杂但能直接解决印刷企业多人交叉修改文件的混乱问题。5. 环境准备Ubuntu 安装 Odoo 与基础配置在开发和测试环境里建议先在 Ubuntu 服务器上把 Odoo 跑起来。搜索热词里“ubuntu安装odoo”“linux odoo安装部署”经常出现说明很多人卡在环境搭建这一关。下面给出一个常见的 Ubuntu 安装流程重点是通用步骤和容易踩坑的地方。5.1 安装系统依赖Odoo 依赖 Python 3、PostgreSQL、wkhtmltopdf 等组件。下面的命令适用于 Ubuntu 20.04/22.04 等版本如果你使用新版 Ubuntu 或 Debian个别包名会有差异。sudo apt update sudo apt upgrade -y sudo apt install -y git python3-pip python3-dev python3-venv \ build-essential libxml2-dev libxslt1-dev zlib1g-dev \ libsasl2-dev libldap2-dev libssl-dev libjpeg-dev libpq-dev这里需要注意Odoo 不同版本对 Python 版本的依赖不一样。在安装前先用python3 --version确认版本满足你所用 Odoo 版本的要求。如果版本不满足不要直接硬装优先考虑使用对应版本的 Ubuntu 或使用 pyenv 管理 Python 版本。5.2 创建系统用户和数据库用户生产环境推荐单独创建一个名为odoo的系统用户来运行 Odoo不要用 root 运行也不要用个人账号运行。sudo adduser --system --home/opt/odoo odoo sudo su - postgres -c createuser -s odoo sudo -u postgres psql -c alter user odoo with password odoo;这里最容易踩的坑是PostgreSQL 用户和系统用户名要保持一致否则 Odoo 连接数据库时会因为对不上用户名报错。在本地调试时如果 PostgreSQL 使用 peer 认证db_user配置成与系统用户一致即可免密连接。5.3 安装 wkhtmltopdfOdoo 打印 PDF 报表时需要 wkhtmltopdf。如果缺少这个组件打印报表时会报错或者导出 PDF 空白。sudo apt install -y wkhtmltopdf不同 Ubuntu 版本下 wkhtmltopdf 的 apt 源可能缺失或存在兼容性问题。如果apt安装失败可以到 wkhtmltopdf 官网下载对应系统版本的 deb 包手动安装安装完成后用wkhtmltopdf --version验证。5.4 下载 Odoo 源码并创建虚拟环境Odoo 官方支持 git 克隆源码的方式部署。下面这类方式是目前社区常见做法sudo mkdir -p /opt/odoo sudo chown odoo:odoo /opt/odoo sudo -u odoo git clone https://www.github.com/odoo/odoo /opt/odoo/odoo --depth 1 cd /opt/odoo sudo -u odoo python3 -m venv odoo-venv sudo -u odoo ./odoo-venv/bin/pip install -r odoo/requirements.txt使用--depth 1只克隆最近一次提交可以节省下载时间和磁盘空间。在正式生产环境建议锁定具体的 Odoo 版本分支不要长期跟最新提交否则后续升级可能带来兼容性问题。5.5 创建配置文件并启动在/etc/odoo.conf中创建配置文件[options] addons_path /opt/odoo/odoo/addons,/opt/odoo/my-addons db_host False db_port False db_user odoo db_password Falseaddons_path里既有 Odoo 内置模块目录也有自己开发的模块目录。如果插件目录权限不对启动时会出现模块列表加载不出来的情况。启动命令如下sudo -u odoo /opt/odoo/odoo-venv/bin/python /opt/odoo/odoo/odoo-bin -c /etc/odoo.conf第一次启动时Odoo 会初始化数据库并在日志中打印服务地址。看到类似HTTP service (werkzeug) running on 0.0.0.0:8069的日志就表示启动成功。这里要特别提醒以上步骤只是最小可运行的部署方式正式生产环境建议再加 Nginx 反向代理、HTTPS、PostgreSQL 定期备份、Odoo 日志轮转等配置。不要在没有任何备份策略的前提下直接拿生产环境测试模块。6. 实现印刷行业文档管理模块下面开始实现一个最小可用的印刷行业文档管理模块。代码按 Odoo 15/16/17 的常见写法演示。如果你的项目还在 Odoo 12 或更早版本部分字段和装饰器请对照官方 API 调整。6.1 创建模块目录结构在自定义 addons 目录下创建模块mkdir -p print_document/models mkdir -p print_document/views mkdir -p print_document/security touch print_document/__init__.py touch print_document/__manifest__.py__init__.py内容# 文件路径print_document/__init__.py from . import models__manifest__.py内容# 文件路径print_document/__manifest__.py { name: 印刷行业文档管理, version: 1.0.0, category: Sales, summary: 印刷企业订单、印前、生产环节文档版本管理, description: 印刷行业文档管理模块支持客户来稿、打样稿、签样稿、印前拼版文件等文档类型的版本管理、签入签出和业务关联。, depends: [base, sale_management, mrp, mail], data: [ security/ir.model.access.csv, views/print_document_views.xml, ], installable: True, application: True, }depends根据你的业务需要如果只需要订单关联去掉mrp也可以。本文为了演示工单关联保留了对生产模块的依赖。6.2 模型代码文档主记录与版本子表文件路径print_document/models/print_document.py# 文件路径print_document/models/print_document.py import base64 import hashlib from odoo import api, fields, models, _ from odoo.exceptions import ValidationError class PrintDocument(models.Model): _name print.document _description 印刷文档主记录 _inherit [mail.thread, mail.activity.mixin] _order create_date desc, id desc name fields.Char(string文档名称, requiredTrue) code fields.Char(string文档编号, copyFalse) doc_type fields.Selection([ (customer_file, 客户来稿), (proof, 打样稿), (signed, 签样稿), (prepress, 印前拼版文件), (ctp, CTP输出文件), (process, 工艺参数), (other, 其他), ], string文档类型, defaultcustomer_file) order_id fields.Many2one(sale.order, string销售订单, ondeleterestrict) product_id fields.Many2one(product.product, string产品, ondeleterestrict) workorder_id fields.Many2one(mrp.workorder, string生产工单, ondeleterestrict) state fields.Selection([ (draft, 待处理), (review, 审核中), (confirmed, 已确认), (archive, 已归档), ], string状态, defaultdraft, trackingTrue) version_ids fields.One2many(print.document.version, document_id, string版本记录) current_version_id fields.Many2one(print.document.version, string当前生效版本) checked_out_by fields.Many2one(res.users, string当前签出人, copyFalse, trackingTrue) api.constrains(name, order_id) def _check_unique_document(self): for rec in self: if rec.order_id: domain [ (name, , rec.name), (order_id, , rec.order_id.id), (id, !, rec.id), ] if self.search_count(domain) 0: raise ValidationError(_(同一销售订单下文档名称不能重复。)) def action_checkout(self): 签出文档锁定当前版本不允许他人继续修改。 self.ensure_one() if not self.current_version_id: raise ValidationError(_(当前文档还没有版本无法签出。)) if self.checked_out_by: raise ValidationError(_(当前文档已被 %s 签出。) % self.checked_out_by.name) self.write({checked_out_by: self.env.user}) self.current_version_id.write({checked_out_by: self.env.user}) def action_checkin(self): 签入文档解除锁定。 self.ensure_one() if self.checked_out_by and self.checked_out_by ! self.env.user: raise ValidationError(_(你不是当前签出人无法签入。)) self.write({checked_out_by: False}) if self.current_version_id: self.current_version_id.write({checked_out_by: False}) def action_to_confirmed(self): 手动确认文档状态表示文档可以用于生产。 self.ensure_one() if self.state draft: self.write({state: confirmed}) else: raise ValidationError(_(只有待处理状态的文档可以确认为已确认。)) class PrintDocumentVersion(models.Model): _name print.document.version _description 印刷文档版本 _order sequence desc, id desc document_id fields.Many2one(print.document, string所属文档, requiredTrue, ondeletecascade) sequence fields.Integer(string版本序号, readonlyTrue) version_name fields.Char(string版本名称, readonlyTrue) attachment_id fields.Many2one(ir.attachment, string文件, requiredTrue) file_hash fields.Char(string文件SHA256) note fields.Text(string修改说明) checked_out_by fields.Many2one(res.users, string签出人, readonlyTrue) api.model_create_multi def create(self, vals_list): for vals in vals_list: document_id vals.get(document_id) doc self.env[print.document].browse(document_id) max_seq max(doc.version_ids.mapped(sequence)) if doc.version_ids else 0 vals[sequence] max_seq 1 vals[version_name] v%d % (max_seq 1) attachment_id vals.get(attachment_id) if attachment_id: attachment self.env[ir.attachment].browse(attachment_id) vals[file_hash] self._compute_file_hash(attachment) return super().create(vals_list) staticmethod def _compute_file_hash(attachment): 读取附件内容并计算 SHA256用于文件完整性校验。 if not attachment.datas: return try: raw base64.b64decode(attachment.datas) return hashlib.sha256(raw).hexdigest() except Exception: return 我在代码里做了几件值得注意的事_inherit [mail.thread, mail.activity.mixin]让文档主记录支持消息跟踪谁在什么时候改了状态、签出、签入都会留下记录。版本子表create时自动计算版本序号不需要人工维护。file_hash在创建版本时自动计算如果后续生产工单要从系统导出文件可以先校验哈希值确认文件没有被篡改。action_checkout和action_checkin实现了最基本的签入签出控制。增加了“同一订单下文档名称不能重复”的约束避免业务员重复上传同名文档造成混乱。需要注意的是这里用attachment.datas读取的是 base64 编码后的数据。对于超大文件读取到 Python 内存中会占用较多内存生产环境建议改用ir.attachment的_file_read或者流式读取方式并评估服务端限流和内存配置。6.3 视图代码菜单、列表和表单文件路径print_document/views/print_document_views.xml!-- 文件路径print_document/views/print_document_views.xml -- odoo !-- 列表视图 -- record idview_print_document_tree modelir.ui.view field namenameprint.document.tree/field field namemodelprint.document/field field namearch typexml tree string印刷文档 field namecode/ field namename/ field namedoc_type/ field nameorder_id/ field nameproduct_id/ field namestate/ field namecurrent_version_id/ field namechecked_out_by/ /tree /field /record !-- 表单视图 -- record idview_print_document_form modelir.ui.view field namenameprint.document.form/field field namemodelprint.document/field field namearch typexml form string印刷文档 header button nameaction_checkout string签出 typeobject attrs{invisible: [(checked_out_by, !, False)]}/ button nameaction_checkin string签入 typeobject attrs{invisible: [(checked_out_by, , False)]}/ button nameaction_to_confirmed string确认可用于生产 typeobject attrs{invisible: [(state, !, draft)]}/ /header sheet div classoe_title h1field namename//h1 field namecode placeholder文档编号可选/ /div group group field namedoc_type/ field namestate/ field nameorder_id/ field nameproduct_id/ field nameworkorder_id/ /group group field namecurrent_version_id/ field namechecked_out_by/ /group /group notebook page string版本记录 nameversions field nameversion_ids tree editablefalse field nameversion_name/ field nameattachment_id widgetmany2one_binary/ field namefile_hash/ field namechecked_out_by/ field namenote/ /tree /field /page /notebook /sheet /form /field /record !-- 窗口动作 -- record idaction_print_document_list modelir.actions.act_window field namename印刷文档/field field nameres_modelprint.document/field field nameview_modetree,form/field field namecontext{search_default_doc_type: customer_file}/field /record !-- 顶级菜单和子菜单 -- menuitem idmenu_print_document_root name印刷文档 sequence20 web_iconprint_document,static/description/icon.png/ menuitem idmenu_print_document_list parentmenu_print_document_root name文档目录 actionaction_print_document_list/ /odoo在版本记录里我用widgetmany2one_binary显示附件上传控件这是 Odoo 中比较常用的文件上传方式。点击回形针或选择按钮就能把文件作为附件上传到版本记录中。6.4 权限 CSV 文件文件路径print_document/security/ir.model.access.csvid,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink access_print_document_user,print.document.user,model_print_document,base.group_user,1,1,1,0 access_print_document_version_user,print.document.version.user,model_print_document_version,base.group_user,1,1,1,0这个权限表给了所有内部用户对文档主记录和版本记录的读、写、创建权限但没有删除权限。删除权限需要单独配置给管理员或者特定安全组。在生产环境中建议再增加一个“印前工程师”用户组单独控制签样稿、拼版文件的写权限让业务员只能创建客户来稿类型。6.5 安装并升级模块把print_document目录放到配置好的addons_path中后有两种方式安装方式一命令安装sudo -u odoo /opt/odoo/odoo-venv/bin/python /opt/odoo/odoo/odoo-bin \ -c /etc/odoo.conf \ -d demo \ -u print_document \ --stop-after-init方式二界面安装在 Odoo 后台开启开发者模式进入“应用”菜单点击“更新应用列表”搜索print_document点击安装。升级模块后如果看到“模型已安装”且菜单“印刷文档”出现在顶部导航就说明模块成功加载。7. 运行结果与效果验证模块装好后不要急着录入大量数据建议先按下面的路径做一轮功能验证确认每个关键点都是合格的。7.1 验证路径一创建文档并上传第一个版本在“印刷文档 文档目录”中新建一条文档记录填写文档名称、类型、关联的销售订单然后在“版本记录”页签添加一条记录上传一个测试 PDF 文件。预期效果版本名称自动生成为v1。file_hash字段自动填充为一串 64 位十六进制字符。state默认为“待处理”。如果版本名称没有自动生成说明create方法中的版本计算逻辑没有执行。可以先查看版本子表的sequence字段如果为空则在表单视图中把该字段设为 readonly 状态或者检查模块是否成功升级。7.2 验证路径二新增第二个版本再添加一条版本记录上传修改后的第二次文件。预期效果版本名称自动生成为v2。之前的v1记录仍然存在文件内容没有被覆盖。文档主记录的current_version_id暂不会自动变化需要人工指定当前生效版本。这里要注意当前生效版本的自动切换可以写在版本创建逻辑里也可以由人工控制。在印刷生产场景中我更推荐人工指定当前生效版本因为“最新上传的版本”未必是“客户最终确认的版本”比如客户可能退回使用 v1 版本这时只靠上传顺序判断是错误的。7.3 验证路径三签出与签入使用用户 A 打开文档点击“签出”。预期效果是checked_out_by显示为用户 A其他用户再点击签出会报错“当前文档已被某用户签出”。用户 A 上传新版本并确认无误后点击“签入”预期效果是checked_out_by清空。这里的重点是异常路径也要测如果用户 A 签出后没有签入就关闭页面文档会被一直锁住。生产环境建议增加一个定时任务自动释放超过一定时间未签入的文档锁或者增加管理员强制签入按钮。7.4 验证路径四唯一性约束在同一销售订单下创建两个名称完全相同的文档记录预期效果是第二条保存时报错提示“同一销售订单下文档名称不能重复。”如果数据成功保存了要么没有升级最新模块要么约束写错了字段。7.5 验证路径五状态流转把文档从“待处理”点击“确认可用于生产”状态变成“已确认”。再次点击会报错提示只有待处理状态才能确认。这个验证逻辑是为了防止重复确认导致状态不可控。8. 常见问题与排查方法在实际开发和上线过程中下面这些问题是比较常见的我把排查思路整理成表格方便你在遇到问题时快速定位。问题现象可能原因排查方式解决方案模块安装后菜单不显示没有更新应用列表进入开发者模式后“更新应用列表”刷新应用列表并重新搜索模块模型报KeyError或字段不存在模块没有升级成功查看 Odoo 日志执行-u print_document强制升级版本名称没有自动变成 v1/v2create方法没有执行在版本子表点击“创建”后看 sequence 字段检查版本子表视图是否允许创建检查代码中的api.model_create_multifile_hash为空attachment.datas读取失败或文件尚未写入先确认附件能正常下载用 try/except 捕获异常查看日志输出同一订单下重复文档名仍能保存约束没生效确认模块升级成功检查模型名重新触发升级大文件上传超时或失败Nginx 请求体大小限制查看 Nginx 错误日志调整client_max_body_size并考虑单独配置大文件上传入口点击打印报表报错wkhtmltopdf 未安装或版本不兼容在服务器执行wkhtmltopdf --version重新安装或安装兼容版本附件文件无法下载ir.attachment存储路径被改动检查filestore目录是否存在恢复文件存储路径检查磁盘权限签出后忘记签入导致文件锁定没有强制释放机制查看checked_out_by字段增加定时任务或管理员强制签入按钮生产工单引用签样稿时未校验状态业务约束未加在工单模型上检查mrp.workorder是否有相关约束在mrp.workorder上增加关联检查和状态校验这里的两个高频坑需要多说几句。第一个坑是模块升级不彻底。很多初学者改了 Python 代码后只在界面里刷新页面没有真正升级模块。Odoo 的模型字段变更必须执行模块升级才会同步到数据库。所以在改模型、改视图、改权限后一定要执行-u print_document或者用开发者模式的“升级”按钮重新升级模块。第二个坑是大文件处理。印刷文件动辄几百 MB直接用 Odoo 默认的附件上传方式很可能超时或者内存溢出。更稳妥的做法是配置 Nginx 或反向代理的client_max_body_size并考虑用 Dropbox、Nextcloud、对象存储等方式对接大文件。从项目规划阶段就要评估文件大小和存储策略不要把 Odoo 的 filestore 当成无限容量网盘使用。9. 最佳实践与工程建议模块跑通只是第一步把它做成一个印刷企业真正日常使用的功能还需要在工程层面做大量细化。9.1 文档命名规范系统里有了版本号文件名本身就可以简化。建议规定文件名只写“客户简称产品名称用途”版本信息交给系统维护。禁止在文件名中出现最终版、修改版、打死不改版这类字样。同时在name字段的填写上也要给出命名模板比如“客户-产品-文档类型”。如果担心业务员乱填可以在 Odoo 里配置正则校验不满足规则就禁止保存。9.2 权限边界要收敛默认权限表我给了所有内部用户完整的写权限这在正式环境是不推荐的。建议最小权限原则业务员只能创建和编辑“客户来稿”“其他”类型。印前/工程人员才能修改“打样稿”“签样稿”“拼版文件”。生产班组只读或者按工单过滤。删除权限只给系统管理员。Odoo 的权限控制可以精细到ir.rule记录规则建议按部门或用户组增加数据级权限。例如印前工程师只能看到自己负责的文档管理层可以查看全部。9.3 备份策略不仅要备份数据库还要备份 filestore很多人以为备份 Odoo 只要备份 PostgreSQL 数据库就够了这是一个非常大的误区。数据库里存的是元数据和附件路径真正的文件二进制内容在filestore目录中。如果只备份数据库一旦服务器磁盘损坏所有附件都会丢失。生产环境备份策略至少要包含两部分# 备份数据库 pg_dump -U odoo -h localhost -F c odoo_prod odoo_prod.dump # 备份 filestore tar -czf filestore_$(date %F).tar.gz /opt/odoo/.local/share/Odoo/filestore建议把数据库和 filestore 的备份放到不同的存储介质上并定期做一次“恢复演练”确认备份确实能用。9.4 流程约束要落到系统里不要只在制度上写“签样稿确认后才能生产”。可以在mrp.workorder或其他生产单据模型上增加约束当用户选择文档时检查该文档状态是否为“已确认”如果未确认就弹窗报错。代码很简单但能防止生产班组在不知情的情况下使用错误版本。9.5 添加审计日志Odoo 的mail.thread已经能记录字段变化可以在此基础上做更完整的审计。例如谁在什么时间上传了哪个版本、谁签出了文档、谁把文档状态从“待处理”改成“已确认”这些记录要保留至少一年。印刷行业客户投诉、质量追溯时这些日志就是证据。9.6 历史数据迁移很多印刷企业已经把文件堆在共享文件夹里很多年了上线新系统时把这堆文件一次性导入到 Odoo 是很有挑战的事。建议分两步先迁移业务价值高的签样稿、拼版文件和生产工单关联文档。普通历史参考文件可以只做索引不迁移文件本尊等哪天真要用的时候再去原位置找。迁移时不能只搬文件还要把历史版本、修改时间、操作人尽量导入到系统中否则只搬一个“最终版”过去历史追溯链条还是断的。10. 总结与实际项目落地建议这篇文章从印刷行业文档混乱的痛点开始分析了 Odoo 中ir.attachment和 Documents 模块各自的边界然后给出了一个“文档主记录 版本子表”的轻量方案并完整实现了文档类型、状态、版本、签