first version

2026-07-23 20:41:25 +08:00
parent 00a0938a1b
commit 10cff754a4
211 changed files with 11577 additions and 842 deletions
@@ -0,0 +1,136 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\StoreModel;
+use App\Models\SupplierModel;
+use App\Models\UserModel;
+use App\Services\WechatService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序认证（微信登录 / 手机号绑定 / 当前用户信息）
+ *
+ * authGuard: users（provider 指向 UserModel，与后台 sys_users 天然隔离）；
+ * authorize: true 仅要求登录（sanctum + authGuard:users），不做细粒度权限点；
+ * token abilities ['mini'] 作来源标记。
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class AuthController extends BaseMiniController
+{
+    /** 小程序登录：wx.login 的 code → openid → 自动注册/登录 → 签发 token */
+    #[PostRoute('/auth/login', authorize: false)]
+    public function login(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'code' => 'required|string',
+        ], [
+            'code.required' => '缺少登录凭证 code',
+        ]);
+
+        $session = app(WechatService::class)->code2Session($data['code']);
+
+        $user = UserModel::firstOrNew(['openid' => $session['openid']]);
+        $isNew = ! $user->exists;
+
+        if ($user->status === UserModel::STATUS_DISABLED) {
+            throw new RepositoryException('账号已被停用，请联系客服');
+        }
+        if ($isNew) {
+            $user->type = UserModel::TYPE_PENDING;
+            $user->status = UserModel::STATUS_NORMAL;
+        }
+        if (! empty($session['unionid'])) {
+            $user->unionid = $session['unionid'];
+        }
+        $user->last_login_at = now();
+        $user->save();
+
+        $token = $user->createToken('mini', ['mini'])->plainTextToken;
+
+        return $this->success([
+            'token' => $token,
+            'user' => $this->formatUser($user->fresh(['store.level:id,name', 'supplier:id,name'])),
+        ], $isNew ? '注册成功' : '登录成功');
+    }
+
+    /**
+     * 绑定手机号：phoneCode 换手机号 → 按手机号自动匹配门店/供应商
+     * （命中门店 → type=1+store_id；命中供应商 → type=2+supplier_id；都不命中 → 保持待绑定，后台人工处理）
+     */
+    #[PostRoute('/auth/phone', authorize: true)]
+    public function phone(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'phoneCode' => 'required|string',
+        ], [
+            'phoneCode.required' => '缺少手机号授权凭证 phoneCode',
+        ]);
+
+        $phone = app(WechatService::class)->getPhone($data['phoneCode']);
+
+        $user = $this->currentUser($request);
+        $user->phone = $phone;
+
+        if (! $user->isBound()) {
+            $store = StoreModel::where('phone', $phone)
+                ->where('status', StoreModel::STATUS_NORMAL)
+                ->first();
+            if ($store !== null) {
+                $user->type = UserModel::TYPE_STORE;
+                $user->store_id = $store->id;
+                $user->supplier_id = 0;
+            } else {
+                $supplier = SupplierModel::where('phone', $phone)
+                    ->where('status', SupplierModel::STATUS_NORMAL)
+                    ->first();
+                if ($supplier !== null) {
+                    $user->type = UserModel::TYPE_SUPPLIER;
+                    $user->supplier_id = $supplier->id;
+                    $user->store_id = 0;
+                }
+            }
+        }
+        $user->save();
+
+        return $this->success([
+            'user' => $this->formatUser($user->fresh(['store.level:id,name', 'supplier:id,name'])),
+        ]);
+    }
+
+    /** 当前用户信息（含门店客户等级 —— 全局价格体系依据 / 供应商信息） */
+    #[GetRoute('/auth/info', authorize: true)]
+    public function info(Request $request): JsonResponse
+    {
+        $user = UserModel::with(['store.level:id,name', 'supplier:id,name'])
+            ->find($request->user()->id);
+        if ($user === null) {
+            throw new RepositoryException('账号不存在');
+        }
+
+        return $this->success(['user' => $this->formatUser($user)]);
+    }
+
+    /**
+     * 小程序端用户信息输出结构
+     *
+     * @return array<string, mixed>
+     */
+    private function formatUser(UserModel $user): array
+    {
+        return [
+            'id' => $user->id,
+            'nickname' => $user->nickname,
+            'avatar' => $user->avatar,
+            'phone' => $user->phone,
+            'type' => $user->type,
+            'store' => $user->store,
+            'supplier' => $user->supplier,
+        ];
+    }
+}
@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\StoreModel;
+use App\Models\SupplierModel;
+use App\Models\UserModel;
+use Illuminate\Http\Request;
+use Modules\Common\Http\Controllers\BaseController;
+
+/**
+ * 小程序端控制器基类
+ *
+ * 无 #[RequestAttribute]，不会被 AnnoRoute 注册为路由。
+ * 提供当前用户获取与门店/供应商绑定前置校验。
+ */
+abstract class BaseMiniController extends BaseController
+{
+    /**
+     * 当前小程序用户（auth:sanctum 注入的 tokenable）
+     */
+    protected function currentUser(Request $request): UserModel
+    {
+        $user = UserModel::find($request->user()->id);
+        if ($user === null || $user->status === UserModel::STATUS_DISABLED) {
+            throw new RepositoryException('账号不存在或已被停用');
+        }
+
+        return $user;
+    }
+
+    /**
+     * 门店端前置校验：type=门店 且 store_id>0 且门店正常
+     */
+    protected function ensureStoreBound(UserModel $user): StoreModel
+    {
+        if ($user->type !== UserModel::TYPE_STORE || $user->store_id <= 0) {
+            throw new RepositoryException('尚未绑定门店，请联系客服处理');
+        }
+        $store = StoreModel::find($user->store_id);
+        if ($store === null || $store->status !== StoreModel::STATUS_NORMAL) {
+            throw new RepositoryException('门店不存在或已停用，请联系客服处理');
+        }
+
+        return $store;
+    }
+
+    /**
+     * 供应商端前置校验：type=供应商 且 supplier_id>0 且供应商正常
+     */
+    protected function ensureSupplierBound(UserModel $user): SupplierModel
+    {
+        if ($user->type !== UserModel::TYPE_SUPPLIER || $user->supplier_id <= 0) {
+            throw new RepositoryException('尚未绑定供应商，请联系客服处理');
+        }
+        $supplier = SupplierModel::find($user->supplier_id);
+        if ($supplier === null || $supplier->status !== SupplierModel::STATUS_NORMAL) {
+            throw new RepositoryException('供应商不存在或已停用，请联系客服处理');
+        }
+
+        return $supplier;
+    }
+}
@@ -0,0 +1,89 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\NoticeModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序通知（本人通知 + 全员广播）
+ *
+ * 广播已读处理：user_id=0 的广播是全局共享记录，直接改 is_read 会影响其他用户，
+ * 因此标记已读时复制一条本人专属的已读记录（data.broadcast_from 记来源），
+ * 列表查询时排除已有已读副本的广播。
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class NoticeController extends BaseMiniController
+{
+    /** 本人通知 + 全员广播（user_id in [0, 当前id]），分页 + unread_count */
+    #[GetRoute('/notice', authorize: true)]
+    public function index(Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+
+        // 本人已读过的广播来源ID（已读副本记录）
+        $readBroadcastIds = NoticeModel::query()
+            ->where('user_id', $user->id)
+            ->whereNotNull('data->broadcast_from')
+            ->pluck('data->broadcast_from');
+
+        $query = NoticeModel::query()->where(function ($q) use ($user, $readBroadcastIds) {
+            $q->where('user_id', $user->id)
+                ->orWhere(function ($broadcastQuery) use ($readBroadcastIds) {
+                    $broadcastQuery->where('user_id', NoticeModel::BROADCAST_USER_ID);
+                    if ($readBroadcastIds->isNotEmpty()) {
+                        $broadcastQuery->whereNotIn('id', $readBroadcastIds->all());
+                    }
+                });
+        });
+
+        $unreadCount = (clone $query)->where('is_read', NoticeModel::UNREAD)->count();
+
+        $data = $query->orderBy('id', 'desc')
+            ->paginate((int) $request->input('pageSize', 10))
+            ->toArray();
+        $data['unread_count'] = $unreadCount;
+
+        return $this->success($data);
+    }
+
+    /** 标记已读（广播 → 复制本人已读副本；个人通知 → 直接更新） */
+    #[PutRoute('/notice/{id}/read', authorize: true, where: ['id' => '[0-9]+'])]
+    public function read(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+
+        $notice = NoticeModel::whereIn('user_id', [NoticeModel::BROADCAST_USER_ID, $user->id])->find($id);
+        if ($notice === null) {
+            throw new RepositoryException('通知不存在');
+        }
+
+        if ($notice->user_id === NoticeModel::BROADCAST_USER_ID) {
+            $exists = NoticeModel::where('user_id', $user->id)
+                ->where('data->broadcast_from', $notice->id)
+                ->exists();
+            if (! $exists) {
+                NoticeModel::create([
+                    'user_id' => $user->id,
+                    'type' => $notice->type,
+                    'title' => $notice->title,
+                    'content' => $notice->content,
+                    'data' => ['broadcast_from' => $notice->id] + (array) $notice->data,
+                    'is_read' => NoticeModel::READ,
+                    'read_at' => now(),
+                ]);
+            }
+        } elseif ($notice->is_read === NoticeModel::UNREAD) {
+            $notice->is_read = NoticeModel::READ;
+            $notice->read_at = now();
+            $notice->save();
+        }
+
+        return $this->success();
+    }
+}
@@ -0,0 +1,219 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Http\Requests\Mini\MiniOrderRequest;
+use App\Models\ProductModel;
+use App\Models\ProductPriceModel;
+use App\Models\StoreOrderItemModel;
+use App\Models\StoreOrderModel;
+use App\Services\BillNumberService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序门店订单（下单 / 历史 / 详情 / 取消 / 周期汇总）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class OrderController extends BaseMiniController
+{
+    /**
+     * 下单：逐行取当前门店等级价快照，服务端重算 amount 与 total（不接受前端金额）
+     */
+    #[PostRoute('/order', authorize: true)]
+    public function store(MiniOrderRequest $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+        if ($store->level_id <= 0) {
+            throw new RepositoryException('门店未设置客户等级，无法下单，请联系客服');
+        }
+
+        $items = $request->validated('items');
+        $remark = (string) ($request->validated('remark') ?? '');
+
+        $order = DB::transaction(function () use ($store, $items, $remark) {
+            $productIds = array_map(static fn ($row) => (int) $row['product_id'], $items);
+
+            $products = ProductModel::query()
+                ->where('status', ProductModel::STATUS_ON)
+                ->whereIn('id', $productIds)
+                ->get()
+                ->keyBy('id');
+
+            $prices = ProductPriceModel::query()
+                ->where('level_id', $store->level_id)
+                ->whereIn('product_id', $productIds)
+                ->pluck('price', 'product_id');
+
+            $totalQuantity = '0';
+            $totalAmount = '0';
+            $now = now();
+            $rows = [];
+            foreach ($items as $row) {
+                $productId = (int) $row['product_id'];
+                $product = $products->get($productId);
+                if ($product === null) {
+                    throw new RepositoryException('存在已下架或不存在的商品，请刷新后重试');
+                }
+                if (! isset($prices[$productId])) {
+                    throw new RepositoryException('商品「' . $product->name . '」未设置您所在等级的价格，无法下单');
+                }
+
+                $price = (string) $prices[$productId];
+                $quantity = (string) $row['quantity'];
+                $amount = bcmul($price, $quantity, 2);
+                $totalQuantity = bcadd($totalQuantity, $quantity, 2);
+                $totalAmount = bcadd($totalAmount, $amount, 2);
+
+                $rows[] = [
+                    'store_id' => $store->id,
+                    'product_id' => $productId,
+                    'product_name' => $product->name,
+                    'product_spec' => $product->spec,
+                    'price' => $price,
+                    'quantity' => $quantity,
+                    'weight' => 0,
+                    'amount' => $amount,
+                    'remark' => '',
+                    'created_at' => $now,
+                    'updated_at' => $now,
+                ];
+            }
+
+            $order = StoreOrderModel::create([
+                'order_no' => app(BillNumberService::class)->make('SO'),
+                'store_id' => $store->id,
+                'order_date' => $now->toDateString(),
+                'total_quantity' => $totalQuantity,
+                'total_weight' => 0,
+                'total_amount' => $totalAmount,
+                'status' => StoreOrderModel::STATUS_PENDING,
+                'remark' => $remark,
+            ]);
+
+            foreach ($rows as &$itemRow) {
+                $itemRow['order_id'] = $order->id;
+            }
+            StoreOrderItemModel::insert($rows);
+
+            return $order;
+        });
+
+        return $this->success([
+            'id' => $order->id,
+            'order_no' => $order->order_no,
+            'total_amount' => $order->total_amount,
+        ], '下单成功');
+    }
+
+    /** 历史订单：当前门店强制过滤，?status=&page=&pageSize= */
+    #[GetRoute('/order', authorize: true)]
+    public function index(Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $query = StoreOrderModel::query()->where('store_id', $store->id);
+        if ($request->filled('status')) {
+            $query->where('status', (int) $request->input('status'));
+        }
+
+        $data = $query->orderBy('order_date', 'desc')
+            ->orderBy('id', 'desc')
+            ->paginate((int) $request->input('pageSize', 10))
+            ->toArray();
+
+        return $this->success($data);
+    }
+
+    /**
+     * 按周期聚合金额/数量：?period=day|week|month（分组列表，period_label 可作下钻查询参数）
+     */
+    #[GetRoute('/order/summary', authorize: true)]
+    public function summary(Request $request): JsonResponse
+    {
+        $period = (string) $request->query('period', 'month');
+        if (! in_array($period, ['day', 'week', 'month'], true)) {
+            throw new RepositoryException('period 参数只能是 day/week/month');
+        }
+
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        // 按数据库方言选择周期分组表达式（生产 MySQL / 测试 SQLite）
+        $driver = DB::connection()->getDriverName();
+        if ($driver === 'sqlite') {
+            $format = match ($period) {
+                'day' => '%Y-%m-%d',
+                'week' => '%Y-W%W',
+                default => '%Y-%m',
+            };
+            $labelExpr = "strftime('{$format}', order_date)";
+        } else {
+            $format = match ($period) {
+                'day' => '%Y-%m-%d',
+                'week' => '%x-W%v',
+                default => '%Y-%m',
+            };
+            $labelExpr = "DATE_FORMAT(order_date, '{$format}')";
+        }
+
+        $rows = StoreOrderModel::query()
+            ->where('store_id', $store->id)
+            ->where('status', '<>', StoreOrderModel::STATUS_CANCELLED)
+            ->selectRaw("{$labelExpr} as period_label")
+            ->selectRaw('SUM(total_amount) as total_amount, SUM(total_quantity) as total_quantity, COUNT(*) as order_count')
+            ->groupBy('period_label')
+            ->orderByDesc('period_label')
+            ->limit(50)
+            ->get()
+            ->toArray();
+
+        return $this->success(['period' => $period, 'groups' => $rows]);
+    }
+
+    /** 订单详情（校验归属：仅能查看本店订单） */
+    #[GetRoute('/order/{id}', authorize: true, where: ['id' => '[0-9]+'])]
+    public function detail(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $order = StoreOrderModel::with('items')
+            ->where('store_id', $store->id)
+            ->find($id);
+        if ($order === null) {
+            throw new RepositoryException('订单不存在');
+        }
+
+        return $this->success($order->toArray());
+    }
+
+    /** 取消订单（仅待汇总可取消） */
+    #[PutRoute('/order/{id}/cancel', authorize: true, where: ['id' => '[0-9]+'])]
+    public function cancel(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $order = StoreOrderModel::where('store_id', $store->id)->find($id);
+        if ($order === null) {
+            throw new RepositoryException('订单不存在');
+        }
+        if ($order->status !== StoreOrderModel::STATUS_PENDING) {
+            throw new RepositoryException('仅待汇总的订单可以取消');
+        }
+
+        $order->status = StoreOrderModel::STATUS_CANCELLED;
+        $order->save();
+
+        return $this->success([], '订单已取消');
+    }
+}
@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\ProductCategoryModel;
+use App\Models\ProductModel;
+use App\Models\ProductPriceModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序商品（分类树 + 列表，价格 = 当前门店客户等级价）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class ProductController extends BaseMiniController
+{
+    /** 分类树（仅含上架商品的分类及其祖先，保证树结构完整） */
+    #[GetRoute('/product/categories', authorize: true)]
+    public function categories(): JsonResponse
+    {
+        $activeCategoryIds = ProductModel::query()
+            ->where('status', ProductModel::STATUS_ON)
+            ->distinct()
+            ->pluck('category_id')
+            ->map(static fn ($id) => (int) $id)
+            ->filter(static fn (int $id) => $id > 0);
+
+        $categories = ProductCategoryModel::query()
+            ->where('status', ProductCategoryModel::STATUS_NORMAL)
+            ->get()
+            ->keyBy('id');
+
+        // 保留有上架商品的分类 + 其全部祖先
+        $keep = [];
+        foreach ($activeCategoryIds as $categoryId) {
+            $cursor = $categoryId;
+            $guard = 0;
+            while ($cursor > 0 && $guard++ < 20 && $categories->has($cursor)) {
+                $keep[$cursor] = true;
+                $cursor = (int) $categories[$cursor]->parent_id;
+            }
+        }
+
+        $filtered = array_values(array_filter(
+            $categories->toArray(),
+            static fn (array $item) => isset($keep[$item['id']])
+        ));
+
+        return $this->success(ProductCategoryModel::buildTree($filtered));
+    }
+
+    /**
+     * 商品列表：价格取当前门店客户等级价（未绑等级的门店报错）；
+     * ?category_id=&keyword=&page=&pageSize=
+     */
+    #[GetRoute('/product/list', authorize: true)]
+    public function products(Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+        if ($store->level_id <= 0) {
+            throw new RepositoryException('门店未设置客户等级，无法展示价格，请联系客服');
+        }
+
+        $query = ProductModel::query()
+            ->where('status', ProductModel::STATUS_ON)
+            ->with('category:id,name')
+            ->with(['prices' => static fn ($q) => $q->where('level_id', $store->level_id)]);
+
+        $categoryId = (int) $request->input('category_id', 0);
+        if ($categoryId > 0) {
+            $query->where('category_id', $categoryId);
+        }
+        $keyword = trim((string) $request->input('keyword', ''));
+        if ($keyword !== '') {
+            $query->where(static function ($q) use ($keyword) {
+                $q->where('name', 'like', '%' . $keyword . '%')
+                    ->orWhere('spec', 'like', '%' . $keyword . '%');
+            });
+        }
+
+        $pageSize = (int) $request->input('pageSize', 10);
+        $data = $query->orderBy('sort')
+            ->orderBy('id')
+            ->paginate($pageSize)
+            ->toArray();
+
+        // 扁平化价格：prices[0].price → price（未设等级价为 null）
+        foreach ($data['data'] as &$row) {
+            $row['price'] = $row['prices'][0]['price'] ?? null;
+            unset($row['prices']);
+        }
+
+        return $this->success($data);
+    }
+}
@@ -0,0 +1,105 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\StatementModel;
+use App\Services\ExportService;
+use App\Services\StatementGenerateService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PostRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * 小程序门店对账单（自助生成 / 查看 / 导出）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class StatementController extends BaseMiniController
+{
+    /** 对账单列表（当前门店） */
+    #[GetRoute('/statement', authorize: true)]
+    public function index(Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $data = StatementModel::query()
+            ->where('store_id', $store->id)
+            ->orderBy('id', 'desc')
+            ->paginate((int) $request->input('pageSize', 10))
+            ->toArray();
+
+        return $this->success($data);
+    }
+
+    /** 生成对账单：快照当前回款周期，settlement_date = period_end + cycle 天 */
+    #[PostRoute('/statement/generate', authorize: true)]
+    public function generate(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'period_start' => 'required|date_format:Y-m-d',
+            'period_end' => 'required|date_format:Y-m-d|after_or_equal:period_start',
+        ], [
+            'period_start.required' => '请选择对账周期开始日期',
+            'period_start.date_format' => '开始日期格式为 Y-m-d',
+            'period_end.required' => '请选择对账周期结束日期',
+            'period_end.date_format' => '结束日期格式为 Y-m-d',
+            'period_end.after_or_equal' => '结束日期不能早于开始日期',
+        ]);
+
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $statement = app(StatementGenerateService::class)->generate(
+            $store,
+            $data['period_start'],
+            $data['period_end'],
+        );
+
+        return $this->success([
+            'id' => $statement->id,
+            'statement_no' => $statement->statement_no,
+            'total_amount' => $statement->total_amount,
+            'settlement_date' => $statement->settlement_date?->toDateString(),
+        ], '对账单已生成');
+    }
+
+    /** 对账单详情（校验归属，含单品对账状态标识） */
+    #[GetRoute('/statement/{id}', authorize: true, where: ['id' => '[0-9]+'])]
+    public function detail(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $statement = StatementModel::with('items')
+            ->where('store_id', $store->id)
+            ->find($id);
+        if ($statement === null) {
+            throw new RepositoryException('对账单不存在');
+        }
+
+        return $this->success($statement->toArray());
+    }
+
+    /** 导出对账单：?format=xlsx|pdf */
+    #[GetRoute('/statement/{id}/export', authorize: true, where: ['id' => '[0-9]+'])]
+    public function export(int $id, Request $request): Response
+    {
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $statement = StatementModel::where('store_id', $store->id)->find($id);
+        if ($statement === null) {
+            throw new RepositoryException('对账单不存在');
+        }
+
+        return app(ExportService::class)->download(
+            'statement',
+            $statement,
+            (string) $request->query('format', ExportService::FORMAT_XLSX),
+        );
+    }
+}
@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序门店设置（回款周期自配置，影响对账单应结算日期）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class StoreController extends BaseMiniController
+{
+    /** 修改回款周期（≥0，无上限） */
+    #[PutRoute('/store/paymentCycle', authorize: true)]
+    public function paymentCycle(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'payment_cycle_days' => 'required|integer|min:0',
+        ], [
+            'payment_cycle_days.required' => '回款周期不能为空',
+            'payment_cycle_days.integer' => '回款周期必须为整数',
+            'payment_cycle_days.min' => '回款周期不能小于 0',
+        ]);
+
+        $user = $this->currentUser($request);
+        $store = $this->ensureStoreBound($user);
+
+        $store->payment_cycle_days = (int) $data['payment_cycle_days'];
+        $store->save();
+
+        return $this->success(['payment_cycle_days' => $store->payment_cycle_days], '回款周期已更新');
+    }
+}
@@ -0,0 +1,104 @@
+<?php
+
+namespace App\Http\Controllers\Mini;
+
+use App\Exceptions\RepositoryException;
+use App\Models\PurchaseOrderItemModel;
+use App\Models\PurchaseOrderModel;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Modules\AnnoRoute\Attribute\GetRoute;
+use Modules\AnnoRoute\Attribute\PutRoute;
+use Modules\AnnoRoute\Attribute\RequestAttribute;
+
+/**
+ * 小程序供应商端（接收采购单 / 明细 / 确认接单）
+ */
+#[RequestAttribute('/mini', 'mini', authGuard: 'users')]
+class SupplierController extends BaseMiniController
+{
+    /** 收到的采购单：含本供应商 is_sent=1 明细的采购单（去重） */
+    #[GetRoute('/supplier/purchases', authorize: true)]
+    public function purchases(Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $supplier = $this->ensureSupplierBound($user);
+
+        $purchaseIds = PurchaseOrderItemModel::query()
+            ->where('supplier_id', $supplier->id)
+            ->where('is_sent', PurchaseOrderItemModel::SENT)
+            ->distinct()
+            ->pluck('purchase_id');
+
+        $data = PurchaseOrderModel::query()
+            ->whereIn('id', $purchaseIds)
+            ->orderBy('purchase_date', 'desc')
+            ->orderBy('id', 'desc')
+            ->paginate((int) $request->input('pageSize', 10))
+            ->toArray();
+
+        return $this->success($data);
+    }
+
+    /** 采购单明细：仅本供应商且已发送的明细行 */
+    #[GetRoute('/supplier/purchases/{id}', authorize: true, where: ['id' => '[0-9]+'])]
+    public function detail(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $supplier = $this->ensureSupplierBound($user);
+
+        $purchase = PurchaseOrderModel::find($id);
+        if ($purchase === null) {
+            throw new RepositoryException('采购单不存在');
+        }
+
+        $items = $purchase->items()
+            ->where('supplier_id', $supplier->id)
+            ->where('is_sent', PurchaseOrderItemModel::SENT)
+            ->get();
+        if ($items->isEmpty()) {
+            throw new RepositoryException('该采购单无贵司的采购明细');
+        }
+
+        return $this->success([
+            'id' => $purchase->id,
+            'purchase_no' => $purchase->purchase_no,
+            'purchase_date' => $purchase->purchase_date?->toDateString(),
+            'remark' => $purchase->remark,
+            'items' => $items->toArray(),
+        ]);
+    }
+
+    /** 确认接单：本供应商已发送明细批量记录 supplier_confirmed_at（幂等） */
+    #[PutRoute('/supplier/purchases/{id}/confirm', authorize: true, where: ['id' => '[0-9]+'])]
+    public function confirm(int $id, Request $request): JsonResponse
+    {
+        $user = $this->currentUser($request);
+        $supplier = $this->ensureSupplierBound($user);
+
+        $purchase = PurchaseOrderModel::find($id);
+        if ($purchase === null) {
+            throw new RepositoryException('采购单不存在');
+        }
+
+        $items = $purchase->items()
+            ->where('supplier_id', $supplier->id)
+            ->where('is_sent', PurchaseOrderItemModel::SENT)
+            ->get();
+        if ($items->isEmpty()) {
+            throw new RepositoryException('该采购单无贵司的采购明细');
+        }
+
+        $now = now();
+        $confirmed = 0;
+        foreach ($items as $item) {
+            if ($item->supplier_confirmed_at === null) {
+                $item->supplier_confirmed_at = $now;
+                $item->save();
+                $confirmed++;
+            }
+        }
+
+        return $this->success(['confirmed' => $confirmed], '已确认接单');
+    }
+}