贸易备件 ERP 系统

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

摘要

• 本系统是一套面向贸易备件业务的轻量 ERP：覆盖报价 → 客户订单 → 背靠背采购 → 收货入库 → 库存与批次追溯 → 交货出库 → 退货 → 开票结算全链路，并配套经营看板、控制台待办、客户/供应商门户与外部接口集成。
• 技术栈为 FastAPI + SQLAlchemy + pymssql（后端）、Vue 3 + Element Plus + Vite（前端）、SQL Server 2025（数据库），单端口 8000 部署，前后端同源免跨域。
• 当前规模：数据库 96 张表 / 1556 列 / 167 个 CHECK 约束，菜单 233 项（页面 49 + 功能权限点 173 + 目录 11）；后端 Python 源文件 111 个，前端 Vue/TS 源文件 116 个。
• 质量保障：30 个验收脚本共 1129 条断言全绿，另有结构闸门（schema_guard）、权限巡检（perm_audit –strict）、真实浏览器截图取证三道门禁。
• 合理性结论：系统的核心设计（口径唯一真相源、不存第二份账、三层权限边界、软控优先、脚本化验收）是自洽且可维护的；本轮体检发现并修复了 3 处问题（1 处页面级崩溃、1 处门户数据泄漏、1 处门户误报），另有 8 项已知局限与建议在第 6.3 节列明。

目录

1  系统概述

2  数据库设计

3  部署与环境

4  核心业务流程

5  安全与权限体系

6  系统设计合理性评估

7  质量保障体系

8  接口集成

9  运维保障

10  使用指引摘要

11  交付物清单

附录 A  验收脚本基线全表

1  系统概述

1.1  业务定位与范围

系统服务对象为从事工业备件贸易的中小企业（单法人）。业务主线：销售侧从客户报价出发，确认后生成客户订单；采购侧按「背靠背」方式从客户订单一键生成采购订单，向供应商采购；货物入库后按批次管理库存（含效期与安全库存预警）；按订单交货出库并同步外发 ASN 报文；开票结算形成应收/应付台账并支持对账勾稽。内部用户通过浏览器操作，客户与供应商通过门户账号查看自己的单据与台账（严格的数据隔离与字段裁剪）。

系统同时提供：经营指挥看板（接单/发货/开票三口径）、控制台待办（9 组待办 + 8 项风险）、月别盘点、仓间调拨、借出归还、月结关账、单据打印、Excel 导入导出（含期初建账）、接口集成（Outbox 派发 / 重试 / 死信 / 日对账 / 报文归档）与全过程审计留痕。

系统主动脉

1.2  总体架构

系统采用前后端同源的单端口部署：前端构建产物（frontend/dist）由后端静态托管，浏览器只访问 8000 端口；接口走 /api 前缀，门户与内部账号共用同一前端，由后端按账号类型隔离数据。

1.3  技术栈

1.4  代码规模

2  数据库设计

2.1  分域 DDL（database/schema）

建表脚本按业务域拆分为 18 个文件，按文件名顺序执行；每个文件含幂等的建表语句与 CHECK 约束。结构基线（baseline_columns.json，96 表/1556 列/167 CHECK）由 schema_guard 冻结。

2.2  结构闸门（schema_guard）

• 只增不改：删表、删列、改类型、收紧可空、新增必填无默认 → 非零退出，禁止执行。
• 比对 CHECK 约束：枚举集合变小或交叉 = FAIL（防止状态枚举被悄悄改小）；变大 = ADD 放行；范围型降级为表达式比对。
• 交付前冻结基线：python scripts/schema_guard.py –freeze；用 –baseline 副本造破坏来验证闸门本身有效。

2.3  初始化与种子（scripts/init_db.py）

init_db.py 幂等可重复执行，流程：读 .env → 建库（若缺）→ 按序执行 18 个 DDL → 执行 20 个种子 SQL（字典、菜单、权限点、状态机边、演示主数据、对端配置等）→ 创建初始管理员 → 发号器对齐（seq_align 只增不减）。重跑 init_db 会把菜单授权恢复为种子口径（界面手工放宽的授权会被撤回），这是「种子即授权真相源」的设计。

3  部署与环境

3.1  交付包目录结构

3.2  环境变量（backend/.env）

复制 .env.example 为 .env 后填写；.env 含明文凭据，已在 .gitignore 中，绝不进入仓库与交付包。

3.3  安装与启动

