这是一篇软工课程作业博客

项目

内容

这个作业属于哪个课程

北航2020春软件工程 006班（罗杰、任健 周五）

这个作业的要求在哪里

个人博客作业-软件案例分析

个人课程目标

系统地学习软件工程理论知识与实践方案

这个作业在哪个具体方面帮助我实现目标

学习如何分析一款软件的功能需求与用户群像

在上一篇博客中我简单介绍了OCR Form Tools及其本地部署，这篇博客则将进一步评测整个软件。

本工具的数据存储基于Azure存储服务，下文使用的均为开发老师提供的测试仓库，内含5份训练用表单pdf文件。同时本地有一份相同格式的表单pdf文件，作为测试数据用。

创建项目

运行后看到初始界面。

可以看到整体界面设计走的是微软在10年后一贯的扁平风，dark theme的配色让人一下子联想起其王牌产品vs和vsc。点击New Project尝试新建一个表单识别项目：

这个表单的各种verify都是齐全的，placeholder和键入提示也非常清晰。

注意到这里需要添加一个新的Connection才能与Azure存储服务建立关联。界面中很贴心地提供了“Add Connection”按钮，也可以直接点击界面左侧的小插销图标进入Connection管理页面并完成添加。

完毕后回到刚才的新建项目表单。继续完成其余的信息填写并创建新的表单识别项目

进入编辑器，看到待标注的pdf预览页面。

添加tags

为了训练识别模型，我们需要把待标注的表单中，我们感兴趣的信息（如姓名、地址、电邮）标注出来，作为不同的特征以备模型使用。为了区分这些信息，我们要将其标上不同的tag

首先添加名为Name的tag并将它的类型设为string

点选pdf文档中的名字字段John Singer，看到选框变色后按下提示的标注键“1”，看到名字被红框框选并出现在右侧Name tag下，标注成功。

依次添加Email、Zipcode、ExpDate、Amount几个tag，并为其指定string、integer、date、number类型，来测试不同类型tags的标注；在全部五份pdf上完成上述tags的标注

可以看到已标注的文件会有一个小图标标记。

标注用的pdf阅读器支持滚轮缩放与拖拽移动，由于做了ocr预处理所以文本点选十分便利，按提示键入数字标注，键入delete删除，键鼠配合下可以迅速完成标注。五份文件的五种tags标注我在十分钟内全部完成，效率相当高。

模型训练

标注完成后点击左侧train按钮进入训练页面

点击右侧的train训练一个新模型，完成后返回了模型信息和各tag的预测准确率

模型测试

训练得到模型后点选左侧predict页面，尝试使用刚刚训练的模型预测一份新的pdf。Browse选择文件后在左侧预览，然后点击predict开始预测

完成后返回结果和置信度

可以看到各个tags都被正确框选了。由于这个pdf并没有出现在训练集里，因此说明模型训练很成功。注意到还可以下载json格式的预测结果(原文太长，这里截取其中一段)：

"fields":{"Email":{"type":"string","valueString":"jaimeg@outlook.com","text":"jaimeg@outlook.com","page":1,"boundingBox":[2.045,6.0200000000000005,3.345,6.0200000000000005,3.345,6.15,2.045,6.15],"confidence":0.99,"elements":["#/analyzeResult/readResults/0/lines/25/words/0"],"fieldName":"Email","displayOrder":1},"Zipcode":{"type":"integer","valueInteger":5001,"text":"05001","page":1,"boundingBox":[7.2250000000000005,6.55,7.58,6.55,7.58,6.655,7.2250000000000005,6.655],"confidence":0.999,"elements":["#/analyzeResult/readResults/0/lines/33/words/0"],"fieldName":"Zipcode","displayOrder":2},"Amount":{"type":"number","text":"45.00","page":1,"boundingBox":[6.54,7.84,6.875,7.84,6.875,7.95,6.54,7.95],"confidence":1,"elements":["#/analyzeResult/readResults/0/lines/42/words/0"],"fieldName":"Amount","displayOrder":4},"ExpDate":{"type":"date","text":"10 / 21","page":1,"boundingBox":[4.49,7.88,4.92,7.88,4.92,8.01,4.49,8.01],"confidence":1,"elements":["#/analyzeResult/readResults/0/lines/38/words/0","#/analyzeResult/readResults/0/lines/39/words/0","#/analyzeResult/readResults/0/lines/40/words/0"],"fieldName":"ExpDate","displayOrder":3},"Name":{"type":"string","valueString":"Jaime Gonzales","text":"Jaime Gonzales","page":1,"boundingBox":[2.365,5.74,3.35,5.74,3.35,5.845,2.365,5.845],"confidence":0.97,"elements":["#/analyzeResult/readResults/0/lines/15/words/0","#/analyzeResult/readResults/0/lines/15/words/1"],"fieldName":"Name","displayOrder":0}}}],"errors":[]}}

