admin/craftlabs-authorization-sdk
1
0
Fork 0
mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 18:10:30 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
Files
307a019d4894c5127a4da6cf5c44c56a2717b3bc
craftlabs-authorization-sdk/docs/engineering/FRONTEND_UI_SPECIFICATION.md
T
huangping 650c1caffa docs(engineering): I8/I9 iteration artifacts and frontend UI specification 
Add I8/I9 design and implementation review markdown, update parallel iteration
index and I7 review cross-links, and add FRONTEND_UI_SPECIFICATION for design
handoff (Figma Make).

Made-with: Cursor
2026-04-07 21:26:51 +08:00

308 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 交付平台前端 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` 源码走查整理，供设计跟进。 |
Reference in New Issue View Git Blame Copy Permalink