# Single Warehouse Stocktake Flow 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:** Change 百华仓库盘库 into a current-selected-warehouse-only flow: select a warehouse bar first, click 盘库, confirm/export one locked warehouse sheet, import only that same stocktake workbook, show a modal diff immediately, and confirm to reset that warehouse inventory and unlock it.

**Architecture:** Backend becomes the source of truth for single-warehouse stocktake rules, workbook validation token checks, import overwrite behavior, and current-warehouse history filtering. Frontend removes multi-warehouse selection from the stocktake dialog and renders two blocks: a stocktake flow block for the currently selected warehouse and a stocktake records block filtered to that warehouse. The diff review is opened as a modal immediately after each import; cancel closes the modal and leaves the warehouse locked for re-import.

**Tech Stack:** FastAPI, SQLAlchemy ORM, openpyxl, Python unittest, Vue 3 Composition API, Node built-in `assert`, Vite.

---

## Scope Rules

- Keep existing stocktake tables: `wh_stocktake`, `wh_stocktake_warehouse`, `wh_stocktake_line`, and `wh_stocktake_adjustment`.
- Do not add a migration unless tests prove existing columns cannot represent the requested flow.
- Backend must reject multi-warehouse stocktake creation even if a caller bypasses the UI.
- Backend must reject import files that are not for the current stocktake number and current warehouse.
- Re-importing a corrected workbook must replace the previous imported diff preview for that same stocktake before confirmation.
- Frontend must not let the user choose warehouses inside the stocktake dialog. The active warehouse comes from the warehouse bar selection.
- The workspace root `/Users/souplearn/Gitlab/py/ForgeFlow-ERP` is not a git repository in this environment, so plan steps do not include commits.

## File Structure

- Modify: `backend/app/services/stocktake.py`
  - Enforce one warehouse per stocktake.
  - Build and validate workbook check tokens.
  - Export one warehouse workbook with a validation marker.
  - Import only matching current-stocktake/current-warehouse workbooks.
  - Reset previous imported preview rows before re-import.

- Modify: `backend/app/api/routes/inventory.py`
  - Filter stocktake history by current warehouse with `warehouse_id`.
  - Keep import/export route shapes stable.

- Modify: `backend/app/schemas/operations.py`
  - Tighten `StocktakeStartCreate` to one warehouse in request validation if supported by current Pydantic.

- Modify: `backend/tests/test_stocktake_excel_diff_confirm.py`
  - Add backend regression tests for single-warehouse start, validation marker export, wrong stocktake import rejection, wrong warehouse import rejection, and re-import overwrite.

- Modify: `frontend/src/components/StocktakeDialog.vue`
  - Replace multi-warehouse overview cards with current warehouse flow + current warehouse records.
  - Start and export in one user action.
  - Open diff as modal immediately after import.
  - Cancel diff modal without unlocking; allow re-import.

- Modify: `frontend/src/utils/stocktakeWorkflow.js`
  - Add current-warehouse-only helpers for active stocktake lookup and panel routing.

- Modify: `frontend/scripts/test-stocktake-workflow.mjs`
  - Update workflow tests to cover current-selected-warehouse behavior and no global fallback.

- Modify: `frontend/src/styles/main.css`
  - Style the two-block stocktake dialog, current warehouse badge, and diff modal.

---

## Task 1: Backend Failing Tests for Single-Warehouse Rules

**Files:**
- Modify: `backend/tests/test_stocktake_excel_diff_confirm.py`

- [ ] **Step 1: Add imports used by new tests**

Ensure this import line includes `Workbook`:

```python
from openpyxl import Workbook, load_workbook
```

If the file currently imports `Workbook` inside a test method, leave local imports alone unless duplicate imports become confusing.

- [ ] **Step 2: Add a test that multi-warehouse stocktake creation is rejected**

Append this method to `StocktakeExcelDiffConfirmTest`:

```python
    def test_start_stocktake_rejects_multiple_warehouses_for_current_bar_flow(self) -> None:
        from fastapi import HTTPException

        now = datetime.now(UTC)
        aux = Warehouse(
            id=2,
            warehouse_code="WH-AUX-01",
            warehouse_name="辅料库",
            warehouse_type="AUX",
            status="ACTIVE",
            created_at=now,
            updated_at=now,
        )
        self.db.add(aux)
        self.db.commit()

        with self.assertRaises(HTTPException) as exc:
            start_stocktake(self.db, warehouse_ids=[self.raw.id, aux.id], user_id=1, remark="多库盘库")

        self.assertEqual(exc.exception.status_code, 400)
        self.assertIn("一次只能盘一个仓库", exc.exception.detail)
```

- [ ] **Step 3: Add a test that export includes a validation marker and one warehouse sheet**

