Kirill
447 lines
14 KiB
Markdown
447 lines
14 KiB
Markdown
# Admin Orders UX Improvements Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Добавить в списке заказов маркер `Цена не подтверждена` и заменить смену статуса в деталке на быстрые кнопки допустимых переходов.
|
||
|
||
**Architecture:** Изменения ограничены фронтендом (`client`) и опираются на текущие поля заказа (`status`, `deliveryType`, `deliveryFeeLocked`) и текущую логику переходов `getAdminNextOrderStatuses`. Серверные API и контракты не меняются, синхронизация данных остается через существующую инвалидацию React Query.
|
||
|
||
**Tech Stack:** React, TypeScript, MUI, TanStack React Query, Vitest, Testing Library.
|
||
|
||
---
|
||
|
||
## File Structure
|
||
|
||
**Create:**
|
||
- `client/src/shared/lib/order-requires-price-approval.ts`
|
||
- `client/src/shared/lib/__tests__/order-requires-price-approval.test.ts`
|
||
- `client/src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
- `client/src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx`
|
||
|
||
**Modify:**
|
||
- `client/src/pages/admin-orders/ui/AdminOrdersPage.tsx`
|
||
- `client/src/features/order-detail/ui/OrderDetailContent.tsx`
|
||
|
||
---
|
||
|
||
### Task 1: Вычисление признака "цена не подтверждена"
|
||
|
||
**Files:**
|
||
- Create: `client/src/shared/lib/order-requires-price-approval.ts`
|
||
- Test: `client/src/shared/lib/__tests__/order-requires-price-approval.test.ts`
|
||
|
||
- [ ] **Step 1: Write the failing unit test**
|
||
|
||
```ts
|
||
import { describe, expect, it } from 'vitest'
|
||
import { orderRequiresPriceApproval } from '../order-requires-price-approval'
|
||
|
||
describe('orderRequiresPriceApproval', () => {
|
||
it('returns true for delivery pending payment with unlocked delivery fee', () => {
|
||
expect(
|
||
orderRequiresPriceApproval({
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'delivery',
|
||
deliveryFeeLocked: false,
|
||
}),
|
||
).toBe(true)
|
||
})
|
||
|
||
it('returns false when delivery fee is already locked', () => {
|
||
expect(
|
||
orderRequiresPriceApproval({
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'delivery',
|
||
deliveryFeeLocked: true,
|
||
}),
|
||
).toBe(false)
|
||
})
|
||
|
||
it('returns false for pickup even if payment is pending', () => {
|
||
expect(
|
||
orderRequiresPriceApproval({
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'pickup',
|
||
deliveryFeeLocked: false,
|
||
}),
|
||
).toBe(false)
|
||
})
|
||
|
||
it('returns false for non-pending statuses', () => {
|
||
expect(
|
||
orderRequiresPriceApproval({
|
||
status: 'PAID',
|
||
deliveryType: 'delivery',
|
||
deliveryFeeLocked: false,
|
||
}),
|
||
).toBe(false)
|
||
})
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `cd client && npm test -- src/shared/lib/__tests__/order-requires-price-approval.test.ts`
|
||
Expected: FAIL with module/function not found.
|
||
|
||
- [ ] **Step 3: Write minimal implementation**
|
||
|
||
```ts
|
||
type PriceApprovalOrder = {
|
||
status: string
|
||
deliveryType: 'delivery' | 'pickup'
|
||
deliveryFeeLocked: boolean
|
||
}
|
||
|
||
export function orderRequiresPriceApproval(order: PriceApprovalOrder): boolean {
|
||
return order.status === 'PENDING_PAYMENT' && order.deliveryType === 'delivery' && order.deliveryFeeLocked === false
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Run test to verify it passes**
|
||
|
||
Run: `cd client && npm test -- src/shared/lib/__tests__/order-requires-price-approval.test.ts`
|
||
Expected: PASS (4 tests).
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add client/src/shared/lib/order-requires-price-approval.ts client/src/shared/lib/__tests__/order-requires-price-approval.test.ts
|
||
git commit -m "test: add price approval predicate for admin orders"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Маркер "Цена не подтверждена" в списке заказов
|
||
|
||
**Files:**
|
||
- Modify: `client/src/pages/admin-orders/ui/AdminOrdersPage.tsx`
|
||
- Test: `client/src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx`
|
||
|
||
- [ ] **Step 1: Write the failing component test for chip visibility**
|
||
|
||
```tsx
|
||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
|
||
import { render, screen } from '@testing-library/react'
|
||
import { describe, expect, it, vi } from 'vitest'
|
||
import { AdminOrdersPage } from '../AdminOrdersPage'
|
||
|
||
const fetchAdminOrdersMock = vi.fn()
|
||
|
||
vi.mock('@/entities/order/api/admin-order-api', () => ({
|
||
fetchAdminOrders: fetchAdminOrdersMock,
|
||
fetchAdminOrder: vi.fn(),
|
||
}))
|
||
|
||
describe('AdminOrdersPage price approval marker', () => {
|
||
it('shows "Цена не подтверждена" for eligible order', async () => {
|
||
fetchAdminOrdersMock.mockResolvedValueOnce({
|
||
items: [
|
||
{
|
||
id: 'order-1',
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'delivery',
|
||
deliveryFeeLocked: false,
|
||
totalCents: 10000,
|
||
currency: 'RUB',
|
||
createdAt: new Date().toISOString(),
|
||
updatedAt: new Date().toISOString(),
|
||
user: { id: 'u1', email: 'a@example.com' },
|
||
itemsCount: 1,
|
||
},
|
||
],
|
||
total: 1,
|
||
page: 1,
|
||
pageSize: 20,
|
||
})
|
||
|
||
const qc = new QueryClient()
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<AdminOrdersPage />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
expect(await screen.findByText('Цена не подтверждена')).toBeInTheDocument()
|
||
})
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `cd client && npm test -- src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx`
|
||
Expected: FAIL because chip text is not rendered yet.
|
||
|
||
- [ ] **Step 3: Implement marker in `AdminOrdersPage`**
|
||
|
||
```tsx
|
||
import Chip from '@mui/material/Chip'
|
||
import { orderRequiresPriceApproval } from '@/shared/lib/order-requires-price-approval'
|
||
|
||
// ...
|
||
|
||
{group.items.map((o) => {
|
||
const needsPriceApproval = orderRequiresPriceApproval({
|
||
status: o.status,
|
||
deliveryType: o.deliveryType,
|
||
deliveryFeeLocked: o.deliveryFeeLocked,
|
||
})
|
||
|
||
return (
|
||
<TableRow key={o.id} hover>
|
||
<TableCell>
|
||
<Stack direction="row" spacing={1} alignItems="center">
|
||
<Box component="span">{o.id.slice(-8)}</Box>
|
||
{needsPriceApproval && <Chip size="small" color="warning" label="Цена не подтверждена" />}
|
||
</Stack>
|
||
</TableCell>
|
||
{/* ... */}
|
||
</TableRow>
|
||
)
|
||
})}
|
||
```
|
||
|
||
- [ ] **Step 4: Add negative case and rerun test**
|
||
|
||
```tsx
|
||
it('does not show marker for non-eligible order', async () => {
|
||
fetchAdminOrdersMock.mockResolvedValueOnce({
|
||
items: [
|
||
{
|
||
id: 'order-2',
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'delivery',
|
||
deliveryFeeLocked: true,
|
||
totalCents: 10000,
|
||
currency: 'RUB',
|
||
createdAt: new Date().toISOString(),
|
||
updatedAt: new Date().toISOString(),
|
||
user: { id: 'u2', email: 'b@example.com' },
|
||
itemsCount: 2,
|
||
},
|
||
],
|
||
total: 1,
|
||
page: 1,
|
||
pageSize: 20,
|
||
})
|
||
|
||
const qc = new QueryClient()
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<AdminOrdersPage />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
expect(await screen.findByText('order-2'.slice(-8))).toBeInTheDocument()
|
||
expect(screen.queryByText('Цена не подтверждена')).not.toBeInTheDocument()
|
||
})
|
||
```
|
||
|
||
Run: `cd client && npm test -- src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add client/src/pages/admin-orders/ui/AdminOrdersPage.tsx client/src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx
|
||
git commit -m "feat: show price approval marker in admin orders list"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Быстрые кнопки смены статуса в деталке
|
||
|
||
**Files:**
|
||
- Modify: `client/src/features/order-detail/ui/OrderDetailContent.tsx`
|
||
- Test: `client/src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
|
||
- [ ] **Step 1: Write failing tests for quick actions**
|
||
|
||
```tsx
|
||
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
|
||
import { fireEvent, render, screen } from '@testing-library/react'
|
||
import { describe, expect, it, vi } from 'vitest'
|
||
import { OrderDetailContent } from '../OrderDetailContent'
|
||
import type { AdminOrderDetailResponse } from '@/entities/order/api/admin-order-api'
|
||
|
||
const setAdminOrderStatusMock = vi.fn(async () => undefined)
|
||
|
||
vi.mock('@/entities/order/api/admin-order-api', async () => {
|
||
const actual = await vi.importActual<object>('@/entities/order/api/admin-order-api')
|
||
return {
|
||
...actual,
|
||
setAdminOrderStatus: setAdminOrderStatusMock,
|
||
postAdminOrderMessage: vi.fn(async () => undefined),
|
||
}
|
||
})
|
||
|
||
function buildDetail(patch: Partial<AdminOrderDetailResponse['item']>): AdminOrderDetailResponse['item'] {
|
||
return {
|
||
id: 'o1',
|
||
status: 'PENDING_PAYMENT',
|
||
deliveryType: 'delivery',
|
||
deliveryCarrier: null,
|
||
paymentMethod: 'online',
|
||
itemsSubtotalCents: 10000,
|
||
deliveryFeeCents: 500,
|
||
deliveryFeeLocked: false,
|
||
totalCents: 10500,
|
||
currency: 'RUB',
|
||
addressSnapshotJson: null,
|
||
comment: null,
|
||
createdAt: new Date().toISOString(),
|
||
updatedAt: new Date().toISOString(),
|
||
user: {
|
||
id: 'u1',
|
||
email: 'a@example.com',
|
||
displayName: null,
|
||
avatar: null,
|
||
avatarStyle: null,
|
||
},
|
||
items: [],
|
||
messages: [],
|
||
...patch,
|
||
}
|
||
}
|
||
|
||
describe('OrderDetailContent quick status actions', () => {
|
||
it('renders quick action buttons for next statuses', () => {
|
||
const qc = new QueryClient()
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<OrderDetailContent detail={buildDetail({ status: 'PENDING_PAYMENT', deliveryType: 'delivery' })} orderId="o1" />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
expect(screen.getByRole('button', { name: /Оплачен/i })).toBeInTheDocument()
|
||
})
|
||
|
||
it('calls setAdminOrderStatus on click', () => {
|
||
const qc = new QueryClient()
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<OrderDetailContent detail={buildDetail({ status: 'PENDING_PAYMENT', deliveryType: 'delivery' })} orderId="o1" />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
fireEvent.click(screen.getByRole('button', { name: /Оплачен/i }))
|
||
expect(setAdminOrderStatusMock).toHaveBeenCalledWith('o1', 'PAID')
|
||
})
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: Run test to verify it fails**
|
||
|
||
Run: `cd client && npm test -- src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
Expected: FAIL because old `Select` UI is still used.
|
||
|
||
- [ ] **Step 3: Replace select with quick action buttons**
|
||
|
||
```tsx
|
||
<Stack spacing={1}>
|
||
<Typography variant="subtitle2" sx={{ fontWeight: 700 }}>
|
||
Быстрый переход статуса
|
||
</Typography>
|
||
|
||
{nextStatuses.length === 0 ? (
|
||
<Typography variant="body2" color="text.secondary">
|
||
Статус финальный, смена недоступна
|
||
</Typography>
|
||
) : (
|
||
<Stack direction={{ xs: 'column', sm: 'row' }} spacing={1}>
|
||
{nextStatuses.map((nextStatus) => {
|
||
const isCancel = nextStatus === 'CANCELLED'
|
||
return (
|
||
<Button
|
||
key={nextStatus}
|
||
variant={isCancel ? 'outlined' : 'contained'}
|
||
color={isCancel ? 'error' : 'primary'}
|
||
onClick={() => statusMut.mutate(nextStatus)}
|
||
disabled={statusMut.isPending}
|
||
>
|
||
{ORDER_STATUS_MAP[nextStatus] ?? nextStatus}
|
||
</Button>
|
||
)
|
||
})}
|
||
</Stack>
|
||
)}
|
||
</Stack>
|
||
```
|
||
|
||
- [ ] **Step 4: Add pending/empty-state assertions and rerun tests**
|
||
|
||
```tsx
|
||
it('disables all quick action buttons while mutation is pending', () => {
|
||
const qc = new QueryClient()
|
||
setAdminOrderStatusMock.mockImplementationOnce(() => new Promise(() => {}))
|
||
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<OrderDetailContent detail={buildDetail({ status: 'PENDING_PAYMENT', deliveryType: 'delivery' })} orderId="o1" />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
const paidButton = screen.getByRole('button', { name: /Оплачен/i })
|
||
fireEvent.click(paidButton)
|
||
expect(paidButton).toBeDisabled()
|
||
})
|
||
|
||
it('shows final state note when no transitions available', () => {
|
||
const qc = new QueryClient()
|
||
render(
|
||
<QueryClientProvider client={qc}>
|
||
<OrderDetailContent detail={buildDetail({ status: 'DONE', deliveryType: 'delivery' })} orderId="o1" />
|
||
</QueryClientProvider>,
|
||
)
|
||
|
||
expect(screen.getByText('Статус финальный, смена недоступна')).toBeInTheDocument()
|
||
})
|
||
```
|
||
|
||
Run: `cd client && npm test -- src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add client/src/features/order-detail/ui/OrderDetailContent.tsx client/src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx
|
||
git commit -m "feat: replace admin order status select with quick actions"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: Регрессия, линт и финальная проверка
|
||
|
||
**Files:**
|
||
- Modify (if needed): `client/src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx`
|
||
- Modify (if needed): `client/src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
- Modify (if needed): `client/src/shared/lib/__tests__/order-requires-price-approval.test.ts`
|
||
|
||
- [ ] **Step 1: Run focused test suite for changed units**
|
||
|
||
Run:
|
||
`cd client && npm test -- src/shared/lib/__tests__/order-requires-price-approval.test.ts src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx`
|
||
Expected: PASS.
|
||
|
||
- [ ] **Step 2: Run frontend lint**
|
||
|
||
Run: `cd client && npm run lint`
|
||
Expected: PASS with no new lint errors.
|
||
|
||
- [ ] **Step 3: Run format check**
|
||
|
||
Run: `cd client && npm run format:check`
|
||
Expected: PASS, no formatting violations.
|
||
|
||
- [ ] **Step 4: Fix issues if any and re-run exact failed command**
|
||
|
||
Run (example): `cd client && npm run lint`
|
||
Expected: PASS after fixes.
|
||
|
||
- [ ] **Step 5: Final commit**
|
||
|
||
```bash
|
||
git add client/src/pages/admin-orders/ui/AdminOrdersPage.tsx client/src/features/order-detail/ui/OrderDetailContent.tsx client/src/shared/lib/order-requires-price-approval.ts client/src/shared/lib/__tests__/order-requires-price-approval.test.ts client/src/pages/admin-orders/ui/__tests__/AdminOrdersPage.test.tsx client/src/features/order-detail/ui/__tests__/OrderDetailContent.test.tsx
|
||
git commit -m "feat: improve admin orders flow for price approval and status updates"
|
||
```
|