# Sample Freight Menu 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:** 复用 `biz_sample_freight` 与现有 CRUD/API；扩展列表 `includeItems` 与筛选；新增样本 options 接口；前端标准列表 + `el-table` `span-method` 渲染批次 rowspan。前端固定菜单模式须同步 `sqxp.ts` 与 `backend/app/api/menu.py`。

**Tech Stack:** FastAPI、SQLAlchemy、Vue 3、Element Plus、MySQL 菜单 SQL。

**Spec:** `docs/superpowers/specs/2026-10-08-sample-freight-menu-design.md`  
**Demo:** `docs/demos/2026-10-08-sample-freight-menu-demo.html`

---

## File map

| 文件 | 职责 |
|------|------|
| `docs/sql/migrations/2026-10-08-sample-freight-menu.sql` | sys_menu + 角色授权（DB 菜单模式） |
| `backend/app/api/menu.py` | 前端菜单树插入运费信息 |
| `web-admin/src/router/modules/sqxp.ts` | 前端路由 |
| `backend/app/crud/sample_freight.py` | list 增强、items enrichment、sample_options |
| `backend/app/api/sample_freight.py` | 查询参数 + sample-options 路由 |
| `backend/tests/test_sample_freight.py` | list filters / span helper 单测 |
| `web-admin/src/api/sample-freight.ts` | 客户端类型与 API |
| `web-admin/src/views/cell-storage/sample-freight/index.vue` | 列表页 |
| `web-admin/src/views/cell-storage/sample-freight/FreightConfigDialog.vue` | 配置运费弹窗 |
| `web-admin/src/views/cell-storage/sample-freight/FreightEditDialog.vue` | 编辑方式/金额 |
| `web-admin/src/App.vue` | 标题竖条规则（若需显式注册「运费信息」） |

---

### Task 1: 菜单 SQL + 前后端路由骨架

**Files:**
- Create: `docs/sql/migrations/2026-10-08-sample-freight-menu.sql`
- Modify: `backend/app/api/menu.py`（`CellStorageSampleInfo` 节点后插入）
- Modify: `web-admin/src/router/modules/sqxp.ts`（同上）
- Create: `web-admin/src/views/cell-storage/sample-freight/index.vue`（空壳列表）

- [ ] **Step 1: 写菜单迁移 SQL**

菜单 id 使用：`50000000000000000000000000000021`  
parent：`CEL00000000000000000000000000001`  
perms：`cell-storage:sample-freight:list`  
path：`sample-freight`  
component：`/cell-storage/sample-freight/index`  
order_num：取样本信息菜单 `50000000000000000000000000000013` 的 `order_num + 1`（或固定写在样本信息之后的数值，实现时查库确认；幂等 INSERT）。

授权：已有 `cell-storage:sample-info:list`（menu id `50000000000000000000000000000013`）的角色补 `sys_role_menu`（对照 `2026-10-05-presign-order-menu.sql`）。

- [ ] **Step 2: `menu.py` 在 SampleInfo 后插入**

```python
{
    "id": "50000000000000000000000000000021",
    "name": "CellStorageSampleFreight",
    "path": "sample-freight",
    "component": "/cell-storage/sample-freight/index",
    "meta": {
        "title": "运费信息",
        "keepAlive": True,
        "menuCode": "cell-storage:sample-freight:list",
    },
},
```

- [ ] **Step 3: `sqxp.ts` 同步插入同结构路由**（`CellStorageSampleInfo` 与 `CellStoragePaymentConfirm` 之间）

- [ ] **Step 4: 空壳页面**

```vue
<template>
  <div class="page-container">
    <section class="panel">
      <div class="panel-top">
        <h2 class="title-bar-heading">运费信息</h2>
      </div>
      <div class="filter-block"><!-- Task 5 填充 --></div>
      <div class="list-toolbar"><!-- Task 5 --></div>
      <div class="list-body list-wrap">
        <el-empty description="运费列表加载中…" />
      </div>
    </section>
  </div>
</template>

<script setup lang="ts">
  defineOptions({ name: 'CellStorageSampleFreight' })
</script>
```

- [ ] **Step 5: Commit**

```bash
git add docs/sql/migrations/2026-10-08-sample-freight-menu.sql \
  backend/app/api/menu.py \
  web-admin/src/router/modules/sqxp.ts \
  web-admin/src/views/cell-storage/sample-freight/index.vue
git commit -m "feat: add sample freight menu route and page shell"
```