Append this method:

```python
    def test_single_warehouse_export_contains_validation_marker(self) -> None:
        stocktake = start_stocktake(self.db, warehouse_ids=[self.raw.id], user_id=1, remark="原材料盘库")
        workbook = build_stocktake_workbook(self.db, stocktake.id)
        output = BytesIO()
        workbook.save(output)
        loaded = load_workbook(BytesIO(output.getvalue()), read_only=True, data_only=True)

        self.assertEqual(loaded.sheetnames, ["原材料库"])
        rows = list(loaded["原材料库"].iter_rows(values_only=True))
        headers = rows[0]

        self.assertIn("盘库校验码", headers)
        self.assertIn("仓库ID", headers)
        self.assertEqual(rows[1][headers.index("盘库单号")], stocktake.stocktake_no)
        self.assertEqual(rows[1][headers.index("仓库ID")], self.raw.id)
        self.assertEqual(
            rows[1][headers.index("盘库校验码")],
            f"{stocktake.stocktake_no}|{self.raw.id}|RAW",
        )
```

- [ ] **Step 4: Add a helper for workbook mutation in tests**

Append this private helper method to the test class:

```python
    def _exported_workbook_bytes(self, stocktake) -> bytes:
        workbook = build_stocktake_workbook(self.db, stocktake.id)
        output = BytesIO()
        workbook.save(output)
        return output.getvalue()
```

- [ ] **Step 5: Add a test that wrong stocktake number is rejected**

Append this method:

```python
    def test_import_rejects_workbook_from_other_stocktake_number(self) -> None:
        from app.services.stocktake import import_stocktake_workbook

        stocktake = start_stocktake(self.db, warehouse_ids=[self.raw.id], user_id=1, remark="原材料盘库")
        workbook = load_workbook(BytesIO(self._exported_workbook_bytes(stocktake)))
        worksheet = workbook["原材料库"]
        headers = [cell.value for cell in worksheet[1]]
        worksheet.cell(row=2, column=headers.index("盘库单号") + 1).value = "PK-OTHER-001"
        worksheet.cell(row=2, column=headers.index("盘库校验码") + 1).value = "PK-OTHER-001|1|RAW"
        output = BytesIO()
        workbook.save(output)

        with self.assertRaises(ValueError) as exc:
            import_stocktake_workbook(self.db, stocktake.id, output.getvalue(), user_id=1)

        self.assertIn("不属于当前盘库单", str(exc.exception))
```

- [ ] **Step 6: Add a test that wrong warehouse marker is rejected**

Append this method:

```python
    def test_import_rejects_workbook_from_other_warehouse(self) -> None:
        from app.services.stocktake import import_stocktake_workbook

        stocktake = start_stocktake(self.db, warehouse_ids=[self.raw.id], user_id=1, remark="原材料盘库")
        workbook = load_workbook(BytesIO(self._exported_workbook_bytes(stocktake)))
        worksheet = workbook["原材料库"]
        headers = [cell.value for cell in worksheet[1]]
        worksheet.cell(row=2, column=headers.index("仓库") + 1).value = "成品库"
        worksheet.cell(row=2, column=headers.index("仓库ID") + 1).value = 999
        worksheet.cell(row=2, column=headers.index("盘库校验码") + 1).value = f"{stocktake.stocktake_no}|999|FINISHED"
        output = BytesIO()
        workbook.save(output)

        with self.assertRaises(ValueError) as exc:
            import_stocktake_workbook(self.db, stocktake.id, output.getvalue(), user_id=1)

        self.assertIn("不属于当前仓库", str(exc.exception))
```

- [ ] **Step 7: Add a test that re-import overwrites previous diff preview**

Append this method:

```python
    def test_reimport_overwrites_previous_stocktake_preview(self) -> None:
        from app.services.stocktake import import_stocktake_workbook

        stocktake = start_stocktake(self.db, warehouse_ids=[self.raw.id], user_id=1, remark="原材料盘库")

        workbook = load_workbook(BytesIO(self._exported_workbook_bytes(stocktake)))
        worksheet = workbook["原材料库"]
        headers = [cell.value for cell in worksheet[1]]
        worksheet.cell(row=2, column=headers.index("盘点重量(kg)") + 1).value = 90
        output = BytesIO()
        workbook.save(output)
        first_preview = import_stocktake_workbook(self.db, stocktake.id, output.getvalue(), user_id=1)
        self.assertEqual(first_preview["summary"]["loss_count"], 1)

        workbook = load_workbook(BytesIO(self._exported_workbook_bytes(stocktake)))
        worksheet = workbook["原材料库"]
        headers = [cell.value for cell in worksheet[1]]
        worksheet.cell(row=2, column=headers.index("盘点重量(kg)") + 1).value = 100
        output = BytesIO()
        workbook.save(output)
        second_preview = import_stocktake_workbook(self.db, stocktake.id, output.getvalue(), user_id=1)

        self.assertEqual(second_preview["summary"]["loss_count"], 0)
        self.assertEqual(second_preview["summary"]["match_count"], 1)
        line = self.db.scalar(select(StocktakeLine).where(StocktakeLine.stocktake_id == stocktake.id))
        self.assertEqual(line.diff_type, "MATCH")
        self.assertEqual(float(line.counted_weight_kg), 100)
```

