# 膨润土矿山与猫砂出口 ERP 系统使用说明书 版本：v1.0 适用企业：膨润土矿山、膨润土加工厂、膨润土猫砂生产与出口公司 ## 1. 系统入口 当前系统入口分为两类： 1. 本机入口：`http://127.0.0.1:8000` 2. 公网入口：由管理员提供的 HTTPS 地址 打开首页后可以看到： - 中文首页 - 中文接口文档入口 - 系统健康检查入口 - 各业务模块说明 ## 2. 登录方式 1. 打开系统首页。 2. 点击“打开中文接口文档”。 3. 找到“认证登录”模块。 4. 使用 `JSON 登录获取 Token` 接口登录。 5. 登录成功后复制返回的 `access_token`。 6. 在接口文档右上角点击 `Authorize`。 7. 输入： ```text Bearer 你的access_token ``` 注意：`Bearer` 后面有一个空格。 ## 3. 角色权限 系统预置以下角色： - 超级管理员：全部权限 - 财务经理：财务、销售查询、库存查询 - 销售经理：销售、外贸、客户与 SKU 基础资料 - 生产经理：生产、库存查询、质检查询 - 仓库管理员：库存、矿山入库、生产查询 - 质检员：质检、矿山查询、生产查询 - 采购员：采购、供应商、库存查询 - 老板/管理层：看板、财务、销售、生产、库存、外贸查询 如果接口返回“当前角色无权访问该模块”，说明当前登录账号角色权限不足。 ## 4. 推荐业务流程 ### 4.1 基础资料准备 先维护以下资料： - 客户：日本客户、韩国客户、中东客户、欧洲客户等 - 供应商：包材供应商、香精供应商、活性炭供应商等 - 仓库：原矿仓、半成品仓、成品仓、包材辅料仓 - SKU：原矿 SKU、粉体 SKU、猫砂 SKU、包材 SKU、辅料 SKU - 币种和汇率：人民币、美元、日元等 - 贸易条款：FOB、CIF、EXW 核心接口： - `POST /skus` 创建 SKU - `GET /skus` 查询 SKU 列表 - `POST /customers` 创建客户 - `POST /suppliers` 创建供应商 ### 4.2 原矿入库 当矿山开采出原矿后，使用“原矿入库”功能录入： - 矿区 - 批次号 - 原矿 SKU - 入库仓库 - 吨数 - 含水率 - 白度 - 吸水率 - 蒙脱石含量 - 开采成本 系统会自动： - 生成原矿批次 - 写入原矿库存 - 写入总库存 - 计算单位吨成本 - 记录库存流水 核心接口： - `POST /mining/raw-lots` - `GET /mining/inventory` ### 4.3 生产制造 生产猫砂前，需要先建立 BOM 配方。 BOM 可以包含： - 原矿 - 包材 - 活性炭 - 香精 - 其他辅料 - 工艺损耗率 创建生产工单时输入： - 目标成品 SKU - 计划生产数量 - 使用的 BOM - 计划开始时间 - 计划结束时间 系统会自动： - 计算原矿需求 - 计算包材需求 - 校验库存是否足够 - 生成领料单 - 生成破碎、筛分、烘干、钠化、造粒、包装工序 完工入库时输入： - 实际产出数量 - 实际消耗原料 - 实际损耗 - 质检结果 - 入库仓库 - 人工成本 - 制造费用 系统会自动： - FIFO 扣减原料库存 - 增加成品库存 - 生成成品批次 - 计算实际生产成本 - 建立原矿批次到成品批次的追踪关系 核心接口： - `POST /production/bom` - `POST /production/orders` - `POST /production/orders/{id}/start` - `POST /production/orders/{id}/complete` - `GET /production/orders` ### 4.4 销售订单 销售订单录入： - 客户 - SKU - 数量 - 单价 - 币种 - 贸易条款 - 物流成本 - 包装要求 - 是否 OEM 系统会自动： - 计算订单收入 - 计算产品成本 - 计算包装成本 - 计算物流成本 - 计算毛利 - 计算毛利率 - 生成应收账款 - 生成订单利润快照 核心接口： - `POST /quotations` - `POST /sales-orders` - `GET /sales-orders` - `POST /sales-orders/{id}/deliver` - `GET /sales-orders/{id}/profit` ### 4.5 外贸报价 外贸报价适用于给海外客户快速核价。 输入： - SKU - 数量 - 目标利润率 - 贸易条款：FOB、CIF、EXW - 汇率 - 海运费 - 港杂费 - 包装成本 系统输出： - RMB 总报价 - USD 总报价 - RMB 单吨价 - USD 单吨价 - RMB 单袋价 - USD 单袋价 - 预计毛利 - 预计毛利率 核心接口： - `POST /trade/quote` ## 5. 财务模块重点说明 财务模块的目标是把销售、库存、生产、外贸成本汇总到利润和现金流中，帮助管理层判断订单是否赚钱、SKU 是否赚钱、客户是否值得继续开发。 ### 5.1 财务数据从哪里来 系统不是让财务手工重复录入全部金额，而是从业务单据自动汇总： - 销售收入来自 `sales_orders.total_amount` - 产品成本来自 `sales_orders.product_cost` - 包装成本来自 `sales_orders.packaging_cost` - 物流成本来自 `sales_orders.logistics_cost` - 订单毛利来自 `sales_orders.gross_profit` - 应收账款来自 `invoices` - 收款记录来自 `receipts` - 生产成本来自 `production_orders` 和 `production_costs` - 库存金额来自 `stock_balances.avg_cost * stock_balances.quantity` - 费用来自 `expense_records` - 现金流来自 `cashflow_records` ### 5.2 应收账款 应收账款用于查看客户还有多少钱没付。 核心接口： - `GET /finance/accounts-receivable` 关注字段： - `invoice_no`：应收发票号 - `sales_order_id`：对应销售订单 - `customer_id`：客户 - `amount`：应收金额 - `paid_amount`：已收金额 - `status`：收款状态 - `due_date`：到期日 使用建议： 1. 每天查看未收款发票。 2. 优先跟进金额大、到期近或已逾期客户。 3. 收到客户汇款后，应录入收款单并更新发票状态。 4. 对海外客户要同时关注币种和汇率。 ### 5.3 单订单利润 单订单利润用于判断某个订单是否赚钱。 核心接口： - `GET /sales-orders/{id}/profit` 利润口径： ```text 订单毛利 = 销售收入 - 产品成本 - 包装成本 - 物流成本 毛利率 = 订单毛利 / 销售收入 ``` 重点看： - `revenue`：订单收入 - `product_cost`：产品成本 - `packaging_cost`：包装成本 - `logistics_cost`：物流成本 - `gross_profit`：毛利 - `gross_margin`：毛利率 如果订单毛利为负，常见原因： - 单价太低 - 包装成本太高 - CIF 海运费上涨 - 实际生产损耗超标 - 原矿成本或辅料成本上涨 - 订单数量小，固定费用摊薄不足 ### 5.4 SKU 利润分析 SKU 利润用于判断哪些产品赚钱，哪些产品拖累利润。 核心接口： - `GET /finance/sku-profit` 重点看： - `sku_id`：SKU - `sales_qty`：销售数量 - `revenue`：销售收入 - `cost`：销售成本 - `gross_profit`：毛利 - `gross_margin`：毛利率 使用建议： 1. 按毛利额排序，找出主要利润来源。 2. 按毛利率排序，找出高价值产品。 3. 对低毛利或负毛利 SKU 重新核价。 4. 对 OEM SKU 单独分析，避免定制包装和辅料侵蚀利润。 ### 5.5 客户利润贡献 客户利润贡献用于判断客户质量，而不是只看销售额。 核心接口： - `GET /finance/customer-profit` 重点看： - `customer_id`：客户 - `revenue`：客户销售收入 - `cost`：客户总成本 - `gross_profit`：客户贡献毛利 - `gross_margin`：客户毛利率 使用建议： 1. 高收入低利润客户，要重新谈价格或贸易条款。 2. 高利润客户，要重点维护和复购开发。 3. OEM 客户要单独核算包装、打样、版费和额外质检成本。 4. 海外客户要关注汇率波动和海运费变化。 ### 5.6 月度 P&L 利润表 月度 P&L 用来查看公司每个月整体经营结果。 核心接口： - `GET /finance/pnl/monthly?period=2026-06` 字段解释： - `sales_revenue`：销售收入 - `sales_cost`：销售成本 - `gross_profit`：毛利 - `production_cost`：生产成本 - `logistics_cost`：物流成本 - `packaging_cost`：包装成本 - `labor_cost`：人工成本 - `management_expense`：管理费用 - `net_profit`：净利润 - `gross_margin`：毛利率 - `net_margin`：净利率 当前系统的月度 P&L 计算口径： ```text 销售收入 = 当月销售订单金额汇总 销售成本 = 当月销售订单产品成本汇总 毛利 = 销售收入 - 销售成本 - 包装成本 - 物流成本 净利润 = 毛利 - 管理费用 ``` 注意： - v1.0 是经营分析口径，不是完整会计准则报表。 - 如果要正式财务入账，下一阶段应增加总账、科目、凭证、期末结转。 - 如果销售订单用 USD 录入，后续应增加按汇率折算 RMB 的报表口径。 ### 5.7 现金流 现金流用于查看实际进出钱，不等于利润。 核心接口： - `GET /finance/cashflow` 现金流来源： - 客户收款 - 供应商付款 - 费用报销 - 运费支付 - 税费 - 工资 - 其他现金收支 使用建议： 1. 利润表显示赚钱，不代表现金已经收到。 2. 应收账款过高会造成现金流紧张。 3. 出口订单账期长，要重点监控回款。 4. 大额采购包材或海运费付款应提前做现金计划。 ### 5.8 财务日常使用顺序 建议财务每天按这个顺序使用： 1. 查看 `应收账款`：确认哪些客户未付款。 2. 查看 `销售订单利润`：确认新订单是否赚钱。 3. 查看 `SKU 利润分析`：发现低利润产品。 4. 查看 `客户利润贡献`：发现高价值客户和低价值客户。 5. 查看 `月度 P&L`：掌握本月经营结果。 6. 查看 `现金流`：确认实际资金流入流出。 ### 5.9 财务录入怎么用 首页左侧点击 `财务录入`，可以直接录入四类财务数据： 1. `录入客户收款`：选择未收发票，输入收款金额、日期和收款账户。保存后系统会自动增加收款单、更新发票已收金额，并把销售订单状态改为未收、部分收或已收。 2. `录入供应商付款`：选择供应商、币种、付款金额和付款日期。保存后系统会自动生成现金流流出。 3. `录入费用`：输入费用日期、金额、成本中心、费用项目和备注。保存后金额会进入当月 P&L 的管理费用，并自动生成现金流流出。 4. `录入手工现金流`：只用于工资、税费、银行手续费、其他临时收支等不是订单自动生成的资金流水。 财务录入后，回到 `财务报表` 页面并刷新，就能看到应收账款、现金流和月度 P&L 的变化。 ### 5.10 老板/管理层重点看什么 老板不需要每天看所有单据，重点看： - 今日订单金额 - 本月销售额 - 本月毛利 - 本月净利润 - SKU 利润排行 - 客户利润排行 - 应收账款预警 - 库存金额 - 原矿库存吨数 - 成品库存吨数 - 生产损耗率 - 外贸订单预计利润 ## 6. 当前 v1.0 的限制 当前版本已经能跑通主业务链路，但还不是最终生产级财务系统。 已支持： - SKU - 原矿入库 - 库存余额 - FIFO 出库 - BOM - 生产工单 - 成品入库 - 质量检测 - 销售订单 - 外贸报价 - 应收账款 - 收款录入和应收核销 - 供应商付款录入 - 费用录入 - 现金流录入 - 订单利润 - SKU 利润 - 客户利润 - 月度 P&L 后续建议升级： - 前端管理后台 - 采购完整流程 - 更完整的采购对账、付款核销和审批流程 - 正式总账和会计科目 - 多币种汇兑损益 - 期末成本结转 - 库存金额报表 - 生产损耗分析看板 - 数据备份和恢复 - 正式 PostgreSQL 数据库 - 正式域名和 HTTPS 常驻部署 ## 7. 公网访问注意事项 如果使用临时 Cloudflare Tunnel： - 电脑必须开机 - 后端服务必须运行 - 隧道进程必须运行 - 网络不能断 - 临时公网地址可能会变化 - 不保证长期稳定 如果要真正做到“任何设备、任何 IP、随时打开”，建议升级为： 1. 正式域名 2. Cloudflare 正式命名隧道或云服务器 3. PostgreSQL 数据库 4. 每日自动备份 5. 强密码和分角色账号 6. HTTPS 7. 日志监控 ## 8. 安全要求 请遵守： - 不要公开管理员密码 - 不要多人共用超级管理员账号 - 外部访问必须使用强密码 - 离职员工要停用账号 - 财务经理账号只给财务人员 - 生产、仓库、销售分角色使用 - 定期备份数据库文件 - 临时隧道不用时应关闭 ## 9. 常见问题 ### 打不开公网网址 检查： - 电脑是否开机 - 后端服务是否运行 - 隧道服务是否运行 - 网络是否正常 - 临时隧道地址是否已经变化 ### 登录后调用接口提示未认证 检查： - 是否复制了完整 `access_token` - 是否在 `Authorize` 中填写了 `Bearer token` - `Bearer` 和 token 中间是否有空格 - token 是否过期 ### 调接口提示无权限 说明当前账号角色没有该模块权限，需要超级管理员调整角色。 ### P&L 是负数 可能原因： - 示例数据中有些订单成本高于收入 - 物流成本或包装成本较高 - 产品标准成本偏高 - 订单单价偏低 这不是系统错误，说明该订单或该月经营口径下亏损。