# harborline-console

**Repository Path**: zhnn112/harborline-console

## Basic Information

- **Project Name**: harborline-console
- **Description**: 货代公司一站式物流平台
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Harborline · 货代业务中台前端原型

Harborline 是一个可连续操作的国际货代业务原型，用 Vue 3 与内存 Mock 演示“客户询价 → 多来源产品查询 → 方案比选 → 报价审批 → 订舱履约 → 单证 → 财务复核”的跨模块协作。

> 当前仓库是前端业务设计与交互验证版本，不连接真实船司、邮箱、支付、数据库或身份服务。所有查询结果、发送动作、跟踪事件和财务结果均为确定性的 Mock；演示业务时间固定为 `2025-06-03`。

## 快速开始

```bash
npm install
npm run dev
```

默认地址为 `http://localhost:5174`：

- `/showcase`：无需登录，面向甲方展示产品价值、业务闭环与客户门户成品预览。
- `/tour`：无需登录，观看五角色业务动画。
- `/dictionary`：无需登录，查询货代术语、实体字段、状态和对象关系；字典覆盖不少于当前原型涉及的核心业务域。
- `/login`：选择岗位或客户身份进入系统，无需密码。

生产构建与本地预览：

```bash
npm run build
npm run preview
```

## 推荐演示路径

第一次观看建议按下面顺序操作，而不是从各模块列表随机浏览。

1. 先打开 `/showcase` 了解产品价值与全链路能力，再到 `/tour` 查看商务、履约、财务、客户和管理员如何交接；遇到陌生字段时在 `/dictionary` 检索。
2. 以“商务 · 客户与报价”登录，进入“询价与产品查询”，打开 `INQ-2025-0061`。这条询价已经具备客户、航线、箱型、时间窗和服务范围，可以直接发起查询。
3. 在产品查询页查看船司直连、企业合约、合作代理、Excel 价表四类来源的成功、超时和部分失败结果；重试失败来源后进入方案比选。
4. 比较承运人、服务名、ETD/ETA、舱位、截点、免箱期、费用、有效期、可靠性和来源证据，选中一个候选产品后进入 `/quotes/new`。
5. 在报价制作页确认被冻结的成本来源，逐项填写客户售价，查看毛利并保存草稿或提交复核。候选产品可以直接生成报价，不要求先写入运价库。
6. 另行演示长期运价：进入 `/rates/import`，模拟加载 Excel/合同来源，完成字段映射、最低费用校验并提交；切换到“商务 · 运价与审批”在 `/rates/review` 复核后才可用于后续报价。
7. 以“履约 · 运输执行”登录，依次查看 `/bookings`、`/operations`、`/exceptions` 和 `/documents`。订舱、执行任务、异常案件和单证版本都从同一 Shipment 推导。
8. 以财务身份进入 `/finance/receivables` 查看应收与逾期，再到 `/finance/payables` 查看待审核、差异和待付款审批；打开 `/finance/vendor-bills/VB-2025-0088` 演示“报价成本快照—供应商账单—履约证据”三方对比。`/billing` 继续保留为综合财务入口和客户发票入口。
9. 切换到外部客户，验证其只能看到本企业询价、已发布报价、对外履约信息、已签发单证和本企业发票，不能看到候选成本、供应商账单或内部异常证据。

## Provider、候选产品与运价库

这三个概念在系统中彼此独立：

- **Provider** 是“从某类来源取得并标准化数据”的软件边界，不是某个供应商账号，也不是数据库表。当前业务界面只显示“船司直连、企业合约、合作代理、Excel 价表”，技术适配器名称不会暴露给普通用户。
- **候选产品** 是针对一条完整询价得到的当次可选方案，包含承运人、服务、船期、舱位、截点、费用、限制和来源快照。它可以直接进入报价。
- **运价库** 保存经过标准化和人工审核、预期可重复使用的内部成本资料。它不是每次查询结果的缓存，也不应自动吞入全部候选产品。

推荐采用混合方式：客户需求完整后按需查询最新船期、舱位和即期价格；企业合约、确认过的 Excel 价表以及确有复用价值的候选方案，才进入运价审核并沉淀。一次性、临期、来源不完整或限制强的方案只保留在本次询价和报价快照中。

详细业务判断见[系统设计报告](./docs/系统设计报告.md)。

## 五个核心角色与岗位

角色定义稳定能力，Profile 表示同一角色下的具体人员、复核岗位和数据范围。这样只保留五个核心角色，也能演示经办人与复核人分离。

