zkxw/docs/sop-templates/SOP富文本制作标准.md

SOP 富文本制作标准（基于 SOP-CC-001-E01-01）

本文档沉淀自 SOP-CC-001-E01-01（存储样本接收操作记录）的落地过程，作为后续工艺 SOP 富文本的权威约定。新工艺按本标准执行，避免重复踩坑。

---

1. 架构与数据流

层级	路径 / 表	说明
模板源码	docs/sop-templates/{工艺编码}.html	权威 HTML；不进 Docker 镜像亦可，以仓库为准
Logo 等静态资源	web-admin/public/sop-templates/	前端可访问，路径形如 /sop-templates/xxx-logo.jpeg
工艺库	biz_process.sop_content	运行时 TinyMCE 内容（模板灌库后的快照）
工艺路线步骤	biz_process_route_step.sop_content	从工艺库拷贝的快照；改工艺库不会自动同步
生产任务步骤	biz_production_task_step.sop_content	同上，执行期可再编辑
编辑 / 打印样式与交互	web-admin/src/utils/sop-print.ts	勾选、下划线、A4、打印嵌入图
编辑器组件	web-admin/src/components/TinyMceEditor/index.vue	show-print 开启 SOP A4 模式

字段 DDL：docs/sql/2026-08-25-biz-process-sop-content.sql（三表 LONGTEXT sop_content）。

快照原则：路线 / 任务步骤的 sop_content 为拷贝。更新模板后须分别：

1. 更新 HTML 模板
2. 重新灌 biz_process（seed SQL）
3. 按需执行同步脚本，覆盖关联路线 / 任务步骤

参考：docs/sql/2026-08-25-seed-sop-cc-001-content.sql、docs/sql/2026-08-25-sync-sop-cc-001-content-to-routes-tasks.sql。

---

2. 版式规范（A4 竖版）

• 纸张：210mm × 297mm（A4 portrait）
• 外层容器：class="sop-record sop-a4 sop-{业务短码}"，建议 height/min-height: 297mm，padding: 16mm 15mm 20mm
• 字号：页眉主标题 / 编码行 12pt（小四）；正文 10.5pt（五号）
• 页眉主标题可加粗；表格内标签不加粗
• 标点统一英文半角：:, ,, ; 等
• 边框色：#334155；正文字色：#1e293b
• 列宽按 Word 原稿比例用 <colgroup> 固定；可用 table-layout:fixed
• 需要撑满剩余高度的操作区：行加 sop-fill-row，左标题 sop-fill-label，正文 sop-fill-cell

页眉三列（推荐结构）

1. Logo（居中）
2. 记录名称（居中、加粗、宋体系）
3. 两行：文件编码 / 版本号

Logo：src="/sop-templates/{资源名}"（站点根路径，勿用相对路径）。

---

3. 必备 CSS 类（勿随意改名）

样式与交互集中在 sop-print.ts 的 SOP_SHARED_CONTENT_STYLE。模板 HTML 只负责结构 + 类名，复杂勾选/对齐逻辑不要另写一套。

类名	用途
sop-record sop-a4	A4 外层
sop-header-table	页眉表
sop-body-table	正文表
sop-fill-row / sop-fill-label / sop-fill-cell	可撑高填写区；左侧标题上下居中
sop-row-hidden	页眉表或非主操作区行（工序/试剂/仪器设备/清场/签名等）；编辑与打印均不展示，HTML 仍保留便于后续恢复
sop-option	选项整组（勾选框 + 文案），可点击
sop-check	勾选框本体
sop-check--checked	已勾选（编辑态视觉）
data-sop-checked="1"	勾选态属性兜底（序列化 / 打印）
sop-underline	下划线填写区，左对齐；运行时字色 #059669、字重 700，下划线 #10b981（见 sop-print.ts）
sop-blank-cell	空白填写单元格，左对齐；运行时字色/字重同上
sop-option-cell / sop-option-cell-wide	窄格内选项间距

---

4. 交互控件写法（标准片段）

4.1 勾选框（必须）

空 span 会被 TinyMCE 清掉，且内部   会影响基线。统一写法：

<span class="sop-option">
  <span class="sop-check" contenteditable="false" data-mce-contenteditable="false">&nbsp;</span>选项文案
</span>

约定：

• 点击 .sop-check 或整组 .sop-option 切换勾选
• 勾选后同时有 class sop-check--checked 与属性 data-sop-checked="1"
• 不要用原生 <input type="checkbox">（除非后续统一改造）
• 勾选框与文字：底边对齐（样式在 sop-print.ts，top: -3px 微调；新工艺勿再各写一套偏移）

