SignatureSystem/seal_srs.md

一、引言

1.1 项目背景

为适配泛微 Ecology OA流程审批场景，实现审批环节自动插入个人电子签名 / 公用公章；模拟人工手写、手持盖章的真实效果，通过图像处理实现签章差异化，提升仿真度。

服务基于 Python Flask 开发，内置独立 Web 服务，采用绿色免安装模式，可直接在 Windows 10/Windows 11 系统运行，无需部署 IIS、Apache、Nginx 等第三方网站服务；数据库采用 MySQL，连接端口、账号、密码可通过配置文件自定义，服务每次启动自动加载最新配置。

系统包含 API测试、OA/API 请求监控、批量 Word 转换与自动签名、数据库管理等前端页面。其中 API测试页面合并原综合调试页和原 API 专用测试页的功能与元素；系统支持数据库图片原图 / 抠图效果双预览、数据增删改查与批量导入；无论是前端手动操作，还是泛微 OA 等第三方系统通过真实 API 接入调用，前端日志窗口均可实时展示完整请求、处理、响应全流程日志，满足线上联调、问题排查、运行监控需求。

1.2 核心目标

用户还需要通过域代码传入日期。字体默认小四号。（用户直接在签名后写日期）

1. 系统兼容 Windows 10、Windows 11（32/64 位），绿色免安装，独立 Web 服务运行，不依赖系统网站组件；
2. 数据库连接参数可配置，服务启动强制读取配置文件最新参数；
3. 支持数据库条目选中后，预览原始图片、自动抠图效果图；数据库记录 is_signature=true 时，在线预览对该记录执行手写签字黑白二值化预览处理；
4. 区分两类请求来源：前端页面手动操作、外部第三方 API 调用，两类请求的全流程日志均实时推送至前端日志窗口；
5. 日志内容完整覆盖 API 入参、参数校验、数据库查询、图片处理、Word 签章、接口返回、异常详情；
6. 保留原有人员 ID / 姓名匹配、图片缩放、噪点、旋转、参数校验、自动闭环定位等全部业务规则；
7. 日志支持多维度筛选、溯源，满足运维监控与故障定位需求。

1.3 术语定义

表格

术语	说明
人员 ID	字符串类型，仅支持大小写英文字母、阿拉伯数字，数据表唯一主键，全局不可重复
图片二进制数据	签章图片以 Blob 二进制格式存储在 MySQL 字段中
自动抠图	将图片纯白色背景转为 Alpha 透明通道
透明边框裁剪	剔除图片四周所有透明区域，保留图案最小外接矩形
等比例缩放	仅以目标高度（厘米）为基准缩放，宽度按原图比例自动计算
自动闭环定位	日志异常行点击后，自动跳转并高亮页面对应输入 / 操作项，形成「日志 - 操作区」溯源闭环
绿色版	免安装、不写入注册表、不修改系统环境变量，解压即可启动运行
内置 Web 服务	Flask 原生 WSGI 服务，作为独立 Web 容器对外提供页面与 API，无需额外网站服务
原图预览	查看数据库中存储的原始签章图片
抠图预览	查看经过「白底转透明通道」处理后的图片效果
前端操作日志	用户在页面手动点击、提交表单产生的运行日志
外部 API 日志	泛微 OA 等第三方系统调用服务端 API 接口产生的请求与处理日志
日志实时推送	API 请求触发后，处理步骤日志即时展示在前端日志区，无明显延迟

---

二、总体架构与全局业务流程

2.1 整体架构

服务分为五大模块，Web 容器为程序内置，独立运行，不依赖第三方 Web 服务：

1. 接入层
   • API测试页面、OA/API 请求监控页面、批量 Word 转换与自动签名页面、数据库管理页面：面向内部测试、运维、管理员
   • 对外 API 接口 /api/word/sign：面向泛微 OA 等第三方系统接入
2. 配置层：全局配置文件，存储 MySQL 端口、账号、密码等参数，服务启动优先加载
3. 数据层：MySQL 数据库（user_sign表，存储人员信息 + 签章图片二进制数据）
4. 核心处理层：图片处理引擎 + Word 文档签章引擎 + 全链路日志打点模块
5. 文件层：临时文件目录、Word 输出目录、日志目录、批量导入缓存目录

2.2 通用前置规则

1. Word 来源二选一：①前端 / API直接上传 Word 文件流；②传入服务端 Word 绝对路径 doc_path；
2. 签章图片来源二选一：①传入user_id → 查询 MySQL 获取图片；②前端 / API直接上传图片文件流；
3. 优先级规则：同时上传图片文件 + 传入user_id，优先使用上传的图片文件；
4. 图片处理固定流水线（顺序严禁变更）：自动抠图→裁透明边框→条件判断是否执行等比例缩放→边缘集中型随机噪点→角度旋转。

---

三、核心业务规则

3.1 人员匹配规则

