# 交付平台前端 UI 需求规格说明（走查稿）

> 依据 `web/delivery-platform-ui` 源码整理，供 Figma Make / 设计迭代与产品跟进维护。  
> 侧栏实现见 `src/layout/MainLayout.vue`；路由与角色见 `src/router/index.js`。

---

## 1. 全局壳层（需登录页共用）

| 区域 | 内容 |
|------|------|
| 侧栏品牌 | 文案：`创飞 · 交付平台` |
| 侧栏菜单 | 见 §2（按角色 `v-if` 显示） |
| 顶栏右侧 | 当前用户展示名（`displayName`）、链接按钮「退出」 |
| 主内容区 | 路由出口，背景为控制台风格浅灰 |

### 1.1 角色与菜单可见性

与路由 `meta.roles` 一致：

- **SYS_ADMIN**：可见下文全部侧栏项（无单独剔除）。
- **DEVELOPER**：客户管理、项目管理、合同管理、交付管理、许可 SN、集成环境、产品线；**无** Callback 收件箱。
- **OPS**：Callback 收件箱、集成环境、产品线；**无** 客户 / 项目 / 合同 / 交付 / 许可 SN。

### 1.2 信息架构说明

当前侧栏为 **单层 `el-menu`**，无折叠分组、无物理「二级子菜单」。本文 **一级 = 产品模块**，**二级 = 侧栏入口 + 由其进入的子页面**（详情、向导、弹窗表单）。

---

## 2. 按模块：菜单项 → 页面 → 数据与操作

### 2.1 首页

| 项 | 说明 |
|----|------|
| 路由 | `/`，`HomeView.vue` |
| 侧栏 | 「首页」 |
| 内容 | 信息 Alert（I7：按角色展示入口；Callback 仅 OPS / SYS_ADMIN）；当前用户与角色；**与侧栏一致的模块快捷链接**（随角色过滤） |
| 附加 | 「调试」：`GET /api/v1/ping` 按钮 + JSON 文本结果区 |

---

### 2.2 客户管理

| 项 | 说明 |
|----|------|
| 路由 | `/customers`，`CustomersView.vue` |
| 侧栏 | 「客户管理」 |
| 列表筛选 | 关键词（名称或统一社会信用代码）、「查询」 |
| 表格列 | 客户名称、统一社会信用代码 |
| 行操作 | 编辑、删除（确认框） |
| 工具栏 | 「新建客户」 |
| 分页 | 10 / 20 / 50；total、sizes、prev、pager、next、jumper |

#### 无独立菜单：新建 / 编辑客户（`el-dialog`，宽约 480px）

| 字段 | 校验 / 约束 | API 语义 |
|------|----------------|----------|
| 客户名称 | 必填，`maxlength=200`，字数统计 | `POST` / `PUT` body |
| 统一社会信用代码 | 选填，`maxlength=32` | 空则不发该字段 |
| 底部 | 取消、保存（loading） | `createCustomer` / `updateCustomer` |

---

### 2.3 项目管理

| 项 | 说明 |
|----|------|
| 路由 | `/projects`，`ProjectsView.vue` |
| 侧栏 | 「项目管理」 |
| 列表筛选 | 客户下拉（可清空、可搜索）、「查询」 |
| 表格列 | 客户（名）、项目名称、阶段（字典中文） |
| 行操作 | 编辑、删除（确认框） |
| 工具栏 | 「新建项目」 |
| 分页 | 同客户管理 |

#### 无独立菜单：新建 / 编辑项目（`el-dialog`，宽约 520px）

| 字段 | 校验 / 约束 | 说明 |
|------|----------------|------|
| 客户 | 必填 | 选项来自客户列表（最多 500 条） |
| 项目名称 | 必填，`maxlength=200` | |
| 阶段 | 必填 | `GET /api/v1/dictionaries/PROJECT_PHASE`，前端兼容多种响应包裹形态 |

---

### 2.4 合同管理

| 项 | 说明 |
|----|------|
| 列表路由 | `/contracts`，`ContractsView.vue` |
| 侧栏 | 「合同管理」 |
| 列表筛选 | 关键词（合同标题）、「查询」 |
| 表格列 | 合同标题/编号、客户、项目、状态（Tag）、创建时间 |
| 行操作 | 「详情」→ `/contracts/:id` |
| 工具栏 | 「新建合同」→ `/contracts/new` |

#### 无菜单：新建合同向导（`/contracts/new`，`ContractWizardView.vue`）

三步 `el-steps`：

**步骤 0 — 客户与项目**

- 客户必选；项目必选；项目下拉随所选客户过滤；更换客户时清空项目。

**步骤 1 — 合同基本信息**

