# Client Web Instructions

## 项目定位

- 本项目是入驻企业及其成员使用的客户工作台，所有业务数据都处于企业租户上下文中。
- 当前范围包括注册、业务总览、企业资料、企业成员、企业角色与权限、头程订单、客户资金账户、客户财务账单查询与客户确认，以及海外仓贴标、转运、废弃和退货换标自助服务。
- 用户可见的“平台—客户”层级语义读取 `../../docs/平台客户层级与权限契约.md`；涉及统一 API、Token、会话撤销或可靠事件时按需读取 `../../docs/统一认证与服务通信契约.md` 对应章节。本文件中的 `tenant` 仅表示服务端隔离上下文，不扩展用户可见产品层级。
- 不在本项目实现平台内部运营管理、品牌官网、仓库 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 前缀；全部业务共用 `src/api/http.ts` 和同一 Access/Refresh Token。`API_PROXY_TARGET` 仅供本地 Vite 代理连接测试入口，不进入客户端构建。独立海外 HTTP 客户端与代理已移除。新增或变更环境变量时同步更新 `.env.example`，不得提交真实密钥或环境专属凭据。
- `src/styles/`：全局设计令牌和布局；优先复用现有 `--primary`、`--navy`、`--border`、`--muted`。
- 本应用多个模块稳定复用的前端模型放到应用内 `shared/`，客户工作台专属类型保留在对应业务模块。不要链接应用目录之外的 TypeScript 包，服务端契约以 `baiyue-firstleg` Controller/OpenAPI 为准。

## 测试环境样式验收

- 测试环境验收使用本轮动态创建并已审核通过的客户管理员，或由用户显式提供的客户账号，不依赖固定业务客户或固定账号。
- 账号与密码不写入仓库；从本机未提交环境变量或 `C:/Users/BY-OY/.codex/chongchong-global-dev-acceptance.env` 读取。若显式验收凭据不存在，再向用户索取。
- 当前只有一个测试环境。不要把密码、Token 或真实接口地址写入源码、测试快照、日志或 `AGENTS.md`；测试环境变更时只更新本机凭据。
- 由人工使用该身份进入真实页面，按 `1920×1080` 视口和 `100%` 浏览器缩放完成操作与截图，再把截图发送给 AI 核对加载、空态、错误态、权限态和桌面布局；AI 默认不主动调用截图或视觉类技能取证。

## 模块快速查询

退货预报与签收结果：`src/modules/overseas-warehouse/views/ReturnOrdersView.vue`、`api/returnOrders.ts`；菜单仍名为“退货换标”。列表路由 `return-relabel`、独立新建路由 `return-relabel/create` 与详情路由均复用该页面，并分别由 `createPage/detailPage` 明确模式；新建页直接填写海外仓、联系人、客户参考号及 SKU 预报明细，取消或提交后返回列表，不再由 `WarehouseServiceView.vue` 或列表内弹框承载。客户退货库存/箱号共用 `views/ReturnInventoryView.vue`、`api/returnInventory.ts`，`return-cartons` 传 `cartonOnly=true`。Backend 为 Lastleg `returnreceipt/`，退货单签收完成不等于换标或退货出库完成；后续换标、出库须按各自业务状态核对。

先从 `src/modules/registry.ts` 确认模块，再按目标模块的 `routes.ts → views/ → api/、store/、contracts.ts 或 public.ts` 查询。页面是否正式开放以 `routes.ts` 的 `release` 为准，不从任务或进度文档推断。

