ouyangxq
b34626bd4b
新增 29 个模块级 AGENTS.md，补齐入口表指向，使 33 个业务模块均可从入口直达页面与接口。 - 每个模块指引统一为：路径基准 / 页面与入口表 / 关键边界 / 验证入口 - 入口表 35 行改为指向 modules 下的 AGENTS.md，补齐费用项目、审计日志、尺寸配置、装柜照片等缺失词条 - 详细索引最长行从 1315 字符压缩到 699 字符，规则正文移入新增的“货柜工作台规则”小节 - 仅索引文档，未改动业务代码
127 lines
14 KiB
Markdown
127 lines
14 KiB
Markdown
# Admin Web Instructions
|
||
|
||
## 快速读取顺序
|
||
|
||
1. 用“模块快速路由”选择最小业务模块，进入后读取该目录最近的 `AGENTS.md`；按 `routes.ts → pages/ → api/types/stores/composables` 下钻，不先扫描全部 `src/`。
|
||
2. 视觉还原、布局/交互承载方式变更或真实页面验收时读取 `../../docs/Admin-Client前端原型还原验收规则.md`；需要原型依据才读取 `../../docs/悦/货代SAAS平台后台/AGENTS.md` 并定位目标片段。纯文案、逻辑或单元测试任务不自动读取。
|
||
Admin 样式优化还须读取 `../../docs/Admin高密度界面规范.md` 的“样式维护边界”和“新模块接入规则”；以已确认密度与彩色页签为视觉基线，逐操作保留业务语义和承载方式。国内仓、客户管理是样板；新增菜单按本轮范围显式接入，货柜管理入口见 `../../docs/Admin货柜管理样式核对记录.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` 对应章节。
|
||
|
||
普通单端任务的最小读取集是本文件、目标模块最近的 `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`，不提交真实地址或凭据。
|
||
|
||
## 模块快速路由
|
||
|
||
按短表定位后按需查 [业务细则](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 当前只验收 `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
|
||
```
|
||
|
||
- 源码、依赖或构建配置变更至少运行 `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 验收后仍由人工完成页面和截图确认。
|