- 合同标题/编号：必填，`maxlength=256`，字数统计。
- 备注：选填，`textarea`，`maxlength=4000`。

**步骤 2 — 明细行**

- 表内编辑：标的/行项名称（`itemName`）每行必填，`maxlength=256`。
- 数量：`el-input-number`，`precision=4`，`min=0.0001`，须大于 0。
- 单位：选填，`maxlength=32`。
- 至少保留一行；「添加明细」；「删除」（仅一行时删除禁用）。

**提交**：先 `createContract`，再对每行 `addLine`；成功跳转合同详情。

#### 无菜单：合同详情（`/contracts/:id`，`ContractDetailView.vue`）

| 区块 | 行为 |
|------|------|
| 头部 | ← 合同列表；标题「合同详情」；状态 Tag；**草稿** 显示「保存」 |
| 描述区 | 标题/备注：草稿可编辑；客户/项目只读（优先接口 name，否则 ID 映射） |
| 状态操作条 | 依状态显示按钮（均需确认）：草稿→提交待生效；待生效→确认生效；生效→发起变更 / 终止合同；变更中→完成变更 |
| 合同明细 | 草稿可「添加明细」、行内编辑/删除；非草稿只读 |
| 明细弹窗 | 添加/编辑：行项名称必填；数量必填；单位选填 |
| 最近审计 | 列：时间、操作者、动作、摘要（`listAuditEvents` 归一化展示） |

**合同状态枚举（Tag）**

| 值 | 中文 |
|----|------|
| DRAFT | 草稿 |
| PENDING_EFFECTIVE | 待生效 |
| EFFECTIVE | 生效 |
| CHANGING | 变更中 |
| TERMINATED | 已终止 |

---

### 2.5 交付管理

| 项 | 说明 |
|----|------|
| 列表路由 | `/deliveries`，`DeliveriesView.vue` |
| 侧栏 | 「交付管理」 |
| 列表筛选 | 项目下拉、批次编码关键词、「查询」 |
| 表格列 | 批次编码、项目、合同 ID、状态 Tag、计划交付日、创建时间 |
| 行操作 | 「详情」→ `/deliveries/:id` |
| 工具栏 | 「新建交付批次」→ `/deliveries/new` |

#### 无菜单：新建交付批次（`/deliveries/new`，`DeliveryBatchWizardView.vue`）

| 字段 | 校验 | 说明 |
|------|------|------|
| 项目 | 必填 | 可搜索 |
| 合同 | 选填 | 依赖项目；按 `projectId` 过滤合同 |
| 批次编码 | 必填，`maxlength=64` | |
| 计划交付日 | 选填 | 日期，`YYYY-MM-DD` |
| 备注 | 选填，`maxlength=4000` | |
| 底部 | 「创建并返回列表」/「创建并进入详情」 | |

#### 无菜单：交付批次详情（`/deliveries/:id`，`DeliveryBatchDetailView.vue`）

| 区块 | 行为 |
|------|------|
| 头部 | ← 交付列表；状态 Tag；**PENDING** 时：「保存抬头」「标记已交付」（确认） |
| 抬头 | 批次编码 / 项目 / 合同 ID / 完成时间只读；**PENDING** 可编辑计划交付日、备注 |
| 交付明细 | **PENDING** 可增删改；列：排序、说明、数量、合同行 ID |
| 明细弹窗 | 排序 number 0–999999；说明必填，`maxlength=512`；数量必填；合同行 ID 选填 |

**交付状态枚举**

| 值 | 中文 |
|----|------|
| PENDING | 待交付 |
| DELIVERED | 已交付 |
| CANCELLED | 已取消 |

---

### 2.6 许可 SN

| 项 | 说明 |
|----|------|
| 列表路由 | `/licenses/sn`，`LicenseSnListView.vue` |
| 侧栏 | 「许可 SN」 |
| 列表筛选 | 项目、SN 关键词、「查询」 |
| 表格列 | SN 编码、项目、合同行 ID、状态 Tag、创建时间 |
| 行操作 | 「详情」→ `/licenses/sn/:id` |
| 工具栏 | 「新建许可 SN」→ `/licenses/sn/new` |

#### 无菜单：新建许可 SN（`/licenses/sn/new`，`LicenseSnWizardView.vue`）

| 字段 | 校验 | 说明 |
|------|------|------|
| SN 编码 | 必填，`maxlength=128` | |
| 项目 | 选填 | 可搜索 |
| 合同行 ID | 选填，number ≥1 | MVP 手工录入提示 |
| 激活备注 | 选填，`textarea`，`maxlength=512` | |
| 底部 | 创建并返回列表 / 创建并进入详情 | |

#### 无菜单：许可 SN 详情（`/licenses/sn/:id`，`LicenseSnDetailView.vue`）