- [ ] **Step 8: Run tests and confirm they fail for missing implementation**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/backend
.venv/bin/python -m unittest tests.test_stocktake_excel_diff_confirm
```

Expected: fail because current backend still allows multi-warehouse stocktakes and does not export/validate `盘库校验码` and `仓库ID`.

---

## Task 2: Backend Single-Warehouse Service Implementation

**Files:**
- Modify: `backend/app/services/stocktake.py`
- Modify: `backend/app/schemas/operations.py`

- [ ] **Step 1: Add workbook validation headers**

In `backend/app/services/stocktake.py`, extend `STOCKTAKE_EXCEL_HEADERS` so the first columns are:

```python
STOCKTAKE_EXCEL_HEADERS = [
    "盘库单号",
    "盘库校验码",
    "仓库ID",
    "快照行ID",
    "仓库",
    "库位",
    "物料编码",
    "物料名称",
    "批次号",
    "来源材料分批次号",
    "系统数量",
    "系统重量(kg)",
    "系统单价",
    "盘点数量",
    "盘点重量(kg)",
    "盘点备注",
]
```

- [ ] **Step 2: Add validation token helper**

Add below `stocktake_warehouse_type_label`:

```python
def stocktake_validation_token(stocktake_no: str, warehouse_id: int, warehouse_type: str | None) -> str:
    return f"{stocktake_no}|{int(warehouse_id)}|{str(warehouse_type or '').upper()}"
```

- [ ] **Step 3: Enforce one warehouse in service**

In `start_stocktake`, after `ids = ...`, add:

```python
    if len(set(ids)) != 1:
        raise HTTPException(status_code=400, detail="一次只能盘一个仓库，请先在仓库栏选中单个仓库")
```

Keep the existing empty and invalid warehouse checks.

- [ ] **Step 4: Tighten schema request validation**

In `backend/app/schemas/operations.py`, change:

```python
class StocktakeStartCreate(BaseModel):
    warehouse_ids: list[int] = Field(min_length=1)
    remark: str | None = None
```

to:

```python
class StocktakeStartCreate(BaseModel):
    warehouse_ids: list[int] = Field(min_length=1, max_length=1)
    remark: str | None = None
```

- [ ] **Step 5: Update export rows to include token and warehouse ID**

In `build_stocktake_workbook`, compute token per stocktake warehouse. Replace worksheet append rows so empty marker rows start with:

```python
token = stocktake_validation_token(stocktake.stocktake_no, warehouse.id, warehouse.warehouse_type)
worksheet.append(
    [
        stocktake.stocktake_no,
        token,
        warehouse.id,
        "",
        sheet_name,
        "",
        "",
        "",
        "",
        "",
        0,
        0,
        0,
        0,
        0,
        EMPTY_STOCKTAKE_MARKER_REMARK,
    ]
)
```

For normal stocktake lines, row values must start with:

```python
[
    stocktake.stocktake_no,
    stocktake_validation_token(stocktake.stocktake_no, line.warehouse_id, line.warehouse_type),
    line.warehouse_id,
    line.id,
    line.warehouse_name,
    ...
]
```

Update column widths list to 16 columns:

```python
[18, 30, 10, 12, 14, 14, 18, 28, 22, 24, 14, 16, 12, 14, 16, 24]
```

- [ ] **Step 6: Add helper to get the single stocktake warehouse**

Add below `_stocktake_lines`:

```python
def _single_stocktake_warehouse(db: Session, stocktake_id: int) -> StocktakeWarehouse:
    rows = db.scalars(
        select(StocktakeWarehouse).where(StocktakeWarehouse.stocktake_id == stocktake_id).order_by(StocktakeWarehouse.id.asc())
    ).all()
    if len(rows) != 1:
        raise HTTPException(status_code=400, detail="当前盘库单不是单仓库盘库，无法继续处理")
    return rows[0]