自此这个项目的主体功能被我们串通了：首先将pdf训练集上传到azure storage blob，连接并创建项目后借助该工具对其进行标注，然后训练模型，即可得到一个识别该格式表单的模型。此后，将需要识别的新表单输入训练好的模型，即可导出格式化后的表单数据。

个人体验

总的来说我很喜欢这个工具，我认为它可以大幅改进目前表单处理需要大量人力的境况。具体来说，我认为优点有：

1. 借助ocr预标注实现的快速字段选择，及基于快捷键的操作，这样的设计十分用户友好，标注效率相当高
2. 一站式模型训练，标注好的数据立即移交模型，训练后立即使用，节省了大量繁琐的api调用，隐藏了机器学习训练-推断工作流的大量细节，即使没有相关技术背景的人员也可以轻松上手使用
3. 基于react spa，以web应用的形式提供，免去安装部署等步骤，开袋即食
4. 对于后端模型配置只需要提供其base url，这使得工具可以轻松接入任何使用相同api接口的模型后端，有较强的可扩展性
5. 清爽的界面

虽然整个工具体验过程很顺滑，但个人认为依旧存在一些小问题：

1. 标注界面的功能提示过于隐晦，对于新用户不易理解新建tags上的数字图标代表对应标注按键；也没有提示使用delete键删除已框选字段
2. 虽然提供了tag类型，但是不点开tags设置菜单是不能看到tag类型的，因此对tag类型设置的审阅比较麻烦，当tag较多时容易产生设置疏漏。一般来说模型对不同的特征类型会选用不同的预编码处理，因此错误的tag类型可能会导致模型采用次优或错误的特征编码方式，影响模型精度。（这里建议，在标注界面和下方这个训练结果表格上都加注tag类别）
3. 现在的模型只支持Azure存储服务，对于已经有自己的表单存储解决方案的用户稍显不友好
4. 模型预测不能批量上传、批量推断
5. 下载的json格式包含大量用户不感兴趣的原始数据（如检测框位置等）；没有提供excel等格式的结果导出，使得非专业人员难以将该工具直接整合入工作流。

由于课程作业要求寻找软件Bug，我在不同运行环境与浏览器下对软件进行了黑箱测试，发现如下问题：

首先在Docker Toolbox虚拟环境下以docker运行时，连接远程仓库会失败。报错信息难以被用户理解，因此这应该是开发者意料之外的未处理异常：

由于官方提供的docker镜像已为release版构建，没有提供足够的调试信息，同时考虑windows下模拟Docker Toolbox的网络环境进行复现较为复杂，因此这里没有进一步尝试定位错误原因，仅作出错误报告。

另一个问题有关标注。在标注测试文件中的小数数据时，会发生一次点击后单条数据被重复标注的情况：

上图分别为点选测试文件CCAuth-1.pdf和CCAuth-2.pdf中amount字段并标注的结果，可以发现小数都被错误地选择了两次。分析原因可能是因为pdf文档中处理小数元素分了父子两级，而两级都被ocr单独识别为一个词块，而两者的碰撞框重合了，因此发生复选。针对这个问题，或许可以考虑，当所选两个词块的范围出现重合或包含时，进行一些判断与处理。

需要指出，这些都不是多么严重的问题——前者是在极端运行环境下才会出现的偶发错误，相对软件的目标群体及使用场景而言完全在可接受范围内；后者则是标注时的一些小概率出现的功能缺陷，也没有显著降低使用体验。

实际上，必须承认这款工具的软件质量是很高的。我在Chrome、Firefox、Edge等多款主流浏览器上进行了大量黑箱测试，均没有发现明显的功能或显示错误。

在完整运行一遍后，我对这个项目的功能已经有了大致认识。我的理解是，这是一个为后端表单识别算法设计的表单标注工具，提供了非常高效易用的格式化表单文件标注功能，借助其可以快速构建训练集；同时其也简化了后续工作，可以立即训练、使用给定训练集上训练的识别模型。

