mobile-app/AGENTS.md

Mobile App Instructions

项目定位

• 本项目面向企业客户和业务人员，提供独立移动端应用体验。
• 规划范围为登录、企业身份、头程下单、订单查询、审批、结算、消息和个人中心。
• 与 client-web 共享业务语义和后端契约，但移动端只实现适合移动场景的流程，不机械复制桌面工作台。

当前阶段门禁

• 当前技术栈、目标平台、最低系统版本、发布渠道和一期范围尚未确认。
• 未形成明确决策前，不创建正式脚手架、不引入移动框架、不生成锁文件，也不假设原生、跨端或 WebView 方案。
• 技术选型至少比较原生能力、跨端复用、包体与性能、推送、支付或系统权限、可访问性、测试和发布成本。
• 决策完成后先更新 README.md、依赖清单和本文件，再开始功能实现；把准确的安装、运行、测试和构建命令写入文档。

产品与架构原则

• 以短路径和单手操作为优先，复杂管理能力留在客户工作台；核心任务要有清晰的中断与恢复机制。
• 认证、租户、用户、订单和结算模型应与 services/api 及 packages/shared 的公共契约保持一致，平台专属适配留在应用内部。
• 将页面、领域状态、API 适配、设备能力和持久化隔离，禁止业务代码直接散落调用平台原生接口。
• 网络访问统一处理超时、取消、重试、令牌失效和标准错误；涉及创建订单、审批、结算的请求必须考虑幂等。
• 离线能力只覆盖明确批准的场景；缓存数据必须有过期和清除策略，不将敏感数据长期明文保存在设备上。

安全、体验与质量

• 不记录密码、完整令牌、身份证明、结算凭据或客户隐私；截图、日志和崩溃报告也遵守该规则。
• 权限请求遵循最小化与按需原则，说明用途并处理用户拒绝、系统限制和权限被撤销的情况。
• 每个流程覆盖加载、空数据、弱网、离线、重复提交、会话过期和服务端失败状态。
• 支持动态字体、屏幕阅读器、足够触控区域、可见焦点或选中态以及横竖屏和安全区域。
• 技术栈确定后建立单元、组件和关键流程测试，并以真实声明的命令作为交付门禁；在此之前记录人工验证设备和系统版本，不虚构自动化结果。