uni-answer-sheet 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 更新记录
+
+## 2.2.0
+
+- 所有版式固定一张纸，只在纸内换栏。超过容量的内容保留在草稿中，纸面和题块列表显示提示，可打开完整内容窗口继续编辑。
+- 超限时 `save()` / `validate()` 返回 `CONTENT_OVERFLOW`，`getRecognitionData()` 拒绝导出不完整坐标。删减后自动回排，全部容纳后恢复保存。
+- 支持载入原先多纸面的草稿，保留题目和富文本；须调整到一张纸内再保存。
+- 公共挂载 API、文档版本与富文本插件协议保持兼容，继续配合宿主显式安装的 `uni-editor@0.2.1` 使用。
+
+## 2.1.0
+
+- 新增 `getRecognitionData()`，`save()` 成功数据新增 `recognitionData`；等待字体、图片及分页稳定后测量。
+- 使用坐标协议版本 2：`origin: 'topLeftPaper'`、96 dpi 像素，每张物理纸面左上角为原点。四角定位点、父区域、作答线和单元格均使用纸面全局坐标；跨页片段保留题目关联。
+- 导出考号、班级、缺考标记、选项、填空、主观作答、评分框、选做题、禁答区、页码、学科、二维码及辅助定位点，校验越界和标记重叠。
+- 补齐作业卡班级／学号卷头、无分值批阅框、禁止答题区与空白答题区，并支持保存和回显。
+- 回显忽略传入的坐标缓存，按当前内容重新计算；题卡文档版本保持 1，挂载 API 和富文本插件协议保持兼容。
+- 建议配合 `uni-editor@0.2.1` 使用；保留对 `0.2.0` 题干字母框坐标的兼容。两个包由宿主分别安装。
+
+坐标输出采用本包的扁平结构；参考项目旧版 `cutparamJsonstr2` 协议映射、扫描图像校正及识别服务不包含在本包中。PDF 服务和演示按钮也不进入 npm 包。

package/README.md

@@ -4,22 +4,22 @@
 
 `2.0.0` 使用全新的 DOM 插件 API，与原 `1.x` Vue 组件版接口不兼容。升级时请按本文重新挂载和注册富文本插件，旧版数据需转换为本文说明的文档格式。
 
+`2.2.0` 将所有版式固定为一张物理纸面，新增超出内容的完整编辑窗口，并在保存及坐标导出时校验容量。升级后，原先多纸面的数据可作为草稿回显，但必须调整到一张纸内才能保存。挂载 API、文档版本和插件协议保持兼容。详见 [更新记录](./CHANGELOG.md)。
+
 ## 安装与依赖
 
 ```sh
-npm install uni-answer-sheet
+npm install uni-answer-sheet@^2.2.0
 # 富文本由业务方单独安装，不会随制卡包自动安装。
-npm install uni-editor@^0.2.0
+npm install uni-editor@^0.2.1
 ```
 
 `uni-answer-sheet` 不依赖、不打包、不自动下载 `uni-editor`，也没有自动安装编辑器的 peer dependency。`uni-editor/plugin` 从 **0.2.0** 提供，旧版 0.1.0 没有此入口。两个包各自包含内部所需运行时。
 
-本地验证未发布的版本时，可以分别安装构建生成的 `.tgz` 文件。
-
-如果 npm 尚未提供配套的 `uni-editor@0.2.0`，需先手动安装该版本的本地包；`uni-editor@0.1.0` 无法作为制卡编辑器插件使用：
+本地验证未发布的版本时，从仓库根目录分别安装构建生成的 `.tgz` 文件：
 
 ```sh
-npm install ./uni-editor-0.2.0.tgz
+npm install ./artifacts/uni-answer-sheet-2.2.0.tgz ./artifacts/uni-editor-0.2.1.tgz
 ```
 
 ## 原生 JavaScript / TypeScript
