# AGENTS.md

本文件用于约束在 `Loan/client` 仓库内工作的 AI agent / 协作者，目标是让改动更稳、更贴近当前项目结构，并减少无关返工。仓库信息变化后，请同步更新此文件。

## 项目概览

- 项目名称：`Loan Assistant` / `借贷助手` 客户端
- 技术栈：`Expo 55`、`React Native 0.83`、`React 19`、`TypeScript`、`expo-router`、`NativeWind 4`、`@ant-design/react-native 5`
- 目标平台：`iOS`、`Android`、`Web`
- 包管理器：仓库包含 `pnpm-lock.yaml`，默认优先使用 `pnpm`
- 当前 UI 基调：浅色主题，根布局与全局 Provider 在 `src/app/_layout.tsx`

## 常用命令

- 安装依赖：`pnpm install`
- 启动开发环境：`pnpm start`
- 启动 Android：`pnpm android`
- 启动 iOS：`pnpm ios`
- 启动 Web：`pnpm web`
- 代码检查：`pnpm lint`

如果必须使用 `npm`，请确保不要混乱提交锁文件；默认仍以 `pnpm-lock.yaml` 为准。

## 目录约定

- `src/app`：`expo-router` 路由入口、`layout`、页面级 screen 文件
- `src/app/(tabs)`：底部标签页相关路由
- `src/components`：跨页面复用组件
- `src/components/ui`：更基础的 UI 组件与页面积木
- `src/hooks`：自定义 hooks
- `src/utils`：基础能力与业务支撑工具，例如 `api`、`auth`、`storage`
- `src/constants`：主题和常量
- `src/global.css`：`NativeWind` 全局样式入口
- `assets`：运行时资源
- `design`：设计参考稿或静态参考资料，默认不作为运行时代码来源
- `docs/antd`：本地 Ant Design RN 参考文档，新增或调整组件时优先查阅
- `android`、`ios`：原生工程，除非是原生能力、权限、构建配置相关改动，否则不要随意修改
- `dist`：构建产物目录，不要手工编辑

## 代码组织规则

- 路由文件尽量保持轻量，复杂 UI 和业务逻辑优先下沉到 `src/components`、`src/hooks`、`src/utils`
- 本项目已配置路径别名：
  - `@/*` -> `src/*`
  - `@/assets/*` -> `assets/*`
- 新页面优先放在 `src/app` 下对应路由位置，不要回退到旧式集中路由表
- 涉及标签页结构时，同时检查 `src/app/(tabs)/_layout.tsx`
- 平台差异优先通过 `*.web.tsx` 等平台文件处理，避免在单文件里堆过多平台分支
- 尽量复用已有基础组件，不要在页面里重复造按钮、输入框、弹窗、状态标签

## UI 与样式约定

- 样式方案以 `NativeWind + global.css + tailwind.config.js` 为主
- 组件型交互优先复用 `@ant-design/react-native`
- 根节点已经包裹 `@ant-design/react-native` 的 `Provider`，全局 Provider 变更集中放在 `src/app/_layout.tsx`
- 项目已有一套 Tailwind 扩展颜色和圆角 token，新增样式优先复用，不要到处散落魔法值
- 如果引入新的 Ant Design RN 组件，先查 `docs/antd/llms-semantic.md` 或 `docs/antd/llms-full.txt`
- Web 与 Native 表现如果需要分流，优先延续现有 `component.tsx` / `component.web.tsx` 结构

## 数据、认证与存储

- 网络请求优先复用 `src/utils/api.ts` 中的统一请求封装，不要重复创建新的 axios client
- 接口地址与版本信息优先从现有配置读取，不要在页面或组件中硬编码 base URL
- 鉴权上下文在 `src/utils/auth.tsx`，修改登录态逻辑时同步检查 Provider、hook、请求头注入
- 本地持久化与缓存使用 `src/utils/storage.ts` 中的 `MMKV` 封装，避免绕过统一入口

## 工程约定

- TypeScript 处于 `strict` 模式，新增代码不要用 `any` 糊过去，必要时补充明确类型
- `expo-router` 已启用 `typedRoutes`，新增路由时保持类型友好
- 项目开启了 `reactCompiler`，默认不要为了“优化”到处添加 `useMemo` / `useCallback`
- JS 层改动默认不要动 `android/`、`ios/`
- 配置类文件如 `app.json`、`babel.config.js`、`metro.config.js`、`tailwind.config.js` 修改前先确认影响范围
- 不要引入重量级新依赖，除非现有方案明显无法满足需求

## Agent 工作方式

- 开始前先看 `git status --short`，确认工作区是否已有用户未提交改动
- 不要回滚与当前任务无关的变更
- 先阅读相关文件，再改代码；避免“按印象重写”
- 优先做最小必要改动，保持与现有风格一致
- 修改公共能力时，检查调用方是否需要同步更新
- 如果改动影响路由、鉴权、全局 Provider、主题或构建配置，在说明中明确指出

## 验证要求

- 最低要求：执行 `pnpm lint`
- 如果改动影响页面交互、路由、平台差异或构建配置，尽量补充对应平台验证
- 如果因为环境限制无法完成验证，需要在最终说明中明确写出“未验证项”

## 提交说明建议

最终汇报建议至少包含以下信息：

- 改了什么
- 为什么这么改
- 怎么验证
- 还有哪些风险或待补充项

## 待项目负责人补充