1. 人员 ID 为字符串类型，仅支持大小写英文字母、阿拉伯数字，禁止中文、符号、空格；
2. 人员姓名支持中文字符、英文字符；
3. 若传入user_id为空字符串，则放弃 ID 匹配，改用人员姓名进行数据库匹配；
4. 人员 ID 全局唯一，数据库层面设置唯一约束，前端与服务端均做重复校验。
5. 数据库字段 user_sign.is_signature 和 API 请求项中的 is_signature 均不得作为数据库匹配过滤条件。API 调用时无论 JSON 中 is_signature 为 true 还是 false，也无论数据库记录 is_signature 为 true 还是 false，均按当前匹配模式在所有数据库记录中按 user_id 或 user_name 查询。

3.2 图片缩放规则

1. 当前 API 使用 height 表示图片目标高度，img_height 为旧字段，已被替代。
2. height 单位为厘米，保留 1 位小数，有效范围为 0.1..10.0。
3. use_global_height=true 时所有盖章项使用全局 height；false 时使用每个盖章项自己的 height。
4. 有效高度缺失或非法时，该盖章项跳过高度调整，继续处理并写入 WARN 日志。
5. 缩放只按高度等比例缩放，宽度按原图比例自动计算。

3.3 图片处理规则

1. 固定流水线：可选手写签字黑白二值化（is_signature=true 时）→ 白底转透明抠图 → 裁剪透明边框 → 可选按 height 等比例缩放 → 边缘噪声 → 旋转。
2. 边缘噪声使用整数 noise_level=0..10。0 表示不加噪声，1..10 表示逐步增强的边缘不规则效果；单项非法时使用 0 并告警。
3. 旋转使用 rotate_min、rotate_max 表示整数角度范围，单位度，端点范围为 -180..180；单项非法或缺失时使用 0..0 并告警。

---

四、数据库设计

4.1 数据表结构（user_sign表）

表格

字段名	数据类型	约束	说明
user_id	VARCHAR(50)	PRIMARY KEY	人员 ID，字符串类型，仅支持大小写字母、数字
user_name	VARCHAR(100)	NOT NULL	人员姓名，支持中文、英文字符
sign_image	LONGBLOB	NOT NULL	签章图片二进制数据（PNG/JPG/JPEG 格式）
is_signature	TINYINT(1)	NOT NULL DEFAULT 0	数据库图片属性。1/true 表示手写签字，数据库管理页面在线预览时执行黑白二值化；0/false 表示普通签章图片，不执行该预览处理。该字段不参与 API 匹配过滤
create_time	DATETIME	DEFAULT CURRENT_TIMESTAMP	记录创建时间
update_time	DATETIME	DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP	记录更新时间

4.2 数据库配置规则

1. MySQL 默认配置：端口33366，管理员账号admin，默认密码admin；
2. 所有数据库连接参数（主机、端口、账号、密码、数据库名）均可通过配置文件自定义修改；
3. 服务每次启动自动读取配置文件最新内容，修改配置后需重启服务生效。

---

五、前端页面详细设计

5.1 整体布局方案

采用 顶部通栏 + 左侧操作区 + 右侧日志区 经典三栏布局，主打 PC 端使用，整体宽度适配 1920/1366 主流显示器：

1. 顶部通栏（Header）：高度 60px，全局标题 + 服务状态 + 系统信息，贯穿页面全宽；
2. 左侧主操作区（Left）：固定宽度 480px，纵向排列功能卡片，按用户操作流程从上至下排布；
3. 右侧日志展示区（Right）：自适应剩余宽度，分为日志工具栏、日志内容区两大块。

5.2 API测试页面

API测试页面合并原综合调试页面和原 API 专用测试页面，访问地址为 http://服务IP:5001/api-test。页面必须同时支持手动签章调试和 API 请求构建/发送/响应查看。

主要功能元素：

1. Word .docx 文档来源选择。
2. 签章图片来源和匹配模式选择，包括上传图片、数据库 ID、数据库名称、auto 自动匹配。
3. 多签章项配置，单次请求最多 100 个签章项。
4. 全局和单项的对齐、高度、噪声、旋转、is_signature 配置。
5. 根据用户输入构建完整 /api/word/sign JSON 请求，并显示完整 JSON 预览。
6. 支持发送测试请求、成功 .docx 返回结果下载/显示、失败 JSON 错误体展示。
7. 提供 OA Action 兼容性示例，说明按 HTTP 状态码和 Content-Type 区分成功/失败。
8. 保留执行签章、清空表单、清空日志、业务规则提示和全流程日志。

5.3 数据库管理页面