@@ -162,7 +162,7 @@ await sheet.initialize({
 | `choiceType` | `choiceDirection` | `false` 横排 / `row`，`true` 竖排 / `column` |
 | `mixOb` | `mergeObjective` | 客观题合并 |
 
-别名仅用于初始化输入，保存仍使用当前文档字段；同时传两种字段时必须一致。卷头的 `focusText`、`writeKaohao`、`missExam`、`mifeng`、`kaohao`、`weishu` 已与参考项目同名，放在 `header`。参考项目 `answerInfo.courseCode` 是二维码显示开关，和这里的课程编码不是同一字段；当前不接收该二维码开关，也不接收整个 `pageinfoJsonstr` 作为初始化配置。
+别名仅用于初始化输入，保存仍使用当前文档字段；同时传两种字段时必须一致。卷头的 `focusText`、`writeKaohao`、`missExam`、`mifeng`、`kaohao`、`weishu` 已与参考项目同名，放在 `header`。参考项目 `answerInfo.courseCode` 是二维码显示开关，对应这里的 `recognition.examQrCode`，和课程编码 `courseCode` 分开。当前不接收整个 `pageinfoJsonstr` 作为初始化配置。
 
 ## 保存与完整性
 
@@ -182,7 +182,7 @@ interface ValidationIssue {
 }
 ```
 
-成功数据包含原始 `CardDocument`（`version: 1`、创建信息、卷头、题块、富文本、题型配置）以及参考项目格式的 `sectionInfoList`、`quesTextMap`。稳定题目 ID 与展示题号分别保留。完整数据可直接通过 `initialValue` 或 `load()` 回读；导出的对象是独立副本，外部修改不会影响当前题卡。
+成功数据包含原始 `CardDocument`（`version: 1`、创建信息、卷头、题块、富文本、题型配置）、参考项目格式的 `sectionInfoList`、`quesTextMap`，以及当前排版的 `recognitionData`。稳定题目 ID 与展示题号分别保留。完整数据可直接通过 `initialValue` 或 `load()` 回读；导出的对象是独立副本，外部修改不会影响当前题卡。
 
 校验包括：
 
@@ -191,12 +191,95 @@ interface ValidationIssue {
 - 少选得分、选做数量、断句评分、作文格数/行数等题型约束。
 - 富文本结构、空公式、图片地址和可见图片加载失败。
 - 题卡合一的题干、材料、选项内容，以及所选填涂位置的对应关系。普通答题卡不要求填写题干，也不要求提供正确答案。
-- 纸面标题、不可拆分内容的纵向溢出，以及未分片编辑区域的横向溢出。
+- 纸面标题、单张纸容量、不可拆分内容的纵向溢出，以及未分片编辑区域的横向溢出。
+- 定位点及识别区域是否在纸面内、标记是否重叠、二维码 ID 和学科识别编码是否有效。
 
 无法在 8 秒内完成输入/上传或稳定测量时返回 `EDITOR_BUSY` / `LAYOUT_PENDING`；容器隐藏或未设置有效尺寸时返回 `LAYOUT_UNAVAILABLE`，不会跳过布局校验。校验是当前数据和实际渲染的完整性检查，不判断学科内容或答案是否正确。外部图片/字体稍后失效仍需业务方管理。
 
 结构非法的数据在加载前抛出 `AnswerSheetDataError`，其 `issues` 提供字段位置；缺少题干、分值等可编辑草稿允许加载，但不能通过保存校验。实例未就绪/已销毁属于调用错误，会抛异常。
 
+## 定位标记与识别坐标
+
+新建后的纸面自动显示四角定位点，上方 26×13 px、下方 13×26 px。从 `2.2.0` 起，所有版式固定 **1 个物理纸面**，两栏和三栏都在同一张纸内换栏。学科标记沿用参考项目 15 个标准学科的四方格映射。二维码编码内容为 `creation.exampaperId` 本身。
+
+A3 双栏、三栏仍有 2、3 个栏页码，均属于同一张纸；保存成功时 `recognitionData.pages.length === 1`。
+
+### 单张纸容量
+
+内容超限时不新增纸面。纸面仅显示能排下的部分，边界和题块列表显示“未排入纸张”提示；点击“查看完整内容”打开可拖拽窗口，查看、编辑完整草稿。窗口标出未排入的内容，修改后实时重排。单独答题卡的题干及合并填涂区使用不同打印投影时，提示整个受影响题块，避免标注错误的正文截断位置。
+
+`getDocument()` 和 `onChange` 始终保留完整草稿，包括未排入的内容。`save()` / `validate()` 返回带 `blockId` 的 `CONTENT_OVERFLOW`，不提供可保存数据；`getRecognitionData()` 抛出 `AnswerSheetDataError`。完整内容窗口不参与纸面坐标测量。所有内容排入纸张后恢复保存及 PDF 导出。旧版多纸面文档可作为草稿回显，但同样必须调整到一张纸内才能保存。
+
+```ts
+await sheet.initialize({
+  name: '期中考试', gradeCode: 'S01', courseCode: 'MATHS',
+  exampaperId: 'paper-123',
+  recognition: {
+    examQrCode: true,     // 默认 false
+    subjectMarkers: true, // 默认 true；自定义学科无标准编码时可关闭
+    pointBlack: false    // 参考项目考号区的辅助识别点，默认 false
+  }
+});
+const saved = await sheet.save();
+if (saved.ok) {
+  const coordinates = saved.data.recognitionData;
+  // 或单独获取：await sheet.getRecognitionData()
+  // 同样等待排版并校验，不通过时抛出 AnswerSheetDataError。
+}
+```
+
+坐标结构：
+
+- `version: 2`、`unit: 'px'`、`dpi: 96`、`origin: 'topLeftPaper'`。这是坐标协议版本，题卡文档的 `version: 1` 不变。
+- `pages[]` 每项对应一个物理纸面，`pageNumber` 从 1 开始；A3 的两栏／三栏属于同一项。
+- 每面包含 `pageSize`、`anchorOrigin`、`anchorSize`、`panelSize`、四个 `anchors` 和 `regions[]`。`anchorOrigin` 仅记录左上定位点在纸面上的位置，与 `anchors.topLeft.x/y` 一致；它不再充当坐标原点。
+- **所有区域、单元格及四个定位点都使用所在物理纸面左上角 `(0, 0)` 的全局坐标**，向右为 X 正方向、向下为 Y 正方向。`rect: { x, y, width, height }` 已包含纸面边距和栏位置，可直接使用，不需要累加定位点或父区域偏移。
+- 每张物理纸面独立从 `(0, 0)` 开始；不包含视口缩放、滚动、上一张纸的高度或纸张之间的展示间距。密封线条码、顶部二维码仍在纸张内，坐标无需使用负值。
+- 区域通过 `blockId`、`questionId`、`partId`、`answerId`、`optionId` 关联源数据；`role` 区分 `region`、`cell`、`line`。跨栏区域分开记录并保留相同题目 ID，选做共享区域另有 `questionIds`。
+- `sectionType` 包括 `ClassId`、`StudentId`、`IgnoreFlag`、`MultiChoice`、`Checkbox`、`FrameOnly`、`ScoreBox`、`QuestionChoice`、`Blank`、`PageCode`、`SubjectCode`、`ExamQrCode`、`ReferencePoint`。填涂区域包含实际单元格坐标，不依赖等宽假设。
+
+读取单元格示例：
+
+```js
+const coordinates = await sheet.getRecognitionData();
+const paper = coordinates.pages.find(page => page.pageNumber === 2);
+const option = paper?.regions.find(region => region.optionId === 'option-A');
+if (option) {
+  // 直接取第二张物理纸面上的位置，parentId 只表示归属。
+  // drawBoxOnPaper 代表宿主自己的绘制方法。
+  const { x, y, width, height } = option.rect;
+  drawBoxOnPaper(2, x, y, width, height);
+}
+```
+
+这是扁平的制卡坐标协议，不是旧版 `cutparamJsonstr2` 的嵌套结构。回显时忽略传入的 `recognitionData`（包括旧 `version: 1 / topLeftAnchor` 数据），保存时按当前字体、内容和版式重算并返回版本2。独立答题卡临时“编辑题目”时，保存会结束临时编辑并测量正式纸面。
+
+换算毫米时，矩形各数值乘 `25.4 / 96`；换算以左上角为原点的 PDF 点坐标时乘 `72 / 96`。若 PDF 库以左下角为原点，矩形下边缘的 Y 应使用 `(paper.pageSize.height - y - height) * 72 / 96`。定位点同样保存全局坐标，供扫描端做图像配准。最终 PDF 识别应使用 **PDF 渲染浏览器重新测量的坐标**。
+
+## 作业卡卷头与无分值批阅
+
+```js
+await sheet.initialize({
+  name: '数学作业', gradeCode: 'J01', courseCode: 'MATHS',
+  layout: { usage: 'homework', preset: 'a3-two', scanMarking: false },
+  header: { tiaomaStyle: 1, classText: true }
+});
+```
+
+`layout.usage` 为 `exam`（默认）或 `homework`，独立于新建入口的 `mode`。界面可在“页面布局 → 题卡用途”切换。作业卷头的 `tiaomaStyle` 沿用参考字段：`1` 为班级／两位学号填涂，`2` 为条码；`classText` 默认 `true`，控制班级填涂区。考试的考号位数、密封线等配置保留，切回考试时恢复。
+
+作业题配置可勾选“无分值”，保存为 `score: 0`、`itemScores: [0, ...]`；`null` 仍表示未配置，保存校验不通过。手阅无分值题使用参考项目的半对／错批阅框，多小题共用答题外框并显示 `(1)`、`(2)` 等批阅框。网阅隐藏手阅批阅框。跨页／跨栏时，仅首段保留批阅框，续段为 `FrameOnly`。
+
+坐标新增 `ClassId`；班级和两位学号各包含 20 个 `cell`，`value` 如 `1:9` 表示十位的数字 9，`2:0` 表示个位的数字 0，显示顺序为 9→0。选择题和填空题完整分区外框使用 `scope: 'section'`，内部题目区域、作答线和填涂格通过 `parentId` 建立层级；**所有层级的矩形都使用同一纸面全局坐标，父子关系不影响坐标值**。
+
+断句题的题干字母框与普通选择题一样按 `optionId` 导出；没有选项正文的断句题不提供“各选项前空方框”设置。制卡适配层兼容 `uni-editor@0.2.0` 的题干字母框坐标，`uni-editor@0.2.1` 在 `getAnswerRegions()` 中直接提供这些区域，并修复固定行高的累计排版偏移。
+
+## 禁答区与空白答题区
+
+“添加题块”弹窗的纸面区域入口，普通答题卡显示“禁止答题区”，题卡合一显示“空白答题区”。区域可编辑文字、拖动调整高度、复制、删除和调整顺序。源数据存为 `kind: 'area'`、`areaType: 'forbiden' | 'editArea'`、`answerHeight`、`document`，保留参考项目 `forbiden` 的拼写。
+
+默认禁答区高 100 px，空白答题区高 200 px。禁答区与参考项目一致，不能拆分，高度不超过一栏，剩余空间不足时整块换栏；空白答题区可连续跨栏，超出单张纸的部分保留在草稿中。它们不属于题目，不进入 `sectionInfoList`，需用完整保存数据回显。切换题卡合一时，与参考项目一样删除不适用的纸面区域。仅含纸面区域的卡不能作为完整试卷保存。
+
 ## 回显已保存的题卡
 
 将之前 `save()` 成功返回的 **`result.data` 整体保存**，回显时传给 `load(data): Promise<void>`。JSON 字符串先 `JSON.parse()`，不要传 `{ ok, data }` 外层结果，也不要只传 `sectionInfoList`。

package/REFERENCE_ASSETS.md

@@ -0,0 +1,7 @@
+# Reference project assets
+
+The homework marking glyphs in `src/card/reference/HomeworkMarking.tsx` use the exact outlines of the reference project's iconfont characters U+E6CF (`piyue-banduicuo`) and U+E6D1 (`piyue-cuo`).
+
+Source: `web-user/src/style/global.scss`, iconfont project 1458451, font file `font_1458451_5u779h2hy9n.ttf` (the reference project's configured asset). They are embedded as local SVG paths; no runtime request to the font service is made.
+
+These are reference-project assets, not glyphs supplied under a bundled npm dependency's license.

package/THIRD_PARTY_NOTICES.md

@@ -1255,6 +1255,12 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+## qrcode-generator@2.0.4
+
+License: MIT
+
+
+
 ## react-dom@19.1.1
 
 License: MIT
@@ -1519,3 +1525,12 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+# Reference project assets
+
+The homework marking glyphs in `src/card/reference/HomeworkMarking.tsx` use the exact outlines of the reference project's iconfont characters U+E6CF (`piyue-banduicuo`) and U+E6D1 (`piyue-cuo`).
+
+Source: `web-user/src/style/global.scss`, iconfont project 1458451, font file `font_1458451_5u779h2hy9n.ttf` (the reference project's configured asset). They are embedded as local SVG paths; no runtime request to the font service is made.
+
+These are reference-project assets, not glyphs supplied under a bundled npm dependency's license.