# 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//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` 目录执行： ```bash pnpm install pnpm dev pnpm test pnpm typecheck pnpm build ``` - 日常变更至少运行 `pnpm typecheck`；交付前运行 `pnpm build`。 - 当前测试使用 Node.js 内置测试运行器，执行 `pnpm test`；项目仍未声明 lint 脚本，不得声称 lint 已通过。 - 不手工修改 `dist/` 或 `node_modules/`；依赖变更必须同步当前项目依赖清单和锁文件。