• 访问地址：http://服务IP:5001/db-manager
• 核心功能：
  1. 数据列表展示：分页显示所有人员签名记录，支持按人员 ID、姓名搜索
  2. 单条增删改查：新增、编辑、删除、查看单条记录
  3. is_signature 图片属性维护：新增、编辑和批量导入时可设置该字段；true 表示手写签字，false 表示普通签章图片
  4. 图片双预览：选中条目后，同步展示原始图片与处理后效果图。若该记录 is_signature=true，处理后预览先执行黑白二值化，再进入自动抠图/透明预览；若为 false，则不执行二值化，仅按普通签章图片预览
  5. 批量导入：支持批量上传图片文件，自动截取文件名作为人员姓名，人员 ID 支持自动递增生成
  6. 批量导入异常处理：写入失败不清空数据，标注异常条目，自动跳过错误继续执行，成功条目自动移除，保留失败条目待二次处理

---

六、日志体系设计

6.1 日志分类与格式

系统日志分为前端操作日志和外部 API 日志两类，统一格式：

plaintext

[时间戳(精确到毫秒)] [日志级别] [请求来源] 详细日志内容

• 日志级别：INFO（黑色）、WARN（橙色）、ERROR（红色 + 浅红背景）
• 请求来源：[前端操作]（灰色标签）、[外部API]（蓝色标签）

6.2 外部 API 日志强制记录内容

1. 请求接入：客户端 IP、请求时间、接口地址、完整入参、参数校验结果
2. 图片匹配：图片来源判断、ID / 姓名匹配过程、数据库查询结果
3. 图片处理：抠图、裁剪、缩放、噪点、旋转每一步执行状态与参数
4. Word 处理：文档读取、标记查找、图片插入、文件保存状态
5. 请求收尾：临时文件清理、接口返回数据、总耗时
6. 异常信息：错误描述、错误代码、出错环节、堆栈简要信息

6.3 日志功能

1. 实时推送：所有日志实时展示在前端窗口，延迟≤200ms
2. 自动刷新：默认 2 秒自动刷新，可手动关闭
3. 多维度筛选：全部日志、仅前端操作日志、仅外部 API 日志、仅异常日志
4. 关键字搜索：支持按 IP、人员 ID、错误信息等检索
5. 自动闭环定位：
   • 前端操作异常日志：点击后高亮对应输入框 / 控件
   • 外部 API 异常日志：点击后弹出详情弹窗，展示完整入参与错误信息
6. 一键定位异常：自动跳转到第一条异常日志并展示溯源信息

---

七、绿色部署与运行环境

7.1 运行环境

• 操作系统：Windows 10、Windows 11（32 位 / 64 位）
• 权限要求：普通用户权限即可运行，无需管理员权限
• 依赖：无外部依赖，所有运行时、库文件均内置在绿色包中

7.2 绿色包结构

plaintext

WordSignService/
├── bin/                  # 程序运行文件
├── mysql/                # 内置MySQL 5绿色版数据库
├── config.ini            # 全局配置文件
├── start.bat             # 一键启动脚本
├── stop.bat              # 一键停止脚本
├── install_service.bat   # 注册Windows系统服务脚本
├── uninstall_service.bat # 卸载Windows系统服务脚本
├── temp/                 # 临时文件目录（自动创建）
├── logs/                 # 日志文件目录（自动创建）
└── output/               # 处理后Word文件输出目录（自动创建）

7.3 启动与服务注册

1. 手动启动：双击start.bat，自动启动 MySQL 数据库与 Web 服务
2. 系统服务注册：右键以管理员身份运行install_service.bat，将服务注册为 Windows 系统服务，实现开机自动启动
3. 服务卸载：右键以管理员身份运行uninstall_service.bat
4. 停止服务：双击stop.bat或在 Windows 服务管理器中停止

7.4 配置文件说明（config.ini）

ini

[mysql]
host=127.0.0.1
port=33366
user=admin
password=admin
database=word_sign

[web]
host=0.0.0.0
port=5001
debug=false

[log]
level=INFO
file_path=./logs/

所有端口、账号、密码均可在此配置文件中修改，修改后重启服务生效。

---

八、API 接口规范

8.1 签章接口

• 接口地址：POST /api/word/sign
• Content-Type：application/json
• 请求体承载完整 .docx 码流，使用 Base64 文本字段表示；不使用 multipart/form-data 作为核心 API 合同。
• 仅支持 .docx。.doc、.wps、.pdf 等其他格式为类型错误，不进入签章处理。

请求参数：

参数名	类型	必选	说明
docx_name	string	是	原始或逻辑 Word 文件名，必须为 .docx，用于类型校验和返回文件命名
docx_base64	string	是	Base64 编码的 .docx 文件码流
match_mode	string	是	全局图片匹配模式：upload、id、name、auto，单次请求不支持混合模式
stamps	array	条件必选	盖章项列表，最多 100 项。upload/id/name 必填；auto 可省略或为空，表示扫描全部支持的 SET USER_<name> 标记
use_global_align	boolean	否	true 强制使用全局对齐；false 使用单项对齐，缺失或非法时回退全局对齐
align_h	string	否	全局横向对齐：left、center、right，默认 left
align_v	string	否	全局纵向对齐：top、center、bottom，默认 center
use_global_height	boolean	否	true 强制使用全局 height；false 使用单项 height
height	number	否	图片目标高度，单位厘米，保留 1 位小数，有效范围 0.1..10.0；有效高度缺失或非法时该项不调整高度并告警
use_global_noise	boolean	否	true 强制使用全局 noise_level；false 使用单项 noise_level
noise_level	int	否	噪声强度 0..10，默认 0；单项非法时用 0 并告警
use_global_rotate	boolean	否	true 强制使用全局旋转范围；false 使用单项旋转范围
rotate_min	int	否	旋转范围左端点，单位度，范围 -180..180，默认 0
rotate_max	int	否	旋转范围右端点，单位度，范围 -180..180，默认 0