```

- [ ] **Step 7: Update empty marker detection for shifted columns**

No logic change is needed if `_is_empty_stocktake_marker_row` uses header labels. Verify it still checks `快照行ID`, material fields, and numeric columns by name.

- [ ] **Step 8: Add workbook validation helper**

Add below `_is_empty_stocktake_marker_row`:

```python
def _validate_stocktake_row_marker(row: dict[str, object], stocktake: Stocktake, warehouse: StocktakeWarehouse) -> None:
    row_stocktake_no = _clean_text(row.get("盘库单号"))
    if row_stocktake_no != stocktake.stocktake_no:
        raise ValueError(f"存在不属于当前盘库单的行：{row_stocktake_no or '空盘库单号'}")

    row_warehouse_id = _clean_text(row.get("仓库ID"))
    if row_warehouse_id and int(float(row_warehouse_id)) != int(warehouse.warehouse_id):
        raise ValueError("导入清单不属于当前仓库，请确认仓库栏选中项和盘库清单一致")

    row_warehouse_name = _clean_text(row.get("仓库"))
    if row_warehouse_name and row_warehouse_name != warehouse.warehouse_name:
        raise ValueError("导入清单不属于当前仓库，请确认仓库栏选中项和盘库清单一致")

    expected_token = stocktake_validation_token(stocktake.stocktake_no, warehouse.warehouse_id, warehouse.warehouse_type)
    row_token = _clean_text(row.get("盘库校验码"))
    if row_token != expected_token:
        raise ValueError("盘库校验码不匹配，请导入本次盘库导出的仓库清单")
```

- [ ] **Step 9: Add re-import reset helper**

Add below `_validate_stocktake_row_marker`:

```python
def _reset_stocktake_preview_for_reimport(db: Session, stocktake_id: int, warehouse_id: int) -> dict[int, StocktakeLine]:
    lines = db.scalars(
        select(StocktakeLine)
        .where(StocktakeLine.stocktake_id == stocktake_id, StocktakeLine.warehouse_id == warehouse_id)
        .order_by(StocktakeLine.line_no.asc())
    ).all()
    existing_lines: dict[int, StocktakeLine] = {}
    for line in lines:
        if line.lot_id is None and line.diff_type == "NEW_LOT":
            db.delete(line)
            continue
        line.counted_qty = None
        line.counted_weight_kg = None
        line.diff_qty = Decimal("0")
        line.diff_weight_kg = Decimal("0")
        line.diff_amount = Decimal("0")
        line.diff_type = "MATCH"
        line.row_status = "SNAPSHOT"
        line.error_message = None
        line.remark = None
        db.add(line)
        existing_lines[line.id] = line
    db.flush()
    return existing_lines
```

- [ ] **Step 10: Rewrite import to validate current warehouse and overwrite previous preview**

In `import_stocktake_workbook`, after stocktake status check, add:

```python
    stocktake_warehouse = _single_stocktake_warehouse(db, stocktake_id)
```

Then replace `existing_lines = {...}` with:

```python
    existing_lines = _reset_stocktake_preview_for_reimport(db, stocktake_id, stocktake_warehouse.warehouse_id)
```

Inside `for row in rows`, replace the current stocktake number validation with:

```python
        _validate_stocktake_row_marker(row, stocktake, stocktake_warehouse)
```

For new rows without `快照行ID`, remove lookup by arbitrary warehouse name and force the stocktake warehouse:

```python
        warehouse = db.get(Warehouse, stocktake_warehouse.warehouse_id)
        if not item or not warehouse:
            raise ValueError(f"新增批次行物料或仓库不存在：{stocktake_warehouse.warehouse_name} / {item_code}")
```

When creating `StocktakeLine` for new rows, set:

```python
stocktake_warehouse_id=stocktake_warehouse.id,
warehouse_id=warehouse.id,
warehouse_name=warehouse.warehouse_name,
warehouse_type=str(warehouse.warehouse_type or "").upper(),
```

In the missing-line loop, only iterate current `existing_lines`.

- [ ] **Step 11: Return only current warehouse lines after import**

At the end of `import_stocktake_workbook`, replace final `lines = ...` query with:

```python
    lines = db.scalars(
        select(StocktakeLine)
        .where(StocktakeLine.stocktake_id == stocktake_id, StocktakeLine.warehouse_id == stocktake_warehouse.warehouse_id)
        .order_by(StocktakeLine.line_no.asc())
    ).all()
```

- [ ] **Step 12: Run backend stocktake tests**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/backend
.venv/bin/python -m unittest tests.test_stocktake_excel_diff_confirm
.venv/bin/python -m unittest tests.test_stocktake_locking tests.test_stocktake_excel_diff_confirm
```

Expected: both commands pass with `OK`.

---

## Task 3: Backend Routes for Current-Warehouse History and Lines

**Files:**
- Modify: `backend/app/api/routes/inventory.py`

