`

shared/AGENTS.md

@@ -0,0 +1,28 @@
+# Shared Package Instructions
+
+## 项目定位
+
+- 本包提供跨应用共享的 TypeScript 类型、常量、轻量工具和可复用资源。
+- 当前公共能力包括产品名称、用户模型、导航模型、API 响应模型和头程订单状态常量。
+- 只有具有明确跨项目语义，或已经被两个或以上项目稳定复用的能力才进入本包；单一应用的页面状态、UI 组件和临时业务逻辑留在对应项目。尚无消费者的契约型导出必须标记为暂定，并有对应 API 或产品决策依据。
+
+## 公共 API 与依赖边界
+
+- `src/index.ts` 是当前唯一公共入口。新增导出应有清晰命名和稳定语义，不让消费者依赖未导出的内部实现。
+- 公共类型保持平台无关，不依赖 DOM、Vue、微信、uni-app 或 Node 专属运行时，除非任务明确改变本包定位。
+- 不在共享类型中编码客户端鉴权结论；租户隔离、权限和数据合法性仍由 `services/api` 最终校验。
+- 避免以“复用”为由建立宽泛的万能类型。优先使用小而明确的模型，并区分请求、响应、领域状态和展示模型。
+- 新增依赖前先确认原生 TypeScript 能力或现有依赖无法满足需求；本包不应成为所有应用依赖的重量级入口。
+
+## 兼容性与变更原则
+
+- 修改导出名称、字段类型、枚举值或常量语义前，搜索所有消费者并评估兼容性。
+- 优先采用向后兼容的新增；删除或破坏性修改必须同步更新全部消费者，并在交付说明中明确迁移影响。
+- API 契约文档是服务端落地后的唯一权威来源；共享包只映射经确认的客户端模型，不反向定义服务端行为。API 尚未落地前，`ApiResponse` 和订单状态等无消费者导出视为暂定，不得当作已发布契约。
+- 状态码、权限码和业务常量应有唯一来源，不在多个应用中复制维护相同列表。
+
+## 质量门禁
+
+- 当前包未声明独立的安装、测试、类型检查或构建脚本，不得声称这些检查已在本包内通过。
+- 变更公共导出后，至少运行现有消费者的类型检查；当前直接消费者包括 `apps/admin-web` 和 `apps/client-web`。
+- 若新增本包自己的质量脚本，应同步更新 `package.json`、`README.md` 和本文件，并为公共工具及兼容性边界增加测试。