盖章项规则：

1. 每个传入的 stamps 项通过 marker 指定 Word SET xxx 域代码中的 xxx。
2. upload 模式中，每项提供 image_filename 和 image_base64。
3. id 模式中，每项提供 image_id，对应 user_sign.user_id。
4. name 模式中，每项提供 image_name，对应 user_sign.user_name。
5. auto 模式中，真实 Word 域代码必须为 SET USER_<name>。服务去掉 USER_ 前缀，忽略尾部空白和 \* MERGEFORMAT 等 Word 固有开关，用 <name> 查询 user_sign.user_name。
6. auto 模式中，传入的图片 ID、图片名称、图片文件信息一律忽略。
7. auto 模式中，stamps 省略或为空时，服务扫描当前确认支持范围内的全部 SET USER_<name> 标记并自动处理，最多 100 个；stamps 非空时，只处理列表中指定的标记。
8. 每项可配置单项对齐、height、noise_level、rotate_min、rotate_max 和 is_signature。is_signature=true 时，图片解析后先做手写签字黑白二值化，再进入普通抠图、裁剪、缩放、噪声、旋转流程。

响应规则：

1. 成功时返回 HTTP 200，Content-Type=application/vnd.openxmlformats-officedocument.wordprocessingml.document，响应体为完整 .docx 二进制码流，不是 JSON，也不是 Base64。
2. 成功响应可能是全部完成、部分完成并带告警、或无变化文档。告警信息通过响应头、日志和 OA/API 监控页展示，不写入 JSON 成功体。
3. 成功返回文件名使用原始文件基名追加 _signed.docx；原始文件名缺失或非法时使用 signed_yyyyMMdd_HHmmss.docx。
4. 失败时返回非 2xx HTTP 状态，Content-Type=application/json; charset=utf-8，错误体至少包含 success=false、code、message、trace_id 和可选 data。
5. OA Action 适配器按 HTTP 状态码优先、Content-Type 次要校验来区分成功和失败：Word MIME 类型为成功文件流，JSON MIME 类型为错误提示。
6. 成功 .docx 在 OA 中写入由具体 Action 配置的附件/文档字段；SEAL API 不定义具体 OA 字段 ID。

---

九、非功能性需求

1. 性能要求：单文档处理耗时小于 5 秒；20 个并发请求无明显卡顿；确认输入规模为单个 Word .docx 文档不超过 1 MB，单张图片不超过 256 KB
2. 稳定性要求：连续运行 7×24 小时无内存泄漏、服务崩溃
3. 兼容性要求：兼容 Chrome、Edge、Firefox 主流现代浏览器，不兼容 IE 低版本
4. 安全性要求：所有文件上传/JSON 码流做格式校验，防止恶意文件上传；数据库连接密码采用简单混淆存储，不作为强加密
5. 日志要求：日志条数≤1000 条时滚动、检索、定位无卡顿；日志永久留存本地文件

---

十、验收标准

1. 系统可在 Windows 10/11 上绿色免安装运行，不依赖任何第三方网站服务
2. 配置文件修改后重启服务生效，所有端口、账号、密码可自定义
3. 可注册为 Windows 系统服务，实现开机自动启动
4. API测试页、OA/API 请求监控页、批量 Word 转换与自动签名页、数据库管理页功能完整，布局符合设计要求
5. 人员 ID / 姓名双匹配逻辑正确，图片缩放、噪点、旋转效果符合预期
6. 数据库增删改查、批量导入、图片双预览功能正常
7. 前端操作与外部 API 调用的全流程日志实时展示，自动闭环定位功能正常
8. 泛微 OA 系统可通过 API 接口成功调用服务，完成 Word 文档自动签章
9. 所有异常场景有明确提示，服务不崩溃，数据不丢失
10. 外部 API 使用 JSON 请求体承载 .docx Base64，成功返回原始 .docx 二进制，失败返回非 2xx JSON。
11. match_mode=auto 支持省略或传空 stamps 后自动扫描全部 SET USER_<name> 标记，仍受 100 个标记上限约束。
12. 缺失标记、缺失图片、名称重复、部分参数非法等可继续场景必须写 WARN 日志，并按要求返回无变化或部分完成 .docx。
13. 批量页面必须支持合并单元格、输出文件名冲突自动避让、锁定文件单文件失败后批量继续、规则文件损坏不自动覆盖。
14. OA Action 超时默认 30 秒且可配置；SEAL 失败、超时或未知响应不得映射为 Action 成功。

