CaiWuXiTong/modules/EcommerceFinance/Repositories/ShippingOrderRepository.php
limeng f106ef988d feat(发货数据): 按报价管理的报价核算运费,结果显示在发货数据页面 (#1228)
从 2026-11-01 起,按发货日在报价管理里生效的报价版本(与报价管理「当前生效」同一判断:未作废、
已审核/签署生效、执行期间覆盖发货日,取执行日期最新)逐包裹核算运费,写入 jst_oms_shipping_freight。
- 结算重量:实称>线上>重量;按各快递计泡系数取 max(重量, 长×宽×高÷系数);免抛仓(含「配件」仓)不计泡、不收多件费;
  超长费计入,其他附加费不计;城市单独报价、整省「X元/公斤」、洞洞板 9000、个别版本系数等按 10 月逐单核对的口径;
- 计算引擎移植自 10 月离线核算脚本,10 月 29.5 万个包裹逐单比对结果一致(仅 x.xx5 边界按正确四舍五入进位);
- 发货数据同步完成后核算该窗口;报价版本新增/作废/签署归档后按该快递从执行日期起自动重算;
- 新命令 jushuitan:calc-freight --from --to [--carrier];
- 发货数据页面/导出新增「报价核算」列:核算运费、核算-聚水潭运费、报价版本、结算重量依据、核算结算重量、
  计费重量、首重、续重/费率、面单、一口价、多件/超长加收、核算公式、核算状态(合并口径每包裹一行,明细只在第一行)。

同时修复发货数据同步 11 月起频繁失败:副本库查发货视图超时后报 20047 DBPROCESS is dead,
原重试只识别 20003/dbnextrow,整次同步失败(11-17 只同步到 62%)。现把 20047 视为可重连重试,
发货视图每批出库单由 300 降到 100。

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014nvGZkg27YMEdhry6eiuwf

> 开工时标题使用 `WIP: <任务名称>` 并先填写“任务占用与边界”。Codex 完成独立合并前自审后补齐其余内容并移除 `WIP:`。

## 任务占用与边界

- 任务名称:
- 实际开发者:
- 任务来源/团队分工:
- 目标结果:
- 预计修改路径:
- 将写入的公共契约(路由、Controller 方法、Repository、表/视图、`source_key`、`scope`、权限名、菜单键或共享组件):
- 仅复用、明确不修改的公共契约:
- 数据源、表/视图和字段:
- 上游 `source_key` / `scope`:
- 权限名、菜单键或共享组件:
- 明确不修改的范围:

## 开工碰撞检查

- [ ] Codex 已执行 `scripts/codex-task-preflight.ps1`
- [ ] 已检查最新 `main` 和所有远程任务分支
- [ ] 已搜索主线既有页面、接口、Repository 和数据查询
- [ ] 已把“将写入”和“仅复用、不修改”的公共契约分开;仅复用项不作为单独阻断条件
- [ ] 未发现实际写入重叠;或已在下方写明相关分支、具体重叠项和协调结论

相关分支、重叠项与协调结论:

## 实际改动

- 完成内容:
- Codex 实际修改的文件:
- 新增或变更的公共契约:
- 与原计划的差异:

## 验证证据

- 正常流程:
- 空数据/错误输入/无权限场景:
- 受影响旧功能:
- 自动测试及结果:
- 实际页面、接口或只读业务查询结果:

## 风险检查

- [ ] 不涉及金额、权限、审批、数据库迁移、生产配置或数据修复
- [ ] 如涉及上述高风险内容,已在下方写明影响、回滚和所需授权
- [ ] 未提交 `.env`、密码、Token、私钥、真实财务数据、生产日志或构建产物
- [ ] 前端改动符合 `DESIGN.md`;无前端改动则写“不适用”

高风险影响、回滚和授权状态:

## 合并前复查

- [ ] 已重新拉取远程引用并用实际修改范围再次运行碰撞检查
- [ ] PR 不再是 `WIP:`,所有测试结果已经补齐
- [ ] Codex 已重新读取原始需求和验收标准,并逐文件审核 `origin/main...任务分支` 的完整 diff
- [ ] Codex 自审确认无越界修改、重复实现、敏感内容、未处理冲突和未验证结果
- [ ] 合并顺序不会覆盖其他未合并任务
- [ ] 已授权当前任务的 Codex 执行 Squash merge、验证 `main` 并清理任务分支
- [ ] 如涉及生产迁移、数据修复、删除、覆盖配置或部署,已另行取得对应高风险授权

Reviewed-on: #1228
2026-11-18 14:03:04 +08:00

453 lines
20 KiB
PHP
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?php
namespace Modules\EcommerceFinance\Repositories;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Database\Query\Builder;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Cache;
/**
* 发货明细只读仓库。读取扁平表 jst_oms_shipping(对齐工作平台发货数据 47 列),
* 供“发货数据”页面展示与后续快递运费核算使用。
*/
class ShippingOrderRepository
{
private readonly ConnectionInterface $db;
public function __construct()
{
$this->db = DB::connection((string) config('jushuitan.connection', 'jushuitan_local'));
try {
// 合并取"最后一行"值用 GROUP_CONCAT,放宽默认 1024 长度避免截断
$this->db->statement('SET SESSION group_concat_max_len = 4194304');
} catch (\Throwable) {
}
}
/**
* @param array<string,string> $filters
* @return array{data:array,total:int}
*/
public function paginate(array $filters, int $page, int $perPage, string $mode = 'merged'): array
{
$page = max($page, 1);
$perPage = min(max($perPage, 1), 100);
if ($mode === 'detail') {
$q = $this->filteredQuery($filters);
$total = (clone $q)->count();
$rows = (clone $q)
->orderByDesc('ship_time')
->orderByDesc('source_id')
->orderBy('sku_source_id')
->forPage($page, $perPage)
->get()->map(fn ($r) => $this->detailRow((array) $r))->all();
return ['data' => $this->attachFreight($rows, true), 'total' => $total];
}
// 合并:按包裹(source_id)归并
$base = $this->filteredQuery($filters);
$total = (clone $base)->distinct()->count('source_id');
$pageKeys = (clone $base)->select('source_id')->selectRaw('MAX(ship_time) as ship_time')
->groupBy('source_id')->orderByDesc('ship_time')->orderByDesc('source_id')
->forPage($page, $perPage)->pluck('source_id')->all();
if ($pageKeys === []) {
return ['data' => [], 'total' => $total];
}
$rows = (clone $base)
->whereIn('source_id', $pageKeys)
->groupBy('source_id')
->selectRaw($this->mergedSelectRaw())
->orderByDesc('ship_time')
->orderByDesc('source_id')
->get()->map(fn ($r) => (array) $r)->all();
return ['data' => $this->attachFreight($rows, false), 'total' => $total];
}
/** 仅批量读取本月配件及其交易单号对应的三个月首发候选;复用发货数据合并口径。 */
public function accessoryReshipBatches(string $monthStart, string $nextMonth, string $windowStart): \Generator
{
foreach ($this->accessoryFreightBatches($monthStart, $nextMonth) as $accessories) {
$trades = array_values(array_unique(array_filter(array_column($accessories, 'trade_no'), static fn ($trade) => trim((string) $trade) !== '')));
$originals = $trades === [] ? [] : $this->db->table('jst_oms_shipping')
->where('warehouse_name', '<>', \Modules\EcommerceFinance\Services\AccessoryReshipMatcher::WAREHOUSE)
->where('ship_time', '>=', $windowStart)->where('ship_time', '<', $nextMonth)
->whereIn('trade_no', $trades)->whereNotNull('express_no')->where('express_no', '<>', '')
->select(['trade_no', 'barcode', 'express_no', 'express_name1', 'express_name2', 'ship_time', 'warehouse_name'])
->get()->map(fn ($row) => (array) $row)->all();
yield compact('accessories', 'originals');
}
}
/** 常州配件按发货包裹合并,运费只累计一次;两个扣款明细共用同一口径。 */
public function accessoryFreightBatches(string $monthStart, string $nextMonth): \Generator
{
$last = null;
while (true) {
$query = $this->db->table('jst_oms_shipping')
->where('warehouse_name', \Modules\EcommerceFinance\Services\AccessoryReshipMatcher::WAREHOUSE)
->where('ship_time', '>=', $monthStart)->where('ship_time', '<', $nextMonth);
if ($last !== null) $query->where('source_id', '>', $last);
// 指定条码顺序,保证“第一个条码”在重复匹配时稳定。
$select = 'source_id, MAX(express_no) as express_no, MAX(trade_no) as trade_no, MAX(express_name1) as express_name1, MAX(express_name2) as express_name2, MAX(ship_time) as ship_time, SUM(freight) as freight, GROUP_CONCAT(DISTINCT barcode ORDER BY id SEPARATOR \',\' ) as barcode';
$accessories = $query->groupBy('source_id')->selectRaw($select)->orderBy('source_id')->limit(1000)->get()->map(fn ($row) => (array) $row)->all();
if ($accessories === []) return;
yield $accessories;
$last = $accessories[array_key_last($accessories)]['source_id'];
}
}
/** 明细口径:无尺寸(0)的长宽高/体积显示为空白,对齐工作平台导出明细(合并保持 0)。 */
private function detailRow(array $r): array
{
foreach (['length_cm', 'width_cm', 'height_cm', 'volume_cm3'] as $c) {
if (array_key_exists($c, $r) && $r[$c] !== null && $r[$c] !== '' && (float) $r[$c] == 0.0) {
$r[$c] = null;
}
}
return $r;
}
/**
* 包裹内"最后一行"(按明细 id 顺序)的值。工作平台合并的商品名称/供应商取的是
* 条码串最后一个商品那行(样本 6213/6216、575/575),不是 MIN。
*/
private function lastOf(string $expr): string
{
// SEPARATOR 只能是字符串常量;用名称里不会出现的 '#~#' 作分隔
return "NULLIF(SUBSTRING_INDEX(GROUP_CONCAT(COALESCE({$expr}, '') ORDER BY `id` SEPARATOR '#~#'), '#~#', -1), '')";
}
/** 合并聚合 SELECT:条码/商品ID 逗号拼接、数量/重量/体积/金额/运费求和、长宽高取最大、其余取值。 */
private function mergedSelectRaw(): string
{
$sum = ['qty', 'freight', 'online_weight', 'actual_weight', 'volume_cm3', 'weight_kg',
'settle_weight_kg', 'settle_volume_cm3', 'recon_weight_kg', 'recon_volume_cm3', 'amount', 'settle_freight'];
$concat = ['item_id', 'barcode'];
$min = ['product_name', 'supplier_name', 'product_code'];
$all = ['express_no', 'trade_no', 'item_id', 'barcode', 'product_name', 'qty', 'pkg_count',
'receiver_state', 'buyer_nick', 'receiver_name', 'shop_name', 'express_name1', 'warehouse_name',
'ship_time', 'freight', 'online_weight', 'actual_weight', 'length_cm', 'width_cm', 'height_cm',
'volume_cm3', 'receiver_city', 'receiver_district', 'supplier_name', 'receiver_address',
'receiver_mobile', 'receiver_phone', 'express_name2', 'platform', 'buyer_memo', 'seller_memo',
'package_no', 'amount', 'product_code', 'download_time', 'pay_time', 'freight_rate', 'freight_formula',
'weight_kg', 'settle_weight_kg', 'settle_volume_cm3', 'recon_weight_kg', 'recon_volume_cm3',
'finished_barcode', 'finished_name', 'finished_supplier', 'settle_freight', 'front_no'];
// 组合件拆件后明细存部件值,合并取整行值(m_*),普通行 m_* 为空则回落原列
$mcol = ['product_name' => 'm_name', 'volume_cm3' => 'm_volume_cm3',
'length_cm' => 'm_length_cm', 'width_cm' => 'm_width_cm', 'height_cm' => 'm_height_cm'];
$parts = ['MAX(id) as id', 'source_id'];
foreach ($all as $c) {
if ($c === 'product_name') {
$parts[] = $this->lastOf("COALESCE(`m_name`, `product_name`)") . " as `{$c}`";
} elseif (isset($mcol[$c])) {
$fn = $c === 'volume_cm3' ? 'SUM' : 'MAX';
$parts[] = "{$fn}(COALESCE(`{$mcol[$c]}`, `{$c}`)) as `{$c}`";
} elseif (in_array($c, $sum, true)) {
$parts[] = "SUM(`{$c}`) as `{$c}`";
} elseif (in_array($c, $concat, true)) {
$parts[] = "GROUP_CONCAT(DISTINCT `{$c}` SEPARATOR ',') as `{$c}`";
} elseif (in_array($c, $min, true)) {
$parts[] = $this->lastOf("`{$c}`") . " as `{$c}`";
} else {
$parts[] = "MAX(`{$c}`) as `{$c}`";
}
}
return implode(', ', $parts);
}
/**
* @param array<string,string> $filters
* @return \Generator<int,array<string,mixed>>
*/
public function exportRows(array $filters, int $batchSize = 1000, string $mode = 'merged'): \Generator
{
$batchSize = min(max($batchSize, 1), 5000);
$last = null;
if ($mode === 'detail') {
while (true) {
$query = $this->filteredQuery($filters);
if ($last !== null) {
$query->where('id', '>', $last);
}
$rows = $query->orderBy('id')->limit($batchSize)->get()->all();
if ($rows === []) {
return;
}
foreach ($this->attachFreight(array_map(fn ($row) => $this->detailRow((array) $row), $rows), true) as $row) {
yield $row;
}
$last = (int) $rows[array_key_last($rows)]->id;
if (count($rows) < $batchSize) {
return;
}
}
}
// 合并导出:按 source_id 键集分页 + 归并
while (true) {
$query = $this->filteredQuery($filters);
if ($last !== null) {
$query->where('source_id', '>', $last);
}
$keys = (clone $query)->select('source_id')->distinct()
->orderBy('source_id')->limit($batchSize)->pluck('source_id')->all();
if ($keys === []) {
return;
}
$rows = $query->whereIn('source_id', $keys)->groupBy('source_id')->selectRaw($this->mergedSelectRaw())
->orderBy('source_id')->limit($batchSize)->get()->all();
if ($rows === []) {
return;
}
foreach ($this->attachFreight(array_map(fn ($row) => (array) $row, $rows), false) as $row) {
yield $row;
}
$last = (int) $rows[array_key_last($rows)]->source_id;
if (count($rows) < $batchSize) {
return;
}
}
}
/** 报价核算结果列(jst_oms_shipping_freight):页面/导出列名 => 结果表字段。 */
public const FREIGHT_COLUMNS = [
'qc_freight' => 'freight', 'qc_diff' => null, 'qc_quote_version' => 'quote_version', 'qc_basis' => null,
'qc_settle_weight' => 'settle_weight', 'qc_charge_weight' => 'charge_weight', 'qc_first_price' => 'first_price',
'qc_rate' => 'rate', 'qc_miandan' => 'miandan', 'qc_flat_price' => 'flat_price', 'qc_extra_fee' => 'extra_fee',
'qc_formula' => 'formula', 'qc_status' => 'status',
];
/**
* 把报价核算结果并到发货数据行上。合并口径每个包裹一行;明细口径只放在包裹的第一行,避免求和重复。
*
* @param list<array<string,mixed>> $rows
* @return list<array<string,mixed>>
*/
private function attachFreight(array $rows, bool $detail): array
{
$ids = array_values(array_unique(array_filter(array_map(static fn ($r) => (int) ($r['source_id'] ?? 0), $rows))));
if ($ids === []) {
return $rows;
}
try {
$results = $this->db->table('jst_oms_shipping_freight')->whereIn('source_id', $ids)->get()->keyBy('source_id')->all();
$firstIds = $detail
? $this->db->table('jst_oms_shipping')->whereIn('source_id', $ids)->groupBy('source_id')
->selectRaw('source_id, MIN(id) as first_id')->pluck('first_id', 'source_id')->all()
: [];
} catch (\Throwable) {
return $rows; // 结果表未迁移时不影响发货数据显示
}
foreach ($rows as &$row) {
$sid = (int) ($row['source_id'] ?? 0);
$res = $results[$sid] ?? null;
if ($res === null || ($detail && (int) ($firstIds[$sid] ?? 0) !== (int) ($row['id'] ?? -1))) {
continue;
}
foreach (self::FREIGHT_COLUMNS as $key => $field) {
if ($field !== null) {
$row[$key] = $res->{$field};
}
}
$row['qc_diff'] = $res->freight !== null && $res->jst_freight !== null
? round((float) $res->freight - (float) $res->jst_freight, 2) : null;
$row['qc_basis'] = $this->freightBasis($res);
}
unset($row);
return $rows;
}
/** 结算重量依据,如「实称重量 5.2kg;体积重 6.1kg(÷8000)」「线上重量 3kg;免抛仓不计泡」。 */
private function freightBasis(object $res): ?string
{
if ($res->base_source === null) {
return null;
}
$kg = static fn ($v): string => rtrim(rtrim(number_format((float) $v, 4, '.', ''), '0'), '.');
$text = $res->base_source . ' ' . $kg($res->base_weight) . 'kg';
if ((bool) $res->free_warehouse) {
return $text . ';免抛仓不计泡';
}
if ($res->coef !== null && $res->volume_weight !== null) {
return $text . ';体积重 ' . $kg($res->volume_weight) . 'kg(÷' . $res->coef . ')';
}
return $text . ';不计泡';
}
/** @param array<string,string> $filters */
private function filteredQuery(array $filters): Builder
{
$query = $this->db->table('jst_oms_shipping');
if (($filters['express_no'] ?? '') !== '') {
$query->where('express_no', '=', trim((string) $filters['express_no']));
}
if (($filters['sourceno'] ?? '') !== '') {
$query->where('trade_no', '=', trim((string) $filters['sourceno']));
}
// 条形码:单值关键词
if (($filters['barcode'] ?? '') !== '') {
$query->whereRaw("barcode LIKE ? ESCAPE '!'", [$this->contains((string) $filters['barcode'])]);
}
// 供应商/店铺/仓库:多选,精确匹配所选的任意一个
foreach (['supplier_name', 'shop_name', 'warehouse_name'] as $column) {
$values = $this->multi($filters[$column] ?? null);
if ($values !== []) {
$query->whereIn($column, $values);
}
}
// 快递公司:多选,匹配快递名称1/2 任意一个
$couriers = $this->multi($filters['express_company'] ?? null);
if ($couriers !== []) {
$query->where(function (Builder $group) use ($couriers): void {
$group->whereIn('express_name1', $couriers)
->orWhereIn('express_name2', $couriers);
});
}
if (($filters['ship_from'] ?? '') !== '') {
$query->where('ship_time', '>=', $filters['ship_from'] . ' 00:00:00');
}
if (($filters['ship_to'] ?? '') !== '') {
$query->where('ship_time', '<', date('Y-m-d 00:00:00', strtotime($filters['ship_to'] . ' +1 day')));
}
return $query;
}
private function contains(string $value): string
{
return '%' . str_replace(['!', '%', '_'], ['!!', '!%', '!_'], trim($value)) . '%';
}
/**
* 归一多选筛选值为字符串数组(兼容单个字符串)。
* @return array<int,string>
*/
private function multi(mixed $value): array
{
if (is_string($value)) {
$value = $value === '' ? [] : [$value];
}
if (! is_array($value)) {
return [];
}
$out = [];
foreach ($value as $item) {
$item = trim((string) $item);
if ($item !== '' && ! in_array($item, $out, true)) {
$out[] = $item;
}
}
return array_slice($out, 0, 50);
}
/**
* 取某字段去重候选值(供筛选框自动补全)。
* @return array<int,string>
*/
public function distinctValues(string $field, string $keyword, int $limit = 20): array
{
$map = [
'supplier_name' => ['supplier_name'],
'shop_name' => ['shop_name'],
'warehouse_name' => ['warehouse_name'],
'express_company' => ['express_name1', 'express_name2'],
];
if (! isset($map[$field])) {
return [];
}
$limit = min(max($limit, 1), 500);
$like = $this->contains($keyword);
$values = [];
foreach ($map[$field] as $col) {
$rows = $this->db->table('jst_oms_shipping')
->selectRaw($col . ' as v')
->whereRaw($col . " LIKE ? ESCAPE '!'", [$like])
->whereNotNull($col)
->where($col, '<>', '')
->groupBy($col)
->orderBy($col)
->limit($limit)
->pluck('v');
foreach ($rows as $v) {
$v = trim((string) $v);
// 过滤空值与占位脏值(如自动发货仓 send_warehouse 为 "0")
if ($v !== '' && $v !== '0') {
$values[$v] = true;
}
}
}
$values = array_keys($values);
sort($values, SORT_FLAG_CASE | SORT_STRING);
return array_slice($values, 0, $limit);
}
/** 报价录入的近期发货名称候选;只读固定数量的新明细,不在每次输入时扫描整张发货表。 */
public function recentCourierNames(string $keyword, int $limit = 20): array
{
$key = 'shipping:recent-couriers:' . hash('sha256', $this->db->getName() . '|' . $this->db->getDatabaseName());
$names = Cache::remember($key, now()->addMinutes(5), function (): array {
$names = [];
foreach ($this->db->table('jst_oms_shipping')->orderByDesc('id')->limit(10000)->get(['express_name1', 'express_name2']) as $row) {
foreach ([$row->express_name1, $row->express_name2] as $value) {
$name = trim((string) $value);
if ($name !== '' && $name !== '0') {
$names[$name] = true;
}
}
}
$names = array_keys($names);
sort($names, SORT_STRING);
return $names;
});
return array_slice(array_values(array_filter($names, static fn (string $name): bool => mb_stripos($name, $keyword) !== false)), 0, min(max($limit, 1), 20));
}
/** 同步状态(供页面显示同步中/最近完成)。 */
public function syncStatus(): array
{
try {
$row = $this->db->table('jst_sync_state')->where('dataset_key', 'jst.sctrade')->first();
if (! $row) {
return ['code' => 'unavailable', 'last_succeeded_at' => null];
}
$freightPending = $this->db->table('jst_sync_state')
->where('dataset_key', 'like', 'jst.sctrade.freight.%')->where('status', '!=', 'succeeded')->count();
$itemsPending = $this->db->table('jst_sync_state')
->where('dataset_key', 'like', 'jst.sctrade.items.%')->where('status', '!=', 'succeeded')->count();
$code = (string) ($row->status ?? 'unavailable');
return [
'code' => ($freightPending || $itemsPending) && $code === 'succeeded' ? 'partial' : $code,
'last_succeeded_at' => $row->last_succeeded_at ?? null,
'freight_pending' => (bool) $freightPending,
'warning' => implode(' ', array_filter([
$code === 'partial' ? '部分包裹尚需与上游源键核对,原有镜像记录已保留。' : null,
$freightPending ? "{$freightPending} 个日期窗口的运费和结算重量待补,空白不代表 0。" : null,
$itemsPending ? "{$itemsPending} 个日期窗口的商品或金额待核对。" : null,
])),
];
} catch (\Throwable) {
return ['code' => 'unavailable', 'last_succeeded_at' => null];
}
}
}