| 业务 | 模块入口 | 联查模块或服务端 |
|---|---|---|
| 登录、注册与会话 | `src/modules/auth/`、`src/api/session.ts`、`src/api/http.ts` | Backend `auth/`、`iam/`；正常轮换的统一 Access/Refresh Token 会话持久化，“记住账号”只记登录标识；访问令牌失效但刷新令牌仍在时先恢复会话，公开认证接口不得携带旧 Token |
| 企业资料、成员与角色 | `src/modules/tenant-management/`、`src/modules/account/` | Backend `iam/`、`auth/`、`file/`；公司联系电话/邮箱是企业资料，不作为登录标识；成员登录手机号可选，修改时同步 Auth、撤销该账号会话并审计。审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可随营业执照提交，也可在已有营业执照后单独补传或替换。前端角色树到服务端权限的映射统一维护在 `contracts.ts` 的 `FRONTEND_TO_MERCHANT_PERMISSION_CODES`，海外入仓、采购、本土卡车和散板权限必须显式进入该映射 |
| 工作台与系统入口 | `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/`；列表与批量入口 `views/FirstLegOrdersView.vue`，模板/导入 API `api/firstLeg.ts`，入仓详情 `components/InboundCodeAssociationDialog.vue`、`api/inboundCodeAssociations.ts`，独立计费重弹框 `components/InboundBillingPanel.vue`、`api/inboundBilling.ts` | 中文 XLSX 模板按当前客户生成地址、全部有效仓库和渠道下拉，最多 50 行，只创建草稿并支持部分/原子导入；导入结果只显示 Excel 行号，不展示内部 `clientRowId`。所有订单行均可进入计费重弹框，尚未推送时展示明确空态；只有具备编辑权限且服务端返回当前 `SENT` 费用时才可二次确认并提交 `expectedFeeVersion` 与幂等键，成功后版本锁定、平台不得再修改。Backend `order/`、`firstleg/`、`warehouse/`，不得用内部 ID 补齐缺失业务编号 |
| 装柜完成后的退税报关资料 | `src/modules/first-leg/views/FirstLegOrdersView.vue` 的“报关资料”、`components/CustomsDocumentsDialog.vue`、`api/customs.ts` | 只显示登录客户在同柜的退税入仓码；报关开始前可上传、替换、调整同一资料覆盖的一个或多个入仓码及删除误传，全部写入携带幂等键和版本；开始后只读冻结资料，整柜完成后才能下载平台回传的一对一完成文件。Backend `firstleg/customs/container/`、`customs-v1.yaml`，二进制归 `file/` |
| 统一订单展示 | `src/modules/order-management/` | `src/modules/first-leg/` 与对应后端订单契约 |
| 客户财务账单、入仓码联查、收款、未收余额与客户确认 | `src/modules/finance/`；确认与明细入口 `views/FinanceBillsView.vue`、`api/finance.ts`，入仓码通过 `src/modules/first-leg/public.ts` 复用 `InboundCodeAssociationDialog` | Backend `finance/`；账单行只显示服务端 `inboundCode` 并按登录客户查询业务关系，缺失显示“—”，不得回退内部 ID。收款方式由服务端枚举映射中文。出账或已出账调整后为 `PENDING_CONFIRMATION`，客户确认提交登录成员、`expectedVersion` 和幂等键 |
| 客户资金账户、授信与充值申请 | `src/modules/finance/views/FinanceAccountView.vue`、`api/account.ts` | 显示当前企业 CNY 实际余额、冻结金额、授信额度、授信有效期、已用授信、冻结授信、总可用余额和不可变流水；数据加载前显示“—”，不得先伪装为零。授信到期日当天仍有效，次日已用授信并入实际余额，负数实际余额会阻止提交新订单。充值只展示服务端启用的平台统一静态收款码，客户上传 JPG/PNG 付款截图后进入待审核。客户范围只取登录态，无收款码时禁止提交，不模拟支付成功 |
| 海外采购 | `src/modules/cross-border/routes.ts`、`views/ProcurementView.vue`、`components/ProcurementDetailPanel.vue`、`api/procurement.ts` | 独立列表、新建及详情路由；客户范围只取 Token，创建的 `customerName` 只取认证会话企业名称。详情消费独立客户投影，展示履约、已确认箱明细、实际运单和费用结果，不开放内部文件或平台操作。Backend `lastleg-service/procurement/` |
| 美国本土卡与美本土散板 | `src/modules/cross-border/routes.ts`、`components/BusinessOrdersView.vue`、`api/businessOrders.ts` | 两个运输业务共用列表/表单组件，客户范围只取 Token；不消费采购字段或状态。Backend `lastleg-service/` 的 `trucking/`、`looseboard/` 客户接口 |
| 海外仓入库订单 | `src/modules/order-management/routes.ts`、`views/InboundOrdersView.vue`、`api/inboundPlans.ts` | `orders/inbound` 为只读列表/详情，权限 `merchant:warehouse:inbound:list`；不展示或提交内部 ID |
| 海外仓贴标、仓储转运、货物废弃 | `src/modules/overseas-warehouse/routes.ts`、`views/WarehouseServiceView.vue`、`api/warehouseServices.ts` | 三个路由均为 `active`；退货预报另见本节独立入口；贴标申请先选国外中转仓和有库存历史入仓单，换标类型为只换 SKU、只换箱唛、SKU+箱唛。涉及箱唛换标时，整张贴标申请只选择一个 FBA 目的仓，全部箱级明细统一提交该目的仓，模板和明细不再逐行选择目的仓。箱唛换标明细一行固定代表一箱，箱数不可编辑，提交也固定为 1。货物明细外层始终提供“SKU 关联”“箱号关联”“SKU 混箱换标”三套模板的下载、上传，不随换标类型切换；上传只进入待导入关系区，客户可勾选部分或全选后导入本次明细，只有进入明细的库存才随申请提交和冻结。明细也支持手动新增编辑，组合换标以仓库唛头连接旧/新 SKU 和新 FBA 箱唛关系。涉及箱唛换标时必须选择卡车、自提或快递；快递可选择打印面单并上传 PDF/图片。PDA 逐箱换标、上传照片并由仓库复核后，客户详情展示完工照片和“换标完成确认”；客户确认前不得继续出库，确认后卡车进入预排车，自提/快递进入换标出库待创建。历史库存位置不能解释成箱唛与具体托盘快照，客户页面不暴露托盘、库位和内部库存 ID |