---

### Task 2: 后端 list 增强（includeItems + 筛选）— TDD

**Files:**
- Modify: `backend/app/crud/sample_freight.py`
- Modify: `backend/app/api/sample_freight.py`
- Modify: `backend/tests/test_sample_freight.py`

- [ ] **Step 1: 写失败测试 — enrich item 字段形状与 filter helper**

在 `test_sample_freight.py` 追加：

```python
class TestFreightListHelpers(unittest.TestCase):
    def test_item_dict_has_enrichment_keys(self):
        from app.crud.sample_freight import _item_to_dict_enriched

        class I:
            id = "i1"
            freight_id = "f1"
            sample_source = "cell_storage"
            sample_id = "s1"
            sample_code = "CODE1"
            protocol_id = "p1"

        d = _item_to_dict_enriched(
            I(),
            protocol_no="CP001",
            sample_type_name="脐带血",
        )
        self.assertEqual(d["protocolNo"], "CP001")
        self.assertEqual(d["sampleTypeName"], "脐带血")
        self.assertEqual(d["sampleSource"], "cell_storage")
```

- [ ] **Step 2: 跑测确认 FAIL**

```bash
cd backend && source venv/bin/activate && PYTHONPATH=. pytest tests/test_sample_freight.py::TestFreightListHelpers -v
```

Expected: FAIL（`_item_to_dict_enriched` 不存在）

- [ ] **Step 3: 实现 enrichment + 扩展 `list_freights`**

签名改为：

```python
def list_freights(
    db,
    *,
    tenant_no: str,
    page: int = 1,
    page_size: int = 10,
    keyword: Optional[str] = None,
    transport_mode: Optional[str] = None,
    sample_source: Optional[str] = None,  # cell_storage | research_donation
    create_time_from: Optional[str] = None,  # YYYY-MM-DD or datetime
    create_time_to: Optional[str] = None,
    include_items: bool = False,
) -> Tuple[List[Dict[str, Any]], int]:
```

行为要点：

1. `transport_mode` 精确匹配 `BizSampleFreight.transport_mode`（若传）。
2. `sample_source`：仅保留「存在该 source 的 active item」的 freight（`exists` 子查询）。
3. `keyword`：扩展为 OR — 运输方式 value/label、item.sample_code、协议单号（细胞存储 `BizCollectionProtocol.protocol_no`、科研捐赠对应单号字段，查 `research_donation` model 确认字段名，常见 `donation_no` / `protocol_no`）。
4. 时间范围过滤 `create_time`。
5. `include_items=True`：对本页 freight_ids 批量查 items，批量解析 protocolNo / sampleTypeName，写入每条 `items`。

`_item_to_dict_enriched` 在 `_item_to_dict` 基础上增加 `protocolNo`、`sampleTypeName`。

- [ ] **Step 4: API 层透传参数**

`GET /sample-freights` 增加 Query：

- `includeItems: bool = False`
- `transportMode: Optional[str]`
- `sampleSource: Optional[str]`
- `createTimeFrom` / `createTimeTo`

注意：`/sample-freights/sample-options` 须注册在 `/{freight_id}` **之前**，避免路径被当成 id。

- [ ] **Step 5: 跑测 PASS + Commit**

```bash
cd backend && PYTHONPATH=. pytest tests/test_sample_freight.py -v
git add backend/app/crud/sample_freight.py backend/app/api/sample_freight.py backend/tests/test_sample_freight.py
git commit -m "feat(backend): enrich sample freight list with items and filters"
```

---

### Task 3: 样本 options API

**Files:**
- Modify: `backend/app/crud/sample_freight.py`（`list_sample_options`）
- Modify: `backend/app/api/sample_freight.py`
- Modify: `backend/tests/test_sample_freight.py`（可选：纯函数规范化）

- [ ] **Step 1: 实现 `list_sample_options`**

```python
def list_sample_options(
    db,
    *,
    tenant_no: str,
    page: int = 1,
    page_size: int = 20,
    keyword: Optional[str] = None,
    sample_source: Optional[str] = None,  # None = both
) -> Tuple[List[Dict[str, Any]], int]:
    """
    返回:
    {
      sampleSource, sampleId, sampleCode, protocolId, protocolNo,
      sampleTypeName, freightId  # 若已挂运费则带上，供前端提示覆盖
    }
    """
```

实现策略（最小可用）：

