admin-web/shared/AGENTS.md

应用内 Shared Package Instructions

项目定位

• 本包只服务当前前端应用，提供多个业务模块共同使用的 TypeScript 类型、常量和轻量工具。
• 依赖保持为 @chongchong/shared: link:./shared，确保当前应用目录可作为独立容器构建上下文。
• 不承担 Admin、Client 之间的源码复用；跨应用字段需要分别映射同一份 Java Controller/OpenAPI 契约，不能通过目录外链接耦合两个部署单元。

公共 API 与依赖边界

• src/index.ts 是当前唯一公共入口；模块专属页面状态、UI 组件和临时业务逻辑留在对应模块。
• 共享类型保持前端平台无关，不编码鉴权结论；租户隔离、权限、状态机和数据合法性由 baiyue-firstleg Java 服务端最终保证。
• 服务端字段变化先核对 Controller、DTO 和 OpenAPI，再更新本应用的类型、API 适配层和测试；本包不反向定义服务端行为。
• 避免建立宽泛的万能类型或引入重量级依赖。

订单与客户/入库测量与计费/国内货柜履约共享模型索引

• 订单与客户共享消费者：customers、iam、warehouses、master-data、first-leg-orders；稳定导出集中在 src/index.ts（用户、导航、响应、仓库摘要、订单状态）。
• 入库测量与计费共享消费者：inbounds、warehouse-resources、fba-pricing、dimension-config、unified-orders；单模块使用的测量、费用、托盘、库位类型留在模块内，只有真实跨模块复用才新增导出。
• 国内货柜履约仅在服务端字段、权限和 OpenAPI 已稳定，且确有多个 Admin 模块复用时才新增共享导出；先读 ../../../docs/国内货柜履约/国内货柜履约开工门禁.md。订单、柜次、证据和报关的单模块类型仍留在所属模块，不在 shared 预留猜测字段。

定位规则：先在 src/index.ts 确认公共导出，再搜索 src/ 消费者；后端字段或状态有疑问时回到对应 Controller/DTO/OpenAPI，不在 shared 中猜测业务规则。

阶段依据（路径相对本文件所在目录）：订单与客户 ../../../docs/订单与客户/，入库测量与计费 ../../../docs/入库测量与计费/，国内货柜履约 ../../../docs/国内货柜履约/；共享包不保存阶段进度，也不承载跨应用（Client）源码复用。

契约与验证

• 修改导出名称、字段类型、枚举值或常量语义前，搜索当前应用内全部消费者。
• 当前开发阶段按目标模型直接修改；破坏性修改必须同步更新当前应用全部消费者、测试和接口映射，不保留旧模型兼容分支。
• 本包没有独立质量脚本；变更后运行父应用声明的类型检查、测试或构建命令。