---

十一、已确认需求变更：批量 Word 转换与自动签名页面

本节为 2026-05-30 需求讨论后的正式确认内容。若本节与前文旧版页面、接口或验收描述冲突，以本节和当前会话需求账本为准。

11.1 页面目标

批量 Word 转换与自动签名页面用于在前端选择一个 Word 文件夹，递归处理其中的 .docx 文件，通过多条正则规则提取人员姓名，将原可见姓名替换为不可见的 Word SET USER_XXXX 域代码并补偿原字符宽度，然后按 match_mode=auto 自动从数据库匹配签名图片完成盖章/签名。

11.2 正式使用流程

1. 操作员先确认数据库 user_sign 中已经存在本次批量签名需要的人员图片记录，例如 张三、李四、王五。如果 user_name 存在多条记录，服务使用第一条记录并写入 WARN 日志。
2. 操作员打开批量页面后，系统自动加载默认 rules.config。如果用户选择了自定义规则文件，本次规则加载和保存都作用于该自定义文件。
3. 操作员选择 Word 根目录。系统递归扫描该目录和所有子目录，只允许 .docx 文件进入转换和签名流程，.doc 及其他格式跳过或报错，不进入签名处理。
4. 操作员配置或确认多条正则规则。每条规则至少包含规则名称/用途、正则表达式、启用状态和捕获组序号。捕获组序号禁止配置为 0，必须选择 >=1 的具体捕获组；推荐默认使用捕获组 1，例如从 编制：张三 中提取 张三，或从 审核：张sir1 中提取 张sir1。考虑到用户可能不熟悉 Unicode 和正则表达式，页面必须提供中文说明的常用正则提示/模板，用户选择后可插入到当前正在编辑的正则表达式中。常用正则提示必须包含表格匹配模板，用于横向相邻标签/值单元格、纵向相邻标签/值单元格、整格值匹配和部分值匹配。
5. 操作员可在页面输入或粘贴一段正则测试文本，并点击“测试正则”或通过规则编辑自动刷新测试结果。测试结果必须在不修改任何 Word 文件的前提下，显示正则语法错误、未匹配提示、完整匹配文本、配置捕获组提取到的 XXXX、生成的 USER_XXXX 标记、以及将生成的域代码/替换预览。
6. 运行前页面显示真实文件扫描后的匹配预览，包括文件、命中的规则、捕获到的 XXXX、生成的 USER_XXXX 标记以及将被替换的位置。匹配范围包括正文、普通表格、文本框、文本框内表格、页眉、页脚、标题/标题样式文本，以及页眉中嵌套文本框、文本框中再嵌套表格的结构。
7. 表格内正则规则除支持单元格内文本匹配外，还必须支持连续两个单元格的组合匹配：
   • 横向相邻两格：两个单元格在同一行，例如左侧单元格为 编制：、右侧单元格为 张三，规则应能从组合候选中提取 张三。
   • 纵向相邻两格：两个单元格在同一列，例如上方单元格为 审核：、下方单元格为 李四，规则应能从组合候选中提取 李四。
   • 第一版必须支持合并单元格。系统需基于 Word 表格逻辑网格处理横向合并和纵向合并单元格，普通表格和已确认的嵌套表格均需覆盖。
   • 每条规则支持“整格匹配”和“部分匹配”。整格匹配要求参与匹配的单元格文本整体满足规则；部分匹配允许只命中单元格内的一段文本。
   • 替换时只替换配置捕获组对应的原始可见文本，位置落回该捕获组所在的实际单元格；不得把相邻标签单元格误替换。
8. 操作员启动处理后，系统在原位置将捕获到的可见姓名替换为不可见的 Word 域代码 { SET USER_XXXX \* MERGEFORMAT }，并插入普通空格补偿原字符宽度。批量页面不提供域开关选择；\* MERGEFORMAT 固定作为 Word 通用格式开关。宽度优先按原文字运行上下文计算；无法精确计算时采用确定性的近似算法并写入 WARN 日志。
9. 转换后的文档使用 match_mode=auto 自动签名。服务从域代码中去掉 USER_ 前缀，用 XXXX 查询 user_sign.user_name，使用第一条匹配记录；缺失图片、图片损坏、重复姓名、签名失败等情况按文件写入日志。缺失或不可用图片为告警，保留该标记不变，其他标记继续处理，文件可作为部分完成结果返回/保存。
10. 每个处理后的文档自动保存回源文件所在目录，文件名在 .docx 前追加 _signed，例如 xx.docx 保存为 xx_signed.docx。原始文件不得被覆盖。若默认输出名已存在，自动生成 _signed_001、_signed_002 等不冲突文件名，不覆盖已有输出。
11. 如果源文件或输出文件被占用/锁定，只标记该文件失败或跳过并写入 WARN/ERROR 日志，批量任务继续处理其他文件。
12. 批量页面显示总进度和详细状态，包括已扫描、已转换、已签名、部分完成、已跳过、失败数量，当前文件、当前阶段、每个文件状态、生成标记数量、输出路径、告警数量和详细日志。处理期间日志需要及时刷新，便于操作员定位失败文件、缺失图片和重复姓名告警。
13. 处理完成后，操作员可在页面查看成功/部分完成/失败汇总、跳过文件、缺失数据库图片告警、重复姓名告警、锁定文件告警和输出文件列表。