我认为这个工具解决的痛点有：

1. 表单数据难以标注的问题。正常来讲，学习算法关注的数据大多包括：目标字段在文档中的位置、目标字段的真实值、目标字段的数据类型。由于大多数文档格式（pdf、docx等）以xml或类xml的形式组织文档，同时还有大量的纯图像格式表单需要处理，字段在文档中的位置（一般是角点坐标）难以以符合直觉的方式给出，因此标注一个特征往往需要基于各种图形工具测量文本元素坐标，并手动键入其真实值后才能完成——这是十分麻烦的工作，因此人力成本很高。而正如前文分析，这个标注工具很好地简化了这个过程。

我理解目前这个项目暂定的用户群体是：

1. 微软OCR-Form的用户。这个工具正如README描述，是一系列表单工具中打头阵的一个，它旨在（并确实可以）大幅优化OCR-Form的使用体验。借助该工具可以快速标注数据、训练模型、验证模型

同时我认为这个工具有潜力解决的痛点为：

1. 非技术人员难以学习使用机器学习模型处理表单数据的问题。考虑人力、财务等部门，每天有大量的纸质简历、报表需要被数字化处理以方便统计，这个过程是十分繁琐的简单重复劳动——而表单识别模型正是可以解放这些生产力的利器。然而这些报表格式经常变化，对应的识别模型也相应需要重新训练——但人力、财务等部门的职员往往不具备调取api训练模型所需的专业技能，因而这个愿景很难实现。这款工具将整个工作流浓缩简化，隐藏了算法、api调用等技术细节，使得新技术也有望为这些人员赋能。

因此，我认为这个项目未来的潜在用户是：

1. 上文提到的这些非技术从业人员。企业中有大量的报表工作，这个前端项目可以继续发展为（或衍生出）更实用的工具，为他们提供非常强劲的业务武器，解决企业中实际存在的迫切痛点。

为了迎合潜在用户，我认为这个工具还需要完成的功能包括：

1. 上文提到的批量推断、excel下载等功能。我认为一个基于其的理想工作流是，用户上传并标注某种格式的报表，完成模型训练，然后上传大量未经处理的报表数据，批量推断后可以下载一张已经滤去多余信息的excel汇总表格：表格每行对应一个报表文件，每一列对应一个tag（或报表文件名等基本信息）
2. 进一步打磨界面，完善使用提示与内嵌帮助，进一步降低使用门槛

Q: 使用此服务的所有功能，估计这个软件/网站/服务做到这个程度大约需要多少时间(团队人数6人左右，计算机大学毕业生，并有专业UI支持)。（必答）

这个项目是一个前端项目，基于react开发。我们合理假设，6人学生团队中，至少2人熟练掌握vuejs或reactjs前端开发，剩余四人的专业水平与代码能力满足毕业要求，因此这个团队不需要过多的学习开销，开箱即食。整体规划采用双线开发模式：

