admin-web/AGENTS.md

Admin Web Instructions

项目定位

• 本项目是虫虫出海内部运营与管理后台，仅服务平台员工。
• 当前范围包括工作台、客户管理、头程订单、内部用户、角色管理和菜单权限。
• 不在本项目承载企业客户自助流程、品牌官网、微信小程序、独立 APP 或仓库 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/app/：应用装配层，包含布局、根路由、全局守卫和启动入口；不承载具体业务或被业务模块反向依赖。
• src/core/：认证会话、访问控制、导航配置、未保存工作保护和路由安全工具等全应用基础能力；可以被 app 和业务模块使用，但不得依赖业务模块。
• src/modules/：按客户、仓库、头程订单、主数据、下载中心、IAM 等稳定业务领域组织页面、API、类型、组件和路由。新增业务页面必须进入对应模块，不再建立根级 views/。
• src/shared/：与具体业务无关的后台公共 HTTP、组件和工具。模块专属能力先留在模块内部，只有被无关模块真实复用时才上移。
• src/prototype/：未纳入当前迭代的原型页面和原型路由；正式模块不得依赖原型代码。
• src/modules/*/pages/：路由级页面和业务编排；复杂展示、表单、抽屉和交互下沉到同模块组件或 composable。
• src/modules/*/routes.ts：模块路由片段；由 src/app/router/index.ts 统一装配。新增模块时同步维护 src/core/navigation/adminNavigation.ts。
• src/core/*/ 与 src/modules/*/stores/：前者只放全应用基础状态，后者放领域状态；仅页面局部使用的状态留在页面或 composable。
• src/modules/*/api/：领域接口适配；公共 Axios 客户端位于 src/shared/api/http.ts，页面与组件不得散落创建 Axios 实例。
• VITE_API_BASE_URL 控制浏览器请求前缀，API_PROXY_TARGET 控制 Vite 开发代理上游；后者只由开发服务器读取，不进入客户端构建。新增或变更环境变量时同步更新 .env.example，不得提交真实密钥或环境专属凭据。
• 模块专属类型放在对应模块；本应用多个模块稳定复用的前端类型和工具放到应用内 shared/。不要链接应用目录之外的 TypeScript 包，服务端契约以 baiyue-firstleg Controller/OpenAPI 为准。
• src/styles/：设计令牌和全局样式；优先复用现有 --cc-* 变量和组件样式。

依赖方向保持为 app -> modules/core/shared、modules -> core/shared、core -> shared、shared -> 无上层依赖。模块间确需调用时只能引用对方根入口公开的 API 或契约，不得引用其他模块的页面、内部组件或内部目录。

业务与安全约束

• 菜单隐藏和前端路由守卫只改善体验，不能替代服务端鉴权。新增操作必须使用稳定的权限编码，并与 API 权限保持一致。
• 认证统一经过 src/core/auth/auth.ts 和 src/shared/api/http.ts；不要在页面中复制令牌读写或手工拼装 Authorization。
• 当前登录和部分数据仍可能是模拟实现。接入 baiyue-firstleg Gateway 真实接口时删除对应模拟路径，不允许让生产逻辑静默回退到假数据。
• 删除、停用、改权限等高风险操作必须有明确确认、处理中、成功和失败反馈；失败时保留用户上下文，避免误以为已生效。
• 日志、提示和示例数据不得包含真实账号、令牌、客户隐私或生产数据。
• Admin 维护企业所属仓库、往来单位、快递公司等主数据时，必须通过平台企业列表显式选择目标企业；不得从本地存储推断租户。默认可优先选择历史租户 10001（不存在时选择列表第一项），企业雪花 ID 必须按字符串透传，切换企业时不得保留上一企业的编辑、详情或导入上下文。

UI 与交互

• 延续现有后台视觉体系：克制的企业级界面、清晰的信息层级和高密度但可扫描的数据展示。
• 优先使用 Element Plus 与现有复用组件；图标使用 Lucide，不用表情符号充当功能图标。
• 表格、筛选、抽屉和表单应按实际语义覆盖适用的加载、空数据、错误、禁用和无权限状态，不为不适用的组件机械增加状态。
• 保持键盘可操作、可见焦点、表单标签和足够的颜色对比度；不要只用颜色表达状态。
• 新页面至少适配现有 320px 最小宽度策略，并检查侧栏、表格、抽屉和表单在窄屏下的退化方式。

本地命令与质量门禁

在 apps/admin-web 目录执行：

pnpm install
pnpm dev
pnpm test
pnpm typecheck
pnpm build

• 日常变更至少运行 pnpm typecheck 和受影响测试；交付前运行 pnpm test 与 pnpm build，后者也会执行类型检查。
• 当前项目未声明 lint 脚本，不要声称 lint 已通过。若任务新增或变更质量脚本，应同时更新 package.json、README.md 和本文件。
• 不手工修改 dist/ 或 node_modules/；依赖变更必须同步当前项目的 package.json 与锁文件。