664 lines
37 KiB
Markdown
664 lines
37 KiB
Markdown
# 杜康好客 v3.5.1 开发方案
|
||
|
||
> 9 个修改点 · 涉及 4 端（admin-web / h5-shop / mini-user / h5-partner）+ 1 后端
|
||
> **落地对照（已实现）**：[`杜康好客-v3.5.1-开发文档.md`](./杜康好客-v3.5.1-开发文档.md)
|
||
> 本文为开工方案与探索记录；与实现不一致时以落地对照为准。
|
||
> 协作：模块边界仍按 AGENTS.md；`store` 模块 OWNER 为 B+D，**当前由 jacy-dukang 全权**，可直接写 `store_*`/`redeem` 表
|
||
|
||
---
|
||
|
||
## 0. 总体一览
|
||
|
||
| 编号 | 模块 | 改动范围 | 估时 |
|
||
|------|------|----------|------|
|
||
| #1 | 大屏（订单轮播+脱敏） | 后端新增 + admin-web 新页 + OrdersPage 加按钮 | 0.5d |
|
||
| #2 | 门店端核销后即时刷新 | h5-shop RedeemSuccess/Mine/Withdraw 三处 | 0.3d |
|
||
| #3 | 用户端"发票抬头"列表 | 后端新表新接口 + mini-user 新 2 页 + 我的页入口 | 1d |
|
||
| #4 | 用户端订单"申请发票" | 后端新接口 + mini-user 订单列表/详情按钮 | 0.5d |
|
||
| #5 | 合伙人端门店编辑改"提交变更" | 后端新表新接口 + h5-partner StoreDetailPage | 1d |
|
||
| #6 | "套餐审核" 改 "审核通知" | admin-web Layout + StorePackageAuditsPage 改造 | 0.3d |
|
||
| #7 | 门店列表 提现/对比 按钮（信息变更） | admin-web StoresPage + 后端 admin list 返回字段 | 0.3d |
|
||
| #8 | 订单 30 分钟未支付自动取消 | 后端新增定时任务（复用 `payExpireAt` + 现有取消写法） | 0.5d |
|
||
| #9 | 城市合伙人/门店接口强校验 status+bindstatus，否则强制退登录 | 后端 `JwtAuthGuard` 注入状态校验 + `HttpExceptionFilter` 透传 + 两端前端跳登录 | 0.5d |
|
||
|
||
跨模块串联点：**#5 + #6 + #7** 共享同一个 `StoreInfoChangeRequest` 模型与 `AUDIT_NOTICE_CHANGED_EVENT`；**#9** 串联后端守卫 + 前端两端 `api.ts` 的退出逻辑。
|
||
|
||
> **#8 / #9 补充说明**
|
||
> - #8：下单时 `trade.service.ts` 已写 `payExpireAt = now + 30min`（line 206/1590/1935），支付/查询也已校验过期（line 2056/2145），但**缺少把 DB 状态翻成 `CANCELLED` 的定时任务**，本次补上。
|
||
> - #9：需求里的"门店 status + bindstatus"在模型上对应 **StoreAccount.status（门店账号启停，须 `ACTIVE`）+ Store.status（门店启停，须 `OPEN`）**；"合伙人 status + bindstatus"对应 **PartnerAccount.status（须 `ACTIVE`）+ PartnerAccount.bindingStatus（须 `ACTIVE`）**。两端不共用同一模型，校验需分别查。详见 §10。
|
||
|
||
---
|
||
|
||
## 1. 关键决策（已与用户对齐）
|
||
|
||
| 决策点 | 选择 |
|
||
|--------|------|
|
||
| 审核中心合并策略 | 合并套餐审核 + 信息变更 → 统一进「审核通知」 |
|
||
| 大屏实时性 | 3 秒 polling（无 SSE/WS） |
|
||
| 审核通过生效方式 | 直接覆盖 `store` 表 + 审核中隐藏（前端展示 liveSnapshot） |
|
||
| 申请发票范围 | 仅 `COMPLETED` 订单 |
|
||
|
||
---
|
||
|
||
## 2. 数据模型新增（共 2 张表）
|
||
|
||
### 2.1 `UserInvoiceTitle`（发票抬头）
|
||
|
||
```prisma
|
||
model UserInvoiceTitle {
|
||
id BigInt @id @default(autoincrement()) @db.UnsignedBigInt
|
||
userId BigInt @map("user_id") @db.UnsignedBigInt
|
||
titleType InvoiceTitleType @map("title_type") // PERSONAL | ENTERPRISE
|
||
titleName String @map("title_name") @db.VarChar(128)
|
||
taxNo String? @map("tax_no") @db.VarChar(32)
|
||
email String? @db.VarChar(128)
|
||
phone String? @db.VarChar(20)
|
||
addressPhone String? @map("address_phone") @db.VarChar(256)
|
||
bankAccount String? @map("bank_account") @db.VarChar(256)
|
||
isDefault Boolean @default(false) @map("is_default")
|
||
createdAt DateTime @default(now()) @map("created_at") @db.DateTime(3)
|
||
updatedAt DateTime @updatedAt @map("updated_at") @db.DateTime(3)
|
||
|
||
user User @relation(fields: [userId], references: [id], onDelete: Cascade)
|
||
invoices UserInvoice[] // 反向关联，已有
|
||
|
||
@@index([userId, isDefault])
|
||
@@map("user_invoice_title")
|
||
}
|
||
```
|
||
|
||
> 同时在 `model User { ... }` 增加 `invoiceTitles UserInvoiceTitle[]`
|
||
|
||
### 2.2 `StoreInfoChangeRequest`（门店信息变更请求）
|
||
|
||
```prisma
|
||
enum StoreInfoChangeStatus { PENDING APPROVED REJECTED }
|
||
enum StoreInfoChangeSubmitterType { PARTNER SHOP HQ_DIRECT_ADMIN }
|
||
|
||
model StoreInfoChangeRequest {
|
||
id BigInt @id @default(autoincrement()) @db.UnsignedBigInt
|
||
storeId BigInt @map("store_id") @db.UnsignedBigInt
|
||
status StoreInfoChangeStatus @default(PENDING)
|
||
/// liveSnapshot = 变更前 Store 全量快照；proposedSnapshot = 提单时希望变更的字段集合
|
||
liveSnapshot Json @map("live_snapshot")
|
||
proposedSnapshot Json @map("proposed_snapshot")
|
||
/// 可变字段白名单：name/contactPhone/address/intro/benefitUsageRule/coverUrl/envPhotoUrls/openTime/closeTime/openTime2/closeTime2/avgPrice
|
||
changedFields Json @map("changed_fields")
|
||
submitterType StoreInfoChangeSubmitterType @map("submitter_type")
|
||
submitterId BigInt @map("submitter_id") @db.UnsignedBigInt
|
||
rejectReason String? @map("reject_reason") @db.VarChar(512)
|
||
reviewedAt DateTime? @map("reviewed_at") @db.DateTime(3)
|
||
reviewerId BigInt? @map("reviewer_id") @db.UnsignedBigInt
|
||
createdAt DateTime @default(now()) @map("created_at") @db.DateTime(3)
|
||
|
||
store Store @relation(fields: [storeId], references: [id], onDelete: Cascade)
|
||
|
||
@@index([storeId, status])
|
||
@@index([status, createdAt])
|
||
@@map("store_info_change_request")
|
||
}
|
||
```
|
||
|
||
> 同时在 `model Store { ... }` 增加 `infoChangeRequests StoreInfoChangeRequest[]`
|
||
|
||
**Prisma 迁移策略**：
|
||
- 修改 `server/dukang-api/prisma/schema.prisma`
|
||
- 执行 `pnpm db:generate`、`cd server/dukang-api && npx prisma db push`
|
||
- 重启 `pnpm dev:api`
|
||
|
||
---
|
||
|
||
## 3. 后端新增/修改清单
|
||
|
||
### 3.1 新建 `modules/store/store-info-change.{controller,service}.ts`
|
||
|
||
| 路由 | 方法 | 角色 | 说明 |
|
||
|------|------|------|------|
|
||
| `POST /partner/stores/:storeId/info-change-request` | body: `{ fields: Partial<StoreInput> }` | PARTNER | 提交基本资料变更 |
|
||
| `GET /partner/stores/:storeId/info-change-requests` | — | PARTNER | 看本门店历史变更 |
|
||
| `POST /shop/store/info-change-request` | 同上 | SHOP | 门店端提交变更 |
|
||
| `GET /admin/store-info-change-requests?status=&page=` | — | HQ | 列表 |
|
||
| `GET /admin/store-info-change-requests/summary` | — | HQ | 返回 `pendingCount`（与套餐审核汇总汇总求和） |
|
||
| `GET /admin/store-info-change-requests/:id` | — | HQ | 详情（live + proposed diff） |
|
||
| `PUT /admin/store-info-change-requests/:id/audit` | `{ action, rejectReason? }` | HQ | 通过/驳回 |
|
||
|
||
服务函数（`StoreInfoChangeService`）：
|
||
```ts
|
||
submit({ storeId, actorId, actorType, fields }) {
|
||
// 1) 校验 store 归属
|
||
// 2) 拉 live = prisma.store.findUnique，diff 出 changedFields
|
||
// 3) prisma.storeInfoChangeRequest.create（live/proposed JSON）
|
||
// 4) 同 store 已有 PENDING 时直接替换（最新优先）
|
||
// 5) 触发 AUDIT_NOTICE_CHANGED_EVENT
|
||
}
|
||
|
||
audit({ id, action, reason, reviewerId }) {
|
||
if (action === APPROVED) {
|
||
// 把 proposedSnapshot 字段写到 store（白名单）
|
||
// store 通过 storeService.updateByHq()（如无此方法，需新建；不能直接 prisma 改 store）
|
||
// store 信息变更后，partner 端 Strip Pending
|
||
}
|
||
// 写状态/驳回原因
|
||
// 触发 AUDIT_NOTICE_CHANGED_EVENT
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 新建 `modules/trade/invoice-title.{controller,service}.ts`
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `GET /trade/invoice-titles` | — | 当前用户的抬头列表 |
|
||
| `POST /trade/invoice-titles` | body | 新建 |
|
||
| `PUT /trade/invoice-titles/:id` | body | 编辑；可同时 `isDefault=true` 触发其他置 false |
|
||
| `DELETE /trade/invoice-titles/:id` | — | 删除（已被 UserInvoice 引用的禁止删除，返回 409） |
|
||
| `GET /trade/orders/:orderId/invoice-titles` | — | 订单所有可用的抬头（用户的 + 默认） |
|
||
|
||
> 利用已有 `UserInvoice` 表；`UserInvoice.titleId` 可选填空（也可保留 `titleName/taxNo` 冗余快照——**建议保留**：每张发票保存当时的抬头快照，避免抬头被删后历史记录走样）
|
||
|
||
---
|
||
|
||
### 3.3 修改 `modules/trade/trade.controller.ts` — 新增（订单可用发票接口）
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `GET /trade/orders/:orderId/invoice-status` | — | 返回当前订单是否已开票（`EXISTS \| NONE`） |
|
||
| `GET /trade/invoices` | — | 我的发票申请列表 |
|
||
|
||
服务函数基于 `UserInvoice` 现有查询扩展。
|
||
|
||
---
|
||
|
||
### 3.4 修改 `modules/trade/admin-big-screen.controller.ts`（**新建**）
|
||
|
||
| 路由 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `GET /admin/orders/big-screen?limit=20` | — | 返回最近 N 条订单：订单号、金额、商品名/规格/数量、下单人 phone（**强制脱敏**）、下单时间 |
|
||
|
||
关键实现：
|
||
```ts
|
||
const orders = await prisma.order.findMany({
|
||
orderBy: { createdAt: 'desc' },
|
||
take: Math.min(Number(limit) || 20, 50),
|
||
include: { items: true, user: { select: { phone: true } } }
|
||
});
|
||
return orders.map(o => ({
|
||
id: o.id, orderNo: o.orderNo, payAmount: o.payAmount,
|
||
createdAt: o.createdAt,
|
||
userPhoneMasked: o.user?.phone ? maskPhone(o.user.phone) : null,
|
||
items: o.items.map(it => `${it.productName} × ${it.quantity}`).join('，'),
|
||
}));
|
||
```
|
||
|
||
> 复用于 `packages/domain` 中已存在的 `maskPhone` 函数。新建 admin-big-screen.controller.ts 即可，不动 trade.controller.ts。
|
||
|
||
---
|
||
|
||
### 3.5 修改 `modules/store/store.controller.ts` 或 trade ops 模块
|
||
|
||
- 现有 `/partner/stores/:storeId/basic` (PUT) 是**直接生效**的，需保留为 backward-compat；**新增** `/partner/stores/:storeId/info-change-request`（见 3.1）
|
||
- 现有门店端 `/shop/store` (GET) 不变；本次不修改
|
||
|
||
---
|
||
|
||
### 3.6 shared-types 包
|
||
|
||
`packages/shared-types/src/invoice-title.ts` 新增：
|
||
```ts
|
||
export interface UserInvoiceTitleDto {
|
||
id: string; titleType: InvoiceTitleType; titleName: string;
|
||
taxNo?: string; email?: string; phone?: string;
|
||
addressPhone?: string; bankAccount?: string; isDefault: boolean;
|
||
}
|
||
export const INVOICE_CHANGEABLE_FIELDS = [
|
||
'titleName', 'taxNo', 'email', 'phone', 'addressPhone', 'bankAccount', 'isDefault'
|
||
] as const;
|
||
```
|
||
|
||
`packages/shared-types/src/store-info-change.ts` 新增：
|
||
```ts
|
||
export type StoreInfoChangeStatus = 'PENDING' | 'APPROVED' | 'REJECTED';
|
||
export type StoreInfoChangeSubmitterType = 'PARTNER' | 'SHOP' | 'HQ_DIRECT_ADMIN';
|
||
export interface StoreInfoChangeRequestDto { ... }
|
||
export interface StoreInfoChangeSummaryDto { pendingCount: number; }
|
||
export const STORE_INFO_CHANGEABLE_FIELDS = [
|
||
'name', 'contactPhone', 'address', 'intro', 'benefitUsageRule',
|
||
'coverUrl', 'envPhotoUrls', 'openTime', 'closeTime',
|
||
'openTime2', 'closeTime2', 'avgPrice'
|
||
] as const;
|
||
```
|
||
|
||
---
|
||
|
||
### 3.7 shared-events 全局事件
|
||
|
||
新增 `packages/shared-events/src/admin-events.ts` 或在 admin-web 的 `lib/admin-events.ts` 增加：
|
||
```ts
|
||
export const AUDIT_NOTICE_CHANGED_EVENT = 'dukang:audit-notice-changed';
|
||
export const STORE_REDEEM_SUCCESS_EVENT = 'dukang:shop-redeem-success';
|
||
```
|
||
|
||
---
|
||
|
||
### 3.8 新增 `jobs/order-expiry.scheduler.ts`（#8 自动取消过期订单）
|
||
|
||
> 关键事实：下单时 `trade.service.ts` 已写 `payExpireAt = now + 30min`，支付/查询也已校验过期，但**没有定时任务**真正把 `status` 翻成 `CANCELLED`。后端 `src/jobs/` 已用 `@Cron`（`@nestjs/schedule`）范式（`settlement.scheduler.ts`），`ScheduleModule` 已在 `jobs.module.ts` 注册。
|
||
|
||
**新建 `server/dukang-api/src/jobs/order-expiry.scheduler.ts`**：
|
||
```ts
|
||
@Injectable()
|
||
export class OrderExpiryScheduler {
|
||
private readonly logger = new Logger(OrderExpiryScheduler.name);
|
||
constructor(private readonly trade: TradeService) {}
|
||
// 每分钟扫描一次；订单量不大，1 分钟粒度足够"30 分钟"语义
|
||
@Cron('*/1 * * * *', { timeZone: 'Asia/Shanghai' })
|
||
async handleExpiredPendingOrders() {
|
||
try {
|
||
const n = await this.trade.cancelExpiredPendingOrders(200);
|
||
if (n > 0) this.logger.log(`Auto-cancelled ${n} expired pending orders`);
|
||
} catch (e) {
|
||
this.logger.error('Order expiry job failed', e instanceof Error ? e.stack : e);
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**`TradeService.cancelExpiredPendingOrders(limit = 200)`（新增方法）**：
|
||
```ts
|
||
async cancelExpiredPendingOrders(limit = 200): Promise<number> {
|
||
const expired = await this.prisma.order.findMany({
|
||
where: {
|
||
status: 'PENDING_PAY',
|
||
payStatus: 'UNPAID',
|
||
payExpireAt: { lt: new Date() },
|
||
isTest: false, // 跳过测试订单，避免污染数据
|
||
},
|
||
take: limit,
|
||
select: { id: true },
|
||
});
|
||
for (const o of expired) {
|
||
await this.prisma.$transaction(async (tx) => {
|
||
await tx.order.update({
|
||
where: { id: o.id },
|
||
data: { status: 'CANCELLED', cancelledAt: new Date() },
|
||
});
|
||
await tx.commonEvent.create({
|
||
data: buildOrderStatusEvent({ // 复用现有导入（见 line 1810）
|
||
orderId: o.id, fromStatus: 'PENDING_PAY', toStatus: 'CANCELLED',
|
||
operator: 'SYSTEM_AUTO_EXPIRE', remark: '30 分钟未支付自动取消',
|
||
}),
|
||
});
|
||
});
|
||
}
|
||
return expired.length;
|
||
}
|
||
```
|
||
|
||
**注册**：`server/dukang-api/src/jobs/jobs.module.ts` 的 `providers` 增加 `OrderExpiryScheduler`（`TradeModule` 已 import，无需改 imports）。
|
||
|
||
> **待确认**：取消时是否需回滚已占用的 `benefitCoupon`？现有 `cancelPartnerProxyOrder`（line 1791）仅翻状态、未回滚权益券。若业务要求自动取消也释放权益，此处需补 `benefitCoupon.update({ status: 'ACTIVE' })`。
|
||
|
||
---
|
||
|
||
### 3.9 修改 `JwtAuthGuard` + `HttpExceptionFilter`（#9 强校验，详见 §10）
|
||
|
||
> 完整探查见 §10。要点：
|
||
|
||
- **`server/dukang-api/src/common/guards/jwt-auth.guard.ts`**：
|
||
- `canActivate` 改为 `async`；注入 `PrismaService`。
|
||
- 在 `req.user` 组装完成后，按 `actorType` 分支（**仅 STORE / PARTNER，USER 跳过**）：
|
||
- `STORE`：查 `storeAccount(actorId)` → `status` 须 `ACTIVE`；若 `req.user.storeId` 存在，查 `Store` → `status` 须 `OPEN`。
|
||
- `PARTNER`：查 `partnerAccount(actorId)` → `status === 'ACTIVE'` 且 `bindingStatus === 'ACTIVE'`。
|
||
- 不通过 → `throw new ForbiddenException({ reason: 'ACCOUNT_DISABLED', message: '账号已停用或解绑，请重新登录' })`。
|
||
- 覆盖率 100%：`/shop/*`、`/partner/*` 全部经过 `JwtAuthGuard`（含仅用 `JwtAuthGuard` 的合伙人路由）；登录/refresh 走 `OptionalJwtAuthGuard`，不受影响。
|
||
- **`server/dukang-api/src/common/filters/http-exception.filter.ts`**（line 58-60 的 `response.status(status).json({...})`）：
|
||
- 增加透传 `reason` 字段：`reason: (res && typeof res === 'object' && (res as any).reason) ?? null`，使前端能精确识别"账号停用"。
|
||
|
||
---
|
||
|
||
## 4. 前端新增/修改清单
|
||
|
||
### 4.1 admin-web（管理后台）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 1 | `src/pages/OrdersPage.tsx` | 头部加 `<Button>` "大屏" → `window.open('/orders/big-screen?token=xxx','_blank')` |
|
||
| 2 | `src/pages/BigScreenPage.tsx`（**新建**） | 暗色科技风，"杜康好客 · 发布仪式现场" + LIVE 标识 + 大时钟 + 订单表格轮播；3s polling |
|
||
| 3 | `src/App.tsx` | 加路由 `<Route path="/orders/big-screen" element={<BigScreenPage />} />` |
|
||
| 4 | `src/layouts/AdminLayout.tsx` | 菜单项 label `'套餐审核'` → `'审核通知'`；`attachPackageAuditBadge` 改名为 `attachAuditNoticeBadge`，订阅 `AUDIT_NOTICE_CHANGED_EVENT` + 调 `summary` 端点（含合并计数） |
|
||
| 5 | `src/pages/StorePackageAuditsPage.tsx` | 标题 `套餐变更审核` → `审核通知`；加 `<Tabs>`：套餐变更 / 门店信息变更；下方按 `kind` 调不同接口；详情抽屉兼容两类 |
|
||
| 6 | `src/pages/StoresPage.tsx` | 列表中加 `pendingInfoChangeId` 字段；操作列在已有 `pendingPackageAuditId` 旁补 `审核信息 / 对比`；提现按钮（指向 `/finance/store-bills?storeId=`）已存在，本次仅调整文案 |
|
||
|
||
> BigScreenPage 不依赖 AdminLayout（避免侧边栏干扰），可在路由外层做独立壳层。
|
||
|
||
---
|
||
|
||
### 4.2 h5-shop（门店端）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 1 | `src/pages/RedeemSuccessPage.tsx` | 提交成功 onMounted 派发 `window.dispatchEvent(new CustomEvent(STORE_REDEEM_SUCCESS_EVENT, { detail: { storeId, amount }}))`；在 navigate(-1) 之前 |
|
||
| 2 | `src/pages/MinePage.tsx` | 监听 `STORE_REDEEM_SUCCESS_EVENT` → 重跑 `loadMine()`（已存在） |
|
||
| 3 | `src/pages/WithdrawPage.tsx` | 同上监听 → 重跑 `load()` |
|
||
| 4 | `src/lib/useRedeemSuccessBus.ts`（**新建**） | 简单 hook：`useRedeemSuccessListener(handler)` 复用 |
|
||
|
||
---
|
||
|
||
### 4.3 mini-user（用户小程序）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 1 | `src/pages/mine/index.tsx` | SERVICES 数组加一项 `{ icon: iconInvoice, label: '发票管理', url: '/pages/invoice-titles/index' }` |
|
||
| 2 | `src/pages/invoice-titles/index.tsx`（**新建**） | 列表（默认抬头星标 / 编辑 / 删除 / 设为默认）+ 进入"申请发票"快捷入口 |
|
||
| 3 | `src/pages/invoice-title-edit/index.tsx`（**新建**） | 编辑/新建抬头表单 |
|
||
| 4 | `src/pages/orders/index.tsx` | 仅 COMPLETED 订单下方加 `<View className="order-invoice-btn">申请发票</View>` → 跳发票申请页 |
|
||
| 5 | `src/pages/order-detail/index.tsx` | 订单状态 COMPLETED 时，详情页 actionbar 增加"申请发票"按钮 |
|
||
| 6 | `src/pages/invoice-apply/index.tsx`（**新建**） | 复用 SubPageHeader 组件；展示该订单明细 + 已开票则提示已存在 + 抬头选择器 + 提交 |
|
||
| 7 | `src/app.config.ts` | pages 数组增加 3 个新页（`invoice-titles/index`、`invoice-title-edit/index`、`invoice-apply/index`） |
|
||
| 8 | `src/lib/api.ts` | 增加 `requestInvoiceTitles()`、`submitInvoiceApplication()` 等 helper |
|
||
|
||
---
|
||
|
||
### 4.4 h5-partner（合伙人端）
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 1 | `src/pages/StoreDetailPage.tsx` | 底部保存按钮 `保存修改` → `提交变更`；点击后调 `PUT /partner/stores/:id/info-change-request` 而不是 `/basic` |
|
||
| 2 | 同上 | 顶部加一个 `auditBanner`：当 `store.infoChangePending === true` 时提示"有变更待总部审核"（调 list 接口得到 PENDING） |
|
||
| 3 | `src/lib/api.ts` | 加 `submitStoreInfoChangeRequest`、`listStoreInfoChangeRequests` |
|
||
|
||
> **兼容老路径**：保留 `/partner/stores/:id/basic`（PUT）以兼容历史脚本；新按钮走新接口。
|
||
|
||
---
|
||
|
||
### 4.5 h5-shop / h5-partner 强制退出登录（#9，详 §10）
|
||
|
||
> 后端返回 `{ code: 403, reason: 'ACCOUNT_DISABLED', message }` 后，前端需 `clearAuth()` + 跳 `/login`。合伙人端现仅 401 跳登录、门店端缺此逻辑，两端都要补。
|
||
|
||
| # | 文件 | 改动 |
|
||
|---|------|------|
|
||
| 1 | `apps/h5-shop/src/lib/api.ts` | `rawRequest`（~191-227）抛错时附加 `err.reason = json.reason ?? null`；`requestWithAuthRetry` 的不可恢复分支（~262 前）与 `ensureSession` catch（~305）增加 `if (err.reason === 'ACCOUNT_DISABLED') { clearAuth(); window.location.href = '/login'; }` |
|
||
| 2 | `apps/h5-partner/src/lib/api.ts` | `rawRequest` 同样附加 `err.reason`；在现有 401 重定向分支旁增加 `reason === 'ACCOUNT_DISABLED'` 的 `clearAuth() + window.location.href = toAppPath('/login')`（复用既有登录路由） |
|
||
|
||
> 注意：`ACCOUNT_DISABLED` 用专属 `reason` 字段而非复用 403，避免与未来其它 403（权限不足）混淆；`code` 仍为 403 不破坏现有 `err.status` 判断。
|
||
|
||
---
|
||
|
||
## 5. 大屏页面设计要点（#1）
|
||
|
||
```tsx
|
||
// BigScreenPage.tsx 骨架（admin-web 不依赖 AntD）
|
||
export default function BigScreenPage() {
|
||
const [items, setItems] = useState<BigScreenOrder[]>([]);
|
||
useEffect(() => {
|
||
const fetchData = () => request<{ items: BigScreenOrder[] }>(
|
||
'/admin/orders/big-screen?limit=20'
|
||
).then(d => setItems(d.items));
|
||
fetchData();
|
||
const id = setInterval(fetchData, 3000);
|
||
return () => clearInterval(id);
|
||
}, []);
|
||
return (
|
||
<div className="big-screen-page"> {/* 全屏暗色 */}
|
||
<header>
|
||
<span className="title">杜康好客</span>
|
||
<span className="subtitle">发布仪式现场</span>
|
||
<span className="live">● LIVE</span>
|
||
</header>
|
||
<Clock /> {/* setInterval(每秒) */}
|
||
<table>
|
||
<thead>
|
||
<tr><th>下单金额</th><th>下单商品</th><th>下单时间</th><th>下单人</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
{items.map(o => (
|
||
<tr key={o.id}>
|
||
<td>¥{o.payAmount.toLocaleString()}</td>
|
||
<td>{o.items}</td>
|
||
<td>{formatHM(o.createdAt)}</td>
|
||
<td>{o.userPhoneMasked}</td>
|
||
</tr>
|
||
))}
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
CSS 暗色 + 蓝色辉光 + 全屏（`h1 字号 96px、background #001529`），仿参考图。
|
||
|
||
---
|
||
|
||
## 6. 关键交互流程图
|
||
|
||
### 6.1 #1 大屏实时轮播
|
||
```
|
||
[admin BigScreenPage mounted]
|
||
↓
|
||
request GET /admin/orders/big-screen?limit=20
|
||
↓
|
||
[Backend] findMany Order desc createdAt, take 20, mask phone
|
||
↓
|
||
setInterval(3000) → 重复
|
||
```
|
||
|
||
### 6.2 #2 门店端核销即时刷新
|
||
```
|
||
[RedeemSuccessPage] onMount → window.dispatchEvent(STORE_REDEEM_SUCCESS_EVENT)
|
||
↓
|
||
[MinePage useEffect] 收到 → setLoading → request /shop/store
|
||
[WithdrawPage useEffect] 收到 → request /shop/withdraw/summary
|
||
```
|
||
|
||
### 6.3 #5/#6/#7 审核通知闭环
|
||
```
|
||
[Partner StoreDetailPage] 点击"提交变更"
|
||
↓
|
||
PUT /partner/stores/:id/info-change-request {fields}
|
||
↓
|
||
[Backend] 写入 StoreInfoChangeRequest + 触发 AUDIT_NOTICE_CHANGED_EVENT
|
||
↓
|
||
[StoreDetailPage] 显示"有变更待总部审核"banner
|
||
↓
|
||
[admin StorePackageAuditsPage] 进入 → 切到「门店信息变更」Tab → 列表
|
||
↓
|
||
[admin 点"通过"] → PUT .../audit {action:APPROVE}
|
||
↓
|
||
[Backend] proposedSnapshot 写入 store → 触发 AUDIT_NOTICE_CHANGED_EVENT
|
||
↓
|
||
[StoreDetailPage] banner 消失
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 验证 DoD
|
||
|
||
- [ ] `pnpm db:generate && db:validate && npx prisma db push` 无报错
|
||
- [ ] 现有 admin/stores 接口能取到 `pendingInfoChangeId` 字段；旧调用方不报错
|
||
- [ ] 订单「申请发票」按钮仅在 `COMPLETED` 时出现；提交后调用 `/trade/orders/:id/invoices`
|
||
- [ ] 门店端在 A 设备核销 → B 设备 MinePage（如多 Tab）≤3s 看到变化（A 设备本身立即）
|
||
- [ ] 大屏 3s 内出现新单；手机号中间 4 位为 `****`
|
||
- [ ] 合伙人提交门店变更后，门店 C 端/合伙人端展示 liveSnapshot（不立即生效），admin 端能审核通过/驳回
|
||
- [ ] 审核通知 badge = 套餐变更 PENDING + 信息变更 PENDING
|
||
- [ ] #8：构造 `payExpireAt` 已过期的待支付订单，≤1 分钟内状态自动变 `CANCELLED` 且 `cancelledAt` 写入、状态日志 `SYSTEM_AUTO_EXPIRE` 存在
|
||
- [ ] #9：将某门店 `StoreAccount.status` 置非 `ACTIVE`（或 `Store.status` 非 `OPEN`），其门店端任意接口返回 `reason: ACCOUNT_DISABLED`，前端立即 `clearAuth()` 并跳 `/login`
|
||
- [ ] #9：将某合伙人 `bindingStatus` 置非 `ACTIVE`，合伙人端任意接口触发强退登录；`mini-user`（USER actor）不受影响
|
||
- [ ] `pnpm lint && pnpm test` 无新增错误
|
||
|
||
---
|
||
|
||
## 8. 任务拆分（建议 DLV 命名）
|
||
|
||
```
|
||
DLV-W1-M1 #1 大屏（后端 + admin-web 新页）
|
||
DLV-W1-M2 #2 门店端核销事件总线
|
||
DLV-W1-M3 #6 审核通知菜单改 + Tabs 改造（先做，让 #5/#7 共享 UI）
|
||
DLV-W1-M4 #5 合伙人端门店"提交变更"（StoreInfoChangeRequest 全套）
|
||
DLV-W1-M5 #7 门店列表 提现/对比 按钮（信息变更）
|
||
DLV-W1-M6 #3 发票抬头 mini-user 列表 + 编辑
|
||
DLV-W1-M7 #4 订单申请发票（依赖 M6）
|
||
DLV-W1-M8 #8 订单 30 分钟未支付自动取消（后端定时任务，独立）
|
||
DLV-W1-M9 #9 城市合伙人/门店接口强校验 + 前端强制退登录
|
||
```
|
||
|
||
依赖关系：M1 独立；M2 独立；M3 无依赖；M4 / M5 依赖 M3；M6 无依赖；M7 依赖 M6；M8 独立；M9 独立（后端守卫 + 前端两端，互不阻塞）。
|
||
|
||
---
|
||
|
||
## 9. 待确认的设计细节（如需开工前敲定）
|
||
|
||
1. 发票抬头列表页是否需要"设为默认"按钮？
|
||
2. 门店信息变更驳回后，原表单是否需要提示驳回原因？
|
||
3. 大屏是否需要支持"暂停轮播"按钮？
|
||
4. 用户端 `My → 发票管理` 是否需要再放"申请记录"二级入口？
|
||
5. **#8 权益回滚**：自动取消订单时是否需要把已占用的 `benefitCoupon` 置回 `ACTIVE`？（现有手动取消 `cancelPartnerProxyOrder` 未回滚，建议保持一致或明确要回滚）
|
||
6. **#8 扫描粒度**：每分钟一次（`*/1 * * * *`）是否可接受？还是希望 2~5 分钟一次？
|
||
7. **#9 校验范围**：需求只提"城市合伙人 + 门店"。是否也要覆盖 `h5-shop` 的**城市合伙人代运营账号**（`proxyPartnerAccountId` 场景）？目前按"仅 STORE + PARTNER actor"实现。
|
||
8. **#9 提示文案**：强退登录时前端是否需要 toast 提示"账号已停用/解绑，请重新登录"再跳登录页，还是静默跳回？
|
||
9. **#9 测试订单**：`isTest` 门店/合伙人账号是否要跳过强校验（避免测试环境自锁）？
|
||
|
||
---
|
||
|
||
## 10. 状态校验能力探索报告（城市合伙人 / 门店 接口强制退出到登录页）
|
||
|
||
> 本需求：所有 `/shop/*` 与 `/partner/*` 接口需校验 status / bindstatus 是否为开启，否则强制前端退到登录页。以下是按代码实际探查的结果与落地建议。
|
||
|
||
### 10.1 模型字段（server/dukang-api/prisma/schema.prisma）
|
||
|
||
- **Store**（line 1245）：只有 `status StoreStatus @default(PAUSED)`（line 1268），**没有 bindstatus 字段**。
|
||
- `enum StoreStatus`（line 282）：`OPEN / PAUSED / CLOSED`。"开启" = `OPEN`。
|
||
- **PartnerAccount**（line 1030）：`status AccountStatus @default(ACTIVE)`（line 1042）+ `bindingStatus CityPartnerStatus? @default(ACTIVE) @map("binding_status")`（line 1049）。
|
||
- `enum AccountStatus`（line 244）：`ACTIVE / DISABLED`。
|
||
- `enum CityPartnerStatus`（line 203）：`ACTIVE / PAUSED`。"已绑定/开启" = `ACTIVE`。
|
||
- **StoreAccount**（门店登录账号，line 1365）：`status AccountStatus @default(ACTIVE)`（line 1378）——这是门店端真正的"停用开关"，登录时已被校验（`auth.service.ts:1050` `if (account.status !== 'ACTIVE') throw new BadRequestException('门店账号已停用')`）。
|
||
- 结论：需求中的"门店 status + bindstatus"在模型上对应 **StoreAccount.status（账号启停）+ Store.status（门店启停 OPEN）**；"合伙人 status + bindstatus"对应 **PartnerAccount.status + PartnerAccount.bindingStatus**。两端不共用同一模型。
|
||
|
||
### 10.2 后端鉴权守卫（server/dukang-api/src/common/guards/）
|
||
|
||
- 全局错误格式 `http-exception.filter.ts:58-62`：`{ code: status, message, data: null }`；成功 `response.interceptor.ts:13-17`：`{ code:0, message:'ok', data }`。注册于 `main.ts:87-88`。
|
||
- **JwtAuthGuard**（jwt-auth.guard.ts:21-56）：校验 Bearer + `x-client-app` + actorType，写入 `req.user: AuthUser{actorType, actorId, clientApp, storeId?}`。**无 DB 查询、无 status 校验**。
|
||
- 路由守卫分布：
|
||
- `/shop/*` 统一 `@UseGuards(JwtAuthGuard, ShopStoreGuard)`（如 store.controller.ts:186-187、settlement.controller.ts:48-49、redeem.controller.ts:54-55）。
|
||
- `/partner/*` 部分 `@UseGuards(JwtAuthGuard, PartnerPrimaryGuard/PartnerPermissionGuard)`，也有**仅** `@UseGuards(JwtAuthGuard)` 的（settlement.controller.ts:573 `partner/me`、store.controller.ts:75/86、store-package.controller.ts:8）。
|
||
- 现有守卫**均未校验 status/bindstatus**（运行时）：
|
||
- `ShopStoreGuard`（shop-store.guard.ts:1-15）：仅校验 `user.storeId` 存在。
|
||
- `PartnerPrimaryGuard`（partner-primary.guard.ts:11-32）：查 `partnerAccount` + 校验 `isPrimary==1`。
|
||
- `PartnerPermissionGuard`（partner-permission.guard.ts:14-45）：查 `partnerAccount` + 校验权限。
|
||
- `ShopPrimaryGuard`（shop-primary.guard.ts）：查 `storeAccount.isPrimary`。
|
||
- **关键缺口**：登录后账号被停用/解绑，运行时接口不拦截（仅登录时校验过 StoreAccount.status）。
|
||
|
||
### 10.3 前端登录态与退出
|
||
|
||
- **h5-shop/src/lib/api.ts**：token 存 localStorage（ACCESS_TOKEN/REFRESH_TOKEN），profile 存 STORE_PROFILE；`clearAuth`（136-145）清 token。
|
||
- `rawRequest`（191-227）：`json.code !== 0` 抛 Error，`err.status = (>=500?res.status:json.code)`（401→401，403→403）。
|
||
- `requestWithAuthRetry`（249-270）：仅 `err.status===401` 且非豁免路径时尝试 refresh；失败则 `clearAuth()` 并 throw。**shop 端 request 没有跳登录页逻辑**。
|
||
- 登录路由 `/login`（AuthGate.tsx:5、多处 `navigate('/login')`）。
|
||
- **h5-partner/src/lib/api.ts**：结构同构；`request`（217-242）在 `err.status===401` 且本地有 token 时 `clearAuth()` + `showPartnerToast` + `window.location.href = toAppPath('/login')`（不在 /login 时）。**合伙人端已具备"401 强制跳登录"**。
|
||
- 登录路由 `toAppPath('/login')`。
|
||
- 结论：partner 端天然可接 401 强退；shop 端缺这一步。
|
||
|
||
### 10.4 请求封装
|
||
|
||
- 两端共用 fetch 封装（rawRequest / requestWithAuthRetry / request），无 axios。业务 code 与 HTTP 码复用同一 `code` 字段（filter 把 HTTP status 当 code）。
|
||
- `requestWithAuthRetry` 只对 401 重试，**对 403/自定义 code 直接 throw → 不会触发 refresh 死循环**（这是设计专属 code 的基础）。
|
||
|
||
### 10.5 落地建议
|
||
|
||
**后端**：在 `JwtAuthGuard.canActivate` 内（或新建 `AccountActiveGuard` 全局）按 actorType 分支做 DB 校验：
|
||
- `STORE`：查 `StoreAccount(actorId)` → `status` 必须 `ACTIVE`；若 `user.storeId` 存在，查 `Store` → `status` 必须 `OPEN`。
|
||
- `PARTNER`：查 `PartnerAccount(actorId)` → `status===ACTIVE` 且 `bindingStatus===ACTIVE`。
|
||
- 抛 **`ForbiddenException` 携带专属业务 code（如 `ACCOUNT_DISABLED = 499`）** 而非 401，避免误触前端 refresh 重试。需扩展 `HttpExceptionFilter` 透传该 bizCode。
|
||
- 选 JwtAuthGuard 内部做可保证 100% 覆盖（所有 /shop、/partner 都过它，含仅用 JwtAuthGuard 的 partner/me）；`USER` actorType 跳过，不影响 C 端/小程序。
|
||
|
||
**前端**：当 `json.code === ACCOUNT_DISABLED` 时，h5-partner 与 h5-shop 均 `clearAuth()` + 跳 `/login`（partner 已在 401 分支，shop 需补 redirect）。若不想改 filter，可复用 403：但 partner 现只对 401 跳、对 403 不跳，故**专属 code 最稳**。
|
||
|
||
### 10.6 风险点
|
||
|
||
- **性能**：每个 /shop、/partner 请求多 1 次 DB 查询；用 `select` 仅取 status 字段即可，流量低可接受。
|
||
- **登录流程不受影响**：`/shop/auth/login`、`/shop/auth/token/refresh` 等用 OptionalJwtAuthGuard 或无 guard，不会被拦；但 `/shop/auth/me`、`select-store` 用 JwtAuthGuard，停用账号访问会被拦→前端跳登录（符合预期）。
|
||
- **范围**：HQ/admin 走 HqAuthGuard、mini-user 为 USER actor，均不受影响（按需求只做 shop + partner）。
|
||
- **门店校验建议同时覆盖 StoreAccount.status 与 Store.status**，否则只停门店不停账号仍可操作。
|
||
|
||
|
||
---
|
||
|
||
## 11. 订单 30 分钟未支付自动取消 — 代码探索报告
|
||
|
||
> 本报告为 v3.5.1 功能「订单 30 分钟未支付自动改为取消」的实现前探索，供开发方案设计参考。
|
||
|
||
## 1. 订单状态枚举
|
||
- Prisma 定义 `server/dukang-api/prisma/schema.prisma:321-331`：
|
||
```prisma
|
||
enum OrderStatus {
|
||
PENDING_PAY // 待付款
|
||
PENDING_SHIP
|
||
OUT_WAREHOUSE
|
||
SHIPPING
|
||
PENDING_RECEIVE
|
||
COMPLETED
|
||
CANCELLED // 已取消
|
||
REFUNDING
|
||
REFUNDED
|
||
}
|
||
```
|
||
- TS 同步定义 `packages/shared-types/src/enums.ts:71-81`，字符串值完全一致：
|
||
`PENDING_PAY = 'PENDING_PAY'`，`CANCELLED = 'CANCELLED'`。
|
||
- 待付款 = `PENDING_PAY`；已取消 = `CANCELLED`（无 CLOSED / UNPAID 形态，PayStatus 才是 UNPAID）。
|
||
|
||
## 2. 订单创建流程
|
||
- `TradeService.createOrder` `src/modules/trade/trade.service.ts:153`；初始 `status: 'PENDING_PAY'`（:232）、`payStatus: 'UNPAID'`（:233）。
|
||
- 已写入支付截止时间：`const payExpireAt = new Date(Date.now() + 30 * 60 * 1000)`（:206），并落库 `payExpireAt`（:264）。
|
||
- 三条建单路径均已设置该字段：`createOrder`（:206）、`createPartnerProxyOrder`（:1590）、`createHqProxyOrder`（:1935）。
|
||
- 下单时间 `createdAt`（`schema.prisma:1400/1473`）；支付时间 `paidAt`（:1455）；取消时间 `cancelledAt`（:1458，已存在可复用，无需新增字段）。
|
||
|
||
## 3. 现有定时任务机制
|
||
- 已启用 `@nestjs/schedule`：`src/jobs/jobs.module.ts:13` `ScheduleModule.forRoot()`，并注册 BullMQ `DELIVERY_QUEUE`（`jobs.constants.ts`，用于 `delivery.processor.ts`）。
|
||
- `@Cron` 完整示例 `src/jobs/settlement.scheduler.ts`：
|
||
```ts
|
||
@Cron('0 8 * * *', { timeZone: 'Asia/Shanghai' })
|
||
async handleDailyBills() {
|
||
try { /* ... */ }
|
||
catch (e) { this.alert.notify({ level: 'P0', category: 'job', title: '...', dedupeKey: '...' }); }
|
||
}
|
||
```
|
||
- **关键缺口**：`src/jobs/monitor.scheduler.ts:54` `scanStuckOrders()` 已每 5 分钟（`*/5 * * * *`）扫描超时未付款订单，但**只 alert 不取消**（:61-81）。这正是自动取消要补的环节。
|
||
- `payExpireAt` 字段已存在，**无需新增迁移**；但 Order 表无 `(status, payExpireAt)` 复合索引（现有索引见 `schema.prisma:1488-1497`）。
|
||
|
||
## 4. 取消订单的业务影响
|
||
- 现有取消入口仅 `cancelPartnerProxyOrder`（:1791，限 PROXY 单）：事务内 `update status: 'CANCELLED', cancelledAt: new Date()`（:1807）+ 写 `commonEvent` 状态日志（:1809）。
|
||
- 通用状态机 `applyStatusTransition`（:1324）：翻 `order.status` + 写 `commonEvent`（`buildOrderStatusEvent`），但**不处理 `cancelledAt` / `payStatus`**。
|
||
- grep 确认建单与取消均**无库存占用/权益发放**（无 stock/inventory/decrement/release 调用，仅 `benefitCoupon` 出现在查询 include）。→ 自动取消只需翻状态+写日志，**无需回滚库存/释放权益**。
|
||
- 建议：新增 `TradeService.autoCancelExpiredOrders()`，复用 `applyStatusTransition` 但补 `cancelledAt` 写入（或在内联事务中同时置 `status/ cancelledAt/ payStatus`）。
|
||
|
||
## 5. 查询未支付订单
|
||
- 现成写法（`monitor.scheduler.ts:61`）：
|
||
```ts
|
||
this.prisma.order.findMany({
|
||
where: { status: 'PENDING_PAY', payExpireAt: { lt: now } },
|
||
select: { orderNo: true }, take: sample, orderBy: { payExpireAt: 'asc' },
|
||
});
|
||
```
|
||
- 建议加 `payStatus: 'UNPAID'` 过滤更稳妥；字段即 `payExpireAt`（`DateTime?`）。扫描前建议新增 `@@index([status, payExpireAt])`。
|
||
|
||
## 6. 实现建议
|
||
- 在 `MonitorScheduler` 新增 `@Cron`（如每 1 分钟 `*/1 * * * *`）或扩展 `scanStuckOrders`，调用 `TradeService.autoCancelExpiredOrders()`：分页取 `status:PENDING_PAY && payExpireAt<now`，对每个订单用**条件更新** `updateMany({ where: { id, status: 'PENDING_PAY' }, data: { status: 'CANCELLED', cancelledAt: now } })`，并写 `commonEvent`（operator=`'SYSTEM_AUTO_CANCEL'`）。
|
||
- 状态枚举引用：service 层当前直接用字符串 `'PENDING_PAY'`/`'CANCELLED'`（也可 `import { OrderStatus } from 'shared-types'`，二者值一致）。
|
||
- 失败处理沿用现有 `alert.notify` 模式（level P0/P1 + dedupeKey）。
|
||
|
||
## 7. 风险点
|
||
1. **分布式锁/幂等**：多实例下 `scanStuckOrders` 当前无锁（`monitor.scheduler` 已注入 `RedisService`，可加 Redis 分布式锁防重复执行）；`where:{status:'PENDING_PAY'}` 条件更新保证幂等。
|
||
2. **无重复任务冲突**：当前仅 monitor 扫描告警，尚无真正取消任务，新增即补缺口，不会与既有任务重复。支付路径已在校验 `payExpireAt<now` 拒绝支付（:2053、:2142），与自动取消逻辑自洽。
|
||
3. **批量规模**：用 `take` 分页 + `orderBy payExpireAt asc`，勿一次性全量 update，避免长事务。
|
||
4. **索引缺失**：扫描前先加 `@@index([status, payExpireAt])`，否则全表扫描。
|
||
|
||
## 8. 关键文件清单
|
||
- `server/dukang-api/prisma/schema.prisma`（OrderStatus:321；Order 模型:1412-1499；索引:1488-1497）
|
||
- `packages/shared-types/src/enums.ts`（OrderStatus:71）
|
||
- `server/dukang-api/src/modules/trade/trade.service.ts`（createOrder:153；payExpireAt:206/1590/1935；applyStatusTransition:1324；cancelPartnerProxyOrder:1791；支付过期校验:2053/2142）
|
||
- `server/dukang-api/src/modules/trade/trade.controller.ts`（cancel-pay:261）
|
||
- `server/dukang-api/src/jobs/monitor.scheduler.ts`（scanStuckOrders:54）
|
||
- `server/dukang-api/src/jobs/settlement.scheduler.ts`（@Cron 范例）
|
||
- `server/dukang-api/src/jobs/jobs.module.ts`、`jobs.constants.ts`、`delivery.processor.ts`
|