- [ ] **Step 1: Add warehouse filter to stocktake read summary**

Modify `_stocktake_read` signature:

```python
def _stocktake_read(db: Session, stocktake_id: int, warehouse_id: int | None = None) -> StocktakeRead:
```

Replace:

```python
lines = stocktake_lines_for_read(db, stocktake_id)
```

with:

```python
lines = stocktake_lines_for_read(db, stocktake_id)
if warehouse_id:
    lines = [line for line in lines if int(line.warehouse_id) == int(warehouse_id)]
```

- [ ] **Step 2: Filter `/inventory/stocktakes` by warehouse ID**

Change route signature:

```python
def list_inventory_stocktakes(
    limit: int = Query(default=100, ge=1, le=500),
    warehouse_id: int | None = Query(default=None),
    db: Session = Depends(get_db),
) -> list[StocktakeRead]:
```

Replace the query with:

```python
    stmt = select(Stocktake).order_by(Stocktake.started_at.desc(), Stocktake.id.desc()).limit(limit)
    if warehouse_id:
        stmt = (
            select(Stocktake)
            .join(StocktakeWarehouse, StocktakeWarehouse.stocktake_id == Stocktake.id)
            .where(StocktakeWarehouse.warehouse_id == warehouse_id)
            .order_by(Stocktake.started_at.desc(), Stocktake.id.desc())
            .limit(limit)
        )
    rows = db.scalars(stmt).all()
    return [_stocktake_read(db, row.id, warehouse_id=warehouse_id) for row in rows]
```

- [ ] **Step 3: Filter lines endpoint by warehouse ID**

Change route signature:

```python
def list_inventory_stocktake_lines(
    stocktake_id: int,
    warehouse_id: int | None = Query(default=None),
    db: Session = Depends(get_db),
) -> list[StocktakeLineRead]:
```

Replace return with:

```python
    lines = stocktake_lines_for_read(db, stocktake_id)
    if warehouse_id:
        lines = [line for line in lines if int(line.warehouse_id) == int(warehouse_id)]
    return [StocktakeLineRead.model_validate(_stocktake_line_read(line)) for line in lines]
```

- [ ] **Step 4: Preserve import preview response**

In `_stocktake_preview_read`, do not filter because backend import is now single-warehouse. Confirm it still returns `result["lines"]`.

- [ ] **Step 5: Run route-adjacent tests**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/backend
.venv/bin/python -m unittest tests.test_stocktake_locking tests.test_stocktake_excel_diff_confirm
```

Expected: pass with `OK`.

---

## Task 4: Frontend Workflow Helper for Current Warehouse Only

**Files:**
- Modify: `frontend/src/utils/stocktakeWorkflow.js`
- Modify: `frontend/scripts/test-stocktake-workflow.mjs`

- [ ] **Step 1: Add helper for current warehouse history filtering**

In `frontend/src/utils/stocktakeWorkflow.js`, add:

```js
export function stocktakeBelongsToWarehouse(row, warehouseId) {
  const id = Number(warehouseId || 0);
  if (!id || !Array.isArray(row?.warehouses)) return false;
  return row.warehouses.some((warehouse) => Number(warehouse.warehouse_id) === id);
}

export function filterStocktakesForWarehouse(historyRows = [], warehouseId) {
  return historyRows.filter((row) => stocktakeBelongsToWarehouse(row, warehouseId));
}
```

- [ ] **Step 2: Replace global fallback helper usage policy in tests**

In `frontend/scripts/test-stocktake-workflow.mjs`, add imports:

```js
  filterStocktakesForWarehouse,
  stocktakeBelongsToWarehouse,
```

Add assertions:

```js
assert.equal(stocktakeBelongsToWarehouse(lockedRaw, 1), true);
assert.equal(stocktakeBelongsToWarehouse(lockedRaw, 4), false);
assert.deepEqual(filterStocktakesForWarehouse([lockedRaw, emptyExported], 1).map((row) => row.id), [12]);
```

- [ ] **Step 3: Add source assertions that global fallback is not used by dialog**

Add after existing component source assertions:

```js
assert.doesNotMatch(componentSource, /findOnlyActiveStocktake\\(historyRows\\.value\\)/);
assert.match(componentSource, /findActiveStocktakeForWarehouse\\(historyRows\\.value, currentWarehouseId\\.value\\)/);
assert.match(componentSource, /\\/inventory\\/stocktakes\\?warehouse_id=\\$\\{currentWarehouseId\\.value\\}/);
```

- [ ] **Step 4: Run frontend helper test and confirm it fails before dialog implementation**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/frontend
node scripts/test-stocktake-workflow.mjs
```

Expected: fail because `StocktakeDialog.vue` still uses `findOnlyActiveStocktake(historyRows.value)` and does not request `warehouse_id`.

