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/auth/store/auth.ts 和 src/api/http.ts；不要在页面中复制令牌逻辑或持久化密码、敏感资质内容。
• 当前认证仍包含模拟数据。接入真实 API 后移除对应模拟分支，生产环境不得回退为模拟成功。
• 注册、上传资质、成员邀请和订单操作必须提供明确校验、幂等保护、提交中状态和可恢复的失败反馈。

UI 与交互

• 延续现有客户工作台的可信、简洁和服务型视觉语言，与内部管理后台保持品牌关联但不照搬高密度管理界面。
• 优先使用 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/；依赖变更必须同步当前项目依赖清单和锁文件。

一期/二期/三期快速索引

按阶段开展客户工作台任务时，先核对对应阶段文档，再进入模块；阶段范围以用户确认、需求确认表和设计文档为准，原型只用于视觉与交互补充。

阶段	当前状态与边界	Client 代码入口	开始前核对
一期：客户与头程订单闭环	登录/注册、企业资料与资质、成员/角色权限、工作台和头程订单已接入一期后端；当前重点为测试 Gateway 验收，仓库查询与草稿创建仍受后端 S0500 阻断。订单停在已确认的七状态，不对客户开放取消写操作。	src/modules/auth/、tenant-management/、account/、system/、dashboard/、first-leg/、order-management/；路由由各模块 routes.ts 通过 src/modules/registry.ts 组装。	../../docs/一期/README.md、../../docs/一期/一期开发进度表.md、../../docs/一期/一期头程订单闭环设计.md；核对资格门禁、幂等键、状态机、仓库主数据及真实接口错误处理。
二期：到仓与头程计费	客户侧以一期订单为承接面，展示入库/测量/费用结果；技术闭环终点为 WAIT_SPLIT + APPROVED + CONFIRMED，WAIT_SPLIT 等待三期分柜。不得在 Client 暴露 Admin 内部备注、文件或测量原始数据之外的敏感运营字段。	src/modules/first-leg/（订单详情中的到仓、测量、费用只读区）；费用与入库 API、类型和状态映射应与后端 firstleg/ Controller/OpenAPI 对齐。	../../docs/二期/README.md、../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md、../../docs/二期/二期前端联调报告-2026-08-04.md、../../docs/二期/第三方入仓测量接口联调说明-2026-08-04.md；二期开发进度表.md 为旧口径，使用前核对日期与验收终点。
三期：国内出仓	当前 NO-GO、需求确认未完成；Client 暂不新增正式业务入口。阶段终点是国内出仓完成、等待装船，涉及分柜/订舱/拖车/PDA 拣货/装柜证据等能力，必须先解除 P3-Q1/Q2/Q5/Q9/Q11/Q12/Q13 阻断。	规划复用 src/modules/first-leg/、order-management/ 的订单承接与状态展示；新增模块、路由或 release: 'active' 页面前须完成契约和权限确认。	../../docs/三期/README.md、../../docs/三期/三期开发规划.md、../../docs/三期/三期需求确认表.md、../../docs/三期/三期页面与原型清单.md；不得把原型中的完整 WMS、报关或海运流程自动纳入 Client 三期范围。

阶段边界：一期负责客户入驻与下单，二期负责到仓和计费并停在等待三期分柜，三期才进入国内出仓；不要把 PDA、分柜、装柜或完整财务应收应付提前实现到客户工作台。