交付平台前端 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 / 画板拆分建议
- App Shell：侧栏 + 顶栏 + 内容槽（与各列表/详情组合）。
- 一级画板：首页、各侧栏列表页、登录、403、404。
- 二级画板（无侧栏直达）：合同向导（3 步）、合同详情、交付新建、交付详情、许可新建、许可详情、Callback 详情。
- 模态层：客户表单、项目表单、合同行、交付行；各类二次确认可在设计注释中说明。
5. 修订记录
| 日期 |
说明 |
| 2026-04-07 |
初版：按 web/delivery-platform-ui 源码走查整理，供设计跟进。 |
huangping
650c1caffa