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 成功”的原则。