---

## Task 5: Frontend Single-Warehouse Dialog Flow

**Files:**
- Modify: `frontend/src/components/StocktakeDialog.vue`

- [ ] **Step 1: Update imports**

Remove unused imports if no longer needed:

```js
findOnlyActiveStocktake,
warehouseStocktakeStatus
```

Add:

```js
filterStocktakesForWarehouse,
```

- [ ] **Step 2: Replace multi-step labels**

Change `flowSteps` to:

```js
const flowSteps = [
  { key: "export", no: "01", label: "确认盘库并导出" },
  { key: "import", no: "02", label: "导入清单" }
];
```

- [ ] **Step 3: Replace selection state with current warehouse state**

Remove:

```js
const selectedWarehouseIds = ref([]);
const activeWarehouseStatuses = computed(...);
const selectedStartableWarehouseIds = computed(...);
const activeWarehouseNames = computed(...);
```

Add:

```js
const currentWarehouseId = computed(() => Number(props.defaultWarehouseId || 0));
const currentWarehouse = computed(
  () => props.warehouses.find((warehouse) => Number(warehouse.id) === currentWarehouseId.value) || null
);
const currentWarehouseName = computed(() => currentWarehouse.value?.warehouse_name || "未选择仓库");
const currentWarehouseHistoryRows = computed(() => filterStocktakesForWarehouse(historyRows.value, currentWarehouseId.value));
```

- [ ] **Step 4: Replace open watcher**

Replace watcher body with:

```js
watch(
  () => props.open,
  async (open) => {
    if (!open) return;
    activePanel.value = "export";
    activeStocktake.value = null;
    previewLines.value = [];
    previewSummary.value = {};
    diffFilter.value = "ALL";
    confirmDialogOpen.value = false;
    diffDialogOpen.value = false;
    dialogMessage.value = "";
    dialogError.value = "";
    if (!currentWarehouseId.value) {
      setDialogError("请先在仓库栏选中一个仓库，再进行盘库");
      return;
    }
    await loadHistory();
    const activeRow = findActiveStocktakeForWarehouse(historyRows.value, currentWarehouseId.value);
    if (activeRow) {
      await continueStocktake(activeRow, { silent: true });
    }
  }
);
```

- [ ] **Step 5: Add diff modal state**

Add near `confirmDialogOpen`:

```js
const diffDialogOpen = ref(false);
```

In `applyLoadedStocktake`, set `diffDialogOpen.value = false` before loading state.

- [ ] **Step 6: Replace `loadHistory` with warehouse-filtered API call**

Replace `loadHistory` with:

```js
async function loadHistory() {
  try {
    if (!currentWarehouseId.value) {
      historyRows.value = [];
      return;
    }
    historyRows.value = await fetchResource(`/inventory/stocktakes?warehouse_id=${currentWarehouseId.value}&limit=100`, []);
  } catch (error) {
    setDialogError(error.message || "读取盘库记录失败");
  }
}
```

- [ ] **Step 7: Replace start flow with start-and-export action**

Replace `startStocktake` with:

```js
async function startAndExportStocktake() {
  clearDialogFeedback();
  if (!currentWarehouseId.value) {
    setDialogError("请先在仓库栏选中一个仓库");
    return;
  }
  busy.value = true;
  try {
    const stocktake = await postResource("/inventory/stocktakes", {
      warehouse_ids: [currentWarehouseId.value],
      remark: `${currentWarehouseName.value}盘库`
    });
    activeStocktake.value = stocktake;
    await downloadResource(`/inventory/stocktakes/${stocktake.id}/export`, `${stocktake.stocktake_no}_${currentWarehouseName.value}_盘库清单.xlsx`);
    const exportedStocktake = await fetchResource(`/inventory/stocktakes/${stocktake.id}`, null);
    if (!exportedStocktake) {
      throw new Error("导出后读取盘库单失败，请重新打开盘库");
    }
    await loadHistory();
    await applyLoadedStocktake(exportedStocktake, { silent: true });
    setDialogMessage(`盘库单 ${exportedStocktake.stocktake_no} 已导出，${currentWarehouseName.value} 已锁库`);
  } catch (error) {
    setDialogError(error.message || "开始盘库并导出失败");
  } finally {
    busy.value = false;
  }
}
```

Keep `exportStocktake` only if used for continuing a `LOCKED` stocktake that has not exported. If kept, make it use `currentWarehouseName`.

- [ ] **Step 8: Update import stocktake line loading to current warehouse**

In `applyLoadedStocktake`, change line fetch:

```js
const lineRows = await fetchResource(`/inventory/stocktakes/${stocktake.id}/lines?warehouse_id=${currentWarehouseId.value}`, null);
```

