order_system/运行与升级说明.md

# 采购订单系统 v4：运行、升级与验收

当前支持采购订单生成、单次内部审批、企业微信群审批通知、公司 Wi-Fi 内手机审批，以及付款、收票和交货跟进。未接入金额分级、组织架构或第三方电子签章。

## 新电脑首次运行

1. 安装 Python 3.11 或更高版本，在项目根目录执行 `python -m pip install -r po_app/requirements.txt`。
2. 执行 `python po_app/app.py 8080`，或双击 `po_app/启动.bat`。
3. 用浏览器打开 `http://127.0.0.1:8080`。首次运行跳转到管理员初始化页面。
4. 在运行系统的电脑上读取 `po_app/instance/setup.token`，把初始化口令填入页面，设置管理员账号和密码。不要发送该文件给无关人员。
5. 管理员在“用户”页新增制单员、审批员，两个环节分配给不同人员。新增账号首次登录必须修改初始密码。
6. 录入真实供应商和物料，再开始制单。新数据库不再预置演示账号、演示供应商或假银行信息。

系统使用 Waitress 提供服务。源码和 EXE 均支持 `PO_DATA_DIR` 指定数据目录；未设置时分别使用 `po_app` 目录和 EXE 所在目录。`PO_HOST` 默认 `0.0.0.0`；端口已占用时启动程序会在 8120 之前尝试后续端口，以控制台打印地址为准。

多台电脑协作时，在一台固定电脑运行服务，其他电脑访问这台主机的局域网 IP 和实际端口。不要每人启动一套独立 EXE，否则各自数据库互不相通。关闭服务主机的程序会使其他电脑暂时无法访问。

单文件 EXE 位于 `dist/博特维采购订单系统_单文件版.exe`，打包步骤见 README。使用时无需安装 Python，双击默认自动打开浏览器；首次初始化口令位于 EXE 同目录的 `instance/setup.token`。可设置 `PO_OPEN_BROWSER=0` 禁用自动打开浏览器。旧 EXE 不会因源码更新而自动升级。服务若经过 HTTPS 代理，可设置 `PO_HTTPS=1` 启用 Secure Cookie；纯 HTTP 局域网环境不要设置此项。

## 升级已有数据

1. 关闭旧版本服务，并妥善备份原数据目录。不要把旧程序和新程序同时指向同一数据库。
2. 更新源码并安装依赖，使用相同数据目录启动。
3. 程序首次升级已有 `instance/po.db` 时会先创建 `po.db.pre-upgrade-时间.bak`，再在事务中增加所需字段并迁移金额。原来的单号、订单、明细和日志保留。
4. 如果检测到重复单号，程序会停止升级并列出冲突，原数据不改动。先由业务负责人确认正确单号后再处理；系统不会自行给历史订单改号。
5. 从最初的旧版升级时，旧登录失效，账号须修改密码；从 v2 升级到 v3 时，原主管角色改为审批员并使其旧登录失效，其余账号保留当前密码策略。请核对账号角色及实际使用人。
6. 升级前没有记录的提交快照无法补造。历史日志仍可查看，后续提交和审批会形成新快照。需要保存旧的正式文件时，应将原导出文件与旧数据库备份一起保管。

升级后金额在数据库内采用整数存储：数量、单价放大 10000 倍；行金额和总金额以分保存。旧版小数值按四舍五入迁移至对应精度，历史批准金额不自动按新规则重算。后续再次提交或审批时会按新规则校验并计算。

新版程序会生成独立的 `instance/session.key`，不再使用源码固定密钥。也可通过至少 32 字符的 `PO_SECRET_KEY` 提供部署密钥。更换密钥会使全部旧登录失效。

### v2 两级审批合并为 v3 单次审批