• install.bat：建 venv → 装后端依赖 → 生成 .env → npm ci → init_db.py 建库建表；幂等，可重复执行。
• start.bat：起后端 8000（自动构建缺失的 dist；端口占用则不重复启动；健康检查通过后才开浏览器）。
• stop.bat：只杀命令行含 uvicorn 的 PID，不误杀其它占用端口的程序。
• 手动方式：uvicorn app.main:app –host 127.0.0.1 –port 8000（在 backend 目录下执行）。

4  核心业务流程

4.1  主流程总览

主链路：报价单（审批通过）→ 客户订单（确认）→ 采购订单（背靠背生成，备注自动净化不含客户信息）→ 到货收货（箱级收货，生成批次追溯节点）→ 库存（批次/仓别余额，效期与安全库存预警）→ 交货出库（扣减库存，同事务生成 ASN 报文）→ 开票结算（应收台账，勾稽核销）→ 对账单与月结关账。每一环节均受状态机约束（非法流转返回 409）、写审计日志（谁在何时改了什么）。

4.2  登录与工作台

登录页连续 5 次口令错误锁定 15 分钟；登录后进入工作台：顶部为 4 张概览卡（待处理/涉及金额/风险提示/今日登录），左侧为 9 组待办（报价审批、订单确认、采购收货、收货入库、盘点提交、已发未开票、借货未还、到货跟催等，按当前账号权限点裁剪），右侧为 8 项风险提醒（应收逾期、超信用额度、负库存、效期、安全库存缺口等）。右上角铃铛实时显示待办总数，点击直达对应单据。

图 4-1 登录页

图 4-2 控制台工作台：待办直达 + 风险提醒 + 系统概览

4.3  报价管理

报价单支持双价（销售价/参考成本价）与毛利率即时测算，审批通过后可一键转客户订单（幂等，重复转换不重复建单）。报价列表即见毛利率与审批状态；报价统计页支持按月份/客户/业务员等多维汇总。

图 4-3 报价列表（毛利率、审批状态）

4.4  客户订单

客户订单采用「头—行—子行」三层结构：子行是交货与批次关联的最小单位，拆分规则为「一行多交期/多批次时拆子行，子行拆分后不可改、作废后不复用」。订单确认后进入可交货状态；已交数量按实际出库单统计（不读订单上的冗余字段），与订单统计口径同源。

图 4-4 客户订单列表（毛利率列仅内部账号可见）

4.5  背靠背采购

从客户订单一键生成采购订单（背靠背）：逐行带出物料与数量；对供应商的备注自动净化（不含客户名称与客户订单号，防止客户信息外泄到供应链）；支持交期回复与到货跟催；采购收货按箱级计划收货，入库生成批次追溯节点。

图 4-5 采购订单列表（源订单号、币种、已收数量）

4.6  仓储与库存

库存按「物料 + 仓库 + 批次」三维管理：批次余额页展示现存量、可用量、锁定量的同时，展示批次效期（最早入库节点 + 物料保质期实时推算，不落库、杜绝双份账）与安全库存缺口预警。批次追溯页可沿入库→出库→调拨→退回的节点链路完整回溯每一批货物。仓间调拨不改变批次身份，发货记在途、收货才入账。

图 4-6 库存批次余额（效期与效期状态列）

4.7  月别盘点

按月建立盘点单，盘点期间软锁相关库存动作（排除本单自身与未来时间戳节点）；盘点行生成时以账面数量为占位，录入实盘后以 is_counted 标记账实可信度；提交后按差额自动生成盘盈入/盘亏出节点，成本差异进入库存成本明细。

图 4-7 月别盘点报表（期初/实盘/差异金额）

4.8  交货出库与结算

交货单审核后执行出库：扣减批次余额、生成出库追溯节点，并在同一事务内生成 ASN 发货报文（外部接口失败不影响业务主流程，报文进入重试/死信队列人工处理）。支持直发（不经库存）；退货分销售退货与采购退货双机制。开票按发票分摊金额到订单行形成应收台账，发票与台账金额可勾稽核销（差异实时计算并留痕，不做「已处理」假状态）。

4.9  统计报表与经营看板

订单统计提供接单/发货/开票三个口径（分别按下单日/发货日/开票日归属），口径写死在代码不做配置——保证所有人看到同一套数。金额一律不含税、税额单列；多币种按汇率折算；作废单不计入、已关闭计入；已交数量与发货口径一致。经营看板汇总 KPI、客户发货占比、物料发货 TOP、库存分布、交期达成率与风险提醒。

图 4-8 订单统计（三口径切换 + 交期达成率 + 明细）

图 4-9 经营指挥看板（KPI + 三口径趋势 + 风险区）

