# SME-OmniStore P0 阻塞项修复报告（2026-05-09）

> 本报告替代上一份 `FINAL_DELIVERY_REPORT_20260509.md` 中“P0 完成”的结论。上一版仅作为阶段性交付；本轮针对复查指出的 4 个 P0 阻塞项进行修复和验证。

## 修复范围

### 1. 交易链路输入校验

已修复：
- `CartItemIn.product_id >= 1`
- `CartItemIn.variant_id >= 1`（可空）
- `CartItemIn.qty >= 1`
- `CreateOrderIn.points_to_use >= 0`
- `PreviewIn.points_to_use >= 0`
- service 层 `PricingCartItem.__post_init__()` 再次保护：无效 product / SKU / qty 直接 400。
- `inventory.validate_stock()` / `deduct_stock()` / `restore_stock()` 对数量做 service 层保护。

涉及文件：
- `backend/app/api/routers/store/orders.py`
- `backend/app/core/services/pricing.py`
- `backend/app/core/services/inventory.py`
- `backend/tests/test_order_pricing_inventory_safety.py`

### 2. SKU / 商品错配漏洞

已修复：所有 SKU 查询改为 product-scoped：

- pricing：`ProductVariant.id == item.variant_id AND ProductVariant.product_id == item.product_id`
- inventory validate：同上
- inventory deduct：同上，且 `with_for_update()` 锁定的是匹配 product 的 SKU
- inventory restore：按 `{product_id, variant_id}` 成对恢复，避免错配恢复库存

涉及文件：
- `backend/app/core/services/pricing.py`
- `backend/app/core/services/inventory.py`

### 3. Alembic 迁移可信度修复

已修复：
- `001_init_all_tables.py` 补齐 fresh install 所需结构：
  - `brands` 表
  - `products.brand_id / market_price / member_price / low_stock_threshold / allow_oversell / cover_url`
  - `product_variants.barcode / reserved_qty / image_url / weight / sort_order`
  - `categories.seo_keywords / image_url / is_nav_visible / attribute_template`
- 新增 `005_catalog_schema_alignment.py`，用于已有数据库的增量对齐。
- 修复 revision 链：`003 -> 004_add_member_tables -> 005_catalog_schema_alignment`。
- 将远程 DB Alembic 版本升级到 head：`005_catalog_schema_alignment`。

涉及文件：
- `backend/migrations/versions/001_init_all_tables.py`
- `backend/migrations/versions/003_add_smtp_settings.py`
- `backend/migrations/versions/004_add_member_tables.py`
- `backend/migrations/versions/005_catalog_schema_alignment.py`
- `backend/tests/test_migration_catalog_alignment.py`

### 4. 后台商品维护补齐

已修复：
- 商品表单支持品牌选择。
- 商品表单支持市场价、会员价、成本价。
- 商品表单支持允许超卖、低库存预警。
- 商品表单支持多规格 SKU：SKU 编码、条码、价格调整、库存、锁定库存、颜色、尺码、图片、启用状态。
- 商品列表展示品牌、市场价、会员价。
- 后端商品 API create/update/get/list 对齐上述字段，并支持 variants 保存与返回。

涉及文件：
- `backend/app/schemas/product.py`
- `backend/app/api/routers/products.py`
- `frontend/admin/src/api/index.js`
- `frontend/admin/src/views/products/ProductForm.vue`
- `frontend/admin/src/views/products/ProductList.vue`

## 验证结果

### 后端编译与测试

```bash
cd /home/ji/sme-omnistore/backend
PYTHONPYCACHEPREFIX=/tmp/omnistore-pycache ./venv/bin/python -m compileall -q app migrations tests
./venv/bin/python -m pytest tests -q
```

结果：`17 passed, 1 warning in 0.67s`

新增测试覆盖：
- 负数/零数量 API 边界校验
- 负数积分 API 边界校验
- service 层 `PricingCartItem` 非法输入保护
- SKU 查询必须绑定 product_id 的源码断言
- ProductCreate 支持品牌、价格、多 SKU payload
- 迁移文件包含品牌/价格/SKU/分类扩展字段

### Alembic

```bash
cd /home/ji/sme-omnistore/backend
./venv/bin/alembic upgrade head
./venv/bin/alembic current
```

结果：`005_catalog_schema_alignment (head)`

数据库结构抽查：
- `brands` 表存在
- `products` 存在 `brand_id / market_price / member_price / allow_oversell / low_stock_threshold`
- `product_variants` 存在 `barcode / image_url / reserved_qty / sort_order / weight`

### 前端构建

```bash
cd /home/ji/sme-omnistore/frontend/admin && npm run build
```

结果：Vite build 成功。

```bash
cd /home/ji/sme-omnistore/frontend/store && npm run build
```

结果：Nuxt production build 成功。

### P0 行为验证

远程接口验证结果：
- 后台商品创建：品牌、市场价、多 SKU 创建成功。
- `qty=-1` 订单 preview：422。
- `points_to_use=-1` 订单 preview：422。
- SKU / 商品错配 preview：404，拒绝使用不属于该商品的 SKU。
- 正确商品 + 正确 SKU preview：200。

## 当前状态

- 本地最终目录：`/home/node/.openclaw/agents/thinking-bendan/workspace/sme-omnistore-final/`
- 远程运行目录：`/home/ji/sme-omnistore/`
- 后端 API：`http://192.168.50.139:8000`
- 管理后台：`http://192.168.50.139:3001`
- 商城前台：`http://192.168.50.139:3002`

## 仍需注意

- Windows 本机 `esbuild spawn EPERM` 和 `.bin` 缺失更像本机依赖安装/跨系统 node_modules 问题。交付包不应携带 Linux node_modules；建议在 Windows 端删除 `node_modules` 后使用对应包管理器重新安装依赖再构建。