- 若 `sample_source in (None, cell_storage)`：查 `BizProtocolSample` join 协议主表（`del_flag=0`），关键字匹配 sample_code / protocol_no。
- 若 `sample_source in (None, research_donation)`：查捐赠样本 join 捐赠主表。
- 合并结果按 `create_time DESC` 内存分页**可接受首版**；若数据量大改为 UNION SQL。
- 左连 `biz_sample_freight_item` 取当前 `freightId`。

- [ ] **Step 2: 路由**

```python
@router.get("/sample-freights/sample-options")
async def list_sample_freight_options(...):
    ...
```

放在 `/{freight_id}` 路由之前。

- [ ] **Step 3: Commit**

```bash
git add backend/app/crud/sample_freight.py backend/app/api/sample_freight.py
git commit -m "feat(backend): add sample options for freight config dialog"
```

---

### Task 4: 前端 API 扩展

**Files:**
- Modify: `web-admin/src/api/sample-freight.ts`

- [ ] **Step 1: 扩展类型与方法**

```typescript
export type SampleFreightItem = {
  sampleSource: 'cell_storage' | 'research_donation'
  sampleId: string
  protocolId?: string
  sampleCode?: string
  protocolNo?: string
  sampleTypeName?: string
}

export function fetchSampleFreightList(params?: {
  page?: number
  pageSize?: number
  keyword?: string
  transportMode?: string
  sampleSource?: string
  createTimeFrom?: string
  createTimeTo?: string
  includeItems?: boolean
}) { ... }

export function fetchSampleFreightSampleOptions(params?: {
  page?: number
  pageSize?: number
  keyword?: string
  sampleSource?: string
}) {
  return request.get<PageList<SampleFreightItem & { freightId?: string }>>({
    url: '/web/admin/sample-freights/sample-options',
    params
  })
}
```

- [ ] **Step 2: Commit**

```bash
git add web-admin/src/api/sample-freight.ts
git commit -m "feat(web-admin): extend sample-freight API client for menu page"
```

---

### Task 5: 列表页（筛选 + 合并单元格表格）

**Files:**
- Modify: `web-admin/src/views/cell-storage/sample-freight/index.vue`
- Reference: `docs/demos/2026-10-08-sample-freight-menu-demo.html`、`web-admin/src/views/system/unit/index.vue`

- [ ] **Step 1: 扁平行模型 + span-method**

```typescript
type FlatRow = {
  freightId: string
  rowspan: number // 该批次第一行 = items.length || 1；其余 0
  isFirst: boolean
  transportMode: string
  transportModeLabel: string
  freightAmount: number
  linkedSampleCount: number
  createTime: string
  sampleSource?: string
  protocolNo?: string
  sampleCode?: string
  sampleTypeName?: string
  sampleId?: string
  protocolId?: string
}

function flattenFreights(list: SampleFreight[]): FlatRow[] {
  const rows: FlatRow[] = []
  for (const f of list) {
    const items = f.items?.length ? f.items : [null]
    items.forEach((it, idx) => {
      rows.push({
        freightId: f.id,
        rowspan: idx === 0 ? items.length : 0,
        isFirst: idx === 0,
        transportMode: f.transportMode,
        transportModeLabel: f.transportModeLabel || f.transportMode,
        freightAmount: f.freightAmount,
        linkedSampleCount: f.linkedSampleCount ?? (f.items?.length || 0),
        createTime: f.createTime || '',
        sampleSource: it?.sampleSource,
        protocolNo: it?.protocolNo,
        sampleCode: it?.sampleCode,
        sampleTypeName: it?.sampleTypeName,
        sampleId: it?.sampleId,
        protocolId: it?.protocolId
      })
    })
  }
  return rows
}

function spanMethod({ column, row }: any) {
  const mergeProps = [
    'selection',
    'transportMode',
    'freightAmount',
    'linkedSampleCount',
    'createTime',
    'actions'
  ]
  if (!mergeProps.includes(column.property) && column.type !== 'selection') {
    return { rowspan: 1, colspan: 1 }
  }
  if (column.type === 'selection' || mergeProps.includes(column.property)) {
    if (row.rowspan > 0) return { rowspan: row.rowspan, colspan: 1 }
    return { rowspan: 0, colspan: 0 }
  }
  return { rowspan: 1, colspan: 1 }
}
```

注意：为 selection 列设置 `property` 或在 `span-method` 用 `columnIndex` 判断（实现时以 Element Plus 实际 column 对象为准，对照 Demo）。

- [ ] **Step 2: 筛选区 + 加载**

