mescloud/docs/generate_qm_word.py

# -*- coding: utf-8 -*-
"""Generate Word doc from qm-api device integration manual."""

from docx import Document
from docx.shared import Pt, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
from docx.oxml.ns import qn
import os

OUTPUT = os.path.join(os.path.dirname(__file__), "气密工位MES对接说明（设备方）.docx")


def set_cell_shading(cell, color="D9E2F3"):
    from docx.oxml import OxmlElement
    shading = OxmlElement("w:shd")
    shading.set(qn("w:fill"), color)
    shading.set(qn("w:val"), "clear")
    cell._tc.get_or_add_tcPr().append(shading)


def add_heading(doc, text, level=1):
    h = doc.add_heading(text, level=level)
    for run in h.runs:
        run.font.name = "微软雅黑"
        run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
    return h


def add_para(doc, text, bold=False, size=11):
    p = doc.add_paragraph()
    run = p.add_run(text)
    run.font.name = "微软雅黑"
    run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
    run.font.size = Pt(size)
    run.bold = bold
    p.paragraph_format.space_after = Pt(6)
    return p


def add_code(doc, text):
    p = doc.add_paragraph()
    p.paragraph_format.left_indent = Cm(0.5)
    run = p.add_run(text)
    run.font.name = "Consolas"
    run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
    run.font.size = Pt(9)
    run.font.color.rgb = RGBColor(0x33, 0x33, 0x33)
    p.paragraph_format.space_after = Pt(8)
    return p


def add_table(doc, headers, rows, col_widths=None):
    table = doc.add_table(rows=1 + len(rows), cols=len(headers))
    table.style = "Table Grid"
    table.alignment = WD_TABLE_ALIGNMENT.CENTER
    hdr = table.rows[0].cells
    for i, h in enumerate(headers):
        hdr[i].text = h
        set_cell_shading(hdr[i])
        for p in hdr[i].paragraphs:
            for run in p.runs:
                run.bold = True
                run.font.name = "微软雅黑"
                run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
                run.font.size = Pt(10)
    for ri, row in enumerate(rows):
        cells = table.rows[ri + 1].cells
        for ci, val in enumerate(row):
            cells[ci].text = str(val)
            for p in cells[ci].paragraphs:
                for run in p.runs:
                    run.font.name = "微软雅黑"
                    run._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
                    run.font.size = Pt(10)
    if col_widths:
        for i, w in enumerate(col_widths):
            for row in table.rows:
                row.cells[i].width = Cm(w)
    doc.add_paragraph()
    return table


