96 lines
11 KiB
Markdown
96 lines
11 KiB
Markdown
# Client Web Instructions
|
|
|
|
## 项目定位
|
|
|
|
- 本项目是入驻企业及其成员使用的客户工作台，所有业务数据都处于企业租户上下文中。
|
|
- 当前范围包括注册、业务总览、企业资料、企业成员、企业角色与权限、头程订单和客户财务账单只读查询。
|
|
- 不在本项目实现平台内部运营管理、品牌官网、仓库 PDA 作业或仅属于原生移动端的能力。
|
|
|
|
## 技术基线
|
|
|
|
- 使用 Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue。
|
|
- TypeScript 保持严格模式；不要使用 `any` 掩盖接口或状态模型问题，优先从 `@chongchong/shared` 复用公共类型。
|
|
- 使用现有 `@` 别名引用 `src/`，保持 ES Module 和现有无分号风格。
|
|
- Element Plus 组件使用现有自动导入配置；`ref`、`computed` 等 Vue API 必须显式导入。不要手工向 `src/auto-imports.d.ts` 或 `src/components.d.ts` 写入业务声明。
|
|
- 不擅自替换现有框架、路由、状态管理、组件库或构建工具。
|
|
|
|
## 目录与职责
|
|
|
|
- `src/modules/`：按业务域纵向组织页面、路由、业务组件、API、store、类型、数据适配和业务工具。新增业务页面必须进入对应模块，不再在 `src/views/` 堆放。
|
|
- `src/modules/<domain>/routes.ts`：作为模块 manifest 同时声明页面路由、导航元数据和发布状态；`src/modules/registry.ts` 统一组装模块，`src/router/index.ts` 只负责应用壳层和全局守卫。
|
|
- manifest 中 `release: 'active'` 的页面才会进入路由和导航；占位页面必须标记为 `release: 'prototype'`，保留源码但不可通过 URL 访问。接口、权限资源和产品范围确认后才能改为 `active`。
|
|
- `src/components/common/`：跨两个及以上业务模块实际复用的通用组件；仅被一个模块使用的组件保留在该模块内。
|
|
- `src/layouts/`：租户工作台壳层、导航和全局页面结构。
|
|
- `src/router/`：公开页、受保护路由、页面标题和权限元数据；导航与路由必须同步。
|
|
- 模块内 `store/`：该业务跨页面状态；局部表单状态仍留在页面或组件内。跨模块使用 store 时只能导入其公开 store 文件，不得读取模块内部页面或组件实现。
|
|
- `src/api/`：只保留 HTTP、会话令牌、响应类型等全局请求基础设施；业务接口放入对应模块的 `api/`。页面不得直接创建独立 Axios 客户端。
|
|
- 模块之间不得通过相对路径或内部目录穿透；确需协作时只能从目标模块的 `public.ts` 导入。模块内稳定契约放在 `contracts.ts`，稳定的跨应用模型仍应上移到 `@chongchong/shared`。
|
|
- `VITE_API_BASE_URL` 控制浏览器请求前缀，`API_PROXY_TARGET` 控制 Vite 开发代理上游；后者只由开发服务器读取，不进入客户端构建。新增或变更环境变量时同步更新 `.env.example`，不得提交真实密钥或环境专属凭据。
|
|
- `src/styles/`：全局设计令牌和布局；优先复用现有 `--primary`、`--navy`、`--border`、`--muted`。
|
|
- 本应用多个模块稳定复用的前端模型放到应用内 `shared/`，客户工作台专属类型保留在对应业务模块。不要链接应用目录之外的 TypeScript 包，服务端契约以 `baiyue-firstleg` Controller/OpenAPI 为准。
|
|
|
|
## 模块快速查询
|
|
|
|
先从 `src/modules/registry.ts` 确认模块，再按目标模块的 `routes.ts → views/ → api/、store/、contracts.ts 或 public.ts` 查询。页面是否正式开放以 `routes.ts` 的 `release` 为准，不从任务或进度文档推断。
|
|
|
|
| 业务 | 模块入口 | 联查模块或服务端 |
|
|
|---|---|---|
|
|
| 登录、注册与会话 | `src/modules/auth/` | Backend `auth/`、`iam/` |
|
|
| 企业资料、成员与角色 | `src/modules/tenant-management/`、`src/modules/account/` | Backend `iam/`、`file/` |
|
|
| 工作台与系统入口 | `src/modules/dashboard/`、`src/modules/system/` | `src/navigation/clientNavigation.ts`、`src/router/index.ts` |
|
|
| 企业成员消息收件箱 | `src/modules/notifications/` | Backend `iam/src/main/java/com/baiyue/iam/notification/`；列表、详情、已读与未读数契约见 `iam/src/main/resources/openapi/notification-v1.yaml` |
|
|
| 头程下单、订单与履约进度 | `src/modules/first-leg/` | Backend `order/`、`firstleg/`、`warehouse/` |
|
|
| 统一订单展示 | `src/modules/order-management/` | `src/modules/first-leg/` 与对应后端订单契约 |
|
|
| 客户财务账单、收款与未收余额 | `src/modules/finance/` | Backend `finance/`；以登录态客户隔离，只读接口从 `api/finance.ts` 进入 |
|
|
| 跨境与海外仓候选能力 | `src/modules/cross-border/`、`src/modules/overseas-warehouse/` | 先核对各自 `routes.ts` 的发布状态与阶段范围，不自动扩展实现 |
|
|
|
|
## 租户、认证与数据安全
|
|
|
|
- 任何查询和变更都必须以服务端确认的当前租户为边界；绝不从可篡改的前端参数推断授权租户。
|
|
- 企业成员、角色和权限只能管理当前企业范围。前端隐藏不是安全控制，服务端必须重复校验租户与权限。
|
|
- 认证统一经过 `src/modules/auth/store/auth.ts` 和 `src/api/http.ts`；不要在页面中复制令牌逻辑或持久化密码、敏感资质内容。
|
|
- 当前认证仍包含模拟数据。接入真实 API 后移除对应模拟分支，生产环境不得回退为模拟成功。
|
|
- 注册、上传资质、成员邀请和订单操作必须提供明确校验、幂等保护、提交中状态和可恢复的失败反馈。
|
|
|
|
## UI 与交互
|
|
|
|
- 修改已有 Client 原型页面前先读 `../../docs/Admin-Client前端原型还原验收规则.md`，按页面和操作形成原型核对矩阵；本节维护 Client 的实现约束，不复制跨前端验收文档全文。
|
|
- 已向客户讲解或确认过的产品原型是页面视觉与布局实现的直接事实来源。字段顺序、字段分组、字段摆放、列宽、控件宽高、对齐方式、换行方式、区块层级、上下左右边距、内边距、间隙、留白、圆角、边框、阴影、背景色、文字颜色和字号均必须按原型还原，不得只参考大致风格后自行重新排版。
|
|
- 原型中的按钮位置、顺序、尺寸、圆角、边框、背景色、文字色、图标、悬停态、激活态、禁用态和危险语义必须直接按原型实现；不得擅自改为文字链接、不同颜色、不同按钮类型、折叠菜单或自创交互效果，也不得增加原型没有的上浮、缩放、渐变线、装饰图标或其他视觉元素。
|
|
- 原型已经给出明确图标、字符图标、图片资源或按钮内图标时，直接使用原型中的同一方案和资源，不得以 Lucide、Element Plus 默认图标、手绘图标或个人偏好替换。仅当原型没有定义对应图标时，才按本节的默认图标语义补齐。
|
|
- 上述原型还原规则优先于本文件中“延续现有视觉体系”、默认组件样式和默认图标库等一般性规则。只有用户当前明确要求、阶段范围、真实字段长度、响应式、可访问性或接口事实与原型冲突时才允许做最小调整，并须在修改前说明具体差异、原因和影响范围；不得以技术实现方便为由偏离原型。
|
|
- 详情、新增、编辑、审核等操作采用独立页面、居中弹框、侧滑面板或其他承载方式，必须逐页面按对应原型确认，不得全局写死为某一种容器。原型为独立页面时使用正式路由和页面布局；原型为居中弹框时使用模态弹框；只有原型明确为侧滑面板时才使用抽屉。不得因为已有公共组件或改动方便，把原型中的独立页面改成弹框、把弹框改成抽屉，或反向替换。
|
|
- 延续现有客户工作台的可信、简洁和服务型视觉语言，与内部管理后台保持品牌关联但不照搬高密度管理界面。
|
|
- 优先使用 Element Plus 和 Lucide 图标；不使用表情符号代替功能图标，不引入第二套组件库。
|
|
- 业务页按实际场景覆盖适用的加载、空数据、失败、无权限和数据过期状态；危险操作需要确认和明确结果。
|
|
- 保持键盘可达、可见焦点、语义化标签、足够对比度和清晰错误提示。
|
|
- 响应式变更至少检查 320px、720px 和桌面布局；避免只能横向滚动才能完成核心任务。
|
|
|
|
## 本地命令与质量门禁
|
|
|
|
在 `apps/client-web` 目录执行：
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
pnpm test
|
|
pnpm typecheck
|
|
pnpm build
|
|
```
|
|
|
|
- 日常变更至少运行 `pnpm typecheck`；交付前运行 `pnpm build`。
|
|
- 当前测试使用 Node.js 内置测试运行器，执行 `pnpm test`；项目仍未声明 lint 脚本，不得声称 lint 已通过。
|
|
- 不手工修改 `dist/` 或 `node_modules/`；依赖变更必须同步当前项目依赖清单和锁文件。
|
|
|
|
## 一期/二期/三期快速索引
|
|
|
|
按阶段开展客户工作台任务时，先核对对应阶段文档，再按“模块 `routes.ts` → 页面/组件 → `api`、store、contracts”定位；阶段范围以用户确认、需求确认表和设计文档为准，原型只用于视觉与交互补充。本表只描述 Client 页面与客户可见契约，服务端实现详见后端模块指引。
|
|
|
|
| 阶段 | Client 范围边界 | 代码入口 | 开发首读 |
|
|
|---|---|---|---|
|
|
| 一期：客户与头程订单闭环 | 登录/注册、企业资料与资质、成员/角色权限、工作台和头程订单；订单停在已确认的七状态，不对客户开放取消写操作 | `src/modules/auth/`、`tenant-management/`、`account/`、`system/`、`dashboard/`、`first-leg/` | `../../docs/一期/README.md`、一期闭环设计；核对资格门禁、幂等键、状态机、仓库主数据及真实接口错误处理 |
|
|
| 二期：到仓与头程计费 | 客户侧展示已授权的入库、测量和费用结果，终点为 `WAIT_SPLIT + APPROVED + CONFIRMED`；不暴露 Admin 内部备注、文件或未授权原始证据 | `src/modules/first-leg/` | `../../docs/二期/README.md`、二期主流程 |
|
|
| 三期：国内出仓 | 客户仅查看柜次、装柜进度、授权回执和船期，不暴露照片、锁码或后台内部资料 | `src/modules/first-leg/`；统一订单候选入口在 `order-management/` | `../../docs/三期/README.md`、需求确认表、开工门禁、开发规划和页面清单；不自动纳入完整 WMS、报关后台操作或海运运营流程 |
|
|
|
|
阶段边界：一期负责客户入驻与下单，二期负责到仓和计费并停在等待三期分柜，三期才进入国内出仓；不要把 PDA、分柜或装柜后台操作开放到客户工作台。财务作为独立专题按 `../../docs/财务管理/README.md` 与 `src/modules/finance/routes.ts` 定位；当前启用的是客户账单、收款记录和未收余额只读入口，不据此扩展客户侧完整应收应付操作。
|