4.10  单据打印

报价/订单/采购/交货/对账单均提供 A4 打印模板：作废单据带水印标识、读取即写打印审计；对外单据按字段白名单输出（报价与订单不含成本毛利，采购单不含客户信息），浏览器打印或另存 PDF 均可直接使用。

图 4-10 销售订单打印模板（A4、含大写金额与签章位）

4.11  客户/供应商门户

门户账号与内部账号共用同一前端：门户只能访问白名单内的页面，查询范围被服务端强制限定在自己绑定的往来单位（越权访问返回 404，不泄露单据是否存在）；响应中的成本、毛利、采购价、供应商、信用额度等内部字段由中间件统一裁剪——「界面上没有」与「响应里没有」同时成立。

图 4-11 客户门户：仅见自己绑定的订单，无毛利率/拼单组列

图 4-12 客户门户订单详情：无成本/毛利/供应商，无内部动作按钮

5  安全与权限体系

5.1  三层边界

权限核对由只读巡检 perm_audit –strict 完成（角色授权 / 端点门控 / 门户白名单 / 脚本裸删 / CLI 闸门五类检查），作为交付门禁使用（有 ERROR 即失败）。

5.2  审计留痕

所有写操作（含登录取证与敏感查询）写审计日志：操作日志（账号/模块/动作/方法/IP/结果/耗时）、登录日志、状态迁移日志三类；单据修改记录字段级 diff（改前/改后值），查询接口直接回放。审计日志自身被导出时同样留痕（谁导走了日志）。

图 5-1 审计日志（操作/登录/状态迁移三类）

6  系统设计合理性评估

本章从架构角度回答「这套系统设计得是否合理」：先列支撑该结论的核心设计，再列体检发现并已修复的问题，最后列已知的不合理点/局限与改进建议。

6.1  合理且经过验证的核心设计

（1）口径唯一真相源

订单统计、经营看板、控制台待办、应收账龄、勾稽、信用与效期预警，全部调用同一批统计模块（如 sales/order_report.py、report/stock_aging.py），不允许各处自算一份。收益：任何口径修正只改一处，报表之间天然一致。这是报表类系统最容易腐烂的地方，本系统从结构上杜绝了。

（2）不存第二份账

批次效期实时推算不落库；月结关账只做写入闸门不做余额快照；单据变更留痕用字段 diff 写审计而不建版本表。凡是可以从既有数据推导的，一律不存副本——避免副本与真值漂移这一 ERP 系统最常见的腐化路径。

（3）只预警不拦截（软控优先）

信用超限、批次过期、安全库存缺口统一只提示不阻断，成功路径一行不改。业务规则变更（改为硬拦截）是显式决策，而不是 bug 修复——避免了「为了修数据顺手改业务」的失控。

（4）三层权限边界 + 错误分层

前端隐藏只是体验；服务端权限点/状态机/软删/CHECK/审计才是边界；脚本域有独立闸门。错误语义分层清晰：业务错 200+code=1、状态冲突 409、越权 404（不泄露单据存在）、系统错 500。

（5）对外纪律落在响应层

门户数据隔离不靠前端隐藏：服务端 scope 强制覆盖查询参数，响应中间件按黑名单递归删键。新加字段默认被兜住，不会因为某个新接口忘了裁剪而泄漏（本轮体检正因此发现并修复了打印页之外的接口泄漏）。

（6）软删 + 闸门 + 审计的组合

业务数据一律软删可追溯；数据库结构只增不改（schema_guard 把 CHECK 枚举纳入比对）；种子即授权真相源（重跑 init_db 收敛授权，杜绝权限漂移）。

（7）脚本化验收 + 真实浏览器取证

30 个 verify 脚本 1129 条断言随每次交付全量回归；关键交互必须 Playwright 真实浏览器取证并逐张人工复核截图。本轮体检证明其价值：API 全绿的页面上仍抓到一个真实的页面级崩溃。

6.2  本轮体检发现并已修复的问题

系统体检（S8.16）对 49 个页面做了真实浏览器巡检，逐页断言无 JS 运行时异常且关键内容渲染。结果如下：

6.3  已知不合理点与遗留风险

以下问题在体检中如实记录、未经处理（改配置或动数据均需业务确认后另行执行）：

7  质量保障体系

7.1  验收脚本基线

共 30 个验收脚本、合计 1129 条断言，覆盖每个功能切片；任何一次交付（含文档与配置变更）都跑全量回归，全绿才允许交付。断言一律写「包含/不少于」而非「等于」，保证新增切片不会让历史脚本误报。全表见附录 A。

