client-web/AGENTS.md

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/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 与交互

• 已向客户讲解或确认过的产品原型是页面排版、配色、间距、尺寸、图标、按钮、表格、Tab 和组件形态的直接视觉事实来源；实现时必须按原型还原，不得脱离原型自行重新设计、添加装饰或替换风格。只有用户当前明确要求、阶段范围或可访问性/真实数据约束与原型冲突时才允许调整，并须先说明具体差异及原因。
• 原型已经给出明确图标、字符图标或按钮形态时直接使用原型方案，不得以 Lucide、Element Plus 默认样式或个人偏好替换；仅当原型没有定义对应图标时，才按本节的默认图标语义补齐。
• 延续现有客户工作台的可信、简洁和服务型视觉语言，与内部管理后台保持品牌关联但不照搬高密度管理界面。
• 优先使用 Element Plus 和 Lucide 图标；不使用表情符号代替功能图标，不引入第二套组件库。
• 业务页按实际场景覆盖适用的加载、空数据、失败、无权限和数据过期状态；危险操作需要确认和明确结果。
• 保持键盘可达、可见焦点、语义化标签、足够对比度和清晰错误提示。
• 响应式变更至少检查 320px、720px 和桌面布局；避免只能横向滚动才能完成核心任务。

本地命令与质量门禁

在 apps/client-web 目录执行：

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 定位；当前启用的是客户账单、收款记录和未收余额只读入口，不据此扩展客户侧完整应收应付操作。