From 1e26ddad4b41ac86a1c0d6d29027500b3a2f578f Mon Sep 17 00:00:00 2001 From: ouyangxq <775153912@qq.com> Date: Tue, 20 Oct 2026 12:01:43 +0800 Subject: [PATCH] docs(client): add module-level AGENTS indexes for all 11 modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 11 个模块级 AGENTS.md，覆盖企业工作台全部业务模块，入口表统一指向模块指引。 - 统一四段式：路径基准 / 页面与入口表 / 关键边界 / 验证入口 - 补明“页面 -> store -> API”的调用链路，避免只给目录 - 仅索引文档，未改动业务代码 --- AGENTS.md | 28 +++++++++---------- src/modules/account/AGENTS.md | 26 ++++++++++++++++++ src/modules/auth/AGENTS.md | 30 ++++++++++++++++++++ src/modules/cross-border/AGENTS.md | 30 ++++++++++++++++++++ src/modules/dashboard/AGENTS.md | 26 ++++++++++++++++++ src/modules/finance/AGENTS.md | 29 ++++++++++++++++++++ src/modules/first-leg/AGENTS.md | 35 ++++++++++++++++++++++++ src/modules/notifications/AGENTS.md | 28 +++++++++++++++++++ src/modules/order-management/AGENTS.md | 30 ++++++++++++++++++++ src/modules/overseas-warehouse/AGENTS.md | 34 +++++++++++++++++++++++ src/modules/system/AGENTS.md | 24 ++++++++++++++++ src/modules/tenant-management/AGENTS.md | 30 ++++++++++++++++++++ 12 files changed, 336 insertions(+), 14 deletions(-) create mode 100644 src/modules/account/AGENTS.md create mode 100644 src/modules/auth/AGENTS.md create mode 100644 src/modules/cross-border/AGENTS.md create mode 100644 src/modules/dashboard/AGENTS.md create mode 100644 src/modules/finance/AGENTS.md create mode 100644 src/modules/first-leg/AGENTS.md create mode 100644 src/modules/notifications/AGENTS.md create mode 100644 src/modules/order-management/AGENTS.md create mode 100644 src/modules/overseas-warehouse/AGENTS.md create mode 100644 src/modules/system/AGENTS.md create mode 100644 src/modules/tenant-management/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index e8d2eab..6546d57 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,23 +41,23 @@ 本表只保留首个入口；完整 API、字段、状态与恢复规则见 [按需业务索引](docs/business-index.md)。从本应用根执行 `rg -n -F '任务词或文件名' docs/business-index.md` 读取命中条款；涉及业务行为变更时必须核对对应细则，纯定位不全文加载。保留所有适用的最近模块指引。 -表中路径均相对本应用根目录。 +表中路径均相对本应用根目录。模块指引中的后端类名以服务名起算，如 `firstleg/service/X.java` 即 `baiyue-firstleg/firstleg/src/main/java/com/baiyue/firstleg/service/X.java`。 | 业务 | 首个入口 | |---|---| -| 登录、注册与会话 | `src/modules/auth/`、`src/api/session.ts`、`src/api/http.ts` | -| 企业资料、成员与角色 | `src/modules/tenant-management/`、`src/modules/account/` | -| 工作台与系统入口 | `src/modules/dashboard/`、`src/modules/system/` | -| 企业成员消息收件箱 | `src/modules/notifications/` | -| 头程下单、中文批量导入、入仓码关系、箱唛、履约进度与入库费用确认 | `src/modules/first-leg/`、`src/modules/first-leg/views/FirstLegOrdersView.vue`、`src/modules/first-leg/api/firstLeg.ts` | -| 装柜完成后的退税报关资料 | `src/modules/first-leg/views/FirstLegOrdersView.vue`、`src/modules/first-leg/components/CustomsDocumentsDialog.vue`、`src/modules/first-leg/api/customs.ts` | -| 统一订单展示 | `src/modules/order-management/` | -| 客户财务账单、入仓码联查、收款、未收余额与客户确认 | `src/modules/finance/`、`src/modules/finance/views/FinanceBillsView.vue`、`src/modules/finance/api/finance.ts` | -| 客户资金账户、授信与充值申请 | `src/modules/finance/views/FinanceAccountView.vue`、`src/modules/finance/api/account.ts` | -| 海外采购 | `src/modules/cross-border/routes.ts`、`src/modules/cross-border/views/ProcurementView.vue`、`src/modules/cross-border/components/ProcurementDetailPanel.vue` | -| 美国本土卡与美本土散板 | `src/modules/cross-border/routes.ts`、`src/modules/cross-border/components/BusinessOrdersView.vue`、`src/modules/cross-border/api/businessOrders.ts` | -| 海外仓入库订单 | `src/modules/order-management/routes.ts`、`src/modules/order-management/views/InboundOrdersView.vue`、`src/modules/order-management/api/inboundPlans.ts` | -| 海外仓贴标、仓储转运、货物废弃 | `src/modules/overseas-warehouse/routes.ts`、`src/modules/overseas-warehouse/views/WarehouseServiceView.vue`、`src/modules/overseas-warehouse/api/warehouseServices.ts` | +| 登录、注册与会话 | `src/modules/auth/AGENTS.md`、`src/api/session.ts`、`src/api/http.ts` | +| 企业资料、成员与角色 | `src/modules/tenant-management/AGENTS.md`、`src/modules/account/AGENTS.md` | +| 工作台与系统入口 | `src/modules/dashboard/AGENTS.md`、`src/modules/system/AGENTS.md` | +| 企业成员消息收件箱 | `src/modules/notifications/AGENTS.md` | +| 头程下单、中文批量导入、入仓码关系、箱唛、履约进度与入库费用确认 | `src/modules/first-leg/AGENTS.md` | +| 装柜完成后的退税报关资料 | `src/modules/first-leg/AGENTS.md`、`src/modules/first-leg/components/CustomsDocumentsDialog.vue` | +| 统一订单展示 | `src/modules/order-management/AGENTS.md` | +| 客户财务账单、入仓码联查、收款、未收余额与客户确认 | `src/modules/finance/AGENTS.md` | +| 客户资金账户、授信与充值申请 | `src/modules/finance/AGENTS.md` | +| 海外采购 | `src/modules/cross-border/AGENTS.md` | +| 美国本土卡与美本土散板 | `src/modules/cross-border/AGENTS.md` | +| 海外仓入库订单 | `src/modules/order-management/AGENTS.md` | +| 海外仓贴标、仓储转运、货物废弃 | `src/modules/overseas-warehouse/AGENTS.md` | ## 租户、认证与数据安全 diff --git a/src/modules/account/AGENTS.md b/src/modules/account/AGENTS.md new file mode 100644 index 0000000..54c46b1 --- /dev/null +++ b/src/modules/account/AGENTS.md @@ -0,0 +1,26 @@ +# Client 个人资料模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/account/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `views/AccountProfileView.vue`、`utils/accountProfile.ts`；路由 `account/profile`。 +- 后端：个人资料归 `iam/`（`PersonalProfileService.java`），登录手机号变更经 `auth/` 同步并撤销会话。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 个人资料查看与修改 | `views/AccountProfileView.vue`；`account/profile` | `../tenant-management/api/merchantIam.ts`；`iam/` | +| 表单校验与展示映射 | `utils/accountProfile.ts` | 服务端字段 | + +## 关键边界 + +- 个人资料只改本人信息；企业资料（含 `contactPhone`）归 `../tenant-management/`，两处不互相回填。 +- 登录手机号修改由 IAM/Auth 处理并撤销该账号现有会话，前端不自行清理 Token。 +- 敏感字段（证件号、密码）不在页面持久化，也不写入日志或快照。 +- 保存需要明确成功/失败反馈，失败保留已填内容。 + +## 验证 + +- 定向：`pnpm test src/modules/account/<目标测试>`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/auth/AGENTS.md b/src/modules/auth/AGENTS.md new file mode 100644 index 0000000..abaec55 --- /dev/null +++ b/src/modules/auth/AGENTS.md @@ -0,0 +1,30 @@ +# Client 登录与注册模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/auth/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 页面：`views/LoginView.vue`、`views/RegisterView.vue`、`views/LegalDocumentView.vue`（`/login`、`/register`、`/legal/*`）；会话状态在 `store/auth.ts`，请求在 `api/auth.ts`。 +- 后端：登录与 Token 归 `auth/`，注册与资质归 `iam/` + `file/`。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 登录、记住账号 | `views/LoginView.vue` | `api/auth.ts`、`store/auth.ts`；`auth/` | +| 企业注册与资质上传 | `views/RegisterView.vue` | `api/auth.ts`；`iam/`、`file/` | +| 用户协议与隐私政策 | `views/LegalDocumentView.vue`、`legalDocuments.ts` | 静态文案 | +| 认证壳层与布局 | `components/AuthShell.vue` | — | +| 令牌解析与刷新 | `store/auth.ts`、`utils/jwt.ts` | `../../api/http.ts`、`../../api/session.ts` | + +## 关键边界 + +- 页面不拼 `Authorization`、不自行持久化密码；Access/Refresh Token 只在 `store/auth.ts` 与 `src/api/session.ts` 编排。 +- 注册时登录手机号同时初始化公司联系电话，注册完成后两者独立维护；企业资料只改 `contactPhone`。 +- “记住账号”只保存登录 ID，不改变 Token 的持久化与续期策略。 +- 注册必填资质仅营业执照与统一社会信用代码，法人身份证选填；上传成功不等于审核通过。 +- 并发或跨标签页 401 共用一次刷新，每个原请求最多重放一次。 + +## 验证 + +- 定向：`pnpm test src/modules/auth/<目标测试>`；登录或注册字段变化同时核对 `auth/`、`iam/` 合同。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/cross-border/AGENTS.md b/src/modules/cross-border/AGENTS.md new file mode 100644 index 0000000..0a296a9 --- /dev/null +++ b/src/modules/cross-border/AGENTS.md @@ -0,0 +1,30 @@ +# Client 跨境业务模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/cross-border/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，业务细则见 `../../../docs/business-index.md`。 +- 三条业务线共用本模块：`procurement`（海外采购）、`domestic-trucking`（本土卡车）、`pallet-shipping`（美本土散板）；每条都是独立列表 + 建单 + 详情路由。 +- 后端只查 `lastleg-service/` 的 `procurement/`、`trucking/`、`looseboard/`；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 海外采购列表、建单与详情 | `views/ProcurementView.vue`、`components/ProcurementDetailPanel.vue`；`cross-border/procurement`、`.../create`、`.../:orderNo/detail` | `api/procurement.ts`、`procurementSubmission.ts`、`procurementPresentation.ts`；`lastleg-service/procurement/` | +| 本土卡车列表、建单与详情 | `views/DomesticTruckingView.vue`、`components/TransportDemandForm.vue`；`cross-border/domestic-trucking`、`.../create`、`.../:orderNo/detail` | `api/businessOrders.ts`、`transportDemandForm.ts`；`lastleg-service/trucking/` | +| 美本土散板列表、建单与详情 | `views/PalletShippingView.vue`；`cross-border/pallet-shipping`、`.../create`、`.../:orderNo/detail` | `api/businessOrders.ts`；`lastleg-service/looseboard/` | +| 通用业务单展示与车次安排 | `components/BusinessOrdersView.vue`、`fleetArrangement.ts` | `api/businessOrders.ts`；`lastleg-service/fleet/trip/` | +| 柜型与规格换算 | `containerSpecifications.ts` | 本地换算，服务端复核 | + +## 关键边界 + +- 三条线都是客户自助下单，提交后由平台审核；客户侧不提供审核、改价或内部作业动作。 +- 客户与仓库范围只取服务端当前租户上下文，不从前端参数推断；跨客户查询一律拒绝。 +- 提交需要幂等键、提交中状态与可恢复失败反馈；失败保留已填内容。 +- 海外采购的购买、装箱、面单、交寄与国内核费是一条独立链路，改节点前先读 `docs/海外仓业务/采购订单样品履约流程变更需求.md`（工作区路径）。 +- 页面承载方式按已确认原型：列表 + 独立建单/详情路由，不改为弹框或抽屉。 + +## 验证 + +- 定向：`pnpm test src/modules/cross-border/<目标测试>`；接口或类型变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/dashboard/AGENTS.md b/src/modules/dashboard/AGENTS.md new file mode 100644 index 0000000..800ad98 --- /dev/null +++ b/src/modules/dashboard/AGENTS.md @@ -0,0 +1,26 @@ +# Client 工作台模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/dashboard/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `views/DashboardView.vue` 与 `overview.ts`；路由为空路径（登录后默认页）。 +- 后端按卡片来源分别查 `order/`、`firstleg/`、`lastleg-service/`；本模块只做聚合展示。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 业务总览卡片与快捷入口 | `views/DashboardView.vue` | `overview.ts`；按卡片对应的服务 | +| 卡片数据映射与跳转 | `overview.ts` | 各业务模块的公开 API | + +## 关键边界 + +- 只展示服务端或既有模块返回的数据，不在首页二次统计或补算。 +- 快捷入口跳转带明确业务筛选，不用标题文字反推状态。 +- 首页不新增跨客户对比或内部经营指标；客户只能看到本企业数据。 +- 卡片加载失败要单卡片降级，不阻塞整页。 + +## 验证 + +- 定向：`pnpm test src/modules/dashboard/<目标测试>`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/finance/AGENTS.md b/src/modules/finance/AGENTS.md new file mode 100644 index 0000000..b6fa4be --- /dev/null +++ b/src/modules/finance/AGENTS.md @@ -0,0 +1,29 @@ +# Client 财务模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/finance/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，账单与资金细则见 `../../../docs/business-index.md`。 +- 本模块只做客户可见的账单查询、客户确认与资金账户；费用来源、核销与账期归 `backend finance/`，不在前端重算。 +- 后端只查 `finance/`（账单、收款、账户与授信）；文件下载归 `file/`。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 客户财务账单列表、筛选与未收余额 | `views/FinanceBillsView.vue`；`finance/bills` | `api/finance.ts`；`finance/` 账单 | +| 账单详情、入仓码联查与客户确认 | `views/FinanceBillDetailView.vue`；`finance/bills/:billNo/detail` | `api/finance.ts`、`adapters.ts`；`finance/` | +| 客户资金账户、授信与充值申请 | `views/FinanceAccountView.vue`；`finance/account` | `api/account.ts`；`finance/` 资金账户 | +| 跨页契约与稳定类型 | `contracts.ts` | 服务端 DTO | + +## 关键边界 + +- 账单行只显示服务端返回的 `inboundCode`；缺失时显示“—”，不用内部 ID 或本地拼接回退。 +- 实际、冻结、可用余额、授信与流水只消费 Finance 权威结果，前端不自行汇总或推算。 +- 客户确认按服务端允许动作开放，提交金额与状态以服务端返回为准；已确认账单不得在前端改回。 +- 充值申请与账户操作携带幂等键与提交中状态，失败保留原输入。 +- 费用明细与柜级分摊只展示服务端结果；前端不参与分摊计算，也不把退税额或汇率写死。 + +## 验证 + +- 定向：`pnpm test src/modules/finance/<目标测试>`；接口或金额字段变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/first-leg/AGENTS.md b/src/modules/first-leg/AGENTS.md new file mode 100644 index 0000000..b162e7e --- /dev/null +++ b/src/modules/first-leg/AGENTS.md @@ -0,0 +1,35 @@ +# Client 头程模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/first-leg/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，字段与接口细则见 `../../../docs/business-index.md`。 +- 模块分层固定：`views/` 页面、`components/` 业务组件、`api/` 请求、`store/` 跨页状态、`types/`、`utils/`、`data/`；跨模块只能从本目录 `public.ts` 导入。 +- 后端只查 `order/`（订单读写与批量导入）、`firstleg/`（履约进度、入库费用、报关资料）、`file/`（资质与附件）；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 头程订单列表、详情、草稿编辑 | `views/FirstLegOrdersView.vue`；`orders/first-leg`、`orders/first-leg/:orderId/detail`、`orders/first-leg/:draftId/edit` | `api/firstLeg.ts`；`store/firstLegOrders.ts`；`order/` | +| 创建订单入口（选业务类型） | `views/FirstLegOrderCreateHubView.vue`；`orders/first-leg/create` | `components/FirstLegOrderEditorShell.vue` | +| 快速下单（按渠道/目的仓/SKU 生成草稿） | `views/QuickOrderView.vue`；`first-leg/quick-order` | `api/firstLeg.ts`；只生成草稿，不提交、不审核 | +| 中文批量导入与逐行结果 | 订单列表导入入口 | `api/firstLeg.ts`；`order/` 批量导入；入仓码与失败原因逐行展示 | +| 履约进度与入仓码关系 | `components/OrderProgressPanel.vue`、`components/InboundCodeAssociationDialog.vue` | `api/inboundCodeAssociations.ts`、`utils/orderProgress.ts`；`firstleg/` | +| 运输事实与商品图片 | `components/TransportFactsTable.vue`（纯展示）、`utils/transportFacts.ts`、`utils/productImage.ts` | 行数据类型来自 `api/unifiedOrders.ts`；图片读取归 `file/` | +| 入库费用确认与计费重 | `components/InboundBillingPanel.vue` | `api/inboundBilling.ts`；`firstleg/service/MerchantInboundBillingService.java` | +| 装柜后的退税报关资料 | `views/CustomsDocumentsView.vue`、`components/CustomsDocumentsDialog.vue` | `api/customs.ts`、`store/customsPending.ts`、`utils/customsEligibility.ts`；`firstleg/customs/`、`file/` | +| 船期与参考价格 | `views/SailingPricesView.vue`；`first-leg/sailing-prices` | `api/firstLeg.ts`；`firstleg/` 船期价格 | +| 往来单位候选 | `data/firstLegParties.ts`、`api/partners.ts` | `warehouse/` 公共往来单位 | + +## 关键边界 + +- 头程订单只用当前正式读写契约；不得扩展 `LEGACY_MANUAL`、旧系统入仓码、C02 不可用回退旧 API、历史部分响应兼容或其他新旧并跑逻辑。触及该链路时同步删除生产分支、类型、文案、Mock 和测试。 +- 快速下单只创建草稿，不提交、不审核；逐行失败必须回填原因与入仓码，不用内部 ID 代替业务编号。 +- 入库费用确认携带 `expectedFeeVersion` 与幂等键，金额与冻结状态只认服务端结果；所有订单行都可进入计费重弹框，不按行类型隐藏。 +- 报关资料在开始后只读冻结资料，未装柜或无资格时不展示入口；`utils/customsEligibility.ts` 是唯一资格判断入口。 +- 模块间协作只能从本模块 `public.ts` 导入，不穿透其他模块的 `views/` 或内部目录。 + +## 验证 + +- 定向：`pnpm test src/modules/first-leg/<目标测试>`；接口或类型变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/notifications/AGENTS.md b/src/modules/notifications/AGENTS.md new file mode 100644 index 0000000..643cf7f --- /dev/null +++ b/src/modules/notifications/AGENTS.md @@ -0,0 +1,28 @@ +# Client 消息中心模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/notifications/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 页面：`views/NotificationsView.vue`（收件箱）、`views/NotificationDetailView.vue`（详情）；状态在 `store/notifications.ts`，请求在 `api/notifications.ts`。 +- 后端归 `iam/` 的 `notification/` 子域；契约见 `notification-v1.yaml`。 + +## 页面与入口 + +| 目标 | 页面/入口 | API 与后端 | +|---|---|---| +| 消息收件箱、未读与分页 | `views/NotificationsView.vue` | `api/notifications.ts`、`store/notifications.ts`；`iam/notification/` | +| 消息详情与业务跳转 | `views/NotificationDetailView.vue` | `api/notifications.ts` | +| 文案与类型映射 | `presentation.ts`、`contracts.ts` | 服务端模板字段 | +| 对外导出 | `public.ts` | — | + +## 关键边界 + +- 未读计数与已读状态以服务端为准；本地乐观更新后必须回读，不长期保留本地计数。 +- 消息跳转只带业务编号（订单号、入仓码、派送号等），不用内部 ID 作参数或标题。 +- 只展示当前企业范围内的消息；模板变量由服务端填充，前端不补默认值。 +- 消息列表失败要可重试，不清空已有内容。 + +## 验证 + +- 定向：`pnpm test src/modules/notifications/<目标测试>`；字段变化同时核对 `notification-v1.yaml`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/order-management/AGENTS.md b/src/modules/order-management/AGENTS.md new file mode 100644 index 0000000..200f0a0 --- /dev/null +++ b/src/modules/order-management/AGENTS.md @@ -0,0 +1,30 @@ +# Client 订单管理模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/order-management/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，订单与入仓计划细则见 `../../../docs/business-index.md`。 +- 本模块承载客户可见的**统一订单、海外仓入仓计划与派送单**；头程下单与费用确认归 `../first-leg/`。 +- 后端只查 `lastleg-service/` 的 `inboundplan/`、`delivery/`；头程订单事实由 `../first-leg/` 与 `order/` 提供。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 我的订单（统一列表） | `views/MyOrdersView.vue`；`orders/my` | 复用 `../first-leg/api/unifiedOrders.ts`；`order/` | +| 海外仓入库订单列表与详情 | `views/InboundOrdersView.vue`；`orders/inbound`、`orders/inbound/:planNo/detail` | `api/inboundPlans.ts`、`inboundPlanDisplay.ts`；`lastleg-service/inboundplan/` | +| 派送单列表 | `views/DeliveryOrdersView.vue`、`views/deliveryOrders.css`；`orders/delivery` | `api/deliveryOrders.ts`；`lastleg-service/delivery/` | +| 派送单详情与签收结果 | `views/DeliveryOrderDetailView.vue`；`orders/delivery/:deliveryNo` | `api/deliveryOrders.ts` | +| 浏览器读屏验收脚本 | `receiptBrowserAcceptance.mjs` | 仅本地验收，不写业务数据 | + +## 关键边界 + +- 入仓计划与派送单对客户只读；任何状态推进由海外仓作业侧完成，客户端不提供完成/发车类动作。 +- 派送单按目的 FBA 仓拆分，列表与详情必须显示目的 FBA 仓；不得用单个出库号覆盖整批派送。 +- 业务标识用计划号、入仓码、派送号等正式编号；缺失显示“—”，不用内部 ID 回退。 +- 客户与仓库范围只取服务端当前租户上下文，不从前端参数推断。 +- 分页、筛选与导出只消费服务端结果，不在浏览器重排或本地累计。 + +## 验证 + +- 定向：`pnpm test src/modules/order-management/<目标测试>`；接口或类型变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/overseas-warehouse/AGENTS.md b/src/modules/overseas-warehouse/AGENTS.md new file mode 100644 index 0000000..fd770ff --- /dev/null +++ b/src/modules/overseas-warehouse/AGENTS.md @@ -0,0 +1,34 @@ +# Client 海外仓模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/overseas-warehouse/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，页面与字段细则见 `../../../docs/business-index.md`。 +- 五类自助业务共用三个页面文件：`WarehouseServiceView.vue`（贴标、仓储转运、货物废弃）、`ReturnOrdersView.vue`（退货预报与签收）、`ReturnInventoryView.vue`（退货库存与箱号）；按路由区分模式。 +- 后端只查 `lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`、`returnreceipt/`；资源与库位归 `warehouse-overseas-service/`；纯页面与文案不读后端。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 贴标申请列表、新建、详情 | `views/WarehouseServiceView.vue`；`overseas-warehouse/labeling`、`.../create`、`.../:detailNo/detail` | `api/warehouseServices.ts`；`lastleg-service/relabel/` | +| 仓储转运列表、详情与入库测量 | `views/WarehouseServiceView.vue`；`overseas-warehouse/storage-transfer`、`.../:detailNo/detail` | `api/warehouseServices.ts`、`api/transferPickups.ts`；`components/TransferPickupProgressPanel.vue`；`lastleg-service/transfer/` | +| 货物废弃列表、新建与详情 | `views/WarehouseServiceView.vue`；`overseas-warehouse/cargo-disposal`、`.../:detailNo/detail` | `api/warehouseServices.ts`、`utils/discardDocuments.ts`；`lastleg-service/discard/` | +| 退货预报、新建与签收详情 | `views/ReturnOrdersView.vue`；`overseas-warehouse/return-relabel`、`.../create`、`.../:returnNo/detail` | `api/returnOrders.ts`、`utils/returnReceiptDisplay.ts`；`lastleg-service/returnreceipt/` | +| 退货库存查询 | `views/ReturnInventoryView.vue`；`overseas-warehouse/return-inventory` | `api/returnInventory.ts` | +| 退货箱号与箱内明细 | `views/ReturnInventoryView.vue`；`overseas-warehouse/return-cartons`、`.../:cartonMark/detail` | `api/returnInventory.ts`、`utils/returnReceiptDisplay.ts` | +| 换标完工确认与驳回提示 | `components/CompletionConfirmationDialog.vue`、`components/ReviewRejectionNotice.vue`、`components/RelabelDocumentsPanel.vue` | `api/warehouseServices.ts`、`utils/relabelSkuDisplay.ts` | + +`views/LabelingView.vue`、`views/ReturnInboundView.vue`、`views/ReturnOutboundView.vue` 当前未在 `routes.ts` 注册；改动前先确认是否已废弃或仅被内嵌，不要据此认定页面开放。 + +## 关键边界 + +- 换标申请必须提交正数 CNY `chargeAmount`；金额与资金状态以服务端返回为准，不在客户端模拟冻结成功。 +- 退货预报与签收只消费服务端状态与箱号；退货库存按箱号和 SKU 查询，箱内明细以服务端实收为准，不按预报箱数推算。 +- 仓储转运的测量与打托由仓库侧完成，客户端只读展示与确认；转运进度以 `TransferPickupProgressPanel.vue` 消费的服务端事实为准。 +- 货物废弃在待审锁定与实际确认扣减之间不可回退，前端只按服务端允许动作开放按钮。 +- 页面承载方式按已确认原型：贴标、转运、废弃为独立路由页面，退货预报为独立页面，不擅自改为弹框或抽屉。 + +## 验证 + +- 定向：`pnpm test src/modules/overseas-warehouse/<目标测试>`；接口或类型变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/system/AGENTS.md b/src/modules/system/AGENTS.md new file mode 100644 index 0000000..5e2dec2 --- /dev/null +++ b/src/modules/system/AGENTS.md @@ -0,0 +1,24 @@ +# Client 系统页模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/system/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`。 +- 只有 `views/ForbiddenView.vue`（403 无权限页）与 `routes.ts`；不承载业务。 + +## 页面与入口 + +| 目标 | 页面/入口 | 说明 | +|---|---|---| +| 无权限提示页 | `views/ForbiddenView.vue` | 路由守卫或接口 403 后跳转 | +| 系统页路由 | `routes.ts` | 由 `../../router/index.ts` 装配 | + +## 关键边界 + +- 403 页只做提示与返回入口，不暴露权限码、内部角色或接口细节。 +- 不在此模块新增业务页面或全局状态。 +- 权限判断仍在服务端与 `core/access`，页面不补前端鉴权分支。 + +## 验证 + +- 定向：`pnpm test src/modules/system/<目标测试>`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。 diff --git a/src/modules/tenant-management/AGENTS.md b/src/modules/tenant-management/AGENTS.md new file mode 100644 index 0000000..eeb72ac --- /dev/null +++ b/src/modules/tenant-management/AGENTS.md @@ -0,0 +1,30 @@ +# Client 企业设置模块指引 + +## 路径基准与读取顺序 + +- 本文件适用于 `src/modules/tenant-management/`，代码路径相对本目录；应用公共规则见 `../../../AGENTS.md`，层级与权限语义见 `../../../docs/平台客户层级与权限契约.md`。 +- 本模块承载企业资料、成员、角色与权限（`company/profile`、`organization/*`）；账号与登录标识归 `backend auth/`，接入侧实现归 `backend iam/`。 +- 模块对外只暴露 `public.ts` 与 `contracts.ts`，其他模块不得穿透内部 `views/`、`store/`。 + +## 页面与入口 + +| 目标 | 页面/路由 | API 与后端 | +|---|---|---| +| 企业资料、资质上传与状态 | `views/CompanyProfileView.vue`、`utils/qualificationFile.ts`、`utils/qualificationStatus.ts`；`company/profile` | `api/merchantIam.ts`；`iam/`、`file/` | +| 企业成员管理 | `views/MembersView.vue`；`organization/members` | 页面经 `store/tenantAdministration.ts` → `api/merchantIam.ts`；`iam/`、`auth/` | +| 企业角色 | `views/RolesView.vue`；`organization/roles` | 页面经 `store/tenantAdministration.ts` → `api/merchantIam.ts`；`iam/` | +| 角色权限分配 | `views/PermissionsView.vue`；`organization/permissions` | 页面经 `store/tenantAdministration.ts` → `api/merchantIam.ts`；权限码常量见 `contracts.ts` | +| 跨页状态与稳定契约 | `store/tenantAdministration.ts`、`contracts.ts`、`public.ts` | 服务端 DTO | + +## 关键边界 + +- 企业资料只修改 `contactPhone` 等企业联系信息，不提交或回填成员登录手机号；两者独立维护。 +- 成员登录手机号可选；修改时由 IAM/Auth 同步并撤销该账号现有会话，前端不互相回填或联动提交。 +- 审核必填资质仅营业执照与统一社会信用代码；法人身份证选填，可在已有营业执照后单独补传或替换。 +- 企业成员、角色与权限只能管理当前企业范围；前端隐藏不是安全控制，服务端必须重复校验租户与权限。 +- 认证与会话统一经 `../../api/http.ts`、`../../api/session.ts`；页面不读写 Token，不自行处理 401 刷新。 + +## 验证 + +- 定向：`pnpm test src/modules/tenant-management/<目标测试>`；成员或权限字段变化同时运行 `pnpm typecheck`。 +- 本文件或索引变更后，从后端根运行 `./scripts/agents-index-contract.ps1`。