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 或契约，不得引用其他模块的页面、内部组件或内部目录。

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

按阶段处理需求时，先核对仓库根目录对应阶段文档，再按“模块目录 → `routes.ts`/页面 → `api`/类型”定位；阶段范围高于原型中的全量菜单。模块代码均从 `src/` 起算。本表只描述 Admin 页面、路由和前端契约，不替代后端模块指引。

| 阶段 | Admin 范围与入口 | 当前边界 |
|---|---|---|
| 一期：头程订单闭环 | `modules/auth/` 登录；`customers/` 客户与企业审核；`iam/` 内部用户、角色、权限；`warehouses/` 平台收货仓；`master-data/` 快递公司、往来单位；`first-leg-orders/` 头程订单；`dashboard/` 工作台 | 功能基本完成，处于测试环境部署、样本补齐和验收收口；企业审核已合并客户列表，平台 RBAC 仅维护平台员工与平台权限资源 |
| 二期：到仓与头程计费 | `modules/inbounds/` 入库预报、收货、测量/OCR、审核、差异与费用快照；`warehouse-resources/pallets/` 托盘；`warehouse-resources/locations/` 库位；`fba-pricing/`、`dimension-config/` 计费规则与尺寸配置；`unified-orders/` 订单工作流编排 | 页面范围停在 `WAIT_SPLIT + APPROVED + CONFIRMED`；海外仓阶梯费用页面是否开放需单独确认；客户侧可见字段按授权结果映射，内部备注、文件和原始证据不得进入 Client 契约 |
| 三期：国内出仓 | 已确认范围可复用 `first-leg-orders/`、`unified-orders/`、`ocean-bookings/`、`trucking/`，新增能力按稳定契约拆分模块 | 已确认业务规则可进入页面与接口实现；仅未稳定的接口、权限、数据模型和验收项阻断对应页面的发布。不得把原型中的完整 WMS、海外仓或未确认功能提前展示 |

阶段文档入口（路径相对本文件所在目录）：一期读 `../../docs/一期/一期开发进度表.md` 与 `../../docs/一期/一期头程订单闭环设计.md`；二期读 `../../docs/二期/README.md`、`../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md` 及联调报告；三期读 `../../docs/三期/README.md`、`../../docs/三期/三期开发规划.md`、`../../docs/三期/三期需求确认表.md` 和页面清单。阶段状态与代码现状冲突时，以需求确认和验收证据为准，并在改动说明中记录。

## 业务与安全约束

- 当前产品层级只有平台和客户（企业）两级；Admin 不把“租户”作为用户可见概念，不新增租户选择器、目标租户文案或依赖租户上下文才能使用的页面流程。多租户产品能力后续单独设计。
- 平台仓库是公共主数据，不与客户绑定。托盘、库位等仓储资源页面必须能够独立查询全部客户和全部仓库，选择客户不得缩小、清空或禁用仓库候选。
- 后端兼容字段 `tenantId` 仅留在 API 适配层和内部类型中，不在页面文案或交互中暴露；需要客户范围的写操作仍显式选择客户，长整型客户 ID 按字符串透传。

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

## UI 与交互

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

## 公共前端组件复用

- 开发或重构页面前，先检查 `src/shared/components/`，不得在业务页面重复实现已有的查询栏、数据表格、批量导入、弹窗、抽屉、加载错误、状态和复制交互。公共组件无法满足时，先判断能力是否具有跨模块复用价值：通用能力扩展公共组件并补测试；纯业务特例留在所属模块，不用页面级 CSS 覆盖破坏公共组件契约。
- 查询与筛选统一使用 `src/shared/components/QueryToolbar.vue`。通过 `fields` 配置 `input`、`select`、`date`、`daterange`，使用 `v-model` 管理查询模型，并监听 `search`、`reset`；额外操作放入 `actions` 插槽。不要在每个列表页重新编写筛选容器、查询/重置按钮和移动端换行样式。
- 业务数据列表统一使用 `src/shared/components/DataTable.vue`。通过 `columns` 和命名插槽定义列，使用 `v-model:page`、`v-model:page-size` 及 `total` 接入分页；无需分页时可省略 `total`。不得重复拼装 `el-table` 与分页器；“操作”列仍须遵守仓库根规则，放在第一列，固定时固定在左侧。
- 标准 XLSX 批量导入/上传统一使用 `src/shared/components/BatchImportDialog.vue`。页面只维护弹窗开关，传入标题、实体名称、模板文件名、`downloadTemplate` 和 `importFile`，并在 `success` 后刷新列表；文件格式和大小校验、模板下载、提交状态、接口错误、整批校验结果、CSV 错误报告及响应式样式由组件负责。不要在页面内重复创建文件输入框、上传状态、错误报告逻辑或导入弹窗 CSS。
- 普通模态框和侧滑编辑/详情优先使用 `src/shared/components/AppDialog.vue`、`AppDrawer.vue`，复用提交锁定、加载态、底部按钮和窄屏约束；仅当业务交互与其契约明显不同时直接使用 Element Plus 原始容器。
- 列表或详情加载失败优先组合 `src/shared/components/LoadErrorState.vue` 与 `ApiErrorMeta.vue`，保留重试入口及 `requestId`、`traceId`；状态展示和复制操作分别优先使用 `StatusBadge.vue`、`CopyButton.vue`。
- 公共组件的使用示例优先参考已接入页面：查询和表格见 `modules/master-data/express-companies/pages/ExpressCompaniesView.vue`，批量导入见该页面及 `modules/master-data/counterparties/pages/PartnersView.vue`，抽屉见 `modules/downloads/pages/DownloadCenterView.vue`。扩展公共组件时同步检查所有现有消费者，并至少运行组件测试和直接受影响页面测试。

## 本地命令与质量门禁

在 `apps/admin-web` 目录执行：

```bash
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` 与锁文件。