## 租户、认证与数据安全

- 换标申请必须提交正数 CNY `chargeAmount`；入口为 `src/modules/overseas-warehouse/views/WarehouseServiceView.vue` 与 `api/warehouseServices.ts`，金额由服务端再次校验，资金状态以服务端返回为准，不在客户端模拟冻结成功。

- 任何查询和变更都必须以服务端确认的当前租户为边界；绝不从可篡改的前端参数推断授权租户。
- 企业成员、角色和权限只能管理当前企业范围。前端隐藏不是安全控制，服务端必须重复校验租户与权限。
- 注册时登录手机号同时初始化公司联系电话；注册完成后两者独立维护。企业资料只修改 `contactPhone`，个人资料或成员管理中的登录手机号由 IAM/Auth 同步并撤销该账号现有会话，不得在前端互相回填或联动提交。
- 认证统一经过 `src/modules/auth/store/auth.ts`、`src/api/http.ts`、`src/api/session.ts`；全部请求共用统一 Access Token。启动时 Access Token 已过期但 Refresh Token 仍存在，必须先尝试恢复会话；并发或跨标签页 401 共用一次刷新编排，每个原请求最多重放一次，只有明确 401/会话失效才清理 Token 并保留原路径跳转登录页。登录页“记住账号”只保存登录 ID，不改变 Access/Refresh Token 的持久化与续期策略；页面不要复制令牌逻辑或持久化密码、敏感资质内容。
- 当前认证仍包含模拟数据。接入真实 API 后移除对应模拟分支，生产环境不得回退为模拟成功。
- 头程订单统一使用当前正式读写契约；不得继续扩展 `LEGACY_MANUAL`、旧系统入仓码、C02 不可用回退旧 API、历史部分响应兼容或其他新旧并跑逻辑。触及该链路时按根无兼容规则同步删除生产分支、类型、文案、Mock 和测试，不以现有代码或测试仍覆盖旧路径作为保留依据。
- 注册、上传资质、成员邀请和订单操作必须提供明确校验、幂等保护、提交中状态和可恢复的失败反馈。

## UI 与交互

