feat(账户余额): 增加平台与店铺每日余额视图 (#1273)

每日余额明细支持汇总、平台和店铺维度,增加真实每日余额接口、店铺筛选分页及点击日期查看当日四项明细。
This commit is contained in:
qiuxiang 2026-11-19 15:40:23 +08:00
parent 30c4b8cd99
commit 119f52c442
7 changed files with 1282 additions and 166 deletions

View File

@ -131,6 +131,35 @@ class StoreReceivingBalanceOverview extends Controller
}
}
public function dailyBalances(Request $request, StoreReceivingBalanceOverviewService $service)
{
$this->authorizeStoreReceivingBills();
try {
$period = $this->requestedPeriod($request);
$cacheKey = implode(':', [
'ecommerce-finance',
'account-balance-daily',
'v1',
(string) company_id(),
$period[0],
$period[1] ?? '',
]);
return response()->json(Cache::remember(
$cacheKey,
now()->addMinutes(30),
static fn (): array => $service->dailyBalances(...$period),
));
} catch (Throwable $exception) {
report($exception);
return response()->json([
'message' => '每日余额明细暂时无法读取,请稍后重试。',
], 503);
}
}
/** @return array{0:string,1?:string} */
private function requestedPeriod(Request $request): array
{

View File

@ -343,6 +343,138 @@ class StoreReceivingBalanceOverviewService
];
}
/**
* 汇总、平台和店铺三个层级的每日余额。
*
* 平台每日余额以平台期初为起点,按真实账单发生日期滚动;
* 店铺每日余额以店铺期初为起点。任何一层缺少可靠期初时,
* 对应日期的余额返回 null,并在 available 中明确标记。
*
* @return array<string,mixed>
*/
public function dailyBalances(string $periodStart, ?string $periodEnd = null): array
{
[$periodStart, $periodEnd, $periodMonth] = $this->periodForRange($periodStart, $periodEnd);
$dates = $this->dateRange($periodStart, $periodEnd);
$overview = $this->overview($periodStart, $periodEnd);
$platforms = $overview['platforms'];
$stores = [];
$errors = [];
$platformOrder = [];
foreach ($platforms as $index => &$platform) {
$slug = (string) $platform['slug'];
$platformOrder[$slug] = $index;
$activityAvailable = true;
try {
$activity = $this->dailyActivity($slug, $periodStart, $periodEnd, $dates);
} catch (Throwable $exception) {
report($exception);
$activity = ['by_date' => [], 'by_store' => []];
$activityAvailable = false;
$errors[$slug] = $this->safeErrorMessage($exception);
}
$daily = $this->rollDailyBalances(
$dates,
$activityAvailable
&& $platform['available']
&& is_numeric($platform['opening_balance'] ?? null)
? (float) $platform['opening_balance']
: null,
$activity['by_date'],
);
$platform['daily'] = $daily;
$platform['daily_error'] = $activityAvailable ? null : $errors[$slug];
$platform['daily_reconciled'] = $this->dailyReconciled(
$daily,
is_numeric($platform['income'] ?? null) ? (float) $platform['income'] : null,
is_numeric($platform['expense'] ?? null) ? (float) $platform['expense'] : null,
);
try {
$storeBalances = $this->fetchPlatformStoreBalances($slug, $periodStart, $periodEnd);
} catch (Throwable $exception) {
report($exception);
$errors[$slug . ':stores'] = $this->safeErrorMessage($exception);
continue;
}
foreach ($storeBalances as $storeBalance) {
$storeName = $this->storeName($storeBalance['store_name'] ?? '');
$storeKey = $this->dailyStoreKey($slug, $storeName);
$storeDaily = $this->rollDailyBalances(
$dates,
$activityAvailable && is_numeric($storeBalance['opening_balance'] ?? null)
? (float) $storeBalance['opening_balance']
: null,
$activity['by_store'][$storeKey] ?? [],
);
$totals = $this->dailyTotals($dates, $storeDaily);
$stores[] = [
'platform_slug' => $slug,
'platform' => $platform['name'],
'store_name' => $storeName,
'opening_balance' => is_numeric($storeBalance['opening_balance'] ?? null)
? round((float) $storeBalance['opening_balance'], 2)
: null,
'income' => $totals['income'],
'expense' => $totals['expense'],
'amount' => $totals['closing'],
'available' => $totals['available'],
'daily' => $storeDaily,
];
}
}
unset($platform);
usort($stores, static function (array $left, array $right) use ($platformOrder): int {
return [
$platformOrder[$left['platform_slug']] ?? 99,
$left['store_name'],
] <=> [
$platformOrder[$right['platform_slug']] ?? 99,
$right['store_name'],
];
});
$summaryDaily = [];
foreach ($dates as $date) {
$dayRows = array_map(
static fn (array $platform): ?array => $platform['daily'][$date] ?? null,
$platforms,
);
$available = $dayRows !== []
&& ! in_array(null, $dayRows, true)
&& ! in_array(false, array_column($dayRows, 'available'), true);
$summaryDaily[$date] = [
'date' => $date,
'opening' => $available ? round(array_sum(array_column($dayRows, 'opening')), 2) : null,
'income' => $available ? round(array_sum(array_column($dayRows, 'income')), 2) : null,
'expense' => $available ? round(array_sum(array_column($dayRows, 'expense')), 2) : null,
'closing' => $available ? round(array_sum(array_column($dayRows, 'closing')), 2) : null,
'available' => $available,
];
}
return [
...$overview,
'platforms' => $platforms,
'dates' => $dates,
'daily_summary' => $summaryDaily,
'stores' => $stores,
'daily_errors' => $errors,
'store_summary' => [
'store_count' => count($stores),
'available_store_count' => count(array_filter(
$stores,
static fn (array $store): bool => (bool) $store['available'],
)),
],
'daily_note' => '按账单实际发生日期滚动计算;缺少可靠期初或当天没有可计算余额时显示“—”。',
];
}
/**
* 指定平台在账期内的店铺期末余额,供双源核对和趋势复用。
*
@ -449,6 +581,153 @@ class StoreReceivingBalanceOverviewService
];
}
/**
* @return iterable<int,array<string,mixed>>
*/
protected function fetchPlatformDailyRows(string $platform, string $start, string $end): iterable
{
return $this->fetchPlatformRows($platform, $start, $end, null);
}
/** @return list<string> */
private function dateRange(string $start, string $end): array
{
$first = CarbonImmutable::parse($start, 'Asia/Shanghai')->startOfDay();
$last = CarbonImmutable::parse($end, 'Asia/Shanghai')->startOfDay();
if ($last->lt($first)) {
throw new RuntimeException('invalid_balance_overview_period');
}
if ($first->diffInDays($last) > 62) {
throw new RuntimeException('余额明细一次最多查询 62 天');
}
$dates = [];
for ($date = $first; $date->lte($last); $date = $date->addDay()) {
$dates[] = $date->format('Y-m-d');
}
return $dates;
}
/**
* @param list<string> $dates
* @return array{by_date:array<string,array{income:float,expense:float}>,by_store:array<string,array<string,array{income:float,expense:float}>>}
*/
private function dailyActivity(string $platform, string $start, string $end, array $dates): array
{
$dateSet = array_fill_keys($dates, true);
$byDate = [];
$byStore = [];
foreach ($this->fetchPlatformDailyRows($platform, $start, $end) as $row) {
$date = substr(trim((string) ($row['occurred_at'] ?? '')), 0, 10);
if (! isset($dateSet[$date])) {
continue;
}
$storeKey = $this->dailyStoreKey($platform, (string) ($row['store_name'] ?? ''));
$incomeCents = (int) round((float) ($row['income'] ?? 0) * 100);
$expenseCents = (int) round((float) ($row['expense'] ?? 0) * 100);
$byDate[$date]['income_cents'] = ($byDate[$date]['income_cents'] ?? 0) + $incomeCents;
$byDate[$date]['expense_cents'] = ($byDate[$date]['expense_cents'] ?? 0) + $expenseCents;
$byStore[$storeKey][$date]['income_cents'] = (
$byStore[$storeKey][$date]['income_cents'] ?? 0
) + $incomeCents;
$byStore[$storeKey][$date]['expense_cents'] = (
$byStore[$storeKey][$date]['expense_cents'] ?? 0
) + $expenseCents;
}
foreach ($byDate as $date => $value) {
$byDate[$date] = [
'income' => round(($value['income_cents'] ?? 0) / 100, 2),
'expense' => round(($value['expense_cents'] ?? 0) / 100, 2),
];
}
foreach ($byStore as $storeKey => $storeDates) {
foreach ($storeDates as $date => $value) {
$byStore[$storeKey][$date] = [
'income' => round(($value['income_cents'] ?? 0) / 100, 2),
'expense' => round(($value['expense_cents'] ?? 0) / 100, 2),
];
}
}
return ['by_date' => $byDate, 'by_store' => $byStore];
}
/**
* @param list<string> $dates
* @param array<string,array{income:float,expense:float}> $activity
* @return array<string,array{date:string,opening:float|null,income:float,expense:float,closing:float|null,available:bool}>
*/
private function rollDailyBalances(array $dates, ?float $opening, array $activity): array
{
$currentClosing = $opening === null ? null : round($opening, 2);
$daily = [];
foreach ($dates as $date) {
$dayIncome = round((float) ($activity[$date]['income'] ?? 0), 2);
$dayExpense = round((float) ($activity[$date]['expense'] ?? 0), 2);
$dayOpening = $currentClosing;
if ($currentClosing !== null) {
$currentClosing = round($currentClosing + $dayIncome - $dayExpense, 2);
}
$daily[$date] = [
'date' => $date,
'opening' => $dayOpening,
'income' => $dayIncome,
'expense' => $dayExpense,
'closing' => $currentClosing,
'available' => $currentClosing !== null,
];
}
return $daily;
}
/**
* @param array<string,array{income:float,expense:float,closing:float|null}> $daily
*/
private function dailyReconciled(array $daily, ?float $income, ?float $expense): bool
{
if ($income === null || $expense === null || $daily === []) {
return false;
}
$dailyIncome = round(array_sum(array_column($daily, 'income')), 2);
$dailyExpense = round(array_sum(array_column($daily, 'expense')), 2);
return abs($dailyIncome - $income) <= 0.02 && abs($dailyExpense - $expense) <= 0.02;
}
/**
* @param list<string> $dates
* @param array<string,array{income:float,expense:float,closing:float|null,available:bool}> $daily
* @return array{income:float,expense:float,closing:float|null,available:bool}
*/
private function dailyTotals(array $dates, array $daily): array
{
$rows = array_values(array_intersect_key($daily, array_fill_keys($dates, true)));
$available = $rows !== [] && ! in_array(false, array_column($rows, 'available'), true);
return [
'income' => round(array_sum(array_column($rows, 'income')), 2),
'expense' => round(array_sum(array_column($rows, 'expense')), 2),
'closing' => $available
? round((float) ($rows[array_key_last($rows)]['closing'] ?? 0), 2)
: null,
'available' => $available,
];
}
private function dailyStoreKey(string $platform, string $storeName): string
{
$storeName = $this->storeName($storeName);
return in_array($platform, ['pinduoduo', 'douyin'], true)
? JushuitanShopBalanceRepository::normalizeStoreName($storeName)
: $storeName;
}
/** @return array<string,mixed> */
private function flowDetail(string $periodStart, ?string $periodEnd, string $flow): array
{
@ -1126,14 +1405,16 @@ class StoreReceivingBalanceOverviewService
string $platform,
string $start,
string $end,
string $flow,
?string $flow,
): iterable
{
$filters = [
'start' => $start,
'end' => $end,
'business_type' => $flow === 'income' ? '收入' : '支出',
];
if ($flow !== null) {
$filters['business_type'] = $flow === 'income' ? '收入' : '支出';
}
if ($platform === 'taobao-alipay') {
$filters['exclude_store_name_prefix'] = self::OVERVIEW_EXCLUDED_TAOBAO_ALIPAY_STORE_PREFIX;
}
@ -1169,8 +1450,14 @@ class StoreReceivingBalanceOverviewService
{
$query = AccountBill::query()
->where('company_id', company_id())
->where('bill_type', $platform)
->where($flow, '>', 0);
->where('bill_type', $platform);
if ($flow === null) {
$query->where(function (Builder $query): void {
$query->where('income', '>', 0)->orWhere('expense', '>', 0);
});
} else {
$query->where($flow, '>', 0);
}
if (in_array($platform, ['vipshop', 'vipshop-jx'], true)) {
$settlePeriod = "JSON_UNQUOTE(JSON_EXTRACT(payload, '$.settle_period'))";
@ -1187,6 +1474,7 @@ class StoreReceivingBalanceOverviewService
'bill_item' => $platform === 'vipshop-jx'
? (string) data_get($bill->payload ?? [], 'second_remark', '')
: (string) ($bill->bill_item ?? ''),
'occurred_at' => (string) ($bill->occurred_at ?? ''),
'income' => (float) $bill->income,
'expense' => (float) $bill->expense,
];

View File

@ -53,6 +53,8 @@ Route::get('ecommerce-finance/account-bills/overview/balance-detail', [StoreRece
->name('ecommerce-finance.account-bills.overview.balance-detail');
Route::get('ecommerce-finance/account-bills/overview/balance-store-detail', [StoreReceivingBalanceOverview::class, 'balanceStoreDetail'])
->name('ecommerce-finance.account-bills.overview.balance-store-detail');
Route::get('ecommerce-finance/account-bills/overview/daily-balance', [StoreReceivingBalanceOverview::class, 'dailyBalances'])
->name('ecommerce-finance.account-bills.overview.daily-balance');
Route::get('ecommerce-finance/alipay-bills', [AlipayBills::class, 'index'])
->name('ecommerce-finance.alipay-bills.index');
Route::get('ecommerce-finance/alipay-bills/export', [AlipayBills::class, 'export'])

View File

@ -80,6 +80,83 @@ class StoreReceivingBalanceOverviewEndpointTest extends FeatureTestCase
->assertJsonPath('summary.complete', true);
}
public function test_daily_balance_endpoint_returns_platform_and_store_rows(): void
{
$this->user->attachPermission(
Permission::where('name', 'read-admin-panel')->firstOrFail()
);
$payload = [
'month' => '2026-10',
'period' => ['start' => '2026-10-01', 'end' => '2026-10-31'],
'summary' => [
'opening_balance' => 100.0,
'income' => 30.0,
'expense' => 10.0,
'balance' => 120.0,
'platform_count' => 8,
'available_platform_count' => 8,
'complete' => true,
],
'platforms' => [[
'slug' => 'taobao-alipay',
'name' => '淘系支付宝账户',
'daily' => [
'2026-10-01' => [
'date' => '2026-10-01',
'opening' => 100.0,
'income' => 30.0,
'expense' => 10.0,
'closing' => 120.0,
'available' => true,
],
],
]],
'dates' => ['2026-10-01'],
'daily_summary' => [
'2026-10-01' => [
'date' => '2026-10-01',
'opening' => 100.0,
'income' => 30.0,
'expense' => 10.0,
'closing' => 120.0,
'available' => true,
],
],
'stores' => [[
'platform_slug' => 'taobao-alipay',
'platform' => '淘系支付宝账户',
'store_name' => '测试店铺',
'opening_balance' => 100.0,
'income' => 30.0,
'expense' => 10.0,
'amount' => 120.0,
'available' => true,
'daily' => [],
]],
'store_summary' => ['store_count' => 1, 'available_store_count' => 1],
'daily_errors' => [],
'daily_note' => '按账单实际发生日期滚动计算。',
];
$service = Mockery::mock(StoreReceivingBalanceOverviewService::class);
$service->shouldReceive('dailyBalances')
->once()
->with('2026-10-01', '2026-10-31')
->andReturn($payload);
$this->app->instance(StoreReceivingBalanceOverviewService::class, $service);
$this->loginAs()
->getJson(route('ecommerce-finance.account-bills.overview.daily-balance', [
'start' => '2026-10-01',
'end' => '2026-10-31',
]))
->assertOk()
->assertJsonPath('dates.0', '2026-10-01')
->assertJsonPath('platforms.0.daily.2026-10-01.closing', 120)
->assertJsonPath('stores.0.store_name', '测试店铺')
->assertJsonPath('store_summary.available_store_count', 1);
}
public function test_overview_page_uses_the_vue_mount_point(): void
{
$this->user->attachPermission(

View File

@ -377,6 +377,108 @@ class StoreReceivingBalanceOverviewServiceTest extends TestCase
$this->assertSame(330.0, $result['rows'][2]['amount']);
}
public function test_daily_balances_roll_platform_and_store_opening_balances(): void
{
$service = new class extends StoreReceivingBalanceOverviewService {
public function __construct()
{
}
protected function fetchPlatformSummary(string $platform, string $start, string $end): array
{
return [
'opening_balance' => 100.0,
'income' => 15.0,
'expense' => 6.0,
];
}
protected function fetchPlatformStoreBalances(string $platform, string $start, string $end): array
{
$index = array_search($platform, array_column(StoreReceivingBalanceOverviewService::PLATFORMS, 'slug'), true) + 1;
return [[
'store_name' => '店铺-' . $index,
'opening_balance' => 100.0,
'income' => 15.0,
'expense' => 6.0,
]];
}
protected function fetchPlatformDailyRows(string $platform, string $start, string $end): iterable
{
$index = array_search($platform, array_column(StoreReceivingBalanceOverviewService::PLATFORMS, 'slug'), true) + 1;
yield [
'store_name' => '店铺-' . $index,
'occurred_at' => '2026-10-01 12:00:00',
'income' => 10.0,
'expense' => 2.0,
];
yield [
'store_name' => '店铺-' . $index,
'occurred_at' => '2026-10-02 12:00:00',
'income' => 5.0,
'expense' => 4.0,
];
}
};
$result = $service->dailyBalances('2026-10-01', '2026-10-03');
$this->assertSame(['2026-10-01', '2026-10-02', '2026-10-03'], $result['dates']);
$this->assertSame(108.0, $result['daily_summary']['2026-10-01']['closing'] / 8);
$this->assertSame(109.0, $result['daily_summary']['2026-10-02']['closing'] / 8);
$this->assertSame(109.0, $result['daily_summary']['2026-10-03']['closing'] / 8);
$this->assertSame(8, $result['store_summary']['store_count']);
$this->assertSame(8, $result['store_summary']['available_store_count']);
$this->assertSame(100.0, $result['stores'][0]['opening_balance']);
$this->assertSame(109.0, $result['stores'][0]['amount']);
$this->assertTrue($result['stores'][0]['daily']['2026-10-03']['available']);
$this->assertTrue($result['platforms'][0]['daily_reconciled']);
}
public function test_daily_store_balance_stays_unavailable_when_opening_is_missing(): void
{
$service = new class extends StoreReceivingBalanceOverviewService {
public function __construct()
{
}
protected function fetchPlatformSummary(string $platform, string $start, string $end): array
{
return ['opening_balance' => 100.0, 'income' => 10.0, 'expense' => 2.0];
}
protected function fetchPlatformStoreBalances(string $platform, string $start, string $end): array
{
return [[
'store_name' => '待补期初店铺-' . $platform,
'opening_balance' => null,
'income' => 10.0,
'expense' => 2.0,
]];
}
protected function fetchPlatformDailyRows(string $platform, string $start, string $end): iterable
{
yield [
'store_name' => '待补期初店铺-' . $platform,
'occurred_at' => '2026-10-01 12:00:00',
'income' => 10.0,
'expense' => 2.0,
];
}
};
$result = $service->dailyBalances('2026-10-01', '2026-10-01');
$this->assertTrue($result['daily_summary']['2026-10-01']['available']);
$this->assertFalse($result['stores'][0]['daily']['2026-10-01']['available']);
$this->assertNull($result['stores'][0]['daily']['2026-10-01']['closing']);
$this->assertSame(0, $result['store_summary']['available_store_count']);
}
private function service(callable $summary): StoreReceivingBalanceOverviewService
{
return new class($summary) extends StoreReceivingBalanceOverviewService {

View File

@ -50,43 +50,50 @@ class StoreReceivingBalanceOverviewTest extends TestCase
$this->assertStringContainsString('暂不展示不完整合计', $source);
}
public function test_overview_uses_seeded_rolling_data_and_exact_validation_targets(): void
public function test_overview_uses_the_real_daily_balance_endpoint(): void
{
$source = $this->overviewSource();
$this->assertStringContainsString('const mulberry32 = (seed)', $source);
$this->assertStringContainsString('mulberry32(20261001)', $source);
$this->assertStringContainsString('const allocateCents = (targetCents, weights)', $source);
$this->assertStringContainsString('if ([10, 20, 31].includes(dayOfMonth)) expenseWeight *= 1.55;', $source);
$this->assertStringContainsString('const closing = runningOpening + dayIncome - dayExpense;', $source);
$this->assertStringContainsString('runningOpening = closing;', $source);
$this->assertLessThan(
strpos($source, 'const expenseByDay = allocateCents'),
strpos($source, 'const incomeByDay = allocateCents'),
);
$this->assertStringContainsString('${this.apiBase}/daily-balance', $source);
$this->assertStringContainsString('this.dailySummary = body.daily_summary || {}', $source);
$this->assertStringContainsString("this.stores = Array.isArray(body.stores) ? body.stores : []", $source);
$this->assertStringContainsString('dailyLoading', $source);
$this->assertStringContainsString('每日余额按账单实际发生日期滚动计算', $source);
$this->assertStringNotContainsString('const mulberry32 = (seed)', $source);
$this->assertStringNotContainsString('buildSeededTrend', $source);
}
public function test_overview_renders_svg_chart_tooltip_and_sticky_table(): void
public function test_overview_renders_dimension_tables_and_day_detail(): void
{
$source = $this->overviewSource();
$this->assertStringContainsString("label: '汇总'", $source);
$this->assertStringContainsString("label: '平台'", $source);
$this->assertStringContainsString("label: '店铺'", $source);
$this->assertStringContainsString('class="trend-matrix-table"', $source);
$this->assertStringContainsString('class="trend-store-filters"', $source);
$this->assertStringContainsString('v-model="storePlatformFilter"', $source);
$this->assertStringContainsString('v-model.trim="storeKeyword"', $source);
$this->assertStringContainsString('@click="openDailyDetail(\'store\', store, date)"', $source);
$this->assertStringContainsString('v-if="selectedDailyDetail"', $source);
$this->assertStringContainsString('dailyDetailMoney(\'opening\')', $source);
$this->assertStringContainsString('dailyDetailSigned(\'income\')', $source);
$this->assertStringContainsString('dailyDetailSigned(\'expense\')', $source);
$this->assertStringContainsString('dailyDetailMoney(\'closing\')', $source);
$this->assertStringContainsString('trend-store-pagination', $source);
}
public function test_overview_keeps_chart_and_summary_table(): void
{
$source = $this->overviewSource();
$this->assertStringContainsString('<svg', $source);
$this->assertStringContainsString('class="trend-line"', $source);
$this->assertStringContainsString('class="trend-area"', $source);
$this->assertStringContainsString('balance-area-gradient', $source);
$this->assertStringContainsString('@mouseenter="showTooltip($event, point.index)"', $source);
$this->assertStringContainsString('role="tooltip"', $source);
$this->assertStringContainsString('期初 <b>', $source);
$this->assertStringContainsString('收入 <b class="is-income">', $source);
$this->assertStringContainsString('支出 <b class="is-expense">', $source);
$this->assertStringContainsString('期末 <b class="is-balance">', $source);
$this->assertStringContainsString('每日余额明细', $source);
$this->assertStringContainsString('position: sticky;', $source);
$this->assertStringContainsString('max-height: 18.75rem;', $source);
$this->assertStringContainsString(
'注:顶部汇总卡片取自账户余额总览实际数据;每日曲线与明细为演示数据,接入真实流水后自动替换',
$source,
);
$this->assertStringContainsString('{{ dailyNote }}', $source);
}
public function test_overview_tab_is_placed_before_taobao_alipay_navigation(): void