11.3 验收要求

1. 批量页面能按确认流程完成：加载规则、选择递归文件夹、预览匹配和生成标记、转换姓名为隐藏 SET USER_XXXX 域代码并补偿宽度、自动签名、保存 _signed.docx、显示每个文件的进度/状态/日志。
2. 批量转换不得覆盖原始 .docx 文件。
3. 批量转换只处理 .docx，.doc 及其他格式必须明确跳过或提示类型错误。
4. 批量规则必须自动保存到默认 rules.config，启动时默认加载，并支持用户选择自定义规则文件。
5. 批量规则 UI 必须提供面向普通用户的正则辅助：用中文解释常用片段。常用/默认模板不能假定姓名全是中文，必须支持中文、英文字母、数字、点号、下划线和短横线组成的姓名或标识，例如 张sir1；推荐捕获片段为 ([\u4e00-\u9fa5A-Za-z0-9._-]{1,20})。同时可保留纯中文姓名 ([\u4e00-\u9fa5]{2,4}) 作为可选片段。完整模板至少包括 编制：姓名/标识、审核：姓名/标识、签字人：姓名/标识；用户选择后插入当前正则输入框，并立即刷新预览、校验正则和自动保存规则。
6. 批量规则 UI 必须提供正则测试和匹配结果预览：用户可输入测试文本，测试所有启用规则，并看到语法错误、未匹配提示、完整匹配、捕获组提取值、生成的 USER_XXXX 标记、以及域代码/替换预览。测试和预览不得修改任何 Word 文件。
7. 批量表格规则必须支持单元格内匹配、同一行横向连续两格匹配、同一列纵向连续两格匹配，并支持整格匹配与部分匹配两种粒度；相邻格匹配中只替换捕获组所在单元格的原可见文本。
8. 常用正则提示中必须提供表格匹配常用表达式，至少包括：
   • 横向相邻两格模板，例如 编制[:：]\s*([\u4e00-\u9fa5A-Za-z0-9._-]{1,20})，用于同一行标签单元格加值单元格组合匹配。
   • 纵向相邻两格模板，例如 审核[:：]\s*([\u4e00-\u9fa5A-Za-z0-9._-]{1,20})，用于同一列标签单元格加值单元格组合匹配。
   • 表格值整格模板 ^([\u4e00-\u9fa5A-Za-z0-9._-]{1,20})$，用于姓名/标识单独占据整个单元格的场景。
   • 表格值部分模板 ([\u4e00-\u9fa5A-Za-z0-9._-]{1,20})，用于姓名/标识只是单元格部分文本的场景。
   • 每个表格模板的中文说明必须提示应选择的表格方式（单段/单格、横向相邻两格、纵向相邻两格）以及匹配方式（整格匹配或部分匹配）。
9. 捕获组序号 0 必须被判定为非法配置；正则语法错误、无可用捕获组或捕获组越界时，UI 给出提示，运行时跳过该规则并告警，批量继续。
10. 多条规则命中重叠文本时，按配置顺序第一条启用规则优先，后续重叠命中跳过并写 WARN 日志。
11. 默认 rules.config 或自定义规则文件损坏、格式非法或不可读时，不得自动覆盖原文件；页面加载内置默认规则或空规则，并提示操作员修复或重新选择规则文件。
12. 批量输出文件名冲突时自动生成不冲突文件名；源文件、已有输出文件和其他文件不得被覆盖。
13. 第一版批量表格匹配必须支持合并单元格，包括普通表格和已确认嵌套表格中的横向/纵向合并结构。

11.4 已确认的批量异常处理

1. 捕获组序号 0 禁止使用；规则必须指定 >=1 的具体捕获组。
2. 当目标文件 <basename>_signed.docx 已存在时，系统自动生成新的不冲突文件名，例如 <basename>_signed_001.docx，不得覆盖已有文件。
3. 缺失数据库图片或数据库图片不可用时，写 WARN 日志，保留对应标记，返回/保存半成品文档，同时继续处理其他标记和其他文件。
4. 单个文件读写失败、源文件被占用或输出文件被锁定时，仅该文件失败或跳过，批量任务继续。
5. 规则文件损坏或非法时，不自动覆盖原文件；加载内置默认规则或空规则并提示操作员处理。

11.5 已确认的 Word SET 域格式

