# Admin Web Instructions

## 快速读取顺序

1. 由“模块快速路由”选最小模块并读最近 `AGENTS.md`，按 `routes.ts → pages/ → api/types/stores/composables` 下钻，不扫描全部 `src/`。
2. Admin 样式唯一入口为 [Admin 界面规范](../../docs/Admin高密度界面规范.md#按任务阅读)，按任务只读对应章节；提示小字、加载布局、蓝白风格及密度不再分散查多份规范。样板目录仅在需要视觉参考时查，模块核对记录仅在核对范围、业务例外或验收证据时查。
   视觉、布局/交互承载变更或真实页面验收再读 [前端验收规则](../../docs/Admin-Client前端原型还原验收规则.md)；需原型依据再读 `../../docs/悦/货代SAAS平台后台/AGENTS.md` 并定位片段。纯文案、逻辑或单元测试不触发验收矩阵。
3. 标准列表/公共组件读 `src/shared/components/AGENTS.md`；HTTP、Token/刷新读 `src/shared/api/AGENTS.md`；Finance 读 `src/modules/finance/AGENTS.md`；海外仓全流程先读 `../../docs/海外仓业务/README.md`。
4. 平台/客户层级及权限读 `../../docs/平台客户层级与权限契约.md`；统一 API、Token、会话撤销或可靠事件按需读 `../../docs/统一认证与服务通信契约.md` 对应章节。

单端仅读本指引、最近模块指引及命中代码；跨服务状态、权限或接口边界不明才加后端契约。预算遵循根指引，先读适用规则、定向查业务表，跳过无关专题。

## 项目定位与技术基线

- 本项目是虫虫出海内部运营后台，仅服务平台员工；不承载企业客户自助、官网、小程序、独立 APP 或 PDA 作业。
- 使用 Vue 3、TypeScript 严格模式、Vite、Vue Router、Pinia、Element Plus、Axios 和 Lucide Vue；保持 ES Module、现有无分号风格和 `@` 对 `src/` 的别名。
- 不用 `any` 绕过业务模型。模块专属类型留在模块，本应用多模块稳定复用的类型放 `src/shared/`；服务端契约以 Controller/OpenAPI 为准。
- Element Plus 使用现有自动导入；Vue API 显式导入。`src/auto-imports.d.ts`、`src/components.d.ts` 是生成声明，不手工维护业务内容。
- 不更换框架、路由、状态管理、组件库或构建工具，除非任务明确要求并完成影响评估。

## 目录与依赖方向

| 目录 | 职责 |
|---|---|
| `src/app/` | 应用装配、布局、根路由、全局守卫和启动；不承载业务 |
| `src/core/` | 认证、访问控制、导航、路由安全等全应用能力；不得依赖业务模块 |
| `src/modules/` | 稳定业务领域的页面、API、类型、组件和模块路由；新增业务页面不放根级 `views/` |
| `src/shared/` | 无业务归属的 HTTP、组件和工具；只有真实跨模块复用才上移 |
| `src/prototype/` | 未纳入当前迭代的原型实现；正式模块不得依赖 |
| `src/styles/` | 设计令牌和全局样式，优先复用 `--cc-*` 变量 |

- 依赖方向为 `app → modules/core/shared`、`modules → core/shared`、`core → shared`、`shared → 无上层依赖`。模块间只通过对方公开入口或契约协作，不引用其他模块的页面和内部目录。
- 路由级页面放 `modules/*/pages/`，模块路由放 `modules/*/routes.ts` 并由 `app/router/index.ts` 装配；新增模块同步维护 `core/navigation/adminNavigation.ts`。
- 领域接口放 `modules/*/api/`；全部业务共用 `shared/api/http.ts`，具体 Token 与刷新规则见 `shared/api/AGENTS.md`。
- `VITE_API_BASE_URL` 控制唯一浏览器前缀；`API_PROXY_TARGET` 由 Vite 读取并指向统一 Gateway。环境变量变化同步 `.env.example`，不提交真实地址或凭据。

## 模块快速路由

按短表定位后按需查 [业务细则](docs/business-index.md)；涉及业务行为变更时必须核对对应细则及最近模块指引。从应用根执行 `rg -n -F '任务词或文件名' docs/business-index.md`，只读命中条款。

路径从应用根起算，`modules/`、`core/` 从 `src/` 起算；接口片段与符号沿同一行代码定位。模块指引中的后端类名以服务名起算，如 `firstleg/service/X.java` 即 `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/X.java`。

| 业务 | 首个入口 |
|---|---|
| 登录、会话与统一 Token | `modules/auth/AGENTS.md`、`core/auth/` |
| 启动与懒加载资源恢复 | `src/main.ts`、`core/routing/navigationRecovery.ts` |
| 工作台与指标 | `modules/dashboard/AGENTS.md` |
| 自营销量、库存与数据采集 | `modules/self-operated/AGENTS.md` |
| 船期日历 | `modules/sailing-calendar/AGENTS.md` |
| 预约管理、预约列表、跨客户同仓预约 | `modules/appointment-calendar/AGENTS.md`、`modules/overseas-warehouse/` |
| FBA 无匹配价格、人工定价 | `modules/inbounds/fee/api.ts`、`createManualInboundQuote` |
| PDA版本、APK下载、WGT热更新发布与停发 | `modules/pda-releases/AGENTS.md` |
| 客户、企业审核、客户统计 | `modules/customers/AGENTS.md` |
| 供应商、国内整柜 | `modules/suppliers/AGENTS.md`、`modules/domestic-containers/AGENTS.md` |
| 平台仓库与仓储资源 | `modules/warehouses/AGENTS.md`、`modules/warehouse-resources/AGENTS.md` |
| 平台用户、RBAC、导航 | `modules/iam/AGENTS.md`、`core/access/` |
| 国内/海外 PDA 独立人员与海外仓绑定 | `modules/iam/pages/InternalUsersView.vue`、`modules/iam/api/platformIam.ts` |
| 消息中心 | `modules/notifications/AGENTS.md` |
| 订单列表、批量审核预览、详情、商品图片与入库费用 | `modules/unified-orders/AGENTS.md`、`modules/first-leg-orders/` |
| 客户原始申报资料编辑与渠道变更 | `modules/unified-orders/components/OrderDeclarationEditorDialog.vue`、`modules/unified-orders/api/unifiedOrders.ts` |
| 入库扣货、解除与凭证历史 | `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/api.ts` |
| 入库、测量、称重库位状态、客户箱规策略与计价主数据 | `modules/inbounds/AGENTS.md`、`modules/dimension-config/AGENTS.md` |
| 一件代发托盘打印 | `modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/DropshipPalletPrintPanel.vue` |
| 入库单扣货、解除、凭证与历史 | `modules/inbounds/pages/InboundOrdersView.vue`、`modules/inbounds/core/api.ts` |
| 客户专属价格簿、柜级阶梯运费与受控调价 | `modules/fba-pricing/AGENTS.md`、`modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue` |
| 财务、客户资金账户与柜级公共费用分摊 | `modules/finance/AGENTS.md` |
| 货柜双工作台、排柜、预装/装柜清单、装柜照片与证据、真实柜号后补与整柜报关 | `modules/container-loading/AGENTS.md`、`modules/loading-lists/AGENTS.md` |
| 合柜报关 / 同柜不可拆组 | `modules/unified-orders/api/coLoadGroups.ts`、`modules/unified-orders/pages/UnifiedOrdersView.vue` |
| 全局智能装柜工作台、入仓码候选与箱数分配 | `modules/container-loading/components/SmartLoadingDialog.vue`、`modules/container-loading/pages/GlobalSmartLoadingView.vue` |
| 国内货柜履约订舱资料、打印、关联候选与出仓前船期 | `modules/ocean-bookings/AGENTS.md` |
| 订舱级拖车预约 | `modules/trucking/AGENTS.md` |
| 目的港码头拖车与还空预警 | `modules/container-loading/AGENTS.md` |
| 历史报关案件、报关回执与国内出仓 | `modules/customs/AGENTS.md`、`modules/outbound-dispatch/AGENTS.md` |
| 主数据、下载、退避任务重试 | `modules/master-data/AGENTS.md`、`modules/downloads/AGENTS.md` |
| 费用项目、计费科目 | `modules/fee-items/AGENTS.md` |
| 操作日志、审计日志、操作人 | `modules/audit/AGENTS.md` |
| 海外接柜、入库、库存与库内服务 | `modules/overseas-warehouse/AGENTS.md` |
| 海外采购、卡车、散板 | `modules/overseas-business/AGENTS.md` |
| 海外仓业务合作仓与通用资料 | `modules/warehouses/AGENTS.md`、`modules/overseas-master-data/AGENTS.md` |
| 海外仓业务国内出仓后船节点 | `modules/port-schedules/AGENTS.md`、`modules/ocean-bookings/` |
| 海外排车、出库与派送 | `modules/overseas-warehouse/AGENTS.md` |
| 海外异常退回与客户回访 | `modules/overseas-warehouse/AGENTS.md` |

## 海外模块内部快速索引（海外仓全流程）

海外仓作业先读 `src/modules/overseas-warehouse/AGENTS.md`；采购、车队等页面/API 联查按需查 `docs/business-index.md` 同名节。

## 业务、安全与共享装配

- 当前只有平台、客户两级；Admin 不显示“租户”。平台仓库是公共主数据，不与客户绑定；客户筛选不得缩小仓库候选。完整语义见平台客户层级与权限契约。
- 新建客户时，公司联系电话同时初始化首个管理员登录手机号；创建后公司联系电话只属于企业资料，与首个管理员、成员及平台用户登录手机号独立。编辑客户资料不得提交账号手机号变更，账号手机号改动统一走用户管理并由 IAM/Auth 撤销对应会话。
- 菜单、列表路由和详情只读统一使用 `*:list`，写操作使用独立权限；前端守卫不能替代服务端鉴权。供应商固定使用 `platform:supplier:list`。
- 平台用户选择 `OVERSEAS_WAREHOUSE_PDA_OPERATOR` 时必须选择唯一实际海外收货仓，其他角色不得提交 `overseasWarehouseId`；编辑时保留已绑定仓库并按字符串透传长整型 ID，前端校验不能替代 IAM 服务端约束。
- 国内出仓以真实货柜为原子边界：货柜详情只在装柜完成、全部入仓绑定门禁通过且有写权限时显示确认离仓；成功后由服务端同事务推进全部技术行并幂等创建船节点查询。前端不得逐入仓确认、把拖车状态当阻断门禁或重复追加实际船节点。
- `core/navigation/adminNavigation.ts`、`app/router/index.ts` 和模块 `routes.ts` 是共享装配文件；并行任务不得覆盖总控已确认语义，重叠时保留现有改动并回传总控。
- `core/routing/navigationRecovery.ts` 只处理已识别的动态 import/Chunk 资源过期；普通路由错误直接提示。自动恢复前保护未保存表单，同一目标 30 秒内不得重复刷新或形成重载循环。
- 认证统一经过 `core/auth/auth.ts` 和 `shared/api/http.ts`。登录/刷新替换统一 Access/Refresh Token，全部 401 共用刷新并最多重放一次；页面不读写 Token 或手工拼 `Authorization`。
- 接入真实接口时删除对应模拟路径，不允许生产逻辑静默回退假数据。客户专属写操作显式选择客户，长整型 ID 按字符串透传，不从本地存储推断。
- 订舱代理、拖车承运商和报关代理提交服务端供应商 ID，从公共供应商列表选择 `ACTIVE` 且类别/范围匹配的记录；参数变化同步检查 API、类型、表单、展示、Mock/Fixture、测试和 OpenAPI。
- 删除、停用、改权限等高风险操作必须有确认、处理中、成功和失败反馈；失败保留用户上下文。日志、提示和示例不得包含真实账号、Token、隐私或生产数据。
- 页面外观遵循 Admin 界面规范，业务及操作承载核对当前契约、逐操作确认与原型证据；Admin 当前只验收 `1920×1080`、`100%` 缩放。标准列表和共享组件实现继续读 `src/shared/components/AGENTS.md`。

## 开发验收身份

- 开发环境人工验收身份为 `platform_admin`。密码从未提交的 `CHONGCHONG_ADMIN_ACCEPTANCE_PASSWORD` 或 `C:/Users/BY-OY/.codex/chongchong-global-dev-acceptance.env` 读取；缺失时再向用户索取，不写入仓库、日志或快照。
- 视觉验收由人工操作真实页面并截图，AI 核对受影响的状态和桌面布局；缺少截图标记“待人工截图确认”，不自行批量取证。自动检查单独报告“自动检查通过/失败”；纯逻辑且无视觉变化标记“无需视觉验收”，不能据此声称真实页面验收通过。

## 命令与质量门禁

- 国内仓、客户管理密度默认值统一维护在 `src/styles/adminDensityTokens.css`，通用按钮/页签/描述表/弹框规则统一维护在 `adminDensity.css`；页面只选择公共类与语义参数、保留业务布局，不复制通用外观或在页面重新定义 `--admin-*` 默认值。修改前沿实际引用读取模块 CSS，接管后删除冲突旧声明。
- 修改密度样式或接入消费者时更新并运行 `src/styles/adminDensity.test.ts` 维护合同；不得为通过检查删除权限、业务提交或错误处理断言。未接入菜单通过显式密度类隔离。

在 `apps/admin-web` 执行：

```bash
pnpm install
pnpm dev
pnpm test
pnpm typecheck
pnpm build
```

- 按 `../../docs/AI工程执行与协作约束.md` 的“验证范围选择”执行；命令表不是每轮清单。文案/纯展示核对差异，局部逻辑跑定向测试，不自动 typecheck、全量测试或构建。类型关系、模板绑定或模块引用可能受影响时，补最小类型检查；公共能力沿实际消费者验证。
- 构建和全量测试分别按实际影响触发，先说明扩大范围的原因；不因提交或对话收尾触发。仅复用同配置、同文件范围且相关输入未变的成功编译结果。纯文档/索引只检查路径、链接及索引合同。无 lint 脚本，不声称 lint 通过。
- 不手工修改 `dist/`、`node_modules/` 或生成声明；依赖变化同步 `package.json` 与锁文件。
- 测试环境全量验收入口为 `../../baiyue-firstleg/scripts/admin-test-env-acceptance.mjs`，模块说明见同仓库 `scripts/admin-test-env-modules/README.md`；它会写入或停用测试数据，只有本轮明确授权才能运行。
- `pnpm test/typecheck` 和本地回归脚本不代表真实服务验收完成；HTTP 验收后仍由人工完成页面和截图确认。