调用 `fetchSampleFreightList({ includeItems: true, page, pageSize, ...filters })`，字典运输方式用 `fetchDictDataOptions('sample_transport_mode')`。

- [ ] **Step 3: 工具栏**

已选 N 项（按 `freightId` 去重）→ 配置运费 / 取消关联 / 编辑运费；仅第一个主按钮 `type="primary"`；均带 icon。

- [ ] **Step 4: 表格列**

运输方式 Tag、运费金额、关联数、来源 Tag、协议单号、样本编码、样本类型、创建时间、操作（编辑 / 取消关联）。操作列 `fixed="right"` `min-width=260`。

- [ ] **Step 5: Commit**

```bash
git add web-admin/src/views/cell-storage/sample-freight/index.vue
git commit -m "feat(web-admin): render sample freight list with rowspan cells"
```

---

### Task 6: 配置 / 编辑 / 取消关联弹窗

**Files:**
- Create: `web-admin/src/views/cell-storage/sample-freight/FreightConfigDialog.vue`
- Create: `web-admin/src/views/cell-storage/sample-freight/FreightEditDialog.vue`
- Modify: `web-admin/src/views/cell-storage/sample-freight/index.vue`

- [ ] **Step 1: FreightConfigDialog**

- `dialog-form-layout`、`label-position="top"`、`modal-class="protocol-dialog-mask"`
- Tabs：新建 | 关联已有
- 新建：运输方式 select `filterable` `allow-create`；金额 `AmountInput`；样本多选（远程 `fetchSampleFreightSampleOptions`，来源筛选）
- 关联已有：`fetchSampleFreightList` 单选 + 样本多选
- 确定：create 或 link；若样本已有 `freightId` 且不同，确认「将替换原运费关联」

- [ ] **Step 2: FreightEditDialog**

运输方式 + 金额 → `fetchUpdateSampleFreight`；提示同步 N 个样本。

- [ ] **Step 3: 取消关联**

- 工具栏：对每个选中 freightId `fetchSampleFreightDetail` 取 items 全量 unlink（或后端扩展 unlink-all；首版前端传全部 items）
- 行内：弹窗勾选该批次 items 再 unlink

- [ ] **Step 4: Commit**

```bash
git add web-admin/src/views/cell-storage/sample-freight/
git commit -m "feat(web-admin): add freight configure/edit/unlink dialogs on menu page"
```

---

### Task 7: 标题竖条 + 收尾验证

**Files:**
- Modify: `web-admin/src/App.vue`（若「运费信息」未自动命中竖条，在 `panelTitleIconByText` / 等价规则中增加精确匹配「运费信息」）
- graphify

- [ ] **Step 1: 注册面板标题**「运费信息」以显示主色竖条（对照现有「样本信息管理」写法）

- [ ] **Step 2: 跑后端测试**

```bash
cd backend && PYTHONPATH=. pytest tests/test_sample_freight.py -v
```

Expected: PASS

- [ ] **Step 3: 手测清单**

1. 前端模式侧栏出现「运费信息」在样本信息管理下  
2. 执行菜单 SQL（测试库）后 DB 模式亦可见（可选）  
3. 列表合并单元格；混源样本展示  
4. 配置/关联/取消/编辑与协议单数据一致  
5. 合同金额不受影响  

- [ ] **Step 4: 更新图谱**

```bash
./scripts/update-graph.sh all
```

- [ ] **Step 5: Commit**

```bash
git add web-admin/src/App.vue backend/graphify-out web-admin/graphify-out
git commit -m "chore: register freight panel title and refresh graphify"
```

---

## Spec coverage

| Spec | Task |
|------|------|
| 菜单位置 / 路由 / 权限 | 1, 7 |
| 合并单元格列表 | 5 |
| 筛选（方式/来源/关键字/时间） | 2, 5 |
| includeItems + protocolNo/typeName | 2 |
| 配置新建/关联 + 混选样本 | 3, 6 |
| 取消关联 / 编辑 | 6 |
| 协议单入口保留 | 无改协议单（验收手测） |
| Demo 视觉对齐 | 5（对照 HTML） |

## Self-review notes

- 无 TBD；科研捐赠协议单号字段名实现时在 model 中确认后写入 `list_freights` keyword 查询。
- `sample-options` 路由顺序：必须在 `/{freight_id}` 之前。
- 前端固定菜单：`menu.py` + `sqxp.ts` 双写，不可只改 SQL。