| 区块 | 内容 |
|------|------|
| 基础 | SN 编码、创建时间 |
| 绑定与备注 | 表单：项目、合同行 ID、激活备注；「保存绑定」 |
| 状态 | 下拉：REGISTERED / ISSUED / ACTIVATED / SUSPENDED / REVOKED（含中英文标签）；「更新状态」 |

**许可 SN 状态枚举**

| 值 | 中文 |
|----|------|
| REGISTERED | 已登记 |
| ISSUED | 已发放 |
| ACTIVATED | 已激活 |
| SUSPENDED | 已暂停 |
| REVOKED | 已吊销 |

---

### 2.7 Callback 收件箱（SYS_ADMIN、OPS）

| 项 | 说明 |
|----|------|
| 列表路由 | `/callbacks`，`CallbackInboxView.vue` |
| 侧栏 | 「Callback 收件箱」 |
| 列表筛选 | 状态（PENDING / PROCESSED / FAILED / IGNORED）、事件类型、SN、项目 ID（文本）、「查询」 |
| 表格列 | 来源、外部消息 ID、事件类型、SN、状态 Tag、收件时间 |
| 行操作 | 「详情」→ `/callbacks/:id` |

> **扩展说明**：`listCallbackInbox` API 另支持 `productLineId`、`environmentId`、`from`、`to` 等；当前 UI 未暴露，可在后续版本增加筛选。

#### 无菜单：Callback 详情（`/callbacks/:id`，`CallbackInboxDetailView.vue`）

| 区块 | 规格 |
|------|------|
| 主信息 | ID、来源系统、外部消息 ID、事件类型、Schema 版本、幂等键、Webhook 收据 ID、SN、项目/合同/许可 SN/产品线/环境 ID、收件/处理时间、失败原因、备注 |
| Payload | 标题「Payload（脱敏预览）」；深色只读代码块，`pre`，约 `max-height: 420px` 可滚动 |
| I9 Webhook 出库状态 | **仅当**存在 `webhookReceiptId`：加载骨架 / 错误或描述列表：出库状态、尝试次数、上次错误、下次重试、出库更新时间 |
| I8 重新入队 | **同上条件**：配置说明（`LICENSE_WEBHOOK_BASE_URL`、`LICENSE_WEBHOOK_OPS_TOKEN`）；按钮「重新入队出库（DEAD→待投递）」+ 确认 |
| 状态处置 | **仅 PENDING**：标已处理 / 标失败 / 忽略（均确认） |
| 人工挂接 | 许可 SN ID、项目 ID、合同 ID（文本输入）；「保存挂接」需至少填一项 |

**Callback 状态枚举**

| 值 | 中文 |
|----|------|
| PENDING | 待处理 |
| PROCESSED | 已处理 |
| FAILED | 失败 |
| IGNORED | 忽略 |

---

### 2.8 集成环境

| 项 | 说明 |
|----|------|
| 路由 | `/integration/environments`，`IntegrationEnvironmentsView.vue` |
| 侧栏 | 「集成环境」 |
| 页面 | 只读表 + 「刷新」 |
| 列 | 编码、名称、类型、比特 URL（`bitanswerBaseUrl` 等兼容字段）、产品线 ID |
| 分页 | 默认 `pageSize=20`，可选 10/20/50 |

---

### 2.9 产品线

| 项 | 说明 |
|----|------|
| 路由 | `/integration/product-lines`，`IntegrationProductLinesView.vue` |
| 侧栏 | 「产品线」 |
| 页面 | 只读表 + 「刷新」 |
| 列 | 编码、名称、描述、启用（`enabled` / `active` 为 false 显示「否」） |
| 分页 | 同集成环境 |

---

## 3. 无侧栏：认证与异常页

| 路由 | 页面 | 内容 |
|------|------|------|
| `/login` | `LoginView.vue` | 标题「客户商务与交付管理平台（I1）」；用户名、密码；登录 loading；演示账号提示 |
| `/403` | `ForbiddenView.vue` | Result：无权限；「返回首页」 |
| `/*` | `NotFoundView.vue` | Result：404；「返回首页」 |

---

## 4. Figma / 画板拆分建议

1. **App Shell**：侧栏 + 顶栏 + 内容槽（与各列表/详情组合）。  
2. **一级画板**：首页、各侧栏列表页、登录、403、404。  
3. **二级画板**（无侧栏直达）：合同向导（3 步）、合同详情、交付新建、交付详情、许可新建、许可详情、Callback 详情。  
4. **模态层**：客户表单、项目表单、合同行、交付行；各类二次确认可在设计注释中说明。

---

## 5. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-04-07 | 初版：按 `web/delivery-platform-ui` 源码走查整理，供设计跟进。 |