def build():
    doc = Document()
    sec = doc.sections[0]
    sec.top_margin = Cm(2.5)
    sec.bottom_margin = Cm(2.5)
    sec.left_margin = Cm(2.8)
    sec.right_margin = Cm(2.8)

    # Title
    title = doc.add_paragraph()
    title.alignment = WD_ALIGN_PARAGRAPH.CENTER
    tr = title.add_run("气密工位 MES 对接说明（设备方）")
    tr.bold = True
    tr.font.size = Pt(18)
    tr.font.name = "微软雅黑"
    tr._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")

    sub = doc.add_paragraph()
    sub.alignment = WD_ALIGN_PARAGRAPH.CENTER
    sr = sub.add_run("文档版本：v1.0    更新日期：2026-06-08")
    sr.font.size = Pt(10)
    sr.font.color.rgb = RGBColor(0x66, 0x66, 0x66)
    sr.font.name = "微软雅黑"
    sr._element.rPr.rFonts.set(qn("w:eastAsia"), "微软雅黑")
    doc.add_paragraph()

    add_para(doc, "文档用途：气密检测设备与 MES 系统对接，完成本工位进站校验与结果上传。")
    add_para(doc, "对接方：气密设备软件 / 上位机开发")
    add_para(doc, "MES 地址：http://192.168.16.99:8980", bold=True)
    doc.add_paragraph()

    # Section 1
    add_heading(doc, "一、先看这个（1 分钟读懂）", 1)
    add_para(doc, "您的设备软件只需要做 2 件事：")
    add_table(doc, ["时机", "调用哪个接口", "作用"], [
        ["扫码后、开始测试前", "接口 1：qmcheck", "问 MES：这个工件能不能测？"],
        ["测试结束后", "接口 2：qmresult", "告诉 MES：测完了，结果 OK 还是 NG"],
    ], [4, 4.5, 6])
    add_para(doc, "不需要登录、不需要 Token，设备能访问 MES 服务器 IP 即可。")
    add_para(doc, "MES 会提前提供给您的固定参数（请填入下表，对接前向 MES 方确认）：")
    add_table(doc, ["参数", "含义", "示例（以 MES 方确认为准）"], [
        ["oprno", "工位号", "OP450"],
        ["lineSn", "产线编号", "XT"],
    ], [3, 4, 6])

    # Section 2
    add_heading(doc, "二、整体流程（设备侧逻辑）", 1)
    add_code(doc, """操作员扫码（得到 sn）
        │
        ▼
  调用 qmcheck（进站校验）
        │
  result=true 且 data=UD ?
        │
   否 ──┴── 是
   │         │
   ▼         ▼
屏幕提示   开始气密测试
禁止测试   （设备自行测试）
                 │
                 ▼
          调用 qmresult（上传结果）
                 │
           result=true ?
                 │
          否 ────┴──── 是
          │            │
          ▼            ▼
       提示失败     显示上传成功""")

    # Section 3
    add_heading(doc, "三、通信方式（统一约定）", 1)
    add_table(doc, ["项目", "值"], [
        ["协议", "HTTP"],
        ["方法", "POST"],
        ["参数格式", "表单：application/x-www-form-urlencoded"],
        ["编码", "UTF-8"],
        ["返回格式", "JSON 字符串"],
    ], [4, 10])
    add_para(doc, "请求示例格式（所有接口相同）：")
    add_code(doc, """POST http://192.168.16.99:8980/js/a/mes/mesProductRecord/接口名
Content-Type: application/x-www-form-urlencoded

参数1=值1&参数2=值2&...""")
    add_para(doc, "建议每个请求都带上：__ajax=json（固定值，便于返回 JSON）。")

    # Section 4
    add_heading(doc, "四、接口 1：进站校验 qmcheck", 1)
    add_heading(doc, "4.1 什么时候调", 2)
    add_para(doc, "• 操作员扫完条码、设备尚未开始充气/测试之前")
    add_para(doc, "• 每个工件测一次（换件后重新调）")

    add_heading(doc, "4.2 地址", 2)
    add_code(doc, "POST http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmcheck")

    add_heading(doc, "4.3 要传哪些参数", 2)
    add_table(doc, ["参数", "必填", "从哪里来", "说明"], [
        ["sn", "是", "扫码枪 / 人工输入", "工件条码"],
        ["oprno", "是", "MES 提供，写死在配置里", "工位号"],
        ["lineSn", "是", "MES 提供，写死在配置里", "产线号"],
        ["workNum", "建议", "登录工号，没有就传 system", "操作员"],
        ["__ajax", "建议", "固定 json", "—"],
    ], [2.5, 1.5, 4.5, 4.5])

    add_heading(doc, "4.4 请求示例", 2)
    add_para(doc, "表单内容：")
    add_code(doc, "__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&workNum=system")
    add_para(doc, "curl（Windows）：")
    add_code(doc, 'curl -X POST "http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmcheck" ^\n  -H "Content-Type: application/x-www-form-urlencoded" ^\n  -d "__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&workNum=system"')

    add_heading(doc, "4.5 返回怎么判断（设备程序重点）", 2)
    add_para(doc, "返回示例：")
    add_code(doc, '{\n  "result": "true",\n  "message": "工件可以加工",\n  "data": "UD"\n}')
    add_para(doc, "判断规则（写进设备程序）：")
    add_code(doc, 'IF result == "true" AND data == "UD"\n    → 允许开始测试\nELSE\n    → 不允许测试，屏幕显示 message 原文')
    add_table(doc, ["result", "data", "设备怎么处理"], [
        ["true", "UD", "允许测试"],
        ["false", "任意", "禁止测试，显示 message"],
    ], [2.5, 2.5, 8])
    add_para(doc, "常见 message 含义：")
    add_table(doc, ["message 示例", "含义"], [
        ["工件可以加工", "正常，可以测"],
        ["该工件OP180未加工", "前面工位没做，不能测"],
        ["该工件本工位已加工，结果：OK", "已经测过且合格，不必再测"],
        ["该工件未录入系统", "条码错误或 MES 无此件"],
        ["两次气密必须间隔15分钟", "同一工件 15 分钟内不能重复测"],
        ["参数错误1", "sn / oprno / lineSn 有缺失"],
    ], [6, 7])

    # Section 5
    add_heading(doc, "五、接口 2：结果上传 qmresult", 1)
    add_heading(doc, "5.1 什么时候调", 2)
    add_para(doc, "• 气密测试结束后（无论 OK 还是 NG 都要调）")
    add_para(doc, "• 必须先 qmcheck 通过再测；测完再调本接口")

    add_heading(doc, "5.2 地址", 2)
    add_code(doc, "POST http://192.168.16.99:8980/js/a/mes/mesProductRecord/qmresult")

    add_heading(doc, "5.3 要传哪些参数", 2)
    add_para(doc, "必填（少了会报「参数错误1」）：")
    add_table(doc, ["参数", "说明", "示例"], [
        ["sn", "工件条码（与 qmcheck 相同）", "扫码值"],
        ["oprno", "工位号", "OP450"],
        ["lineSn", "产线号", "XT"],
        ["result", "测试结果", "OK 或 NG（必须大写）"],
        ["craft", "工艺号", "固定传 100000"],
        ["__ajax", "建议", "json"],
    ], [2.5, 5, 5.5])
    add_para(doc, "建议传：workNum（操作员工号，没有传 system）")
    add_para(doc, "可选（有就传，便于 MES 存过程数据）：")
    add_table(doc, ["参数", "是否编码", "说明"], [
        ["testPressure", "Base64", "测试压力"],
        ["testPressureUnit", "明文", "单位，如 Pa"],
        ["leakVal", "Base64", "泄漏值"],
        ["leakValUnit", "明文", "单位"],
        ["testTime", "Base64", "测试时间，格式 yyyy-MM-dd HH:mm:ss"],
        ["cxm", "明文", "设备程序号"],
        ["deviceType", "明文", "设备编号"],
        ["remark", "明文", "备注"],
    ], [3.5, 2, 8])
    add_para(doc, "关于 Base64：testPressure、leakVal、testTime 需先 Base64 编码再提交。若暂时不做 Base64，最少只传必填项也能完成工位对接。")
    add_para(doc, "Base64 对照（方便联调）：")
    add_table(doc, ["原始值", "传参值"], [
        ["200", "MjAw"],
        ["5", "NQ=="],
        ["2024-05-16 12:12:00", "MjAyNC0wNS0xNiAxMjoxMjowMA=="],
    ], [5, 8])

    add_heading(doc, "5.4 请求示例", 2)
    add_para(doc, "最简版（能完成工位对接）：")
    add_code(doc, "__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&craft=100000&result=OK&workNum=system")
    add_para(doc, "完整版（含过程数据）：")
    add_code(doc, "__ajax=json&sn=501901660045119990G4JB100071&oprno=OP450&lineSn=XT&craft=100000&result=OK&workNum=system&testPressure=MjAw&testPressureUnit=Pa&leakVal=NQ==&leakValUnit=Pa&testTime=MjAyNC0wNS0xNiAxMjoxMjowMA==&cxm=PROGRAM_01")

    add_heading(doc, "5.5 返回怎么判断", 2)
    add_para(doc, "成功：")
    add_code(doc, '{\n  "result": "true",\n  "message": "操作成功！"\n}')
    add_para(doc, "失败：")
    add_code(doc, '{\n  "result": "false",\n  "message": "该工件本工位已加工，结果：OK"\n}')
    add_code(doc, 'IF result == "true"\n    → 上传成功，MES 工位结果已更新\nELSE\n    → 上传失败，显示 message，建议本地保存待人工处理')
    add_table(doc, ["常见 message", "原因", "建议"], [
        ["操作成功！", "正常", "—"],
        ["参数错误1！", "缺 sn/oprno/lineSn/result", "检查必填参数"],
        ["子工位未配置！", "MES 未配置该工位", "联系 MES 管理员"],
        ["该工件本工位已加工…", "重复上传", "提示用户，勿重复提交"],
        ["该工件OPxxx未加工", "未做 qmcheck 或前序工位未完成", "先校验流程"],
    ], [4.5, 4.5, 4])

    # Section 6
    add_heading(doc, "六、设备程序伪代码", 1)
    add_code(doc, """// 配置项（MES 方提供，写死在设备软件里）
MES_HOST = "192.168.16.99"
MES_PORT = 8980
OPRNO    = "OP450"      // 工位号，向 MES 确认
LINE_SN  = "XT"         // 产线号，向 MES 确认

// 1. 扫码后
sn = 扫码结果
body = "__ajax=json&sn=" + urlEncode(sn)
     + "&oprno=" + OPRNO + "&lineSn=" + LINE_SN
     + "&workNum=" + urlEncode(当前工号或"system")
resp = HTTP_POST("http://" + MES_HOST + ":8980/js/a/mes/mesProductRecord/qmcheck", body)
if resp.result != "true" OR resp.data != "UD":
    显示(resp.message); 停止，不允许测试

// 2. 设备自行做气密测试
testResult = 设备判定结果  // "OK" 或 "NG"

// 3. 测试结束后上传
body = "__ajax=json&sn=" + urlEncode(sn)
     + "&oprno=" + OPRNO + "&lineSn=" + LINE_SN
     + "&craft=100000" + "&result=" + testResult
     + "&workNum=" + urlEncode(当前工号或"system")
resp = HTTP_POST("http://" + MES_HOST + ":8980/js/a/mes/mesProductRecord/qmresult", body)
if resp.result != "true":
    显示("MES上传失败：" + resp.message); 本地记录，供补传
else
    显示("MES上传成功")""")

    # Section 7
    add_heading(doc, "七、联调步骤（双方配合）", 1)
    add_heading(doc, "第 1 步：网络", 2)
    add_para(doc, "□ 气密设备电脑能 ping 192.168.16.99")
    add_para(doc, "□ 浏览器或 Postman 能访问 http://192.168.16.99:8980")

    add_heading(doc, "第 2 步：用 Postman 测通两个接口", 2)
    add_para(doc, "1. 向 MES 方要一个真实可测的工件码 sn")
    add_para(doc, "2. 调 qmcheck，确认返回 result=true, data=UD")
    add_para(doc, "3. 调 qmresult，result=OK，确认返回「操作成功！」")
    add_para(doc, "4. MES 方在后台确认工位结果已更新")

    add_heading(doc, "第 3 步：设备软件接入", 2)
    add_para(doc, "按第六节伪代码接入；先实现最简参数，过程数据稳定后再补。")

    add_heading(doc, "第 4 步：现场验证", 2)
    add_para(doc, "□ 正常件：check 通过 → 测试 → result 上传成功")
    add_para(doc, "□ NG 件：result=NG 上传成功，MES 显示 NG")
    add_para(doc, "□ 重复扫码：check 提示已加工，不允许再测")
    add_para(doc, "□ 错误条码：check 提示未录入系统")

    # Section 8 FAQ
    add_heading(doc, "八、常见问题 FAQ", 1)
    faqs = [
        ("Q1：要不要登录 MES？", "不需要。两个接口均已开放匿名访问。"),
        ("Q2：只调 qmresult 不调 qmcheck 可以吗？", "不建议。可能因前序工位、重复加工等原因上传失败。"),
        ("Q3：craft 为什么固定 100000？", "MES 约定 100000 表示工位总结果（OK/NG），必须传。"),
        ("Q4：result 用小写 ok/ng 可以吗？", "不可以，必须大写 OK / NG。"),
        ("Q5：qmcheck 和 qmresult 的 sn 必须一致吗？", "必须一致，为同一工件条码。"),
        ("Q6：上传失败要不要重试？", "看 message。若是「已加工」等业务拦截，不要盲重试；网络超时可在本地缓存后定时重试 qmresult。"),
        ("Q7：工件码有特殊字符怎么办？", "做 URL 编码（如空格、&、= 等）。"),
    ]
    for q, a in faqs:
        add_para(doc, q, bold=True)
        add_para(doc, "A：" + a)

    # Section 9
    add_heading(doc, "九、对接确认单（请 MES 方填写后发给设备方）", 1)
    add_table(doc, ["项", "值"], [
        ["MES 服务器 IP", "192.168.16.99"],
        ["端口", "8980"],
        ["工位号 oprno", "__________"],
        ["产线号 lineSn", "__________"],
        ["测试用工件码 sn", "__________"],
        ["是否需要传过程数据（压力/泄漏值）", "是 / 否"],
        ["MES 联系人", "__________"],
        ["联系电话 / 微信", "__________"],
    ], [5.5, 8.5])

    doc.save(OUTPUT)
    print("Generated:", OUTPUT)


if __name__ == "__main__":
    build()