| 核心角色 | 岗位 Profile | 主要工作 |
|---|---|---|
| `ADMIN` 管理员 | 管理员 | 跨模块审计、角色能力查看和演示兜底 |
| `COMMERCIAL` 商务 | 客户与报价、运价与审批 | 询价、产品查询、运价、成本毛利、报价和客户沟通 |
| `FULFILLMENT` 履约 | 运输执行、单证复核、海外协同 | 订舱、箱务、任务、跟踪、异常、单证和目的港交接 |
| `FINANCE` 财务 | 财务、资金复核 | 应收、应付、费用审核和付款审批 |
| `CUSTOMER` 外部客户 | 按客户企业登录 | 提交本企业询价，处理已发布报价并查看对外进度和发票 |

`FULFILLMENT_OVERSEA` 不是第六个角色，而是履约角色上的受限 Profile：只处理指定客户组合和目的港动作，并采用外部受众字段投影。

## 前端分层

```text
src/
├── features/              # 页面与页面级交互；包含独立对外展示层及询价、运价、报价、履约、财务等业务域
├── assets/showcase/       # 展示页首屏物流场景素材
├── layout/                # 应用壳、角色化侧栏和全局搜索顶栏
├── shared/                # 表格、状态、异步态、弹窗、路线、差异等共享 UI
├── services/api.js        # 页面唯一使用的应用服务组合门面
├── modules/
│   ├── commercial/        # 询价、四来源查询、候选比选与报价/运价交接
│   ├── fulfillment/       # 订舱、履约任务和异常案件的组合读模型
│   ├── finance/           # 应收、应付、到账核销和三方费用对比
│   ├── crm/               # 客户经营、联系人、跟进与关联业务
│   ├── customer/          # 客户门户、服务工单与公开/内部内容投影
│   └── governance/        # 账号配置、有效授权、数据范围与变更审计
├── domain/                # 权限、报价状态机、审批规则和统一业务错误
├── mock/
│   ├── api.js             # 既有 Mock 应用服务与状态编排
│   ├── repository.js      # 内存集合、快照和恢复边界
│   ├── db.js              # 报价、Shipment、单证、审批和财务种子
│   └── catalog.js         # 客户、港口和运价来源目录
├── store/                 # 会话、五角色能力、岗位 Profile 和全局 UI 状态
├── config/                # 固定演示时钟
└── styles/                # 设计令牌与全局样式

tests/                     # Vitest 领域/组合读模型测试与 Playwright E2E
docs/                      # 系统设计报告
design-system/             # Harborline 视觉与交互基线
```

依赖方向为：`features → services/api → modules 或 mock/api → repository`。页面不直接读取 `db.js`，新增纵向模块也不复制 Shipment 或账务事实；它们从已经完成权限过滤的核心 API 组合出页面需要的工作清单。

## 常用脚本

| 命令 | 作用 |
|---|---|
| `npm run dev` | 启动 Vite 开发服务器 |
| `npm run build` | 生成生产构建到 `dist/` |
| `npm run preview` | 本地预览生产构建 |
| `npm run lint` | 执行 ESLint |
| `npm run typecheck` | 执行 Vue 模板与项目类型检查 |
| `npm test` | 运行 Vitest |
| `npm run test:watch` | 以监听模式运行 Vitest |
| `npm run test:e2e` | 运行 Chromium E2E |
| `npm run check` | 串行执行 lint、类型检查、单测、构建与 E2E |

## 文档

- [产品架构与角色流程](./docs/产品架构与角色流程.md)：本轮代码审查、客户侧/业务侧/管理员侧模块矩阵、子页面、权限、流程与验收路径。
- [完整系统设计报告](./docs/系统设计报告.md)：分层、页面矩阵、角色操作手册、Provider 与运价库判断、状态机、控制点和 Mock 边界。
- [界面设计系统](./design-system/harborline-console/MASTER.md)：视觉令牌、组件规则、响应式与可访问性基线。
- 运行后的 `/dictionary`：面向产品经理的业务术语、实体字段、关系和状态查询。

## 当前边界

本轮新增：客户专属门户 `/portal`（客户登录自动进入）、客户经营 `/customers` 及五个档案页签、服务工单 `/service-requests`、应收详情 `/finance/receivables/:id` 与部分收款核销、管理员治理 `/admin/overview`、账号与授权 `/admin/users`、授权审计 `/admin/audit`、岗位流程 `/workflows`。授权调整实际影响当前会话、列表范围及详情/写入校验；数据仍使用内存 Mock。

- 内存数据刷新后回到种子状态，没有数据库或跨设备持久化。
- 登录只是选择 Mock 调用者上下文，不包含密码、SSO、Token 或服务端鉴权。
- 船司直连、合同匹配、代理回复、Excel 解析、邮件、Agent、跟踪和支付均为业务状态模拟。
- 来源快照是结构化 Mock 证据，不是真实 API 回执、附件或电子签章。
- 当前 Mock 实现权限、状态前置条件、审计轨迹和部分幂等，但不能替代服务端事务、唯一约束和持久化审计。