面向开发者
这份设计文档记录架构和设计取舍,使用了较多内部术语。只想了解怎么使用软件,请看使用指南。
tidoc — 设计文档(DESIGN)
报账凭证管理与整理工具。Mac / Windows 通用桌面程序。
实现状态与开发进度见 README 状态节。本文档只描述设计意图与架构决策,不重复记录「做完了什么」。
- 定位:帮个人、团队和社团集中录入发票及相关材料,核对识别结果,并生成可交换的绑定包。材料和提交文档由报账方案定义;整理人员可用打印导出组件生成提交件。
- 参考仓库(只读,不再改动):
invoice2docx。Tidoc 复用其发票解析和金额校验经验,Word 业务输出采用适配包模板。
核心理念
软件替用户整理和校验,用户只填该填的;能改的在软件里改,不能改的锁死;一切交换通过带校验的绑定包,手工改动包内文件时导入会提示。
1. 名称
- 产品名:tidoc(Tidy + Doc)
- 绑定包 / 汇总文件后缀:
.tidoc
2. 技术选型(定稿)
前端形态:PyWebView 原生窗口 + HTML/CSS/JS 前端。
用户拿到的是一个 tidoc.app(Mac)/ tidoc.exe(Win),双击即进主界面,有独立 Dock / 任务栏图标,不进目录、不弹浏览器、不点脚本。这一条专门解决旧仓库"进目录双击脚本再弹浏览器"的别扭体验。
- 窗口内核用系统自带 WebView(macOS 的 WKWebView、Windows 的 WebView2),不打包浏览器内核,因此体积小。
- 界面用 HTML/CSS/JS 自由编写,能做到简洁美观、动画细腻。
- 后端用 Python,直接复用移植自
engine.py的解析引擎。 - 打包用 PyInstaller,产物按"核心 + 可选组件"拆分。
被否决的备选:Electron(自带 Chromium,体积过大,与"体积小"冲突);Tauri(体积最小但需引入 Rust + 维护 Rust↔Python 通信,复杂度高一档);Flet(旧仓库桌面版走过,界面自由度不如直接写 HTML)。
3. 体积控制与依赖分层
核心(必装)只依赖轻量件:
pywebview(原生窗口)pypdf(读 PDF 文本,轻)Send2Trash(把已归档的外部文件移到系统废纸篓 / 回收站,可恢复)jsonschema(校验团队适配包及共享输出上下文的 Draft 2020-12 Schema)Pillow(付款截图 AI 上传前压缩;二维码取票:读取用户给的二维码图片,转灰度、放大缩小后交给识别库;导出预检时也用它确认 PNG / JPEG 材料能正常打开)zxing-cpp(二维码取票:从图片里识别税务平台的取票二维码;模块名zxingcpp,自带 C++ 原生库,Windows / macOS 都有预编译包,不需要本机编译器)- 标准库
xml、sqlite3、hashlib、hmac、zipfile
二维码取票在核心进程内完成(用户把二维码图片交给软件时识别,随后联网取回发票文件),所以 Pillow 和 zxing-cpp 随核心安装,不做成可选组件。macOS 的 HEIC 图片由系统自带的 sips 转换;Windows 没有可靠的内置解码器,提示用户转存为 JPG / PNG,因此不引入 HEIC 解码库。
核心打包时只保留取票用得到的 Pillow 部分:PyInstaller 构建参数排除 AVIF 解码、Tk / Qt 桥接和色彩管理(PIL.AvifImagePlugin、PIL._avif、PIL.ImageTk、PIL._imagingtk、PIL.ImageQt、PIL.ImageCms、PIL._imagingcms),其中 AVIF 的解码库最大。排除后 PNG、JPEG、WebP、GIF、BMP、TIFF 照常可读,AVIF 图片按“无法读取这张图片”处理。这份清单写在 release.yml 的两个核心构建步骤里,两个平台必须一致,且不得出现在打印、识别组件的构建里(组件独立构建,需要完整的 Pillow);tests/test_core_packaging.py 检查这几点。核心 --self-test 用 zxing-cpp 现生成一个虚构二维码,经 Pillow 存成 PNG 和 JPEG,再用取票的解码函数读回;成品缺库或模块被误排除时自检失败,发布中止。
重依赖全部下沉到「打印导出组件」(可选安装,按需从 COS 下载):
python-docx(读取和检查方案定义的 Word 文档)pypdf(PDF 拼接)Pillow+reportlab(付款截图转 / 拼进 PDF、拼接页编号;打印组件独立构建,带完整的 Pillow,与核心使用同一个版本号)docxtpl+Jinja2(受限 Word 模板渲染)
核心和独立打印组件都依赖 jsonschema 和 Pillow,两份清单里的 Pillow 版本必须相同(CI 会把两份一起安装)。打印依赖清单为 requirements-print.txt。唯一的输出上下文 Schema 位于 schemas/team-adapter/1/context.schema.json,由轻量模块 tidoc_print.context_validation 加载,核心与独立组件使用同一校验器和资源。字段投影模块与校验模块不依赖数据库、API 或 WebView。
总览 Excel 由核心直接手写 OXML + zip 生成(见
services/exports.py),不引 openpyxl;PDF 拼接用 pypdf,不引 pikepdf。
不打包通用 OCR SDK: 默认发票识别走 XML 优先、PDF 文本其次。核心只调用系统原生能力做轻量兜底:查验单发票号归属确认;阿里云 OCR 作为可选组件实现(见第 10 节),SDK 不进核心包,只在用户安装组件并明确点击时调用。
系统原生 OCR 不增加打包体积:macOS 侧复用 pywebview 已引入的 pyobjc(Quartz / Foundation),并在运行时用
objc.loadBundle动态加载系统Vision.framework,无需单独安装pyobjc-framework-Vision;Windows 侧走系统 PowerShell / WinRT,无额外 Python 依赖。PyInstaller 打包时需为这些隐式导入配置 hidden-imports。
4. 总体架构
tidoc App
├─ 核心(必装)
│ ├─ 本地后端(Python,随 App 进程内启动,不对外暴露端口)
│ │ ├─ 解析引擎(移植自 engine.py:XML/PDF 解析、金额闭合校验)
│ │ ├─ 数据层(SQLite + 附件文件仓库)
│ │ ├─ 绑定包 导出/导入(.tidoc,带 HMAC 签名)
│ │ └─ 更新服务(对接腾讯云 COS)
│ └─ PyWebView 原生窗口 + HTML 前端
│ (录入 / 列表 / 搜索筛选 / 编辑 / 备注 / 报账人)
│
├─ 打印导出组件(可选安装,按需从 COS 下载)
│ ├─ 发票 PDF 拼接、付款截图拼接、查验单拼接
│ ├─ 每页信息标注(可选填哪些字段)
│ └─ 方案声明的多份 Word 模板输出
│
└─ OCR 识别组件(可选安装,按需从 COS 下载)
├─ 阿里云增值税发票识别(移植自 invoice2docx,SDK 随组件安装)
├─ 用户在设置内自填 AccessKey,仅保存在本机
└─ 手动触发(批量 / 单条)+ 识别提醒视图建议条,不做后台识别前后端通信走 PyWebView 的 JS↔Python 桥(window.pywebview.api),无需开本地 HTTP 端口,更安全也更简单。
5. 数据模型
Profile(报账人)
报账人表示“这张发票属于谁”,每条发票绑定一个报账人。
name姓名,必填。reviewer审核人,可空。方案控制相关操作的必填要求,以及普通、高级或隐藏显示方式。is_default默认报账人
收款资料保存在独立 payees 记录中,与材料归属人分开。本地方案、批次和本次导出选择完整收款对象,按报账人收款时使用明确映射。旧全局收款设置只用于一次迁移和兼容转发,不再逐字段拼接来源。
Entry(报账条目,以「一张发票」为核心)
id、profile_id(报账人)、created_at、updated_atscheme_id、scheme_revision_id:本地方案和固定修订。默认方案变化只影响新条目。title抬头和title_profile_id配置主体 ID:按条目修订解释。通用方案没有预填学校,BITFSAE 包包含其组织抬头。主体隔离见第 7 节。- 识别得到、默认只读的字段:
invoice_no发票号码invoice_date发票日期seller销售方 / 来源出货厂商、seller_tax_id销售方税号total价税合计,保存精确十进制字符串。缺失与零分别表示,零和负数均为有效金额。buyer_name购买方抬头、buyer_tax_id税号。按条目固定修订的抬头目录校验,不以当前默认方案改写票面事实。items[]物品明细(名称、单位、数量、单价、金额)
- 用户可改字段:
paid_amount实付金额(默认按发票总额;付款截图上传时提示确认或修改)actual_item_name实际物资名称notes条目备注
attachments[]附件status状态:draft草稿 /partial部分材料 /complete完整check_status校验:pass/warning/blocked,及check_message(多条以「;」分隔,每条带类别标记,见tidoc/engine/check_lines.py)check_reviewed已核对的识别提醒(JSON 数组,按显示文字)。提醒文字变化即视为新提醒;只影响「识别提醒」视图和徽标,不改check_status,不进绑定包field_history[]字段级修改记录(不可擦除,见第 6 节)
Attachment(附件)
type:invoice_pdf/invoice_xml/payment_screenshot/physical_image/inspection_pdf/otherrole_id:方案材料角色。自定义角色继续使用type=other,来源角色另保存定义修订。- 内置角色始终参与规则校验;
materials.json实际声明或设为必需的角色才生成新建条目入口和材料要求,未声明的注入角色只用于兼容旧附件。 original_name、stored_path、sha256、added_at- 付款截图可多张;附件可写附件备注
条目标签 / 备注
tags[]条目标签,供筛选与交叉标记(如「待催办」「已交」);支持批量打标 / 去标。notes条目备注,用于记录单张发票的处理信息。- 附件备注只描述具体附件,不替代条目备注。
Batch(报账批次,运营组工作单元)
运营组把「一次要交的这批材料」自由圈选、命名、留存为一个集合:
- 可跨报账人、跨抬头装入任意条目;一个条目至多归属于一个批次,改选批次即移动归属,避免重复报账、导出和统计。
batch_entries关联每条在批次内可带批次级催办备注(如「张三缺查验单」),与条目自身的记账备注分离。- 批次可归档(已提交后归档),可整批导出 / 打印 / 汇总;批次统计给出条数、合计、每报账人小计与缺件数。批次可填写「批次备注」,用于记录用途、注意事项或交接说明,并在批次栏下方与归档确认中展示。
- 归档后,该批次的条目退出「在办」、进入「已归档」;未进批次或属于未归档批次的条目留在在办。打开某个具体已归档批次时查看其完整成员;在批次内确认归档后视图随批次转入「已归档」,不跳回全部在办。全库防重复不因归档而放开。
- 批次只引用条目,不持有材料;删批次不动条目,删条目由外键级联清理关联。
- 批次新建默认方案、字段、收款选择和输出覆盖按本地方案保存。混合方案批次不会共用同名字段,也不会重绑定已有条目。
主界面工作流
- 顶栏只放全局动作:导入、设置、批量导入、新建。
- 工具条第一行放搜索框(宽度随屏宽伸缩、尽量占满)、抬头 / 报账人 / 标签筛选、高级筛选和排序;窄屏只压缩搜索框,不让它独占一行。第二行放批次栏和「全部 / 待补材料」等状态预设:批次栏在左、占满状态预设左侧的剩余宽度,批次多时在栏内横向滚动,状态预设靠右,共用一行以压低工具区高度;剩余宽度连几个批次都放不下时退回上下两行,状态预设在上、批次栏在下。列表上方的条目统计(条数、合计、每报账人小计)同样占满「选择条目」左侧的剩余宽度、放不下就横向滚动,「选择条目」保持在右侧;选中条目后操作按钮变多、统计放不下最小宽度时才换行。macOS 默认的浮动滚动条不占布局位置,这两处需要横向滚动时在下方垫出滚动条的高度并用负外边距抵掉,滚动条落进下方留白,不盖文字,也不改变行高与对齐。Windows 等占位的经典滚动条会撑高统计条、把文字顶高,统计条横向滚动时按量出的滚动条高度用负外边距抵掉,文字仍与「选择条目」居中对齐。批次归属与“未进批次”浏览通过批次栏和条目卡片直接管理。
- 条目列表默认多栏显示;点击卡片或按空格切换选中,通过“打开详情”按钮或 Enter 打开详情。
- 抬头用接近纸面的淡色纯色背景区分,卡片左右内边距对称。浅色和深色主题共用语义色;物资名称前另有一个抬头色小圆点,与名称垂直居中并随名称一起换行;圆点不沿用底色和文字色,而是单独一组饱和、色相拉开的颜色(浅色和深色主题各一组),方案里没有的抬头显示灰点,没有抬头的卡片留空位以保持名称对齐;按抬头分组或已筛选到某个抬头时整页同一个抬头,不显示。选中后在抬头底色上叠一层淡淡的主色,边框换成柔和的主色线,左缘内侧多一条短竖线作为形状线索,不加粗外框;键盘焦点仍是外圈光晕,两种状态互不混淆。悬浮或键盘聚焦可读取完整抬头。
- 条目卡片上的报账人和批次徽章是就地编辑入口;发票、付款截图、实物图、查验按钮左键继续添加或替换,右键在已有材料时调用系统打开。
- 支持卡片勾选、Shift 范围选择和 Cmd/Ctrl+A 全选当前列表;选中后再显示移动批次、标签、汇总、导出、打印、删除。
- 键盘模型:列表是一个 Tab 站,卡片之间用方向键或 Tab / Shift+Tab 移动(
stepEntryTab在列表上统一处理,分组标题的「选中这组」按钮算一站,走到头尾交还给浏览器),空格选中、Enter 打开详情、菜单键或 Shift+F10 打开条目菜单;卡片内的按钮不进 Tab 顺序,键盘上的同类操作走详情和条目菜单。右键菜单(条目、批次)由showContextMenu统一提供 ↑↓ / Home / End / Enter / Esc 操作,并在关闭时把焦点还给打开前的位置。弹窗由modal()统一处理 Esc 与 Enter:Enter 在单行输入框或确认类小窗口里等同页脚最右的主按钮(危险按钮不算,多行文本框用 Ctrl/Cmd+Enter),输入法组字期间不触发;首个控件是文本框的弹窗打开即聚焦它。 - 选择变化只更新受影响卡片的外观与选择语义,焦点切换只更新前后两张卡片。全选、取消和分组选中保留列表节点与滚动位置;分组标题同步显示整组选中状态。前端索引只持有当前列表节点,重绘时清空,单卡刷新时替换。
- 取消选择只访问此前已选的卡片,选择栏只写入改变的文字和状态。取消按钮收起后,焦点回到当前卡片且不滚动。键盘导航按实际显示顺序索引卡片;范围选择沿用筛选结果的顺序。列表重绘先在文档片段中构建,再一次替换内容。
- 设置、报账方案、收款信息、导出记录、更新和打印导出窗口点击后立即占住层级(防止重复打开),但加载窗口在 100 ms 后才显示:快速加载直接出现最终窗口,较慢时显示与最终窗口同宽的骨架加载页,内容到达后在原层级替换,并从加载页当前的高度、透明度和遮罩深浅过渡过去,不再先弹小窗再跳成大窗。窗口打开时遮罩淡入、窗口轻微上移淡入;关闭时留一个不可交互的快照淡出(原窗口立即移除,焦点和下层窗口刷新不受影响);窗口内内容大幅变化(更新检查结果、导出检查结果)时高度平滑过渡。动效只改透明度、位移和窗口高度,时长 130–200 ms,系统开启「减少动态效果」时全部关闭。每次加载持有自己的窗口引用;窗口已关闭时丢弃响应,重新打开互不影响。设置的路径、偏好和本地应用信息通过一次桥调用读取,组件状态另行检查,且不持有后端锁:打印组件的
--capabilities结果按可执行文件的 SHA-256 缓存到组件目录的capabilities-cache.json,文件未变时跨启动复用(超时或无法启动的探测不落盘),安装校验的哈希按文件大小和修改时间复用;目录统计在设置显示后运行,仅捕获数据根时持有后端锁,文件遍历不占用数据库锁。检查更新、下载可选组件和核心更新包同样不持有后端锁:只在读取通道、数据根和写入检查结果时短暂加锁,联网期间其他桥调用照常返回;同一通道的并发检查(启动检查与更新窗口)共用一次请求,检查期间切换了通道的结果不写入记录;组件安装包下载完成后再加锁解压和登记,导出运行打印组件期间组件文件不会被替换。测试版通道并行读取两份清单。「软件更新」窗口先用cached_update_status显示上次检查结果(可选组件的安装状态按本机重算,不联网),后台检查完成后替换;检查期间禁用下载和安装按钮,失败时保留上次结果并给出原因。 - 子页面返回设置时只更新对应摘要,不重建表单;保留输入、折叠状态和滚动位置。弹窗采用静态遮罩和即时开关,避免整页背景模糊及缩放重绘;层级没有变化时不重复写入主界面的 inert 状态。自绘下拉批量读取样式后再包装,关闭弹窗时回收脱离文档的下拉记录。
- 卡片点击和取消即时反馈,连续点击每次切换选择。列表重绘不播放卡片入场动画,悬浮只改变边框和轻量阴影,保持卡片位置。滚动时收起提示并暂停悬浮测量;鼠标停留 160 ms 后显示,已有提示之间直接切换,键盘聚焦即时显示;整张卡片的抬头提示需停留 600 ms,且不参与直接切换,避免扫读列表时提示逐张跟随。卡片在 Chromium(Windows 的 WebView2)上使用
content-visibility: auto,长列表只排版视口附近的卡片;macOS 的 WebKit 在卡片重新进入视口时有漏画缺陷(卡片外框在、内容整块空白),所以那里不启用,每张卡片照常绘制。列表刷新按请求序号只采用最后一次结果;分组浏览时单卡刷新在分组不变时就地替换并更新组合计。 - 删除批次默认只删除组织关系并保留条目,条目回到「未进批次」;可通过默认不勾选的危险复选框同时永久删除该批次内条目及附件,界面须明确提示不可恢复。
- 批次栏先用紧凑的「在办 / 已归档」分段切换工作面,再在同一行展示当前工作面的批次;再次点击当前具体批次会返回所在工作面的汇总视图。按住批次左右拖动可调整顺序(指针事件实现,不与拖入文件的处理冲突),顺序以批次 id 列表存于
meta(tidoc.batch_order);不在列表里的批次(从未排过序或之后新建的)排在最前、按最近更新,因此排过序后批次不会因改动而跳位,新建的批次出现在最前。批次栏重绘时保留横向滚动位置,切换到别的批次时把它滚进视野。批次操作通过悬浮提示和批次菜单发现。单条或批量条目使用统一的目标批次选择器移动归属,也可移到「未进批次」或新建批次。
存储布局(结构化、清晰保存在电脑一处)
<数据根目录>/
├─ tidoc.sqlite # 结构化数据
├─ attachments/
│ └─ <entry_id>/
│ ├─ 发票.pdf
│ ├─ 发票.xml
│ ├─ 付款截图_01.jpg
│ ├─ 付款截图_02.jpg
│ └─ 查验单.pdf
├─ adapters/ # 已安装包、不可变资源和安装日志
├─ export_jobs/ # 导出快照、资源引用和任务结果
├─ exports/ # 生成的绑定包、汇总文件、打印件
├─ components/ # 本机安装的可选组件
└─ updates/ # 待更新文件数据根目录默认在系统应用数据目录,可在设置里改到用户指定位置。
6. 防篡改与修改追踪(核心顾虑)
目的:防止用户绕过软件手工改数据造成混乱甚至欺骗。分两层,强度定为「够用」:
6.1 绑定包 HMAC 签名(检测级,够用)
导出的汇总文本 / 绑定包内嵌一份 HMAC 校验清单,密钥内置于软件。导入时校验:校验不符即判定「已被外部修改」,醒目标红,不静默接受。用途是发现手工改动和文件损坏。密钥随开源代码公开,所以它不能防止有意伪造,也不是加密;需要防伪造时应改用非对称签名,目前没有这个需求。
6.2 字段级修改标记,不可擦除
- 每个可改字段同时存
origin(识别原值)与current(当前值)。 - 人工把
current改为不同于origin的值后,该字段永久打上「已人工修改」标记;付款截图 AI 等自动值单独记录来源,不冒充人工修改。 field_history记录每次改动的时间、旧值、新值、操作人。- 标记与历史不可删除,随条目一起导出,接收方能看到哪些被改过、改成什么。列表里的“已修改”按当前差异派生,规则见第 8.7 节,恢复原值不会擦除历史。
识别精度:旧仓库实测识别较准,用户一般无需改发票号码、总金额等关键字段。关键字段在软件内默认只读;确需修正走「标记为人工修正」的特殊流程并留痕。
7. 抬头与主体隔离
抬头目录属于方案修订,包含名称、税号、简称和语义色。通用方案保留真实购买方,BITFSAE 包提供北理工及教育基金会的公共默认值。修改目录生成新修订,旧条目继续按原修订识别和校验。
- 解析和校验显式接收条目或本次导入的上下文,多个方案及 API 实例不共享全局抬头配置。
- Word 和材料 PDF 每个文件只含一个主体。组键同时考虑名称和税号,税号未知时使用稳定标识,避免同名误合并。
- 跨抬头 Excel 可保留总览,列中注明主体;附件 ZIP 按主体目录隔开。绑定包保留逐条来源,接收时仍在全库查重。
- 已配置主体的税号缺失、不符或与名称矛盾时提示核对。空抬头目录不限制购买方范围,也不套用其他团队的学校默认值。
8. 核心功能(逐条对应最初构想)
8.1 报账人与收款信息
- 报账人只表示发票归属,字段为姓名和审核人。
- 普通使用时默认绑定默认报账人;新增到两个报账人时自动开启代填模式,此后新建 / 批量导入时直接选择报账人。用户仍可在设置中手动关闭。凡弹窗内需要选择报账人的位置,都提供就地新建入口,创建后保留当前任务并自动选中新身份。
- 条目详情可修改报账人并留痕,也可在选择器旁就地新建报账人。
- 收款对象供需要收款段落的输出使用。输出声明
single、by_claimant或none,无收款段落的输出不要求账号。字段定义与选择语义见适配开发手册。
8.2 上传与录入
- 发票 PDF:上传时提示「推荐同时提供 PDF + XML,识别更准」。
- 付款截图:默认关闭 AI 识别,不再调用系统 OCR。配置属于本机全局偏好,不随报账方案导出;旧方案的
assist.payment_ocr只为兼容读取保留,不授权网络调用。在「设置 › 开发者选项」填写 Key 后即可在「云识别」手动识别;「添加截图时自动识别」只控制添加截图时是否自动上传,默认关闭。默认 DeepSeekdeepseek-flash,可选 Qwenqwen3.8-flash或兼容 Chat Completions 的视觉模型。设置项改动即保存;切换服务商时按服务商和地址换用对应的 Key,「其他兼容服务」的地址和模型单独记住;目标没有 Key 时自动识别随之关闭,补填 Key 不会自动恢复上传。提示词默认内置,可在高级选项整体修改或恢复默认,附加要求总接在末尾。费用估算按本机实际平均用量并扣除缓存命中,旧记录没有缓存 Token 时取当时记下的实际费用平均。DeepSeek 官方接口可在用户点击「查询余额」时调用/user/balance,打开设置不联网。图片经 EXIF 方向处理,长边缩至 2000,JPEG 质量 85,原附件不改动;HTTPS 证书校验额外加载 macOS 系统根证书,避免打包版找不到构建机的证书路径;使用非思考模式及流式 JSON,结果经结构和金额校验后使用。退款净支出由 Decimal 计算,并保留核对提醒;深色截图仅提示省墨,不判为材料不合格。 - 识别队列:后台任务使用有界线程池,默认并发 32,上限 64;网络 / 429 / 5xx 重试一次,认证错误不重试。进度读取不占数据库全局锁,显示完成数、进行中、排队、失败、缓存、耗时和费用;明细结果只在任务结束时返回。取消只停止排队中的请求,已取消的截图不写入结果、不计失败。添加、替换、改类付款截图时,前端先跑后台任务并传入任务 ID;后端只采用该任务或本机缓存里的结果,不在 API 锁内联网,没有结果的截图留待「云识别」处理。没有 Key 时不生成付款截图识别提醒;自动识别关闭时不提醒「尚未识别」,已识别的结论照常提醒。识别规则或本机识别设置变化后,启动或保存设置时给所有带付款截图的条目重算一次提醒。结果写入前核对材料 ID、类型与摘要,删除或替换后的材料不采用旧结果。缓存按文件摘要、服务地址、模型、要求、规则版本及密钥摘要隔离;失败结果不落缓存。设置变更不触发识别;开启自动识别后添加截图,或点击「云识别」时才上传。
- 金额采用:添加截图时,金额与发票一致的单张合格截图可填写实付,退款、金额差异、多张截图需确认。「云识别」后只在实付为空(或上次由识别填写)且识别合计等于发票金额时自动填写;其余情况写入识别提醒,详情「付款截图识别」可一键采用识别合计。人工修改的实付不覆盖;识别填写的实付在修改记录中带「[付款截图识别]」来源前缀。
- 提醒内容:每张截图写明文件名和原因(来源不是微信 / 支付宝 / 银行、非人民币、未完成、订单页、收入记录、非付款凭证、识别失败);原因由保存的结构化结果推出,规则改动无需重新上传。多张截图累加后与实付比对,实付为空时与发票金额比对;实付改动后立即重算。新识别值记录
payment_ai来源;旧payment_ocr来源仍可读取。删除或改类最后一张付款截图时,仅撤销仍由识别控制的实付。截图来源、金额或材料判断有疑问时交给人工;不存在系统 OCR 回退。 - 缓存与费用:截图结果保存在本机
payment-ai-cache/;密钥单独存于本机 meta,以服务商和地址隔离,普通界面读取只返回配置状态。费用按服务返回的输入、缓存命中输入、输出 Token 估算;无用量的失败请求标记费用待确认。DeepSeek 官方价格按北京时间高峰、低谷计算,周末全天低谷,2026 年节假日离线表随代码维护;未覆盖年份按工作日保守估算并提示。价格更新日期和官方链接保留在设置内,第三方服务不套用官方价格。累计估算及近期用量保存在本机,不查询余额、不自动联网刷新价格。 - 发票与付款截图分别保留识别版本。发票使用本地解析规则版本;付款截图使用 AI 规则、模型、地址、截图要求及(改过时的)自定义提示词的指纹;使用内置提示词时指纹不变。已有成功结果跳过,失败结果可重试。「云识别」共用入口提供发票 OCR 与付款截图 AI 两项,付款截图不依赖 OCR 组件;「重新识别」只在本机重新解析发票,不联网。付款截图识别结论随绑定包导出,导入后版本标为
<规则版本>:imported,同规则下视为已识别,不因接收方服务商不同而重新上传;提醒按接收方设置重算。 - “实付默认等于发票金额”由方案设置控制。开启时用有效发票金额初始化实付,缺失金额仍留空。修改默认值不批量改写旧条目,也不覆盖人工填写的差异金额。
- 发票查验单 PDF:可单独上传,也可从条目卡片 / 详情进入「在线查验」。查验窗口使用比初版更大的常规窗口,但不默认最大化;在线流程分步预填并触发官网对发票号码、日期与价税合计的原生校验。填充脚本兼容旧版字段 ID 和新版 TDesign 表单,等待表单挂载后填写,最多等待 30 秒;页面跳转后重新注入,每个文档只执行一次,避免重复覆盖用户输入。旧版日期通过 jQuery datepicker 写入并收起,新版日期输入后触发 Enter 确认。
- 验证码自动填写由「设置 → 开发者选项 → 在线查验验证码 AI 识别」的总开关(默认开启)、系统支持自动保存和已保存 AI 识别 Key 三项共同决定是否提供。该开关属于需要自备服务账号、按量计费的功能,与付款截图 AI 识别、阿里云 OCR 一起放在开发者选项里,「查验单」设置只留归档目录和清理原 PDF。满足时查验窗口出现默认勾选的「用 AI 自动填写验证码」,工具条上出现批量查验入口;任一项不满足时二者都不出现,后端也拒绝自动查验。验证码图片会上传到付款截图 AI 所使用的服务商,设置和窗口里都写明并按量计费。官网提示要求全部文字、蓝色文字或红色文字;本机按提示取色并去掉彩色噪点,把原图和分离图一起交给付款截图 AI 所使用的服务商。模型只负责读字,取色、放大和结果校验都在本机;英文字母统一按小写提交。模型说看不清、结果为空或长度异常时换一张,不提交;每个条目最多尝试 10 次,每次都是独立上下文、温度 0、关闭思考,不复用上一次的识别结果。识别失败按原因分类:Key 无效或无访问权限、余额不足、没有 Key 立即停止;服务商限流时多等几秒再换一张;网络超时等其他错误直接换一张。等待(换图间隔、官网限流退避)都可被取消或关闭窗口打断。验证码刷新和查验共用官网页面自身的签名与表单逻辑,不另设 HTTP 通道,也不绕过官网验证;所有窗口共享验证码请求间隔,遇到「访问过于频繁」等待后重新加载。累计识别次数和估算费用保存在本机偏好中,在设置里显示,与付款截图的用量统计分开,不影响截图的每百张估算。
- 批量查验由用户在列表中选中条目后主动开始,默认同时打开 2 个查验窗口(可选 1–4 个)。缺少发票号码、开票日期、价税合计的条目在服务端跳过并写明原因;已有查验单的条目默认也跳过,窗口里勾选「重新查验」后(
replace_existing)才查验,这些条目的会话以替换模式保存,成功后替换最近添加的一份,列表写明「查验单已替换」和第几次查验;每个窗口仍走官网真实页面和自动保存流程,批次只负责排队、窗口并发、逐条进度与取消。每个条目只结束一次,无论成功、失败、超时(10 分钟)还是取消,都会关闭它的窗口并移除会话和临时目录;查验过程中状态读取出错(例如条目已被补上查验单)按失败结束,批量不弹替换确认。识别费用按各条目会话累计,进行中也实时显示。取消只停止剩余条目,已完成并归档的查验单不回滚;进行中关闭批量窗口会先确认,确认后等同取消。 - 应用不会后台打开官网或自动检查;只有用户明确点击「打开查验官网」或批量查验的「开始查验」才联网。查验窗口不向官网暴露主窗口的 JS API。考虑到部分省级验证码接口使用会被 WebView 拒绝的历史证书,应用会在创建任何原生 WebView 前启用 pywebview 的证书错误放行,并在本次运行期间保持;这样 Windows WebView2 能在初始化时注册证书错误处理器,macOS 的验证码子请求也能使用同一策略。主窗口只加载本地文件,唯一的内嵌远程页面仍是用户主动打开的查验平台;这属于内部兼容措施,不在日常界面暴露。
- 查验窗口兼容旧版 jQuery PrintArea 和新版 Print.js:持续发现同源 frame,并在 iframe 的 load 捕获阶段安装子窗口打印转发。子窗口调用 print 时,读取当时的文档,将官网已排好的内容及样式复制到顶层打印容器,避免取到导航前的空文档。保持官网的内容和分页,所有正文页均保留。
- macOS 自动保存:仅在本次会话的可见发票详情包含查验时间、匹配的发票号码和可用「打印」按钮时触发。等字体和图片加载完成后点击官网「打印」,每个文档只触发一次,不提交查验表单。远程页不暴露 Python API;原生打印入口只处理带会话标记的查验窗口,以横向、保存任务和私有临时路径运行,不显示打印对话框。两端共用的版式在分页前缩小,不通过裁剪已有 PDF 缩页:打印内容按
VERIFICATION_PRINT_ZOOM(70%)缩放(CSSzoom)并水平居中,原生打印缩放保持 100%。NSPrintScalingFactor只缩小已排好版的页面,内容会缩在纸张左侧;官网发票版心为固定宽度,原先「原生 80% 加按纸宽收缩」实际约为 72%,直接用 80% 会让两行明细的专用发票挤出第二页,所以取 70%。WKWebView 分页准备是异步的,必须用异步打印入口和完成回调,不能同步运行打印任务;完成前不读 PDF、不删除临时目录,取消时延迟清理。 - Windows 自动保存复用相同的结果检测,二维码地址在弹窗出现后更新而导致解码失败时,在准备期限内继续重试。打印内容通过带会话标记的 WebView2 消息转交原生层,只能输出到该会话预先指定的临时路径,不暴露业务 API 或可指定路径的写文件接口。
PrintToPdfAsync在 UI 线程发起并异步完成,A4 横向、ScaleFactor保持 100%(缩放与居中见上一条)、保留背景图形并强制页面白底;减少空备注框和开票人跨页,真实长内容继续分页,不裁剪、不删页。完成前不解析或清理 PDF,失败后保留系统打印。 - 自动生成的 PDF 仍须通过查验单类型和正文发票号码核对,程序生成的 PDF 标题不作为归属依据,再由附件仓库复制到发起查验的条目、刷新材料状态并关闭窗口。无法确认正文号码时退出自动打印路径,保留窗口与系统打印、上传入口;已有材料不覆盖。自动保存使用会话独立的临时目录,归档或取消后清理,不经过废纸篓,不依赖外部保存目录,也不新增网络行为或打印组件依赖。
- 查验单正文单独解析发票号、次数与查验时间,先做 NFKC 与空白归一,兼容浏览器打印的偏旁字形、全角数字和旧版「查验次数」。计数范围只有正文写「当日」才标为当日;不从文件名、PDF 标题、导入时间或本机日期推断次数。复用附件识别列,缓存规则版本、文件摘要和读取结果;文件替换、改类后失效,启动时补读旧附件。提醒按正文查验时间选新结果,缺失时间时退回添加时间:最新一份为第 1 次不提示,第 2 次或以后、读不出次数(扫描件、图片 PDF 等没有可提取的正文)都提示;较新的第 1 次清除旧次数和读不出次数的提醒,删除新材料后回到剩余材料的结果。详情的查验单分组把每份材料缓存的次数写在文件名下方,缓存缺失时临时读取正文,不写库。卡片「查验」按钮上的标记(次数序数、
?、×N)来自条目的inspection概览:份数加上最新一份的次数,与识别提醒共用同一条「选最新」和「号码不一致不参与」规则;列表只读已缓存的正文信息,不为卡片逐个打开 PDF,缓存由启动时补读和材料变动后的重算维护。只合并带「[查验单]」前缀的识别提醒,保留发票和付款截图提醒,不影响齐备。一个条目默认只保留一份查验单:新增前由前端确认替换目标或保留,服务端核对已有集合与替换目标,确认过期时重新询问。在线查验在开始前就让用户选好「替换哪一份」或「另加一份」(save),会话保存时按当时的已有查验单重新生成确认,所选那份已不在则替换最近添加的一份,查验成功后不再回头询问;没有预先选择时沿用保存时询问;保留多份时写入带「[查验单]」前缀的识别提醒。绑定包只带 PDF,导入时重新读取;不把查验单套用发票解析器后覆盖发票字段,不调用 OCR 或网络。 - 两端保留点击官网「打印」进入系统原生打印的备选流程,打印样式固定为横向。会话默认监测下载、桌面和文档目录,用户可在「设置 → 查验单」选择一个额外目录,不能位于数据根内。文件大小和修改时间稳定后先核对类型和发票号码,再复制归档;文件仍被占用时稍后重试,同名文件重新保存后按新版本重新核对。「归档后清理原 PDF」只针对外部原文件,内部复制成功后通过 Send2Trash 移到废纸篓或回收站,清理失败不回滚材料。打印标题统一为「查验单-发票号码」,macOS 同时设置原生打印任务标题。
- 支持先提交一部分(如只有截图)甚至只是草稿(如只填了实付金额),状态标为 draft/partial,随时补齐。
文件夹批量导入
- 发票 PDF 和 XML 都可用于创建条目。文件夹和多选扫描将可识别号码的独立 XML 单独成组,无法识别的 XML 留在未分组列表中;需要打印票面的输出另查 PDF。
- XML 只是增强识别准确度:优先按发票号配对;文件名近似匹配只作为兜底,短数字文件名不会参与模糊匹配,避免
26.pdf误匹配到2026...或长票号。 - PDF 与 XML 按同一发票配对,XML 独立组也在本次导入范围内查重。付款截图、查验单不单独创建条目。
- 拖入的文件由原生层把真实路径报给后端(PyWebView 的
drop监听),后端直接从磁盘流式复制到中转区,不经页面读取内容;粘贴的文件没有磁盘位置,拿不到原生路径或文件在受保护位置时才退回「页面读取内容再回传」。单个文件上限 100 MB、一次 500 MB 的限制两条路径相同。 - 拖拽 / 粘贴混合材料时,发票 PDF / XML 先进入导入预览;确认时同时选择报账人和目标批次,可选已有批次、「未进批次」或随本次条目新建批次。查验单按发票号、付款截图按 AI 金额绑定到唯一匹配条目。未匹配或匹配不唯一的材料进入「绑定材料」对话框,逐份选择条目。若条目详情处于打开状态,粘贴的材料优先归入当前条目,再继续执行材料类型、发票归属和付款金额校验,并刷新详情状态。
- 扫描会识别常见查验单 PDF(含税务查验平台 PDF),这类文件只提示跳过,不会创建发票条目。
- 扫描预览说明将创建多少条、匹配到多少 XML、哪些 XML 先导入后补票面,以及哪些文件无法识别或已经重复。用户勾选要导入的发票组。
- 创建前按发票号在全库检查重复;没有命中时以发票 PDF / XML 文件摘要兜底。查重范围包含所有报账人、在办及已归档批次、未进批次的条目。命中重复时保留导入预览,显示原条目的销售方、报账人、批次及归档状态,可打开原条目处理。修改归属不放开查重。单条新建与批量、拖拽、粘贴入口共用同一规则。
- 每个分组按“全部成功或全部清理”处理:解析、校验或附件复制任一环节失败,都删除该分组已经写入的条目和附件;其他成功分组不回滚。随发票一同拖入的材料只在至少有条目成功创建后匹配,避免失败时意外落入全库其他条目。
- 批量导入负责把发票文件变成可整理条目。补材料与改字段继续使用条目详情和紧凑绑定对话框。
8.3 识别与校验
发票数据来源优先级
用户一张发票的结构化数据(发票号码、金额、明细等)可以从多个来源获得。按准确度和便捷性排序,优先级如下:
- 原生电子发票 XML(最优) —— 用户向商家索要,程序解析零误差。UI 应引导用户尽量提供 XML。
- 程序解析发票 PDF —— 上传 PDF 后自动用 pypdf 提取文本并识别字段,兼容左右分栏中的空税号、税号文字层落在标签上方、常规逐行明细、按列拆分的文本流、同品名折扣行、数量 / 单价 / 金额列粘连、空单位/数量及规格末尾字母与中文单位粘连,大多数数电发票可准确解析。
- 用户手动填写 / 编辑 —— 识别结果不准或无法识别时,用户直接在界面上编辑修正。编辑体验要足够快捷(inline 编辑、Tab 跳转、明细行增删),使手动填写的成本尽可能低。
- 消费外部 Aspose 版面 XML(下下策) —— 程序本身不做 PDF→XML 转换,只解析用户用 Aspose 等外部工具导出的版面 XML(
engine/parser.py::parse_aspose_xml)。流程长、收益有限,作为最后手段保留;后续若程序直接解析 PDF 的能力提升,此路径可废弃。
设计原则:不要把精力过度投入边缘 PDF 识别的打磨上。大部分发票应该走路径 1 或 2;识别不准时,让用户能快速手动修正(路径 3)比把识别率从 90% 提到 95% 更实际。
解析流程
PDF 明细增加基于文本坐标的补充读取,按独立文本片段分离品名、规格和单位,保留名称内的尺寸星号。在文本显示指令前后用恒等变换刷新 pypdf 文字缓存,避免同字体片段沿用上一段坐标;仅处理内存副本,保留字体原始字节和原文件。逐行金额及整票金额必须与现有结果一致,才补充名称、空单位和缺失规格。移除名称里的文字前,要求被移除部分在规格列中有对应内容;其余名称不缩短、不重排,已有数量保留。行数不一致时,只允许把紧随商品、无单位和数量、且品名一致的负数折扣并回商品,并核对合并金额。PDF 版面文本保留分页边界。品名列中的数字续行可以补入型号;跨页后先跳过重复的票号、购销双方信息,再从明细表头恢复续接,规格列续行不拼入品名。数量与高精度单价粘连时,先按金额闭合拆分;若只有一种拆分与独立读取的票面金额相差不超过一分钱,也可采用该数量。单价和金额均粘连、没有独立金额时仍要求严格闭合,不用容差猜测金额。
明细行明确标有「免税」「不征税」,且税额为空、「***」或零时,按零税额读取;缺失税率或非零税额矛盾不按免税推断。表头与首行明细交叠时先移除表头再读取。未完成的品名到下一条带分类的商品行时结束,避免借用下一条的金额。版面折扣待品名续行读完后按完整名称配对;若规格列中的型号与首行品名粘连,还要求折扣行的首段与全部续行共同印证,才将型号移到规格并合并金额。不能配对的负数行保留,供人工核对。
购销方名称标签与取值分离时,跳过无标签的票头「成品油」分类行,避免它占用名称候选。明确标有名称的取值,以及名称中包含「成品油」的公司仍正常读取;真实名称冲突继续保留提醒。
本地解析证据(票面合计、大写金额、字段候选及来源提醒)和当前采用值分别保存。改总额或采用云识别明细时,用当前字段、明细和原始证据重算提醒;重新识别才替换证据。销售方税号与购买方税号一起保存,绑定包携带证据但不迁移本机识别缓存标记。XML 与 PDF 同时提供时比较关键字段,保留 XML 值并记录差异,PDF 读取失败也保留 XML 并提醒。这些检查保持为非阻断提醒,人工核对后仍可继续输出。
导入即自动解析(优先 XML,其次 PDF 文本),提取发票号码、日期、销售方、价税合计、抬头、税号、明细;检查明细识别完整性、抬头一致性,以及已配置抬头对应的购买方税号是否存在且正确。warning 在界面称为「识别提醒」,用于缺明细、明细识别合计与发票总额不一致、抬头未识别、购买方税号缺失 / 错误 / 与抬头矛盾等自动提醒,不阻断材料齐备;blocked 在界面称为「严重问题」,仅用于抬头分区冲突等会造成材料混入的问题。在顶部「识别提醒」快捷视图中,批量操作栏按需显示「重新识别」,用条目已有的原发票 PDF / XML 原子替换识别明细并刷新提醒;用户修改过的实际物资名称、实付和备注保持不变。
本地发票解析版本变化后,列表按当前筛选范围统计带原始发票、但识别版本不同或为空的条目,显示可关闭的重新识别提示。提示入口复用批量识别窗口,只处理发票,不改变用户已有选择,也不自动解析。关闭状态按数据目录和解析版本保存,下一解析版本重新提示。成功重新识别后更新版本标记;失败条目保留旧标记,仍可重试。提示不改变识别提醒或材料齐备状态。
附件归属校验
- 发票 XML 必须能解析为官方电子发票 XML,非发票 XML 不作为发票附件接收。
- 发票 PDF 不能是查验单 PDF;能解析出发票号时必须与当前条目一致。
- 查验单 PDF 先读文本 / 元数据中的发票号;读不到时,macOS 使用 Vision、Windows 使用 Windows.Media.Ocr 对查验单发票号区域做系统原生 OCR。识别到发票号后必须与当前条目一致;识别不到但能确认是查验单时允许用户添加。
- 付款截图金额可用于给出唯一归属建议,但不作为强校验依据;没有唯一候选时必须手动绑定,用户已有手动实付金额时不自动覆盖。
8.4 汇总与导出
- 输出名称属于本次导出选择。绑定包、总览和附件包分别填写文件名;打印输出按稳定分组 ID 保存名称覆盖,不改方案模板,名称在各输出行下直接修改。名称经核心校验后写入导出计划,生成、记录及按原数据重新生成共用该名称,扩展名由输出类型决定。命名不能引入目录、系统保留名称或同次输出重名;直接导出的文件遇到已有同名文件时提示改名,避免覆盖。
- 界面内汇总给用户看:条数、合计金额、抬头分布、前若干条预览,不直接展示开发者式 JSON。
- 总览 Excel:通用输出包含基础字段,方案输出按声明设置列、行模式、格式和合计。用户文字按文字保存,发票级金额不随明细重复合计。
- 附件整理包:按材料角色、主体和配置目录命名,保留原文件及清单。通用导出与方案输出复用同一写出器。
- 绑定包
.tidoc:给 Tidoc 之间互相导入继续整理,保留报账人姓名 / 审核人、条目归属、材料、修改历史、阿里云识别结果及签名校验。文件选择器、单个文件拖拽 / 粘贴和系统文件关联共用完整性检查与导入预览;一次混入多个包或其他材料时提示分开导入。 - 导入预览在同一列表处理新增和本机已有条目,显示「新增 / 已有·待补充 / 已有·无变化」及补充内容。状态筛选兼作数量统计,搜索覆盖发票号、销售方、报账人和原批次;筛选不改变勾选,显示筛选外已选数量。「全选当前结果」只增减可见行,「仅选当前结果」替换全部选择,「清空选择」取消全部。复选框、查看本机条目和单条设置直接可用,姓名编辑收进「报账人」,使用紧凑表格、行内编辑和独立滚动区;折叠摘要显示已选人数。批次保留「不加入 / 已有批次 / 新建批次」分段切换,右侧按选择显示已有批次或新名称,方案和标签同行排列,字段标签与控件横向对齐。默认勾选包内全部条目,不按当前身份缩小范围;报账人选择只列出本次有条目的身份,历史修改人不作为选择项;新增条目按姓名和审核人复用或创建身份,达到两位报账人后自动开启代填模式;已有条目显示并保留本机身份和方案。
- 导入的批次分配与内容补充分开决定。统一目标默认只用于新增条目;已有条目保留原批次、归档状态和批次内备注,未进批次的保持原状。用户明确勾选移动时,才把本次选中的已有条目也安排到统一目标,包含内容无变化的条目;没有目标时隐藏并重置移动选择,每次打开预览默认关闭。单条设置优先,支持保留原批次、移入已有批次、新建批次和移出批次;不为未使用的统一目标创建空批次。已有批次包含归档批次并标明。每行实时显示批次去向;第一次点导入只核对条目构成、保留数量、目标批次及归档去向,再次确认才写入。
- 绑定包保留交接来源的内部记录,但不将这类记录本身计作内容补充。绑定包按整个包原子处理,任一条目、身份或材料失败时回滚本次写入及文件。发票号或发票文件摘要命中本机条目时,保留本机非空值,只追加缺失材料、合并备注和普通标签,并补齐空缺基础字段、明细、云识别与修改记录。「已报销 / 未报销」「已支付 / 未支付」互斥标签以包内状态替换本机相反状态。条目 / 材料备注和标签是否导出由报账方案中的两个开关决定,默认包含。完整性异常需用户明确确认,新导入或被补充的条目标为严重问题。
8.5 条目管理(批量、便捷)
- 整条删除、批量删除;删除数据库记录时同步删除附件目录,数据库删除失败则恢复暂存的附件目录。
- 修改 / 补充 / 替换附件;文件复制、重命名与数据库记录按可回滚顺序处理,避免失败后留下半份附件或失效路径。可打开文件、在系统文件管理器里定位文件,macOS 下 PDF 直接走系统预览。
- 修改允许修改的选项(实付金额、实际物资名称、条目备注等);多选条目可批量修改报账人,每条分别留痕。
- 关键信息(发票号码、总金额、抬头、税号等)软件内禁止随意改;确需修正走「标记为人工修正」流程并留痕。
8.6 绑定压缩包(.tidoc)导出 / 导入
一个 ZIP 包,内含报账人、条目归属、附件、汇总和 HMAC 校验清单。版本 2 增加身份清单;版本 3 增加云识别结果及修正快照;版本 4 增加条目时间及增量补充;版本 5 增加公共规则投影、来源修订、材料角色和允许交换的扩展值与历史。继续读取版本 1~4;旧客户端需更新后接收版本 5。导入的云识别结果不计入接收方本机调用次数。
备注和标签采用方案的带出建议及用户明确选择。扩展值按 include、ask 和 never 处理;禁止分享的原值和历史值一起移除。收款对象、私人方案实际值、密钥及导出快照不进入公共规则投影。内置材料按稳定的处理类别对应本机角色,自定义材料仍需明确映射;新增和补充条目共用归类及约束校验。交换语义见开发手册。
完整性检查对附件执行流式 HMAC,不把大文件整体读入内存;条目与汇总数据在校验后直接复用已解压内容。本机重复条目的材料、历史、识别记录和批次用批量查询生成预览;用户确认导入时,只要文件大小和修改时间未变,复用该次已验证结果,避免对整包再做一次相同校验。
(条目备注、附件备注与条目标签的定义见第 5 节。)
应用和绑定包图标按平台分开生成:Windows 使用自带透明圆角的多分辨率 ICO,避免系统直接显示无圆角方图;macOS 使用完整方形 ICNS,由系统按当前版本规范裁切。Windows 安装器把 .tidoc 注册为 Tidoc 绑定包,资源管理器显示明确安装的绑定包图标,双击直接启动 Tidoc 并进入该包的导入预览,卸载时自动清除关联;macOS 应用包声明同一扩展名的文档类型和图标。
8.7 分类 / 筛选 / 搜索
按抬头、报账人、日期、销售方、金额区间、状态、条目标签、条目备注、付款截图数量和关键词过滤,也可通过批次栏按「在办」、批次、「未进批次」或「已归档」聚焦;付款截图数量提供「没有付款截图」和「多张(2 张及以上)」两个条件;发票日期提供本月、上月、今年三个快捷范围,按本机日历计算。高级里的「校验」只保留「通过」和「严重问题」,识别提醒由状态预设负责,选中该预设时清掉校验条件,避免两处互相覆盖。排序字段旁有方向按钮,换字段时回到该字段的常用方向(时间、金额降序,销售方升序);空值始终排最后,同值按最近更新和条目 ID 排,列表顺序稳定。分组浏览(不分组 / 按报账人 / 按抬头)放在排序旁,只改变显示,不改变筛选结果。筛选条件直接通过对应控件的浅蓝激活态表达,高级条件同时点亮具体筛选框和「高级」入口,不在工具条下方重复生成条件标签;下拉控件统一箭头、边框和交互状态,展开后的选项列表同样由应用自绘(原生 select 展开的列表由系统控件绘制,与界面其他浮层不一致):原生控件仍留在页面里承担取值与 change,触发器与浮层由前端组件负责,并保留方向键、Home/End、Esc、首字母跳转等原生键盘行为和 listbox 语义。抬头下拉以设置里配置的抬头为固定项,并动态补入数据库中实际出现的其他抬头,存在未配置抬头时在筛选控件显示轻量提示点。常用视图(全部、待补材料、识别提醒、已修改、齐备)作为筛选条内的快捷条件,不拆成左侧多个“页面”。其中“已修改”筛选当前仍有人工差异的发票关键信息、物品明细、实际物资名称和实付金额。历史标记仅用于圈定候选条目,再批量读取当前值、原值和已保存的本地 / 云识别依据判断;恢复原值、与识别结果一致或当前值已由识别更新时移出,金额用 Decimal 按分比较,物品明细按完整内容比较并忽略数据库行 ID。备注、标签、分类、报账人和批次等整理操作不计入,自动识别和本地重新识别也不计入。列表筛选、卡片徽标、汇总计数和详情刷新共用仓储层返回的 modified_fields,物品明细的人工新增、编辑和删除记录前后完整内容,后续识别替换另记来源,供恢复和比对使用;悬浮徽标说明当前人工改动。实付与发票金额的差异仍独立展示。通过卡片勾选、Shift 范围选择(按屏幕上的卡片顺序,分组浏览时也一致)和 Cmd/Ctrl+A 选中条目后,再做批量修改报账人、汇总、导出、打印或删除,重新识别等长任务按条目显示完成进度。
8.8 草稿与部分提交
状态保留 draft、partial 和 complete,列表可按状态筛。
状态按条目固定修订的材料、字段和条件规则推导:
complete(齐备):发票及当前修订所需材料、字段和规则满足,且无核心阻断项。通用方案仅默认要求发票;BITFSAE 要求由内置包声明。draft(草稿):还没有任何材料。partial(部分材料):介于两者之间。
附件或可改字段变化后自动重算并持久化,供列表筛选与导航分区使用。列表卡片把发票 / 实付 / 付款 / 实物 / 查验状态合并到右侧快捷按钮里;同一条目有多张付款截图时,付款按钮直接显示张数。不再重复显示齐备 / 部分材料徽标;卡片优先显示实际所属的批次名称,没有批次时不占位置。启用实物图要求时,详情按钮缩短为“详情”并与实物按钮同排;未启用且条目没有既有实物图时,卡片入口和详情材料分组都隐藏。
方案设置保存抬头、新建默认值和材料要求,并形成新修订。旧条目只在用户明确预览并应用重绑定后改用新规则。材料齐备与本次可导出分别计算:XML 可满足日常发票要求,需要票面的 PDF 输出另查发票 PDF。
9. 打印导出组件(可选安装,主要给运营组)
- 按需从 COS 下载安装;不装不影响核心录入功能。每个版本装进独立版本目录,安装成功后只保留当前版本,旧版本目录随即清理,避免历史版本累积占磁盘。
- 发布版核心调用数据目录中安装并校验过的独立组件;从源码开发运行时优先调用当前工作区组件,避免本地修改被历史安装版本遮蔽。
- 选择范围:跨不同人合并,也可只选某些人某些部分;支持批量与快速勾选。
- 输出的名称、数量、ID、模板和默认选中项来自方案。一个方案可以声明多份 Word,也可以只输出 PDF;不要求文档叫“报账说明”或“验收单”。
- 材料 PDF 按声明选择角色、顺序、A4 图片布局和编号。BITFSAE 默认按条目连续排列,付款截图横向 A4 每页两张;其他方案使用自己的配置。图片转 PDF 时 JPEG 原样嵌入,不解码也不重新压缩,其他格式转成 RGB 后直接交给 reportlab;reportlab 的 ASCII85 外层关闭,生成更快、占用更少,文件更小。
- 通用材料 PDF 供跨方案和未安装来源团队包的资料使用,按真实主体强制拆分并选择内置及自定义材料。核心提供按发票、付款截图、查验单、实物图和其他材料单独拼接的输出;只有 XML 时跳过票面,保留其余可打印材料。界面只列出所选条目中实际存在、可打印的材料种类(发票要求有 PDF),没有可用材料时整段不出现。界面将方案输出与通用等价项合并,生成方式收进「扩展选项」;相同内容的默认总览不再提供重复方式,保留方案自定义的不同输出。
- 查验单空白尾页筛选属于单次输出选择,收进「扩展选项」的对应材料 PDF 分组,各项分别选择,组件支持时新开窗口默认开启,可取消,随导出任务保存。只筛选
inspection_pdf的连续尾页,至少保留第一页;接受无绘制内容,或纸边小字号的重复页眉页脚与页码。对前一页末尾有「备注」标签的查验单,还识别空备注栏跨页:尾页仅含页顶灰色细矩形边框,以及可选的「备」「注」「备注」标签;读取 RGB / ICCBased 色彩空间、坐标变换与矩形裁剪,忽略白色背景和页外边框。图片、表单、其他图形、正文、批注及无法判断的页面保留,不按文字数量删页。筛选用现有 pypdf,在页码计算和编号之前执行,不写回附件,不改绑定包及附件包。 - Word 使用纯数据上下文和受限
docxtpl模板。历史条目缺明细时,导出投影可按条目固定识别上下文安全重解析原 PDF,不写回数据库。仍无明细时使用标记清楚的汇总行;单位和数量保留空值或采用包声明的缺省值。 - 预检按本地方案、修订、主体、收款对象和必要批次分组。材料、审核人、收款对象、金额和方案必填信息缺项只作提醒;缺失金额保留空值。PDF 按实际资源筛选,缺失、无效和不支持的材料跳过;空组不进入输出计划,不生成占位页。路径、上下文结构、模板、资源摘要和组件能力等技术错误仍阻止执行;所有计划文件成功后才发布任务结果。
- 历史任务保存当次数据和资源摘要。重新生成读取原快照,附件缺失或变化时说明原因,不以今天的数据冒充原件。
- 初始任务记录文件写入失败时,数据库任务标为
failed,清理半写文件并使原预览失效;数据库快照和原始材料保留,恢复写入条件后可按原快照重新生成。
10. OCR 识别组件(可选安装)
已实现。 核心另有一层轻量的系统原生 OCR 兜底,仅用于查验单 PDF 发票号归属确认,不用于重识别发票明细;通用发票识别由本组件承担。
默认核心的发票识别仍走 XML 优先、PDF 文本其次,不打包阿里云 OCR SDK,保证体积小(见第 3 节)。阿里云识别作为独立可选组件,从 COS 按需下载;识别调用移植自参考仓库 engine.py 的 parse_aliyun_ocr_invoice,并按当前 API 文档修正字段名(purchaserName / purchaserTaxNumber / specification 等)。
定位与依赖下沉
- 归入可选组件层,与「打印导出组件」并列;组件独立版本、独立更新,安装到
components/ocr/<platform>/,更新对话框单独一行管理。 - 阿里云 OCR SDK 与拆页所需的
pypdf(见requirements-ocr.txt)随组件安装,不进核心包。 - 组件进程接口与打印组件同构:
--input/--resultJSON 文件 IPC +--self-test自检(不联网)。核心通过services/ocr.py适配层探测(python / external / missing / repair 四态)与调用。
调用方式:用户自填阿里云 Key
- 用户在「设置 → 阿里云 OCR」填写自己的
AccessKey ID / Secret;不内置密钥、不走统一云端中转。界面建议使用只授权「文字识别 OCR」的 RAM 账号 Key 以限定泄露损失面。 - Key 存本地 SQLite
meta(tidoc.ocr.accessKeyId/Secret),不写入导出、不随绑定包外传;界面只显示掩码,更换时需完整重填 ID 和 Secret。 - 密钥通过权限 600 的临时 input.json 传给组件子进程,不进命令行参数(避免
ps泄露)。 - 未装组件或未填 Key 时,云识别入口引导安装 / 填写,不静默失败。
触发时机:只有用户点击,不自动花钱
- 批量:选中工具条「云识别」按钮 → 预检确认对话框(发票张数、按 PDF 页数计算的实际调用次数、计费提示、跳过原因)→ 逐张识别并汇报进度。
- 单条:条目详情「阿里云识别」区块、条目右键菜单。
- 建议条:识别提醒视图顶部提示「N 条可用云识别补齐」并一键执行——自动建议、手动触发,替代早期的 auto/always 档位设想(付费接口不在用户无感知时调用)。
- 已有 XML 权威数据的条目默认跳过(可勾选「仅作比对」纳入);无发票 PDF 的条目自动跳过;多选时默认跳过发票文件未变化且已有结果的条目,可取消跳过后重新识别。
结果持久化(防重复计费)
- 单页发票调用一次;多页 PDF 在组件内临时拆成单页逐页调用,全部成功后按原页序合并明细,再对整张发票做金额闭合。紧随商品、名称为空且金额为负的折扣行并入上一商品;纯品名续行只有在下一条负数折扣的完整名称吻合时才补入上一商品。重复名称仅折叠两个完整的带分类商品名称,分类与品名相同时保留原值。任一页失败则整张失败,不保存残缺结果。
- 核心与组件共用仅依赖标准库的
tidoc/ocr_normalization.py。查看、比对和采用旧结果时,按当前规则在本机整理已保存的原始明细;不调用 SDK,不改原始响应、历史解析结果或调用次数。原文损坏或缺失时保留历史解析结果。 - 每次识别(含失败)都追加写入
ocr_results表:原始dataJSON、解析快照、发票文件 sha256、实际 API 调用页数、金额闭合结果、待确认差异列表、时间;自动补齐时同时保存字段及明细的补齐前 / 补齐后快照,详情直接展示。 - 结果与识别时的发票附件 sha256 绑定;发票文件被替换后旧结果标记过期。
- 阿里云结果随
.tidoc绑定包迁移,导入后保留“已识别 / 待确认”状态和详情;导入记录与本机实际调用分开计数。设置中展示本机累计调用次数,方便对账;重复识别不覆盖历史。
结果应用:软件结果优先,云端补空与比对
- 自动补齐:本地为空的比对字段(发票号、日期、销售方、价税合计、购买方抬头、税号;抬头
title关系分区隔离,绝不参与 OCR 采用)直接填入,记[阿里云OCR]留痕。 - 软件优先:销售方和明细不由阿里云自动覆盖或补齐。销售方全角 / 半角标点视为一致;规格型号不参与差异判断。
- 待确认:发票号、日期、总额、购买方相关字段的非空冲突,以及名称、单位、数量、金额或行数有任何差异的明细,只在详情「阿里云识别」折叠区展示,由用户逐项或整套采用;条目卡片挂 OCR 徽标直到处理完。销售方冲突标成「保留软件值」,不产生待确认徽标。差异判定只看云端确有值且与软件值不同的单元格:云端为空的单元格不算差异(没有可采用的值),数量按数值比较(2 与 2.00000000 相同);云端整体未返回明细时不进待确认,详情提示已保留软件明细——此时没有可采用的行,进待确认会让徽标无法消除。
- XML 是税务口径权威数据:XML 来源条目只补空 + 比对。
11. 联网更新(腾讯云 COS)
- COS 放
manifest.json:核心与各组件的最新版本号、下载地址、SHA256、变更说明。 - 默认在启动完成后检查,并在应用持续运行时按到期时间继续检查(每小时最多联网一次,设置中可关闭)→ 比对本地版本 → 在设置旁出现下载动作 → 用户点击后立即显示连接状态并在后台下载 → 校验哈希与解包 → 动作切换为重启 → 退出旧版本、原位替换并自动打开新版本 → 首次启动显示升级前后版本和本次变化。Windows 核心更新在服务器支持时使用四路分段下载,各分段可从已有进度续传;服务器拒绝分段或并发连接失败时自动复用连续部分并退回单连接续传。界面分别显示下载速度与已下载大小、完整性校验和更新文件准备状态。顶栏和更新弹窗共用状态轮询,按实际下载量显示进度。检查本身不自动下载或安装;安装助手在新界面成功启动前保留旧版本用于失败回退。安装位置不可写或源码运行时退回平台安装包。
- 核心与「打印导出组件」独立版本、独立更新,避免整包重下;这是控制体积和更新负担的关键。
- 发布核心版本时不再同步抬高打印组件版本;只有
tidoc_print代码、打印依赖或核心与组件的 JSON 调用协议变化时才单独增加组件版本。 - 测试版通道:带预发布后缀的 tag(
v0.1.39-beta.1)只写入manifest-beta.json,不改写正式版清单;用户在设置里打开「接收测试版更新」后,客户端同时读取两份清单、每个组件取较新的版本(按 semver 比较,同版本正式版高于测试版)。关闭后只收正式版,不会降级,已下载未安装的测试版包被丢弃。默认关闭,稳定版用户不读测试版清单。测试版发布不会重新上传正式版清单已在使用的可选组件版本,避免覆盖其校验值对应的文件。 - 设置中只保留一个「软件与组件」管理入口,在同一行展示核心版本、打印导出组件状态和可用更新提示;两者不再以重复入口指向同一个管理页。
发布流程、COS 路径与客户端更新行为的运维细节见 docs/UPDATE.md,此处只保留设计意图。
12. 人性化与 UI 细节
识别提醒直接显示在条目上,按类别(发票金额、发票信息、抬头税号、付款截图、查验单、其他)标出,「识别提醒」视图可按类别筛选,逐条标为已核对后不再列出,改由「已核对」集中查看和撤销;卡片上的提醒标记可直接点开核对;可改和只读字段采用不同样式;人工修改字段带角标;抬头采用方案声明的语义色。拖拽、批量导入和导出等长任务立即显示阶段,完成或失败后切换为结果提示。
折叠标题共用固定尺寸和位置的三角箭头,收起时只保留紧凑标题行,并保留原生键盘交互。收款信息按内容控制窗口宽度,列表操作与默认选择沿用设置行。导出诊断按阻断、提醒和提示分组,同一问题合并显示,保留受影响发票信息;单份文件的名称直接放在勾选输出的右侧,窄窗口和多份文件换到下方,不与提醒混排:默认名称由后台预览得出(预览计划立即取消,生成时重新检查),分成多份的输出每份一行并标出抬头或收款对象。打开打印窗口时,默认输出选择采用本地方案的当前设置;实际模板、字段和材料规则仍按条目的固定修订解释。
12.1 外观主题
- 顶栏提供一个无文字的明暗切换图标:浅色时显示月亮、深色时显示太阳,点击后直接锁定为另一种外观。切换时从触发按钮位置用约 0.34 秒柔和揭示新主题,旧版 WebView 回退为短暂的颜色与表面过渡;系统开启“减少动态效果”时不播放动画。设置中的「外观主题」另提供跟随系统、浅色、深色三种模式,切换后立即生效。
- 深色主题延续安静、密集的工作台风格:画布与表面用纯中性近黑灰(不带蓝紫偏色),由画布、面板、浮层逐级提亮,去掉整体色雾;强调色使用天蓝(色相约 210°),避免薰衣草蓝带来的偏紫观感;状态色分别保留抬头、齐备、提醒、严重问题和人工修改的业务含义,不采用简单反色。详情里必需但未上传的材料组用琥珀色虚线框提示,重复的「待补」文字提示不再出现。
- 界面中的「tidoc」字样(顶栏与设置关于)使用自适应 SVG 字标:笔画颜色走
currentColor,浅色为墨色、深色为白色,随应用主题即时切换。 - 颜色由语义 CSS 变量统一映射,表单、日期控件、下拉选项与自绘的下拉浮层、滚动条、筛选激活态、选择态、拖拽态、设置、更新与 OCR 区域使用同一套主题。固定品牌图形和高对比提示使用独立颜色,避免被主题色误改。
localStorage保存一份启动前可读取的偏好,SQLite 通用偏好保存长期状态;页面在加载样式前解析主题,原生窗口也按已保存模式或系统外观选择初始背景,减少启动时的明暗闪烁。跟随系统模式监听操作系统变化,无需重启。- 深色仅影响应用界面。打印媒体强制回到白底黑字;实际材料由独立文件与打印导出组件处理,不修改发票、付款截图或查验单内容。
13. 开发进度
各阶段的实现状态见 README 状态节。本文档只保留设计意图与架构决策,不再重复维护阶段编号与勾选状态。
14. 已定决策
- 前端:PyWebView 原生窗口 + HTML(双击即开,体积小,界面自由)。
- 运行方式:同一用户只保留一个主实例;重复启动负责恢复并聚焦已有窗口,携带
.tidoc路径时转交给已有窗口,在当前弹窗结束后进入导入预览,避免多窗口并发编辑同一 SQLite 数据库。 - 改动检测:内置 HMAC 校验,发现手工改动和文件损坏,不防有意伪造。
- 数据存储:SQLite + 附件文件仓库。
- 不做多人云同步(单机 + 绑定包交换)。
- 命名:tidoc,后缀
.tidoc。 - 参考仓库
invoice2docx只读,engine.py移植复用。 - OCR:做成独立可选组件(不进核心包),用户在软件内自填阿里云 Key,仅用户点击时触发(批量 / 单条 + 识别提醒建议条),结果落库并可逐项比对采用(见第 10 节)。
15. 团队适配包
团队通过声明式适配包配置抬头、设置策略、附加字段、材料角色、条件规则和四类输出。公共格式由 schemas/team-adapter/1/ 定义。设置和能力由 tidoc/adapters/registry.py 注册;模板字段及文件名目录来自轻量资源 tidoc_print/context_fields.json,核心与组件读取同一目录。CLI、示例和协议说明见 docs/adapters/。
包加载器检查 JSON Schema、跨文件引用、资源路径、DOCX 结构和能力声明。规则以纯数据表达,不执行适配包代码。方案修订固定在条目上,切换默认方案不会重解释历史条目。个人值、收款账号和历史记录保存在本地数据库,不随公共适配包分发。
应用中的识别和校验显式接收条目修订上下文。engine/validator.py 保留旧独立调用所需的名称及税号常量,但从同一 BITFSAE 内置 scheme.json 读取,不维护学校或税号的字面量副本,也不用于替代应用上下文。
核心发布资源包含 schemas/team-adapter/1/、tidoc/builtin_adapters/ 和共享字段目录。通用包与 BITFSAE 包由同一加载器校验。IPC v2 由核心传入 JSON 上下文和资源表,组件不读取数据库或重新选方案。旧 IPC v1 转换到同一 v2 路径,仅为兼容旧 BITFSAE 请求保留内置模板和组织设置资源。打包位置及自检要求见更新说明。
核心的四类输出在预检中使用共享 context.schema.json 校验完整上下文;打印组件在渲染前再次执行同一检查。源码与外部进程执行相同校验,v1 转换结果也进入此路径。Schema 检查结构、类型和必需字段;资源路径、主体隔离和模板字段权限继续分别检查。缺少 jsonschema 或 context Schema、Schema 损坏时,组件停用 DOCX 和 PDF 渲染能力,自检失败。核心自检也检查该资源。校验诊断只报告 JSON Pointer 和约束,不回显账号、备注等无效值。核心预检把顶层校验与 entries、rows、diagnostics 数组项拆开:顶层按跳过数组项的 Schema 校验,每一项按对应的 $defs 定义单独校验,并按内容摘要记住结果,同一条目出现在多个输出或多次预检中时只校验一次,报告的约束和位置与整体校验相同。导出窗口每次改选项都会重新预检,因此 PDF、图片能否打开的检查按文件路径、大小和修改时间记住结果;同一次预检里每个输出的方案范围和模板引用字段只计算一次。
共享 Schema 用 $defs 复用条目、行、诊断及齐备结构。export.options 和 completeness 只接受正式声明的属性,未知内部字段不能进入公共上下文。
打印组件 --self-test 通过正式 IPC v2 在临时目录生成 DOCX 和材料 PDF,实际加载并使用渲染依赖。它核对 DOCX 中的中文及金额文本,生成包含发票 PDF、图片和编号的材料 PDF 并检查两页结果,随后清理临时目录。依赖能被定位但不能实际加载时,自检报告失败。自检流程及成品验收边界见更新说明。
批次投影仅提供 ID、名称、文本备注和当前组字段;缺失备注转为空字符串。数据库中的 output_settings、updated_at 等内部属性不进入模板上下文。批次与本次设置先由编排器解析,再投影当前输出的有效选项。
输出选项按核心缺省、包定义、本地方案、批次和本次导出逐层解析,固定值和核心不变量最后检查。同一修订的两个本地副本分别保存字段及收款选择。前端负责提供可达的填写入口,后端负责类型、可见条件和必填校验;界面实现与验收状态见 README。
默认输出遵守“缺少键才继承”的规则,显式 [] 表示全不选。本次空选择也不会恢复默认勾选;默认来源及分组选择的完整语义见输出说明。
导出编排器按实际工作更新资源核对、核心 Excel/ZIP 生成、Word/PDF 生成、产物检查和原子保存阶段。前端每 400 ms 查询 get_export_progress(job_id),接口只读取有界内存状态,不访问数据库、不等待长导出持有的 _api_lock。取消接口同样不等待该锁;核心写出器完成当前有界步骤后检查取消,打印进程沿用已有取消与超时机制。界面按可用的完成数显示进度,不推算 Word/PDF 的虚构百分比。
输出预检和重绑定预览返回时,前端核对表单版本及对话框是否仍打开。用户改选择或关闭窗口后,旧响应不覆盖当前表单,也不启用生成或应用按钮;旧输出预览及时取消。重绑定目标方案的异步加载同样核对请求序号和当前选择,丢弃过期结果。
python -m tidoc.adapter_tools 提供源目录初始化、校验、规则说明、fixture 渲染、样例测试、定义差异和严格打包。打包含 DOCX 的适配包时必须安装打印依赖,并以 fixture 完成真实渲染。自动渲染检查不替代在 Windows、macOS 办公软件中人工检查版式。
维护边界
桥接接口按报账方案、官网查验、软件更新和二维码取票拆分,由 Api 汇集并显式暴露继承方法。前端的取票流程与绑定包导入独立成脚本,共用现有窗口状态;绑定包写入分为单条恢复、批次分配和外层事务。异常按可恢复的文件、格式、网络错误捕获;桥接入口、逐条批处理和系统组件边界保留兜底并报告错误。事务和文件补偿捕获 BaseException 后回滚并重新抛出,防止中断留下半份材料。
前端回归优先在 Node 中运行真实函数并检查状态、交互与桥接调用。源码断言仅用于资源打包、脚本加载顺序、样式约束等明确契约,不再以函数体的字符串片段代替行为测试。打印组件能力查询只缓存确定结果;超时和启动失败在下次查询重试。
取票任务各自持有取消信号,下载读取时检查,取消会关闭活动响应或终止系统 curl。XML 与 PDF 并行下载,共用一次参数查询;长度已知时按完整长度读取,长度未知时 PDF 读到 %%EOF、ZIP 读到中央目录结束记录就停止,不再等连接关闭;连接中断或 5xx 在总时限内自动重试。连接建立前仍受网络超时约束,已发出的平台请求无法撤回;前端忽略迟到结果并回收文件。重试沿用已校验的取票链接,再次检查地址限制,不增加后台请求。
16. 文档站
- 定位:面向使用者的文档站(https://tidoc.bitfsae.com)含简介、开始使用、使用指南、更新与组件和常见问题,另设「开发相关」给开发者。读者大多不了解内部逻辑、代码和内部术语,写作规则见 AGENTS.md 的 Documentation site 一节。
- 技术:VitePress,源码在
docs/,依赖只写在docs/package.json,不改变 Python 应用结构;node_modules和构建产物不提交。 - 内容归属:使用说明只写在站点页面(
docs/intro、start、guide、update、faq),截图放docs/public/images/,只用虚构数据。设计取舍留在本文档,发布与运维细节留在 docs/UPDATE.md。DESIGN.md、CONTRIBUTING.md在仓库根目录,由docs/dev/下的页面嵌入;CHANGELOG.md也留在根目录,更新日志页在构建时解析它(docs/update/changelog.data.ts)并按版本显示成时间线,条目文字原样使用,不在站点里另存一份;docs/adapters/与UPDATE.md留在原位,由站点配置的 rewrites 挂到「开发相关」下;实施状态以 README 状态清单为准,历史实施记录通过 Git 历史查阅。这些文件之间的相对链接在渲染时由docs/.vitepress/repo-links.ts改写为站内或 GitHub 地址,源文件不变。 - 部署:腾讯云 EdgeOne Pages 连接 GitHub 仓库,Root Directory 为
docs,构建配置在docs/edgeone.json,main更新后自动构建发布。不使用 GitHub Pages,也不经过官网服务器。项目、域名和证书由维护者在腾讯云配置。 - 下载入口:「下载与安装」页的下载按钮(组件
docs/.vitepress/theme/components/TidocDownload.vue)指向官网的下载网关https://www.bitfsae.com/api/downloads/tidoc-core/{windows|macos}。网关读取img.bitfsae.com/tidoc/manifest.json后跳转到最新版安装包,所以发新版时文档站不用改。manifest.json没有开放跨域读取,页面因此不显示版本号和文件大小;需要时由维护者在对象存储上开放跨域,再让组件读取清单。GitHub Releases 和官网首页入口保留为备用。 - 构建检查:死链接和缺失的截图会使构建失败,修改文档后先运行
cd docs && npm ci && npm run build;.github/workflows/docs.yml在文档相关文件变化时用同一命令构建一遍,合并前暴露这些问题。 - 搜索:使用 VitePress 本地搜索。它默认只按空格和标点切词,一整句中文会成为一个词,所以
docs/.vitepress/search-tokenize.ts把连续汉字切成相邻两字的组合,构建和浏览器两端使用同一个切词函数。
打印组件通过 render_features: ["incomplete_payee"] 声明缺收款对象时的 Word 生成能力。收款对象为空时,模板中已声明字段的空父对象按空值读取;字段拼写错误和缺失字典键仍使用严格校验。核心预检与执行都核对能力,避免旧组件在确认后才失败。
打印导出扩展选项采用紧凑双列表单,标签、控件和间距统一;窄窗口改为单列。重复的默认来源前缀和常驻解释不占用独立行,来源标记放在当前选项末尾,细节用按需提示。金额口径仅对 Word/Excel 显示;选中范围没有图片材料时不显示图片布局。