- 升级同样先备份数据库，再在事务中迁移。原“主管审核”账号统一改为“审批员”，原“经理批准”账号也显示为“审批员”；由任一合格审批员一次确认完成审批，制单人不能审批自己的订单。
- 原“待主管审核”和“待经理批准”均转为“待审批”，不会自动通过。两种状态的订单版本号都会递增，旧页面须刷新；原“审核通过”接口停止受理，避免将旧的一审确认误当成最终审批。
- 既有审核人、审核时间和历史日志保留，在详情页标为“旧流程审核（历史）”。已归档 PDF 的文件内容、摘要和模板版本均保留，不给旧文件重新换章。新完成的审批使用单枚“采购专用章”。
- 企业微信只保留“审批通知群”和可选的“结果通知群”。默认沿用原经理批准群；若原批准群为空，则沿用原主管审核群。请管理员核对群成员，按需把原主管加入新的审批群。
- 尚未发送且仍有效的旧待办改用统一审批群；过期、已处理的旧待办及旧测试通知取消。发送成功的通知记录保留，历史操作不补发。已达到重试上限的记录仍需管理员检查后手动重试。
- 升级不会修改已完成审批的业务状态。降级时必须停服务并恢复升级前备份，不能直接用 v2 程序维护已转换为单次审批的数据。

## 操作规则

### 管理员兼任审批员

管理员账号自带审批权限，可以由同一个人兼任管理员和审批员，无需另建审批账号。管理员可以审批其他账号制的订单；自己制的订单仍需另一位审批人员完成审批。

### 付款、收票和交货跟进

- 审批通过后，在订单详情的“付款与交货跟进”中登记。制单员只维护本人订单的预付款标记、收票情况、交货情况和采购跟进备注；管理员也可维护。审批员及管理员可登记付款状态、实际付款日期和付款备注。
- 收票为未收票 / 已收票；付款为未付款 / 部分付款 / 已付款；交货为未交货 / 部分交货 / 已交货。付款和交货独立维护，因此已付款但未交货、交货后仍有尾款等情况都可记录。
- “已收票”指公司已收到供应商发票。“已收票待付款”统计已收票且付款状态为未付款或部分付款的有效订单；“需预付款”统计已标记提前付款且未付清的有效订单。预付款标记由制单员根据实际安排维护。
- 部分付款、部分交货是整单状态，不计算逐笔付款金额或逐项到货数量；具体批次、预付款比例或尾款说明可填写在备注中。登记部分付款或已付款时须填写实际付款日期。
- 工作台显示各类订单数量及最近 12 张已审批订单，点击分类可查看完整筛选列表。统计遵守用户可见范围，只计审批通过的订单；各分类可能重叠。Excel 台账包含对应状态、日期、备注和待核对提示。
- 修改保留操作人、时间及前后状态。回退已收票、已交货或付款状态时须填写更正原因；旧页面提交会要求刷新，避免覆盖他人刚保存的内容。
- 跟进更新不修改审批结论、审批章或已归档 PDF。复制订单时清空跟进信息；作废后保留跟进历史并停止修改。发起变更重审后保留已发生的事实，再次提交后提示对应经办人重新核对；核对前不将旧标记计入对应完成或待付款分类。

### v3 升级到 v4

先关闭旧程序并备份原数据目录，再在原服务电脑上替换 EXE。启动时会自动备份数据库并增加跟进字段，保留账号、密码、审批、日志和归档 PDF。旧订单的付款、收票和交货情况显示“未登记”，由经办人补录，避免把未记录的历史情况误认为未付款或未交货。更新只需在服务主机进行，其他电脑和手机继续使用原内网地址。

### 制单和审批

- 制单员只可访问自己的订单，审批员和管理员可查看订单全集；读取、复制、PDF、台账和统计遵守一致的数据范围。
- 制单员及管理员可制单。审批员一次确认即可完成审批，但不能审批自己制的订单；管理员也遵守分工限制。
- 驳回只能由当前审批环节的合格人员执行，并必须填写原因。
- 编辑页使用“保存并提交审批”一次保存当前内容并提交。“保存草稿”允许尚未填写完的内容；负数、非法数字和过多小数位仍会被拒绝。
- 正式提交需要供应商、需方、付款方式、交货地点、采购日期，以及有效物料、单位、正数量、正单价和交期。当前规则不允许零价订单；若需要样品或赠品，须先定义单独的业务规则。
- 数量和单价最多四位小数。每行金额按数量乘单价四舍五入到分，合计为各行金额之和；页面和 PDF 均按此口径展示。
- 制单人可撤回待审批订单，修改后重新提交。原提交内容保留在版本记录中。
- 已批准订单由制单人或管理员发起变更后回到草稿，原批准停止使用，必须重新审批。已发出的旧文件不能远程撤销，应另行通知接收人。
- 草稿、驳回单可由有编辑权限的人作废；已批准单由审批员或管理员作废。作废订单不可编辑，导出显示作废水印。
- 每次提交产生不可通过业务页面修改的内容快照。批准时保存 PDF 文件及摘要，后续下载复用该文件；页面图形印章表示内部审批确认，不是第三方证书数字签名。
- 用户页支持新增、编辑、重置密码、启用和停用。改密或修改用户资料会使其原有会话失效；系统必须保留一个启用的管理员。