1. 起步工作，包括梳理需求并初步制定okr、部署生产与测试环境、CI/CD配置、基础组件搭建、以及补充学习相关技术，这个工作一般一周内就能完成
2. 【feat1】pdf reader开发，这是表单识别工具的核心功能，因此需要首先开始迭代，方便之后根据实际开发进度调整开发计划。pdf读取与显示本身是非常难以开发的，幸好如今前端生态趋于完善，可以借助第三方包来实现相关功能。查阅package.json可以看到，OCR Form Tools基于pdfjs实现相关功能。考虑到文档查阅、调整布局等开销，pdf预览工作可以由一到三个人在一个sprint内初步完成。
3. 【feat2】pdf editor开发，这是pdf reader的后继项目，需要在读取pdf后调取ocr接口对pdf做预识别，再提供基本的点选工具，响应键盘事件，实现识别-点选-标记的逻辑。需要考虑接入ocr时的学习成本和一些意料外的适配工作，保守估计这项任务也需要一整个sprint完成。
4. 【feat3】数据管理模型，借助redux（或vuex）实现，给出connection、secure key、project、file、tag、model等数据模型的curd，个人经验来看这项工作涉及的内容比较琐碎但对后续开发尤为重要，需要较多测试与回归，因此需要一到三个人在2个sprint内完成，第一个sprint主要关注代码实现，第二个sprint则侧重问题修复与更详细的验证测试
5. 【feat4】tag创建与设定，为pdf editor提供复数tag、多种类tag的支持；【feat5】接入模型训练后端，将标注好的数据送交模型训练并拿到返回结果。【feat4】和【feat5】一共需要一个sprint，参与人数3人左右
6. 【feat6】异常捕获与处理。需要可以在出现各类错误时捕获并以模态框的形式输出，告知用户错误信息。主要难点在于为axios编写中间件捕获并处理各种http错误。这部分工作可以为【feat5】提供更高效的调试工具，配合react或vue的debug模式可以方便地调试http错误及各种promise带来的隐晦错误。这个工作需要一个sprint，且应该配合【feat5】的开发进度优先提供对开发有帮助的异常处理。
7. 【feat7】模型推断，上传本地文件并调用训练好的模型预测并在pdf reader中展示结果。这个工作在一个sprint内完成，对于【feat5】没有完成的工作可以视情况在这个sprint内完善
8. 【feat8】完善各表单页面。包括新建/编辑connection、新建/编辑project、创建secure key等表单，添加提示、placeholder，并添加必要的前端类型检查与报错提示（如某些字段不能为空、sas uri字段必须符合uri格式，等）。这项工作较为琐碎，预留一个sprint
9. 【feat9】补全各页面间跳转逻辑与数据组织关系，串通创建-预览-标注-训练-测试-结果汇总的整体功能流程。这个工作设计项目各组件细节，需要整个团队合作完成，占用一个sprint。这项工作完成后基本功能定型，可以释出alpha版
10. 【feat10】优化UI，包括配色、图标、字体、页面布局精调、浏览器适配、移动端适配等工作。一到两个sprint的迭代后预期调整出用户体验良好、界面美观的应用，同时修复alpha中发现的问题，可以释出beta版。
11. 充分测试并迭代完善后，可以在beta版的基础上得到最终release版并发布。

可以看到，开发采用自底向上的顺序，前4个sprint中预期完成8个feature的实现，分为两组：

分组

sprint1

sprint2

sprint3

sprint 4

第一组：核心功能线

【feat1】

【feat2】

【feat4】【feat5】

（【feat5】）【feat7】

第二组：基础设施线

【feat3】

【feat3】

【feat6】

【feat8】

后两个sprint需要团队整体协作完成各组件间的衔接并释出测试版本、迭代直至产品正式发布。

照这样组织来计算，这个团队开发需要大概12周的时间，其中到第10周的时候应该已经完成大部分开发工作，只剩细节润饰。

分析这个软件目前的优劣(和类似软件相比)，这个产品的质量在同类产品中估计名列第几？（必答）

实际上这个软件在我看来十分新颖，我暂时没有接触使用过类似软件，因此还在进一步调研，如果想法更新将在这里修改。

需要再次强调的是，这个软件本身的质量很高，有理由相信即使存在同类软件，也难以覆盖该项目带来的完整用户体验

从各方面的问题，推理出这个软件团队在软件工程方面可以提高的一个重要方面(具体建议)。

参考上文对潜在客户的分析。我认为这个项目还有进一步演化并解决痛点需求的巨大空间。

另一方面，我未在这个项目下找到单元测试与e2e测试的相关代码，但是提供了完善的ci配置（参考其azure-pipelines.yml），因此我认为就保证后续迭代质量而言，一些基本的测试工作可以整合入ci

你在第一部分发现的bug，为何软件团队不能在发布前修复？他们是不知道，还是有意不修复？你觉得是什么原因？可以从下面的可能性中选取几个

对于Docker Toolbox下的问题，Docker Toolbox作为已经过时的windows下docker解决方案，市场占有率过于小，且并不属于前端开发时需要考虑的典型运行环境，因此很可能软件团队根本无意在此环境下测试并修复问题——这是合理的，否则将会引来额外开发成本但收效甚微。

对于小数标记重合的问题，由于e2e测试等自动化手段很难覆盖这种与输入软件的文件内容相关的问题，因此只能依靠手动测试的方式被发现——这种方式很难保证覆盖率，因而软件团队可能碰巧由于测试用文件均没有相关问题、人工检查未能覆盖等原因没有发现这个bug。即使已经发现bug，由于pdf预览等相关组件的开发依赖第三方库，不排除这个错误由第三方库引入——如果确实如此，修复这个bug将十分困难。因此我猜测，既有可能开发团队没有发现这个bug，也有可能开发团队发现了这个bug，但由于修复性价比太低从而暂时将其搁置。