CaiWuXiTong/app/Business/KukaPostingBase/KukaPostingLabelImporter.php
chenxi 264423c63f fix(顾家过账): 兼容历史索引字段旧值 (#1219)
身份校验以业务源字段为准,历史搜索索引旧值不再阻断标签导入。

验证:单元测试 5 个、47 条断言通过;生产 13,949 行业务源身份差异 0。
2026-11-17 10:11:02 +08:00

435 lines
14 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 App\Business\KukaPostingBase;
use App\Business\XlsxSheetReader;
use Carbon\CarbonImmutable;
use Illuminate\Database\ConnectionInterface;
use Illuminate\Database\DatabaseManager;
use Illuminate\Support\Facades\Schema;
use InvalidArgumentException;
use RuntimeException;
class KukaPostingLabelImporter
{
private const LABEL_FIELD = '过账标签';
private const ALLOWED_LABELS = [
'是',
'补单(订单四组)',
];
private const IDENTITY_FIELDS = [
'店铺',
'内部订单号',
'线上订单号',
'商品编码',
'原始线上订单号',
];
private const UPDATE_CHUNK = 500;
public function __construct(
private readonly DatabaseManager $databases,
private readonly XlsxSheetReader $reader,
) {
}
/**
* @return array{
* period: string,
* dry_run: bool,
* label_column: string,
* rows: int,
* stores: array<string, int>,
* store_count: int,
* labels: array<string, int>,
* updated: int,
* unchanged: int,
* file_sha256: string
* }
*/
public function import(
string $path,
string $period,
?string $sheetName = null,
?string $labelColumn = null,
int $companyId = 1,
bool $dryRun = false,
): array {
if (preg_match('/^\d{4}-(0[1-9]|1[0-2])$/', $period) !== 1) {
throw new InvalidArgumentException('账期格式必须为 YYYY-MM。');
}
if (! is_file($path) || ! is_readable($path)) {
throw new InvalidArgumentException('月度过账标签文件不存在或不可读。');
}
$connection = $this->connection();
if (! Schema::connection($this->connectionName())->hasTable('kuka_posting_base_rows')) {
throw new RuntimeException('顾家过账基础数据表尚未建立,请先执行数据库迁移。');
}
$allowedStores = array_values(array_filter(array_map(
static fn (mixed $store): string => trim((string) $store),
(array) config('kuka_posting.stores', []),
)));
if ($allowedStores === []) {
throw new RuntimeException('顾家过账基础数据店铺范围未配置。');
}
$labelColumn = trim((string) ($labelColumn ?? ''));
if ($labelColumn === '') {
$labelColumn = CarbonImmutable::createFromFormat('!Y-m', $period)
->format('Y年n月过账');
}
$sheetName = trim((string) ($sheetName ?? ''));
if ($sheetName === '') {
$sheetName = 'Sheet1';
}
$fileHash = hash_file('sha256', $path);
if (! is_string($fileHash)) {
throw new RuntimeException('无法计算月度过账标签文件摘要。');
}
$records = $this->readRecords(
$path,
$sheetName,
$labelColumn,
$allowedStores,
);
if ($dryRun) {
return $this->validateRows(
$connection,
$records,
$period,
$labelColumn,
$companyId,
false,
) + [
'dry_run' => true,
'file_sha256' => strtolower($fileHash),
];
}
$result = [];
$connection->transaction(function () use (
&$result,
$connection,
$records,
$period,
$labelColumn,
$companyId,
): void {
$result = $this->validateRows(
$connection,
$records,
$period,
$labelColumn,
$companyId,
true,
);
$this->applyLabels($connection, $records, $period, $companyId);
});
return $result + [
'dry_run' => false,
'file_sha256' => strtolower($fileHash),
];
}
/**
* @param list<string> $allowedStores
* @return list<array{excel_row_number: int, label: string, identity: array<string, string>}>
*/
private function readRecords(
string $path,
string $sheetName,
string $labelColumn,
array $allowedStores,
): array {
$records = [];
$excelRowNumber = 1;
foreach ($this->reader->rows(
$path,
array_merge([$labelColumn], self::IDENTITY_FIELDS),
[],
$sheetName,
) as $values) {
$excelRowNumber++;
$label = trim((string) ($values[$labelColumn] ?? ''));
if (! in_array($label, self::ALLOWED_LABELS, true)) {
throw new RuntimeException(sprintf(
'Excel 第 %d 行的“%s”只能为“%s”,当前值为“%s”。',
$excelRowNumber,
$labelColumn,
implode('”或“', self::ALLOWED_LABELS),
$label,
));
}
$identity = [];
foreach (self::IDENTITY_FIELDS as $field) {
$identity[$field] = trim((string) ($values[$field] ?? ''));
}
if (! in_array($identity['店铺'], $allowedStores, true)) {
throw new RuntimeException(sprintf(
'Excel 第 %d 行的店铺“%s”不在顾家过账基础数据范围内。',
$excelRowNumber,
$identity['店铺'],
));
}
$records[] = [
'excel_row_number' => $excelRowNumber,
'label' => $label,
'identity' => $identity,
];
}
if ($records === []) {
throw new RuntimeException('月度过账标签文件没有数据行。');
}
return $records;
}
/**
* @param list<array{excel_row_number: int, label: string, identity: array<string, string>}> $records
* @return array{
* period: string,
* label_column: string,
* rows: int,
* stores: array<string, int>,
* store_count: int,
* labels: array<string, int>,
* updated: int,
* unchanged: int
* }
*/
private function validateRows(
ConnectionInterface $connection,
array $records,
string $period,
string $labelColumn,
int $companyId,
bool $lockRows,
): array {
$expectedRows = count($records);
$databaseRows = $this->baseRowsQuery($connection, $period, $companyId)
->count();
if ($databaseRows !== $expectedRows) {
throw new RuntimeException(sprintf(
'月度过账标签文件有 %s 行,但共享镜像 %s 有 %s 行,行数不一致,未写入任何标签。',
number_format($expectedRows),
$period,
number_format($databaseRows),
));
}
$labels = array_fill_keys(self::ALLOWED_LABELS, 0);
$stores = [];
$updated = 0;
$unchanged = 0;
$index = 0;
$query = $this->baseRowsQuery($connection, $period, $companyId)
->orderBy('source_row_number');
if ($lockRows) {
$query->lockForUpdate();
}
foreach ($query->cursor() as $row) {
$record = $records[$index] ?? null;
if ($record === null) {
throw new RuntimeException('共享镜像行数多于月度过账标签文件,未写入任何标签。');
}
$sourceValues = $this->decodeSourceValues($row);
$this->assertIdentity($row, $sourceValues, $record);
$label = $record['label'];
$labels[$label]++;
$store = $record['identity']['店铺'];
$stores[$store] = ($stores[$store] ?? 0) + 1;
if (trim((string) ($sourceValues[self::LABEL_FIELD] ?? '')) === $label) {
$unchanged++;
} else {
$updated++;
}
$index++;
}
if ($index !== $expectedRows) {
throw new RuntimeException('共享镜像行数少于月度过账标签文件,未写入任何标签。');
}
ksort($stores);
return [
'period' => $period,
'label_column' => $labelColumn,
'rows' => $expectedRows,
'stores' => $stores,
'store_count' => count($stores),
'labels' => $labels,
'updated' => $updated,
'unchanged' => $unchanged,
];
}
/**
* @param list<array{excel_row_number: int, label: string, identity: array<string, string>}> $records
*/
private function applyLabels(
ConnectionInterface $connection,
array $records,
string $period,
int $companyId,
): void {
$index = 0;
$batch = [];
$flush = static function () use (&$batch, $connection): void {
if ($batch === []) {
return;
}
$connection->table('kuka_posting_base_rows')->upsert(
$batch,
['company_id', 'period', 'source_row_number'],
['source_values', 'row_hash'],
);
$batch = [];
};
foreach ($this->baseRowsQuery($connection, $period, $companyId)
->orderBy('source_row_number')
->cursor() as $row) {
$record = $records[$index] ?? null;
if ($record === null) {
throw new RuntimeException('共享镜像行数多于月度过账标签文件,标签写入已回滚。');
}
$sourceValues = $this->decodeSourceValues($row);
$this->assertIdentity($row, $sourceValues, $record);
$index++;
if (trim((string) ($sourceValues[self::LABEL_FIELD] ?? '')) === $record['label']) {
continue;
}
$sourceValues[self::LABEL_FIELD] = $record['label'];
$encoded = json_encode(
$sourceValues,
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR,
);
$batch[] = [
'company_id' => $companyId,
'period' => $period,
'source_row_number' => (int) $row->source_row_number,
'store_name' => $row->store_name,
'internal_order_no' => $row->internal_order_no,
'online_order_no' => $row->online_order_no,
'product_code' => $row->product_code,
'source_values' => $encoded,
'row_hash' => hash('sha256', $encoded),
'imported_at' => $row->imported_at,
];
if (count($batch) >= self::UPDATE_CHUNK) {
$flush();
}
}
if ($index !== count($records)) {
throw new RuntimeException('共享镜像行数少于月度过账标签文件,标签写入已回滚。');
}
$flush();
}
/**
* @return array<string, mixed>
*/
private function decodeSourceValues(object $row): array
{
$values = json_decode(
(string) $row->source_values,
true,
512,
JSON_THROW_ON_ERROR,
);
if (! is_array($values)) {
throw new RuntimeException(sprintf(
'共享镜像 source_row_number=%d 的源数据不是有效对象。',
(int) $row->source_row_number,
));
}
return $values;
}
/**
* @param array<string, mixed> $sourceValues
* @param array{excel_row_number: int, label: string, identity: array<string, string>} $record
*/
private function assertIdentity(object $row, array $sourceValues, array $record): void
{
$databaseIdentity = [
'店铺' => trim((string) ($sourceValues['店铺'] ?? '')),
'内部订单号' => trim((string) ($sourceValues['内部订单号'] ?? '')),
'线上订单号' => trim((string) ($sourceValues['线上订单号'] ?? '')),
'商品编码' => trim((string) ($sourceValues['商品编码'] ?? '')),
'原始线上订单号' => trim((string) ($sourceValues['原始线上订单号'] ?? '')),
];
foreach ($databaseIdentity as $field => $value) {
if ($value !== $record['identity'][$field]) {
throw new RuntimeException(sprintf(
'Excel 第 %d 行与共享镜像 source_row_number=%d 的“%s”不一致,未写入任何标签。',
$record['excel_row_number'],
(int) $row->source_row_number,
$field,
));
}
}
// 顶层订单字段是页面搜索用的冗余索引,历史数据可能保留旧值。
// 行身份以 source_values 中的业务源字段为准,本命令不会改动这些索引字段。
}
private function baseRowsQuery(
ConnectionInterface $connection,
string $period,
int $companyId,
) {
return $connection->table('kuka_posting_base_rows')
->where('company_id', $companyId)
->where('period', $period)
->select([
'id',
'source_row_number',
'store_name',
'internal_order_no',
'online_order_no',
'product_code',
'source_values',
'imported_at',
]);
}
private function connection(): ConnectionInterface
{
return $this->databases->connection($this->connectionName());
}
private function connectionName(): string
{
return (string) config('upstream_mirrors.connection', 'business_mirror');
}
}