## 备份和恢复

运行 `python tools/backup_db.py` 创建一致性数据库备份，文件位于 `po_app/instance/backups/`。自定义数据目录时使用 `python tools/backup_db.py --data-dir 数据目录`。备份包含订单、日志、版本、已归档的正式 PDF，以及通知设置和发送队列；工具在备份后执行 SQLite 完整性检查。Webhook 发送凭据保存在本机数据库中，未额外加密；配置通知后，数据库和备份应仅允许受信任管理员读取，不要提交到 Git 或公开分享。

同时定期保管数据目录内的密钥、需要保留的上传文件和旧版导出文件。备份应保存到另一台电脑或独立介质；仅在同一磁盘上留副本不能应对磁盘故障。

恢复时先停止服务，保留当前数据目录副本，再用经确认的备份替换 `instance/po.db`，启动后核对订单数量、最新单号、关键订单明细和审批记录。降回旧版程序时，应使用升级前备份；新版固定精度字段不能由旧版程序维护。

恢复旧备份可能把已发送通知恢复成待发送状态。正式启动前，应在禁用外网发送的维护环境中核对并关闭通知配置，再按需启用，避免历史通知重发。

## 企业微信通知与公司 Wi-Fi 手机审批

### 服务主机与手机

1. 在公司内固定一台服务电脑，通过 `python po_app/app.py 8080` 或配套启动程序运行。给它设置固定内网 IP 或 DHCP 地址保留，例如 `192.168.1.10`，保持开机并关闭自动休眠。
2. Windows 防火墙只需允许公司专用网络内的手机和电脑访问实际服务端口。不要设置公网端口映射。`PO_HOST` 使用默认 `0.0.0.0` 或主机内网 IP，不能只绑定 `127.0.0.1`。
3. 手机连公司 Wi-Fi，在浏览器访问 `http://192.168.1.10:8080`。须使用实际 IP 和控制台实际端口；不要把示例地址直接当作本机地址。访客 Wi-Fi、无线客户端隔离或不同 VLAN 可能需要网管开通相互访问。
4. 审批员使用自己的系统账号。企业微信链接打开后如要求登录，登录及首次改密后会回到原订单。只打开链接不产生审批；仍需点击盖章再确认，或填写原因驳回。明细表可在卡片内左右滑动。

本方案通过公司内网访问订单，不提供外网审批和企业微信免密登录。手机离开公司网络后仍可能收到企业微信通知，但订单链接需回到公司 Wi-Fi 后打开。企业微信客户端若限制打开内网 HTTP 链接，可复制链接到手机浏览器访问；实际客户端行为须用公司的手机现场确认。

### 配置企业微信群