7.2  三道门禁

• 结构闸门 schema_guard：表/列/PK/索引/CHECK 五类比对，只增不改。
• 权限巡检 perm_audit –strict：授权、端点门控、门户白名单、脚本裸删、CLI 闸门五类只读检查，ERROR 即失败。
• 截图取证：关键页面与交互必须真实浏览器截图并逐张人工复核；列表类断言配合几何断言（防止长表格/长抽屉被视口裁剪）。

7.3  回归纪律

回归脚本红了先查残留数据（时间窗断言容易被历史造数污染），确认是代码缺陷才改代码；每修复一处缺陷必须同步撤掉对应的「兜底断言」，防止兜底逻辑把回归吞掉。

8  接口集成

8.1  对端配置与协议分发

外部系统（EDI 报文、3PL 物流、SAP 财务等）在「对端配置」页维护：协议、发送地址、认证方式、超时与退避策略。协议由适配器层分发（MOCK 模拟对端 / REST·ODATA 真实 HTTP / AS2 预留返回明确未实现错误）。密钥只在配置里存环境变量名（secret_ref），真实值走环境变量读取——库里、接口响应里、日志里都不出现明文。

图 8-1 对端配置（协议、认证、超时退避、连通性测试）

8.2  Outbox 派发与死信

• 出库与 ASN 报文生成在同一数据库事务内完成（Outbox 模式），不会出现「业务成功但报文丢失」。
• 派发由显式触发（POST /int/dispatch），不起后台线程；业务拒绝（对端返回 accepted=false）一次判死信不耗退避，网络类错误按退避重试。
• 对端停用时派发记 skipped，报文保持待发——「没发」与「发失败」语义分离。
• 重放重置同一条报文而非新建；报文按月归档导出，删除需显式确认且不删仍被队列引用的报文。

8.3  日对账

按日生成收发对账（发货/收货/调整三类流水与本方单据逐一核对），差异清单进入日对账页人工处理；对账口径唯一来源于 reconcile.py，与报表统计同源。

9  运维保障

9.1  日常运维日报

ops_daily.py 一条命令完成：报文派发 → 接口归档 → 数据库备份 → 风险扫描，整批加数据库级应用锁（计划任务重叠时跳过且退 0）、fail-soft（单步失败不阻断后续步，退出码非 0），每步耗时与退出码写运维日志。风险扫描直接复用看板的 build_risks，不另设阈值。

9.2  备份与恢复

backup_db.py 全量备份 + VERIFYONLY 校验 + 26 张核心表行数清单；升级/加列前必跑。清单按保留期归档；服务器上的 .bak 文件不自动删除（磁盘回收由人工或 DBA 侧处理）。接口报文归档默认只导出不删，物理删除需双重确认参数。

10  使用指引摘要

面向操作用户的完整手册见交付包根目录《使用说明.md》，此处仅摘要：

• 入口：浏览器访问 http://<服务器IP>:8000；账号由管理员在「系统管理→用户管理」分配；门户账号自动落到自己的首个菜单。
• 全局搜索：任意页面按 Ctrl+K 呼出全局搜索（单号/客户/物料直达）。
• 主流程操作次序：报价 → 报价审批 → 转客户订单 → 订单确认 → 背靠背生成采购单 → 采购收货 → 库存入库 → 交货出库 → 开票 → 对账单。
• 待办直达：工作台与右上角铃铛的每一行都可直接跳到对应单据处理；列表页支持 URL 预置筛选（从待办跳转自动带条件）。
• 导入导出：主数据与期初建账在「导入导出中心」两段式操作（先预检看行级错误，再提交）；任意列表页「导出 Excel」与所见即所得。
• 打印：详情页「打印」进入 A4 打印视图，浏览器打印或另存 PDF。
• 常见问题：页面样式错乱先 Ctrl+F5 硬刷新（前端发版后旧缓存引用的样式文件已不存在）；「无权访问」先核对角色授权；接口报文堆积在对端配置页做连通性测试后排障。

11  交付物清单

不含项：.env（含明文凭据）、node_modules、.venv、__pycache__、开发过程截图归档、以及与通用开发模板相关的内部协作文档（CLAUDE.md、通用开发模板*.md、开发规范包-使用说明.md）。这些内容属于开发环境或内部协作资产，不随交付包分发。

附录 A  验收脚本基线全表

合计：30 个脚本 / 1129 条断言。另：权限巡检 perm_audit –strict ERROR 0 / WARN 0；结构基线 96 表 / 1556 列 / 167 CHECK。