- 视觉还原、布局/交互承载方式变更或真实页面验收时读取 `../../docs/Admin-Client前端原型还原验收规则.md`，只为受影响操作形成原型核对矩阵；纯文案、逻辑或测试修改不自动读取。自动检查与人工视觉验收分开报告，无视觉变化时标记“无需视觉验收”。
- 已向客户讲解或确认过的产品原型是页面视觉与布局实现的直接事实来源。字段顺序、字段分组、字段摆放、列宽、控件宽高、对齐方式、换行方式、区块层级、上下左右边距、内边距、间隙、留白、圆角、边框、阴影、背景色、文字颜色和字号均必须按原型还原，不得只参考大致风格后自行重新排版。
- 原型中的按钮位置、顺序、尺寸、圆角、边框、背景色、文字色、图标、悬停态、激活态、禁用态和危险语义必须直接按原型实现；不得擅自改为文字链接、不同颜色、不同按钮类型、折叠菜单或自创交互效果，也不得增加原型没有的上浮、缩放、渐变线、装饰图标或其他视觉元素。
- 原型已经给出明确图标、字符图标、图片资源或按钮内图标时，直接使用原型中的同一方案和资源，不得以 Lucide、Element Plus 默认图标、手绘图标或个人偏好替换。仅当原型没有定义对应图标时，才按本节的默认图标语义补齐。
- 上述原型还原规则优先于本文件中“延续现有视觉体系”、默认组件样式和默认图标库等一般性规则。只有用户当前明确要求、阶段范围、真实字段长度、响应式、可访问性或接口事实与原型冲突时才允许做最小调整，并须在修改前说明具体差异、原因和影响范围；不得以技术实现方便为由偏离原型。
- 详情、新增、编辑、审核等操作采用独立页面、居中弹框、侧滑面板或其他承载方式，必须逐页面按对应原型确认，不得全局写死为某一种容器。原型为独立页面时使用正式路由和页面布局；原型为居中弹框时使用模态弹框；只有原型明确为侧滑面板时才使用抽屉。不得因为已有公共组件或改动方便，把原型中的独立页面改成弹框、把弹框改成抽屉，或反向替换。
- 延续现有客户工作台的可信、简洁和服务型视觉语言，与内部管理后台保持品牌关联但不照搬高密度管理界面。
- 优先使用 Element Plus 和 Lucide 图标；不使用表情符号代替功能图标，不引入第二套组件库。
- 业务页按实际场景覆盖适用的加载、空数据、失败、无权限和数据过期状态；危险操作需要确认和明确结果。
- 保持键盘可达、可见焦点、语义化标签、足够对比度和清晰错误提示。
- 当前样式开发与验收只处理 `1920×1080` 桌面视口，不检查或整改 `720px`、`320px` 及其他窄屏；这些视口不作为测试、截图或交付门禁。保留现有响应式实现，不为当前阶段主动删除，用户恢复多视口验收后再统一处理。

## 本地命令与质量门禁

在 `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/`；依赖变更必须同步当前项目依赖清单和锁文件。

## 全量验收脚本

- Client 全量验收唯一入口为 `../../baiyue-firstleg/scripts/client-test-env-acceptance.mjs`；入库测量与计费专项场景才单独执行 `client-phase2-test-env-acceptance.mjs`，不替代完整入口。
- 入口通过测试环境 HTTP 验证注册/审核、客户隔离、订单、入库计费、文件、财务和权限链路，会创建或修改测试数据，必须获得当前对话明确授权。
- `pnpm test/typecheck` 和 `frontend-full-regression.ps1` 仅是本地质量检查，不代表 Client 服务已完成全量验收。
- HTTP 验收通过后，由人工使用开发验收账号逐页检查真实接口调用、客户可见字段、原型、权限、错误态、空态和 `1920×1080` 桌面布局，并将截图发送给 AI 分析；未收到人工截图时标记为待人工确认，不追加 AI 截图或窄屏浏览器验收。

## Client 全量验收快速索引

当前按客户侧全量业务闭环验收。业务域文档用于核对功能来源和验收证据，不限制本次验收的模块范围；按“模块 `routes.ts` → 页面/组件 → `api`、store、contracts”定位。本表只描述 Client 页面与客户可见契约，服务端实现详见后端模块指引。

| 验收域 | Client 范围与代码入口 | 验收首读 |
|---|---|---|
| 客户基础与订单 | 登录/注册、企业资料与资质、成员/角色权限、工作台和订单 | `src/modules/auth/`、`tenant-management/`、`account/`、`system/`、`dashboard/`、`first-leg/`、`order-management/`；按客户可见契约核对权限、状态、幂等和错误处理 |
| 履约、海外仓与财务 | 入库计费、柜次进度、船期、海外仓贴标/转运/废弃/退货换标、消息和客户账单 | `src/modules/first-leg/`、`overseas-warehouse/`、`finance/`、`notifications/`；按服务端权限核对客户可见字段、客户隔离和只读/写入边界 |

客户侧边界：仍以服务端权限和客户可见字段为准；PDA、平台后台操作和内部证据不因全量验收自动暴露到 Client。财务按 `../../docs/财务管理/` 与 `src/modules/finance/routes.ts` 定位。