- [ ] **Step 9: Replace import fallback**

In `importStocktake`, replace fallback lookup with:

```js
const fallbackRow = findActiveStocktakeForWarehouse(historyRows.value, currentWarehouseId.value);
```

- [ ] **Step 10: Open diff modal immediately after import success**

In `importStocktake`, after setting `activePanel.value = "diff";`, add:

```js
diffDialogOpen.value = true;
activePanel.value = "import";
```

This keeps the flow block on the import step while the modal shows differences.

- [ ] **Step 11: Replace template overview/export/import/history sections**

Replace the current overview/export/import blocks with this two-block flow:

```vue
<section v-if="activePanel === 'export'" class="stocktake-panel stocktake-single-panel">
  <div class="stocktake-action-card stocktake-action-card-wide">
    <span class="stocktake-stage-tag">当前仓库：{{ currentWarehouseName }}</span>
    <strong>01 确认盘库并导出仓库清单</strong>
    <p>点击后系统会锁定当前仓库，并导出本次盘库 Excel 清单。盘库结束前该仓库不能出入库。</p>
    <div class="stocktake-inline-actions">
      <button class="primary-button" type="button" :disabled="busy || !currentWarehouseId" @click="startAndExportStocktake">
        {{ busy ? "处理中..." : "确认盘库并导出仓库清单" }}
      </button>
      <button v-if="activeStocktake?.status === 'LOCKED'" class="ghost-button" type="button" :disabled="busy" @click="exportStocktake">
        重新导出清单
      </button>
    </div>
  </div>
</section>

<section v-if="activePanel === 'import'" class="stocktake-panel stocktake-panel-import">
  <div class="stocktake-action-card stocktake-action-card-wide">
    <span class="stocktake-stage-tag">当前盘库单：{{ activeStocktake?.stocktake_no || "-" }}</span>
    <strong>02 导入盘点后的 Excel</strong>
    <p>只允许导入当前仓库、本次盘库单导出的清单。导入成功后会立刻弹出差异对比。</p>
    <label class="import-dropzone">
      <input ref="fileInputRef" type="file" accept=".xlsx,.xlsm" :disabled="busy" @change="importStocktake" />
      <strong>{{ busy ? "导入中..." : "选择盘点后的 Excel" }}</strong>
      <span>如果差异确认时取消，可以修改 Excel 后重新导入覆盖旧差异。</span>
    </label>
  </div>
</section>
```

- [ ] **Step 12: Move diff table into modal**

Wrap the existing diff panel content in a modal:

```vue
<div v-if="diffDialogOpen" class="stocktake-diff-modal-mask" @click.self="closeDiffDialog">
  <section class="stocktake-diff-modal">
    <header class="stocktake-diff-modal-head">
      <div>
        <p class="eyebrow">盘库差异对比</p>
        <h3>{{ activeStocktake?.stocktake_no }} · {{ currentWarehouseName }}</h3>
      </div>
      <button class="ghost-button" type="button" :disabled="busy" @click="closeDiffDialog">取消，重新导入</button>
    </header>
    <!-- keep current summary cards, toolbar, diff table here -->
    <div class="stocktake-footer">
      <button class="primary-button" type="button" :disabled="busy || !canConfirmCurrentStocktake" @click="openConfirmDialog">
        {{ busy ? "确认中..." : "确认更新库存并解锁" }}
      </button>
    </div>
  </section>
</div>
```

Add:

```js
function closeDiffDialog() {
  if (busy.value) return;
  diffDialogOpen.value = false;
}
```

- [ ] **Step 13: Filter history display to current warehouse**

In history rows template, replace:

```vue
v-for="row in historyRows"
```

with:

```vue
v-for="row in currentWarehouseHistoryRows"
```

Replace empty state condition:

```vue
v-if="!currentWarehouseHistoryRows.length"
```

- [ ] **Step 14: Update confirm success behavior**

In `confirmStocktake`, after successful confirm, replace `emit("close")` with:

```js
diffDialogOpen.value = false;
activePanel.value = "export";
activeStocktake.value = null;
previewLines.value = [];
previewSummary.value = {};
emit("changed");
```

Do not close the whole stocktake dialog automatically unless the user explicitly closes it.

- [ ] **Step 15: Run frontend checks**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/frontend
node scripts/test-stocktake-workflow.mjs
npm run build
```

Expected: workflow test passes and Vite exits code 0.

---

## Task 6: Frontend Styles for Single-Warehouse Flow and Diff Modal

**Files:**
- Modify: `frontend/src/styles/main.css`

- [ ] **Step 1: Add single warehouse flow styles**

Append near existing stocktake styles:

```css
.stocktake-single-panel {
  display: grid;
  gap: 16px;
  align-content: start;
}