1. Word SET 域按 Office Word 语义用于设置书签/变量值，域代码主体采用 SET <bookmark> <text> 的结构；本系统将 USER_XXXX 作为自动签名标记名使用。
2. 批量页面生成的字段固定为 { SET USER_XXXX \* MERGEFORMAT }。其中 USER_XXXX 用于 auto 模式提取 XXXX 并查询 user_sign.user_name，\* MERGEFORMAT 是 Word 字段的通用格式开关，不参与姓名提取。
3. 批量页面不再提供“域开关”或同类可配置项；rules.config 也不保存域开关配置。

---

十二、已确认需求变更：API测试页面合并

本节为 2026-05-30 需求讨论后的正式确认内容。若本节与前文旧版“综合调试页面”“API 测试页面”描述冲突，以本节和当前会话需求账本为准。

12.1 页面结构变更

原“综合调试页面”和原“API 专用测试页面”合并为一个前端页面，合并后的页面名称为“API测试”。当前前端不再保留独立的“综合调试页面”导航项，也不再保留另一个独立的“API 专用测试页面”导航项。

合并后的前端页面为四类：

1. API测试
2. OA/API 请求监控页面
3. 批量 Word 转换与自动签名页面
4. 数据库管理页面

12.2 API测试页面功能范围

“API测试”页面必须保留原两个页面的全部功能和元素：

1. 保留原综合调试页面的手动签章/调试能力：
   • Word .docx 文档来源选择。
   • 签章图片来源和匹配模式选择，包括上传图片、数据库 ID、数据库名称、auto 自动匹配。
   • 多签章项配置，单次请求最多 100 个签章项。
   • 全局和单项的对齐、高度、噪声、旋转、is_signature 配置。
   • 业务规则提示、执行签章、清空表单、清空日志、结果下载/显示。
2. 保留原 API 测试页面的接口构建和联调能力：
   • 根据用户输入构建完整 /api/word/sign JSON 请求。
   • 显示完整请求 JSON 预览。
   • 支持发送测试请求。
   • 成功时显示 .docx 二进制返回结果的下载/保存信息。
   • 失败时显示 JSON 错误响应。
   • 提供 OA Action 兼容性示例，说明 OA Action 如何按 HTTP 状态码和 Content-Type 区分成功/失败。
3. 合并页面的日志能力：
   • 记录参数校验、请求构建、文档/图片编码、签章执行、响应解析、结果下载等全过程日志。
   • 日志展示遵循既有前端日志刷新规则。
   • 可定位的校验错误或执行错误应尽量跳转/高亮到对应输入项或结果区域。

12.3 验收要求

1. 前端导航只出现一个“API测试”页面承接原综合调试和原 API 测试功能。
2. “API测试”页面可以完成手动签章调试，也可以构建、预览、发送完整 API 请求。
3. 原综合调试页面的签章参数控件、原 API 测试页面的 JSON 构建/响应展示控件和日志控件不得因合并丢失。

---

十三、已确认需求变更：数据库图片 is_signature 字段

本节为 2026-05-30 需求讨论后的正式确认内容。若本节与前文数据库、预览或 API 匹配描述冲突，以本节和当前会话需求账本为准。

13.1 字段含义

user_sign 表增加字段 is_signature，类型建议为 TINYINT(1) 或等价布尔字段，默认值为 0/false。

1. is_signature=true：该数据库图片是手写签字图片。
2. is_signature=false：该数据库图片是普通签章/印章图片。
3. 该字段是数据库图片属性，不等同于 API 请求中每个盖章项的 is_signature 参数。

13.2 在线预览规则

数据库管理页面选中一条 user_sign 记录进行在线预览时：

1. 原图预览展示数据库中保存的原始图片。
2. 处理后预览根据该记录的 is_signature 决定是否执行黑白二值化：
   • true：先进行手写签字黑白二值化，使笔画更深，再进行后续普通预览处理。
   • false：不进行黑白二值化，按普通签章图片进行预览处理。

13.3 API 匹配规则

user_sign.is_signature 不参与 API 图片匹配或过滤：

1. match_mode=id 时，只按 user_sign.user_id 查询。
2. match_mode=name 和 match_mode=auto 时，只按 user_sign.user_name 查询。
3. API 请求 JSON 中盖章项的 is_signature 无论为 true 还是 false，都不得限制数据库查询范围。
4. 数据库记录自身的 is_signature 无论为 true 还是 false，都必须纳入正常的 ID/名称/auto 查询范围。

---

十四、已确认需求变更：批量正则相邻单元格匹配

本节为 2026-05-31 需求讨论后的正式确认内容。若本节与前文批量正则匹配范围描述冲突，以本节和当前会话需求账本为准。

14.1 适用范围

批量 Word 转换与自动签名页面的正则规则，除了原有正文、单段文本、单个表格单元格内匹配外，还必须支持表格中连续两个单元格的组合匹配。该能力适用于普通表格，以及已确认范围内的嵌套表格，例如文本框内表格、页眉文本框内表格。

14.2 相邻单元格方向

