client-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 适配层和测试；本包不反向定义服务端行为。
• 避免建立宽泛的万能类型或引入重量级依赖。

兼容性与验证

• 修改导出名称、字段类型、枚举值或常量语义前，搜索当前应用内全部消费者。
• 优先采用兼容性新增；破坏性修改必须同步更新当前应用消费者。
• 本包没有独立质量脚本；变更后运行父应用声明的类型检查、测试或构建命令。

一期/二期/三期契约索引

• 一期共享模型主要服务客户认证、企业资料/成员权限和头程订单：修改订单状态、仓库摘要、资质或权限枚举前，核对 ../../../docs/一期/一期头程订单闭环设计.md 及后端 Controller/DTO/OpenAPI，并搜索 src/modules/ 全部消费者。
• 二期只在客户侧承接到仓与计费结果的展示契约。WAIT_SPLIT + APPROVED + CONFIRMED 是当前技术闭环终点，内部测量明细、备注和文件权限不可通过共享类型绕过；费用字段必须与后端 firstleg/ 契约兼容。
• 三期当前 NO-GO。不得为了预留分柜、装柜、PDA 或报关字段而提前扩展公共枚举；待 ../../../docs/三期/三期需求确认表.md 中 P3-Q1/Q2/Q5/Q9/Q11/Q12/Q13 解除后，再以兼容新增方式定义模型，并同步所有 Client 消费者。

阶段文档入口（路径相对本文件所在目录）：一期 ../../../docs/一期/README.md；二期 ../../../docs/二期/README.md 与 ../../../docs/二期/二期需求优化版-v2-测量计费入库主流程.md；三期 ../../../docs/三期/README.md、../../../docs/三期/三期开发规划.md 和 ../../../docs/三期/三期需求确认表.md。阶段文档优先级高于历史进度表和原型。