.stocktake-diff-modal-mask {
  position: absolute;
  inset: 0;
  z-index: 3;
  display: grid;
  place-items: center;
  padding: 22px;
  background: rgba(15, 23, 42, 0.34);
}

.stocktake-diff-modal {
  display: grid;
  grid-template-rows: auto auto auto minmax(0, 1fr) auto;
  width: min(1320px, calc(100vw - 64px));
  height: min(820px, calc(100vh - 64px));
  min-height: 0;
  overflow: hidden;
  border: 1px solid rgba(148, 163, 184, 0.5);
  border-radius: 24px;
  background: rgba(248, 250, 252, 0.98);
  box-shadow: 0 28px 80px rgba(15, 23, 42, 0.3);
}

.stocktake-diff-modal-head {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 16px;
  padding: 18px 22px;
  border-bottom: 1px solid rgba(148, 163, 184, 0.35);
}

.stocktake-diff-modal .stocktake-summary-grid,
.stocktake-diff-modal .stocktake-empty-state,
.stocktake-diff-modal .stocktake-diff-toolbar {
  margin: 14px 18px 0;
}

.stocktake-diff-modal .stocktake-diff-table-v2 {
  margin: 14px 18px;
  min-height: 0;
}

.stocktake-diff-modal .stocktake-footer {
  padding: 14px 18px 18px;
  border-top: 1px solid rgba(148, 163, 184, 0.35);
}
```

- [ ] **Step 2: Remove or neutralize obsolete overview card styles only if no longer used**

If `.stocktake-overview-card` styles remain unused, leave them in place for now to avoid broad CSS churn. Do not delete large CSS blocks in this task.

- [ ] **Step 3: Run frontend build**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/frontend
npm run build
```

Expected: Vite exits code 0.

---

## Task 7: End-to-End Backend and Frontend Verification

**Files:**
- Verify only.

- [ ] **Step 1: Run backend stocktake tests**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/backend
.venv/bin/python -m unittest tests.test_stocktake_locking tests.test_stocktake_excel_diff_confirm
```

Expected: pass with `OK`.

- [ ] **Step 2: Run backend compile check**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/backend
.venv/bin/python -m compileall app
```

Expected: exit code 0.

- [ ] **Step 3: Run frontend workflow self-test**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/frontend
node scripts/test-stocktake-workflow.mjs
```

Expected output:

```text
stocktake workflow tests passed
```

- [ ] **Step 4: Run frontend build**

Run:

```bash
cd /Users/souplearn/Gitlab/py/ForgeFlow-ERP/frontend
npm run build
```

Expected: Vite exits code 0. Existing chunk warning is acceptable.

- [ ] **Step 5: Manual browser smoke test**

Use the running ERP UI and verify:

```text
1. Select 原材料库 in 百华仓库 warehouse bar.
2. Click 盘库.
3. Dialog shows 当前仓库：原材料库 and no multi-warehouse checkbox cards.
4. Click 确认盘库并导出仓库清单.
5. Exported Excel has one sheet and includes 盘库单号、盘库校验码、仓库ID.
6. Warehouse is locked and stocktake dialog reopens to 导入清单 for the same warehouse.
7. Import the same Excel. Diff modal appears immediately.
8. Click 取消，重新导入. Modal closes, warehouse remains locked, import control remains available.
9. Modify counted weight and import again. New diff replaces old diff.
10. Try importing an Excel from a different stocktake number. System rejects it.
11. Try importing an Excel with wrong warehouse marker. System rejects it.
12. Click 确认更新库存并解锁. Stock is reset to imported workbook values, stocktake is completed, warehouse unlocks.
13. Select another warehouse and click 盘库. Records shown are only for that selected warehouse.
```

---

## Self-Review

- Spec coverage: covers all six user rules: warehouse-bar selected warehouse determines stocktake, flow has confirm/export first step, user can edit sheet offline, reopening same warehouse resumes import step, import opens diff modal with confirm/cancel, and workbook validation rejects wrong stocktake/warehouse files.
- Placeholder scan: no `TBD`, `TODO`, or unspecified edge handling remains.
- Type consistency: backend token format is consistently `"{stocktake_no}|{warehouse_id}|{warehouse_type}"`; frontend current warehouse ID is consistently `currentWarehouseId`.
- Scope risk: existing `wh_stocktake` can technically contain historical multi-warehouse rows from older tests/data. New service rejects new multi-warehouse stocktakes; old records can remain visible in history unless filtered by `warehouse_id`.
- Verification: final plan includes backend unit tests, backend compile, frontend workflow script, frontend build, and browser smoke test.