1. 为审批人员建立一个企业微信群，将需要接收待办的审批员加入该群。按 [腾讯云官方 Webhook 获取说明](https://cloud.tencent.com/document/product/1759/128391) 在 PC 企业微信的群管理中创建自定义消息推送并复制 Webhook。
2. 管理员进入系统“通知配置”，填写手机可访问的内网根地址以及审批通知群的完整 Webhook。内网地址与该群均配置后才能启用；结果通知群为可选项。
3. 结果群接收批准、驳回、撤回、变更和作废的通知。需要让制单人员收到结果时，将其加入该群；当前实现按群推送，不按订单制单人私信。
4. 保存并启用后，点击“测试审批通知群”，在“最近 100 条通知”刷新查看状态，并在真实群内确认收到消息。保存配置本身不会发送测试消息。
5. 用一张测试订单完成提交和一次审批，在手机上确认制单与审批分工、登录回跳和正式 PDF。通知中的待办若已处理，打开时显示最新状态，不会重复审批。

Webhook 保存后不再回显；留空保留已有值，“清除此群配置”才会删除。更换主机 IP 或端口时同步修改内网地址。域名模式需要由公司 DNS 解析到内网主机，程序不会替网管验证 DNS 或配置防火墙。

服务主机需要能够向 `https://qyapi.weixin.qq.com` 发起 HTTPS 请求；公司完全断网时可继续内网审批，但无法推送企业微信。无需企业微信从公网回调本系统。通知正文仅含单号、环节、提交版本、记录时间和链接，不发送明细金额、银行信息、审批意见或密码。消息格式遵循 [腾讯 CloudBase 的企业微信群机器人接口说明](https://docs.cloudbase.net/recipes/connect-wecom-webhook-cloud-function)。

### 发送队列与重试

- 通知默认关闭。只有启用后发生的新状态变更进入队列，历史操作不补发。新增配置和队列表会在启动时自动建立。
- 待办通知随审批事务一起保存，后台发送失败不会撤销订单提交或批准。启动主程序会自动运行发送线程；仅导入 `app` 用于其他 WSGI 部署时，需显式调用 `start_notification_worker(app, Session)`，并在退出时设置返回的停止事件。
- 本实例所有通知群合计每 4 秒最多尝试一条。建议给本系统专用机器人，避免其他系统共用机器人导致超频。
- 首次失败后分别等待 30、60、120、240 秒重试，累计最多 5 次；到达上限后由管理员检查网络、机器人状态和配置，再点击“重试”。
- 发送前核对待办的订单状态与提交版本，已撤回、已处理或重提的旧待办跳过。批准、驳回等结果通知记录发生时的事件，订单实时状态以链接页为准。
- 禁用通知会暂停发送，重新启用后继续处理有效的队列项。移除某个可选群配置后，其未发送通知会跳过。修改群地址后，未发送通知使用新的群地址。
- 网络超时或进程中断可能发生“企业微信已收到、系统尚未记为成功”，因此重试存在重复消息的可能。订单操作仍受登录、CSRF 和版本校验保护。

### 电子章及文件

手机和电脑审批使用同一套服务端逻辑。审批员点击“加盖采购专用章”并确认审批通过时，记录审批人、时间和日志，生成带一枚红色“采购专用章”的正式 PDF，连同 SHA-256 摘要保存到该次提交版本中，后续下载校验摘要并复用同一文件。

采购专用章内不显示审批员姓名和日期。审批人及时间保留在订单审批记录和 PDF 的签署信息中，便于追溯。章面调整适用于新生成文件，已归档 PDF 保持原文件。

图章外圈上半圈为“苏州博特维智能科技有限公司”，下半圈只显示印章号码“3205070994140”，两侧圆点分隔，环绕一圈，不带文字前缀或冒号。PDF 图章尺寸为 32 mm，公司名参考实物章使用细长仿宋字形，横向收窄、纵向拉长；号码使用较小的无衬线字体，缩短所占弧长。中间保留五角星和仿宋“采购专用章”。页面使用 SVG 预览，与 PDF 共用排字坐标和字形缩放参数；中文优先使用系统仿宋，缺少时回退到宋体。公司名读取订单的需方名称，印章号码单独设置，不使用或修改订单税号。

变更重审会清除当前审批信息，保留原提交和归档记录；作废单的当前导出带作废水印。已下载或已发给供应商的旧文件不能远程收回，须另行通知接收人停止使用。这些章是内部审批图形章，当前没有接入公司印章图片、第三方签章服务或证书数字签名。

## 开发验收

```text
python -m pip install -r requirements-dev.txt
python -m pytest tests -q
node tests/test_money_js.cjs
python tools/browser_smoke.py
```

浏览器检查使用本机 Microsoft Edge 的无界面模式，不操作用户已打开的浏览器。会启动临时本地服务、创建临时数据库，输出截图和 PDF 样本到 `tools/out/ui-check-*`。审批员使用手机尺寸与触控模拟；通知使用虚构 Webhook 和模拟发送器，不向真实企业微信群发送。其他单元和接口测试也仅使用临时数据库。

原 `tools/e2e_test.py`、`run_check.py` 和测试入口已经转为调用隔离回归用例，不再依赖原开发电脑路径或在线业务数据库。

验收应至少覆盖：制单与审批两个账号完成正常流程、驳回重提、撤回、作废和变更重审；他人订单访问被拒绝；重复请求不重复建单；并发审批只有一次生效；无效输入不破坏原内容；中文 XLS/XLSX 日期；页面与正式 PDF 金额一致；旧数据迁移、自动备份和恢复核验。

## 本轮验证结果（2026-09-16）

- 76 项隔离回归用例全部通过，覆盖认证、权限、审批、精度、导入、账号维护、并发、迁移、备份恢复、付款交货跟进，以及通知事务一致性、失败重试、过期跳过、并发领取、凭据保护和登录回跳。
- Node.js 金额预览验证通过：逐行舍入合计、半分四舍五入、四位单价及非法数值处理。
- Microsoft Edge 无界面浏览器完成首次设置、用户创建、从订单链接登录及首次改密、采购单和委外单的手机尺寸单次审批、PDF 下载、通知配置和中文 XLSX 原生日期导入，未发现页面脚本错误。320、390、768 像素宽度下工作台、列表及订单页无整页横向溢出；宽表格可在卡片内滑动。
- 源码浏览器记录位于 `tools/out/ui-check-xiftbuej/`。模拟发送收到 1 条测试消息与 2 条批准结果，2 条已经完成的待办被跳过；未发出真实企业微信消息。
- PDF 最终样张已逐页检查。修正单价精度、大写金额尾缀、签署区换行和印章排字；调整委外规格列后，30 行验收样本为 2 页，大小写合计保持在同一页。
- Python 编译检查及 `git diff --check` 通过。新增 v2 到 v3 升级验证、旧审核入口保护、并发审批单次归档、PDF 生成失败回滚与单枚采购专用章检查。
- 去掉章内审批员和日期后，两类订单的审批归档用例及手机浏览器流程再次通过；已检查页面预览和 PDF 章面，章外签署信息与审批记录保留。
- 章面号码为 `3205070994140`，公司名按参考图改为细长仿宋字形，号码缩小并收紧排列。两类订单的审批归档用例及手机浏览器流程通过，页面与 PDF 样张已经渲染检查；图章放大图位于上述浏览器记录目录的 `seal-detail.png`。订单税号保持原值。

### v4 付款交货跟进及 EXE 验收（2026-09-16）

- 新增 10 项跟进用例及 1 项 v3 升级用例，76 项回归全部通过。核对了角色与订单权限、越权字段、CSRF、旧页面冲突、更正原因、工作台分类、台账导出、复制清空、变更后分角色核对和归档 PDF 保持不变。
- v3 升级到 v4 前自动备份，保留账号会话版本、审批状态、订单版本号、历史 PDF 及摘要；历史跟进状态初始化为未登记，重复启动不重复迁移。
- 新版单文件 EXE 位于 `dist/v4/博特维采购订单系统_单文件版.exe`。实际使用 EXE 完成两类订单的建单审批、制单员跟进、审批员部分及全部付款登记、工作台数量及筛选检查，320、390、768 像素宽度下无整页横向溢出。
- EXE 测试记录位于 `tools/out/ui-check-ni65n2lj/`，包含工作台、手机跟进表单和 PDF 样张。重启后付款交货标记保留，正式 PDF 摘要保持一致，通知发送保持关闭；全部测试仅使用临时数据。

### v3 Windows EXE 验收（2026-09-16）

- 使用独立 Python 3.11.9 / PyInstaller 6.22.0 环境，按项目依赖范围生成 Windows 64 位单文件 EXE。打包环境依赖检查通过；使用相同运行库版本的 65 项回归用例全部通过。
- 对 EXE 的独立副本实际执行首次设置、账号创建及首次改密、采购单和 30 行委外单的手机尺寸审批、正式 PDF 下载、中文 XLSX 日期导入、模板和台账下载；静态资源加载正常，无页面脚本错误。
- EXE 在中文路径下、不同工作目录及不含 Python 的 PATH 中启动成功，数据保存在 EXE 同目录。关闭并重启后，登录仍有效，两份归档 PDF 的 SHA-256 与重启前一致；数据库完整性检查通过。
- 测试记录及 PDF 样张位于 `tools/out/ui-check-vxzzkrvg/`。测试副本始终关闭企业微信发送，通知队列为空；测试进程已停止，交付的 EXE 目录不含测试数据库。

验证使用临时数据，没有对实际业务数据库执行升级。EXE 已完成本机验收，尚未进行真实局域网多机验收。企业微信源码测试使用模拟发送，EXE 测试关闭通知；真实 Webhook、公司 Wi-Fi 和手机企业微信客户端仍须按上述接入步骤现场联调；复杂审批规则和第三方签章平台尚未接入。