Admin Web Instructions

快速读取顺序

用“模块快速路由”选择最小业务模块，进入后读取该目录最近的 AGENTS.md；按 routes.ts → pages/ → api/types/stores/composables 下钻，不先扫描全部 src/。
视觉还原、布局/交互承载方式变更或真实页面验收时读取 ../../docs/Admin-Client前端原型还原验收规则.md；需要原型依据才读取 ../../docs/悦/货代SAAS平台后台/AGENTS.md 并定位目标片段。纯文案、逻辑或单元测试任务不自动读取。 Admin 样式优化还须读取 ../../docs/Admin高密度界面规范.md 的“样式维护边界”和“新模块接入规则”；以已确认密度与彩色页签为视觉基线，逐操作保留业务语义和承载方式。国内仓、客户管理是样板；新增菜单按本轮范围显式接入，货柜管理入口见 ../../docs/Admin货柜管理样式核对记录.md。
标准列表或公共组件任务读取 src/shared/components/AGENTS.md；国内/海外 HTTP、Token 或刷新任务读取 src/shared/api/AGENTS.md；Finance 任务读取 src/modules/finance/AGENTS.md；海外仓全流程任务先读 ../../docs/海外仓业务/README.md。
平台/客户层级与权限公共语义读取 ../../docs/平台客户层级与权限契约.md；统一 API、Token、会话撤销或可靠事件任务按需读取 ../../docs/统一认证与服务通信契约.md 对应章节。

普通单端任务的最小读取集是本文件、目标模块最近的 AGENTS.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，不提交真实地址或凭据。

模块快速路由

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

路径从应用根起算，modules/、core/ 从 src/ 起算；接口片段与符号沿同一行代码定位。

业务	首个入口
登录、会话与统一 Token	`modules/auth/`、`core/auth/`
启动与懒加载资源恢复	`src/main.ts`、`core/routing/navigationRecovery.ts`
工作台与指标	`modules/dashboard/`
自营销量、库存与数据采集	`modules/self-operated/AGENTS.md`
船期日历	`modules/sailing-calendar/`
预约管理、预约列表、跨客户同仓预约	`modules/appointment-calendar/`、`modules/overseas-warehouse/`
FBA 无匹配价格、人工定价	`modules/inbounds/fee/api.ts`、`createManualInboundQuote`
PDA版本、APK下载、WGT热更新发布与停发	`modules/pda-releases/pages/PdaReleasesView.vue`、`modules/pda-releases/api/pdaReleases.ts`
客户、企业审核、客户统计	`modules/customers/`
供应商、国内整柜	`modules/suppliers/`、`modules/domestic-containers/`
平台仓库与仓储资源	`modules/warehouses/`、`modules/warehouse-resources/`
平台用户、RBAC、导航	`modules/iam/`、`core/access/`
国内/海外 PDA 独立人员与海外仓绑定	`modules/iam/pages/InternalUsersView.vue`、`modules/iam/api/platformIam.ts`
消息中心	`modules/notifications/`
订单列表、批量审核预览、详情、商品图片与入库费用	`modules/unified-orders/`、`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/measurement/InboundMeasurementDialog.vue`、`modules/inbounds/measurement/InboundMeasurementPanel.vue`
一件代发托盘打印	`modules/unified-orders/pages/UnifiedOrdersView.vue`、`modules/inbounds/core/DropshipPalletPrintPanel.vue`
入库单扣货、解除、凭证与历史	`modules/inbounds/pages/InboundOrdersView.vue`、`modules/inbounds/core/api.ts`
客户专属价格簿、柜级阶梯运费与受控调价	`modules/fba-pricing/carrier-rates/pages/CarrierRatesView.vue`、`modules/fba-pricing/carrier-rates/pages/CarrierRateDetailView.vue`
财务、客户资金账户与柜级公共费用分摊	`modules/finance/AGENTS.md`
货柜双工作台、排柜、预装/装柜清单、真实柜号后补与整柜报关	`modules/container-loading/pages/DomesticContainersView.vue`、`modules/container-loading/pages/OverseasContainersView.vue`
合柜报关 / 同柜不可拆组	`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/`、`modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue`
订舱级拖车预约	`modules/trucking/api/platformTrucking.ts`、`/candidates`
目的港码头拖车与还空预警	`modules/container-loading/pages/OverseasContainersView.vue`、`modules/container-loading/pages/OverseasContainerDetailView.vue`
历史报关协同与国内出仓	`modules/customs/`、`modules/outbound-dispatch/`
主数据、下载、退避任务重试、审计	`modules/master-data/`、`modules/downloads/pages/DownloadCenterView.vue`
海外接柜、入库、库存与库内服务	`modules/overseas-warehouse/`
海外采购、卡车、散板	`modules/overseas-business/`
海外仓业务合作仓与通用资料	`modules/warehouses/`、`modules/overseas-master-data/`
海外仓业务国内出仓后船节点	`modules/port-schedules/`、`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 当前只验收 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 执行：

pnpm install
pnpm dev
pnpm test
pnpm typecheck
pnpm build

源码、依赖或构建配置变更至少运行 pnpm typecheck 和受影响测试，交付前运行 pnpm test 与 pnpm build；不影响代码、契约或配置的纯文档/索引变更只检查路径、链接及索引合同。当前没有 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 验收后仍由人工完成页面和截图确认。

13 KiB Raw Blame History Unescape Escape