4.2 下划线填写

<span class="sop-underline" style="text-align:left; min-width:96px;">&nbsp;</span>

• 必须带 sop-underline
• 内联 text-align:left（防止默认居中）
• min-width 按栏位需要调整

运行时样式（编辑 + 打印，由 sop-print.ts 注入，模板 HTML 勿内联字色）：

• 手填文字：#059669、font-weight: 700
• 下划线：#10b981（约 1.5px）
• 模板固定文案保持深灰；勾选框仍用 #334155 实心态

4.3 空白单元格

<td class="sop-blank-cell" style="border:1px solid #334155; padding:8px;">&nbsp;</td>

---

5. 前端接入约定

• 工艺库 / 路线配置 / 任务步骤：使用 TinyMceEditor，并加 show-print（开启 A4 content_style、勾选交互、打印按钮）
• 打印前：editor.getContent() 取实时 HTML（含勾选态），勿只信可能过期的 v-model
• 打印：printSopHtml() 会
  • 规范化勾选 class / data-sop-checked
  • 将图片 fetch → base64 嵌入（解决 blob 打印页 logo 丢失）
  • 勾选打印样式：白底黑勾（不依赖浏览器「背景图形」）
• 编辑区高度：A4 约 1123px + SOP_EDITOR_EXTRA_HEIGHT_PX（当前 200）

---

6. 灌库与同步流程（每个新工艺）

1. 建模板

   • docs/sop-templates/{process_code}.html
   • Logo → web-admin/public/sop-templates/

2. 生成 seed SQL（示例命名）

   • docs/sql/YYYY-MM-DD-seed-{短码}-content.sql
   • UPDATE biz_process SET sop_content = '...' WHERE process_code = '...' AND del_flag = 0
   • 单引号转义为 ''；含 % 的样式用 mysql 客户端或参数化脚本执行，勿经 SQLAlchemy text() 直接跑（% 会被当占位符）

3. 同步快照（可选但生产常用）

   • 路线：biz_process_route_step，按 process_code 或 process_id + tenant_no + del_flag=0
   • 任务：biz_production_task_step，按 process_code + tenant_no
   • 注意：biz_production_task_step 与 biz_process 的 collation 可能不一致，JOIN 时需 COLLATE utf8mb4_general_ci（见 CC-001 同步脚本）

4. 验收清单

   • 工艺库编辑页：勾选可点、状态保存后重开仍在
   • 下划线填写左对齐
   • 手填区（下划线 / 空白格）为薄荷绿加粗，模板文案为深灰
   • 勾选框底边与旁侧文字对齐
   • 打印：勾选可见、顶部 logo 可见、无多余浏览器页眉页脚（打印对话框关闭「页眉和页脚」）
   • 关联路线 / 任务步骤已有 sop_content（若业务需要）

---

7. 新工艺制作 Checklist（复制用）

工艺编码: _______________
Word/原稿: resources/sop-originals/_______________
HTML: docs/sop-templates/{编码}.html
Logo: web-admin/public/sop-templates/_______________
Seed SQL: docs/sql/____-seed-____-content.sql
Sync SQL: docs/sql/____-sync-____-content-to-routes-tasks.sql（按需）

结构:
[ ] sop-record sop-a4 + 页眉三列表 + 正文表
[ ] 半角标点、五号正文 / 小四页眉
[ ] 勾选均用 sop-option + sop-check（contenteditable=false +  ）
[ ] 下划线均用 sop-underline + text-align:left
[ ] 空白格 sop-blank-cell
[ ] 撑高区 sop-fill-row / label / cell

前端:
[ ] 无需改 TinyMCE（沿用 show-print）；仅新 logo 静态资源

数据:
[ ] 灌 biz_process
[ ] 同步 route_step / task_step（如需要）
[ ] 勾选 / 打印 / logo 人工验收通过

---

8. 参考样例

• 模板：docs/sop-templates/SOP-CC-001-E01-01.html
• 原稿：resources/sop-originals/SOP-CC-001-E01-01 存储样本接收操作记录.docx
• 样式与打印：web-admin/src/utils/sop-print.ts
• 启用打印的页面示例：工艺库、工艺路线配置、生产任务步骤详情

后续每做一个新编码，优先 复制 CC-001 HTML 骨架 → 按 Word 改内容与列宽 → 灌库同步 → 按第 6/7 节验收，不要另起交互与类名体系。