1. 横向相邻两格：两个候选单元格位于同一行，且在表格结构中连续相邻。例如单元格 A 为 编制：，同一行相邻单元格 B 为 张三，规则应能从 A+B 的组合候选中提取 张三。
2. 纵向相邻两格：两个候选单元格位于同一列，且在表格结构中连续相邻。例如上方单元格为 审核：，下方相邻单元格为 李四，规则应能从上下两个单元格组合候选中提取 李四。
3. 相邻单元格组合匹配必须保留可定位信息，知道捕获组文本来自哪个实际单元格。

14.3 整格匹配与部分匹配

每条表格匹配规则需要支持两种粒度：

1. 整格匹配：参与规则的单元格文本整体必须满足规则，适合“标签单元格 + 值单元格”结构固定的表格。
2. 部分匹配：允许正则只命中单元格文本中的一部分，适合单元格内还有说明文字、括号、编号或其他内容的场景。

14.4 替换与预览

1. 仍以配置捕获组提取 XXXX，生成 { SET USER_XXXX \* MERGEFORMAT }。
2. 替换只发生在捕获组对应原始可见文本所在的实际单元格中；例如 编制： 在左格、张三 在右格时，只替换右格中的 张三，不得替换左格标签。
3. 扫描预览、正则测试预览和日志需要展示命中的匹配方式：单元格内、横向相邻两格或纵向相邻两格，以及整格匹配或部分匹配。

14.5 合并单元格支持

1. 第一版必须支持 Word 合并单元格，不作为后续版本能力延后。
2. 系统需要基于 Word 表格逻辑网格识别横向合并和纵向合并结构，例如 gridSpan 和 vMerge 等 Word 表格语义。
3. 合并单元格支持范围包括普通表格，以及已确认的嵌套表格，例如文本框内表格、页眉文本框内表格。
4. 在合并单元格中进行横向或纵向相邻匹配时，仍必须定位到捕获组原始文本所在的实际单元格和字符范围。
5. 若个别异常合并结构无法唯一确定相邻关系，系统采用确定性处理方式并写入 WARN 日志；不得导致整个批量任务停止。

---

十五、已确认需求变更：API 响应与异常处理

本节为 2026-06-03 需求讨论后的正式确认内容。若本节与前文旧版接口、响应或异常描述冲突，以本节和当前会话需求账本为准。

15.1 成功与失败区分

1. 成功接口响应固定为 HTTP 200 + Word .docx MIME 类型 + 原始二进制 .docx 响应体。
2. 成功响应体不包含 JSON，不包含 Base64，也不包含过程元数据。
3. 成功可能是全部完成、部分完成并带告警，或合法无变化文档。告警信息通过响应头、日志和 OA/API 监控页展示。
4. 失败接口响应固定为非 2xx HTTP 状态 + JSON 错误体，接收端可按 HTTP 状态码和 Content-Type 明确区分。
5. OA Action 只有在成功保存返回 .docx 到具体 Action 配置的附件/文档字段后才返回 Action 成功；SEAL 错误、HTTP 失败、超时或未知响应均映射为 Action 失败。

15.2 告警但继续的场景

1. 指定标记未找到：写 WARN 日志，继续其他标记；若没有任何标记可处理，返回原始/无变化 .docx 作为成功响应并带告警。
2. 数据库图片缺失或不可用：写 WARN 日志，保留该标记不变，继续其他标记，返回部分完成 .docx。
3. 名称匹配多条记录：使用第一条记录，并写 WARN 日志。
4. 单项对齐、高度、噪声、旋转参数非法但已有明确回退规则时，按当前回退规则处理并写 WARN 日志。
5. 批量文件级异常，如单个文件被锁定、单个输出写入失败、单个规则非法，均不停止整个批量任务。

15.3 硬错误场景

1. .doc 或其他非 .docx 类型、.docx Base64 非法、文档损坏、文档加密/有密码、文档超过 1 MB，为请求/业务错误，返回非 2xx JSON。
2. 请求中 stamps 超过 100 项，或 auto 自动扫描发现超过 100 个支持标记，为校验错误，返回非 2xx JSON，不得截断处理。
3. 图片超过 256 KB、图片 Base64 结构非法、请求级图片字段不可解析，为校验错误，返回非 2xx JSON；单个数据库图片不可用则按告警但继续处理。
4. 需要数据库的模式下 MySQL 未启动或连接失败，返回 5xx JSON 服务错误，并在监控页显示失败阶段。
5. OA Action 调用 SEAL 的默认 HTTP 超时时间为 30 秒，可配置；超时映射为 OA Action 失败并写 WARN/ERROR 日志。

15.4 Ecology 集成后续

1. 具体 Ecology Java Action 成功/失败常量或配置在集成测试阶段根据客户环境确认。
2. 集成测试可以调整 Action 侧提示文案和失败常量，但不得改变“SEAL 失败/超时/未知响应不能映射为 Action 成功”的原则。