222 篇博文含有标签「iCoding」

个人简介

查看所有标签

节约使用cursor

2026年1月9日 · 阅读需 1 分钟

Quany

软件工程师

微信公众号

节约使用cursor

2026年1月8日 · 阅读需 8 分钟

Quany

软件工程师

想让 Cursor 这个强大的 AI 编程助手既高效又省钱，核心在于理解其运作机制并掌握一些关键技巧。下面我为你整理了一份从基础到进阶的实用指南。

💸 理解 Cursor 的计费方式

首先，清楚钱花在哪里是节约的第一步。Cursor 的计费主要基于以下两种模式之一：

按交互次数计费：在某些版本中，你与 AI 的一次问答（你提问，AI 一次回答）被视为一次交互。每个计费周期通常有免费的交互额度，用完后需要付费或使用慢速队列。
按 Token 计费：这是更本质的计费单位。Token 是 AI 处理文本的基本单位，可以理解为字符或单词。总消耗 = 输入 Token + 输出 Token + 上下文 Token。你提供给 AI 的提示、AI 生成的代码/文本、以及对话历史中所有需要被 AI“记住”的内容都会消耗 Token 。

基于以上计费原理，可以采取以下节约策略。

🧠 优化你的提问方式

高效的提问能显著减少来回沟通的次数和无效输出。

需求明确具体：避免模糊的指令。与其说“帮我写个函数”，不如详细说明技术栈、具体功能、约束条件等。
- 不推荐：帮我写代码
- 推荐：用React Hooks实现一个计数器组件，要求具备增加、减少、重置功能，使用TypeScript编写，状态通过useState管理 。
分阶段处理复杂任务：对于大型功能，不要试图在一个对话中完成。将其拆分为设计、核心功能实现、异常处理、优化等阶段，分步进行。这比一次性请求能节省大量 Token 。
先要方案，再要代码：对于复杂逻辑，可以先开启 Plan Mode 或直接提示 AI 先给出实现计划和方案。你确认方案可行后，再让它生成代码，避免在错误方向上浪费额度。

🔧 善用工具与控制上下文

上下文管理是控制 Token 消耗的关键，因为对话历史越长，消耗的 Token 越多。

精准引用上下文：使用 @ 符号精确地告诉 AI 需要关注哪些文件、文档或过去的对话 (@file, @docs, @past chats)，而不是让 AI 自动加载可能不相关的全部上下文。
管理对话长度：避免所有对话都在一个窗口中进行。为不同的、复杂的任务开启新的独立对话框，以保持每个对话的上下文简洁，减少幻觉和 Token 浪费。
活用 NotePads：对于冗长的需求文档或接口说明，可以先将内容整理到 NotePads 中。在新对话中直接 @NotePads，就能让 AI 基于所有内容生成代码，避免在对话框中粘贴大量文本。
配置 .cursorignore 文件：将项目中不需要被 AI 索引的文件（如 node_modules, 构建产物、日志文件等）忽略掉，可以减少 AI 构建索引时的负担和无关上下文的干扰。

⚙️ 精细配置与模型选择

选择合适的模型：Cursor 提供多种 AI 模型。对于简单的代码补全、行内修改（Ctrl/Cmd + K），默认的 gpt-4o-mini 等较轻量模型通常足够且便宜。处理复杂架构设计时，再切换至 Claude 3.5/3.7 等更强但更贵的模型。
智能配置 Project Rules：Project Rules 是指导 AI 行为的项目规范，但它本身也会作为上下文消耗 Token 。
- 模式选择：对于个人或小型项目，建议使用 Selective Apply（选择性应用）模式，仅在需要时通过 @rules 触发相关规则，这比 Always Apply（始终应用）模式更节省 Token 。
- 规则优化：将规则分级，只将最关键的规定（如安全规则、基础命名规范）设为核心规则。同时，尽量使用简洁的语言编写规则。

下面的表格对比了不同规则应用模式的优缺点：

应用模式	优点	缺点	适用场景
Always Apply	保证代码一致性	固定 Token 开销，可能包含不相关规则	团队协作、企业级项目
Selective Apply	按需使用，灵活性强，节省 Token	可能忘记应用规则	个人项目、预算有限时

💎 核心省钱口诀

总结一下，最核心的节约心法如下：

口诀	具体做法
问题质量 > 问题数量	花时间构思精准的提示词，一次性把需求说清楚。
手动控制 > 自动加载	主动使用 `@` 引用，而非依赖 AI 自动猜测上下文。
任务拆分 > 一蹴而就	将大任务拆成小步骤，分而治之。
合适模型 > 最强模型	根据任务难度匹配模型，好钢用在刀刃上。
人工校验 > 盲目信任	始终检查 AI 生成的代码，避免错误修改导致更多成本。

希望这些技巧能帮助你更高效、更经济地使用 Cursor。如果你对某个特定功能（比如 Rules 的详细配置或 Agent 模式的高级用法）有进一步兴趣，我很乐意提供更具体的介绍。

编写高效的 Project Rules 确实是一门平衡艺术，既要让 AI 精准产出高质量代码，又要避免不必要的资源消耗。下面这个表格总结了高效 Rules 的四大核心原则，你可以先快速了解其精髓。

原则	核心目标	对代码质量的影响	对 Token 节省的贡献
最小化 (Minimization)	规则精炼、专注、可执行	避免模糊指令，提高生成代码的准确性和一致性	减少每次请求携带的冗余信息，直接降低 Token 消耗
结构化 (Structured)	规则模块化、分层次、有边界	让 AI 在特定场景下获得最相关的指导，减少“幻觉”和错误	实现规则的“按需加载”，避免不相关的规则占用上下文
精准引用 (Explicitness)	明确告诉 AI“何时用何规则”	确保 AI 在正确的时机遵循正确的规范，输出稳定可靠	通过 RuleType 等机制精确控制上下文，避免整个规则库被全部发送
一致性 (Consistency)	保持代码风格和架构的统一	提升代码的可维护性和可读性，便于团队协作和后续开发	减少因风格不一致导致的返工和重复生成，间接节省 Token

🛠️ 编写高质量规则的具体方法

掌握了核心原则后，我们来看看如何将它们付诸实践。

使用命令式、否定式语言 规则的本质是指令，而非建议。使用果断、明确的语气，能显著提高 AI 的服从度。
- 不推荐 (模糊、解释型)：“建议优先使用函数式组件。”
- 推荐 (命令式)：“使用 React 函数式组件和 Hooks。”
- 推荐 (否定式)：“禁止绕过 Repository 层直接操作数据库。”
采用新的 .cursor/rules/ 目录结构 放弃传统的单一 .cursorrules 文件。现在更推荐的做法是在项目根目录创建 .cursor/rules/ 文件夹，然后将规则分门别类地存放在不同的 .mdc 文件中。这样做的好处是结构清晰，便于维护，并能更好地与 RuleType 配合实现精准引用。
善用 RuleType 实现精准控制 在每个 .mdc 文件的顶部，你可以通过 YAML front matter 定义 RuleType，这是实现 Token 节省的关键。
- Always：始终生效的通用规则，如项目核心行为、通用代码风格。
- Apply to Specific Files：仅当编辑特定类型文件（如 *.py）时才生效，专用于语言或框架规则。
- Apply Manual：仅在聊天中通过 @规则文件名 显式引用时才生效，适合不常用的特定规则。

💾 最大化节省 Token 的实战技巧

利用 Cache Read 机制 在同一对话中，AI 对已读过的内容（包括规则文件）的后续读取成本会大幅降低。因此，应将相关任务放在同一个对话中完成，而不是每个小任务都开启新对话。
规则内容本身要精炼
- 避免解释性语言：规则中不要写“为什么”，只写“做什么”和“不做什么” 。
- 多用示例代码：对于复杂的模式或规范，一个简短的代码示例比大段文字描述更有效且更省 Token 。
将规则文件纳入版本控制 这不仅便于团队协作，还能确保所有成员和 AI 都基于同一套最新的规则进行开发，避免因规则不一致导致的重复修改和 Token 浪费。

🔍 验证规则是否生效

编写规则后，需要进行测试。你可以尝试让 AI 做一个明显违反规则的操作（例如：“给这个函数添加功能，先不用写测试”）。如果 AI 拒绝执行并提醒你需要遵守测试规则，说明规则已成功生效。

希望这份指南能帮助你打造出既高效又经济的 Project Rules。如果你在实践过程中遇到具体问题，比如针对某个特定框架的规则编写，我很乐意提供更进一步的探讨。

微信公众号

电脑智能化

2026年1月7日 · 阅读需 3 分钟

Quany

软件工程师

实现通过 Email 与 Claude Code 对话的核心方案是使用开源工具 Claude Code Remote。它通过邮件收发机制实现远程控制，非常适合长任务监控和移动办公场景。

核心实现原理

该工具采用 邮件中继 方式工作：

任务完成通知：本地 Claude Code 执行完任务后，自动发送结果邮件到你的邮箱
指令回复：你直接回复该邮件，在正文中写入新指令
自动执行：监控服务检测到白名单邮箱的回复后，自动将指令发送给 Claude Code
循环交互：重复上述流程，实现连续的远程对话

完整配置步骤

前期准备

Node.js 18+ 环境
一个支持 IMAP/SMTP 的邮箱（如 Gmail、Outlook）
tmux 终端复用工具

安装配置

# 克隆项目
git clone https://github.com/JessyTsui/claude-code-remote
cd claude-code-remote

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env

编辑 .env 文件，填入邮箱配置和白名单：

EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
ALLOWED_SENDERS=your-phone-email@gmail.com,your-colleague@company.com

启动服务

需要 两个终端窗口 配合运行：

终端 1：启动邮件监控服务

npm run relay:pty
# 显示 "🚀 Claude Code Remote is running! 📧 Monitoring emails..." 即成功

终端 2：在 tmux 中启动 Claude Code

# 创建新会话
tmux new-session -s my-claude-session

# 在 tmux 中正常启动 Claude
claude

使用流程演示

发起任务：在 tmux 的 Claude 界面输入指令

分析当前目录下所有 Python 文件的复杂度

接收通知：任务完成后，邮箱收到标题为 "Claude Code Remote Task Complete [#ABC123]" 的邮件

回复指令：直接回复邮件，正文写：

把结果生成一个 Markdown 报告，保存到 reports/ 目录

自动执行：回到 tmux 窗口，会看到 Claude 自动接收新指令并执行
持续交互：可无限循环回复邮件，直到任务完成

关键特性与优势

特性	说明
客户端兼容	支持所有邮件客户端（网页版、手机 App、桌面应用）
安全机制	发送者白名单验证 + 会话隔离 + 自动超时
连续对话	支持多轮指令，保持上下文连贯
网络要求	无需公网 IP 或内网穿透，有邮箱即可控制
场景适配	适合长任务监控、远程开发、团队协作

注意事项

邮箱安全：建议使用应用专用密码而非主密码
Token 消耗：每次邮件交互都会消耗 Claude API 额度，重度使用月费约 $100-200
超时设置：长时间未操作的会话会自动失效，需重新启动
环境分离：生产环境建议单独配置 .env.production 文件

该方案已验证可行，多个开发者正在使用。如需更轻量级的实现，也可以基于 Python 编写简易邮件监控脚本调用 Claude API，但完整功能推荐使用 Claude Code Remote 项目。

微信公众号

电脑智能化

2026年1月1日 · 阅读需 1 分钟

Quany

软件工程师

ubuntu

网络配置:安装网卡驱动

sudo apt update
sudo apt install bcmwl-kernel-source

AI不间断运行

邮件往来审批 AI 执行

微信公众号

软件开发需求分类

2025年12月27日 · 阅读需 5 分钟

Quany

软件工程师

在中国软件开发实践中，需求分类已形成与国际接轨且符合本土管理规范的完整体系。以下是基于国内主流方法论（如软考、ASPICE标准、GB/T标准）及行业实践整理的需求分类框架：

一、按抽象级别和来源划分（三级需求体系）

这是中国软件工程领域最标准的分层方式，广泛应用于系统集成、政企项目及大型产品开发：

1. 业务需求（Business Requirements）

定义：组织或业务部门的高层次目标，关注"为什么要做"
来源：客户高层、业务战略、市场分析
示例："提升订单处理效率30%"、"实现跨部门数据打通"
文档形式：项目愿景与范围文档、商业论证

2. 用户需求（User Requirements）

定义：最终用户对系统的期望，描述"用户想要什么"
获取方式：访谈、问卷、用户故事、场景分析
示例："用户能通过手机号快速注册"、"支持批量导入Excel数据"
文档形式：用户故事（敏捷）、用例规约（传统）

3. 系统需求（System Requirements）

定义：系统必须实现的具体技术特性和约束，说明"系统必须做什么"
子类型：
- 功能需求：具体功能点（如"登录验证需支持短信验证码"）
- 非功能需求：性能、安全性、可靠性等质量属性（如"响应时间≤3秒"）
文档形式：软件需求规格说明书（SRS）

追溯关系：业务需求 → 用户需求 → 系统需求（双向可追溯性）

二、按性质划分（功能 vs 非功能）

这是开发团队执行层面的核心分类，直接影响技术方案：

功能需求（Functional Requirements）

定义：系统必须完成的业务功能或服务
占比：通常占需求总数的60-70%
示例：
- 用户登录、权限管理
- 订单创建、支付处理
- 数据导入导出
验证方法：功能测试、接口测试

非功能需求（Non-functional Requirements，NFR）

定义：系统应满足的质量属性或约束条件

关键类别：

类别	说明	示例
性能需求	响应时间、吞吐量	"支持1000并发用户"
安全性需求	数据保护、访问控制	"符合等保2.0三级要求"
可靠性需求	可用性、容错性	"系统可用性≥99.9%"
兼容性需求	软硬件环境适配	"支持Android 8.0+"
可维护性	代码规范、扩展性	"采用微服务架构"
合规性需求	法律、行业标准	"符合GDPR数据保护条例"

国内实践要点：非功能需求在合同验收中占比越来越高，尤其是政府项目对安全和性能有强制性要求。

三、按优先级划分（MoSCoW与Kano模型）

中国项目管理中常用的优先级划分方法：

1. MoSCoW方法

Must Have（必须有）：核心功能，不满足则项目失败
Should Have（应有）：重要功能，但可延期实现
Could Have（可以有）：增值功能，资源允许时实现
Won't Have（暂不需要）：明确排除在本次范围外

2. Kano模型

将需求分为三类：

基本需求：必须满足，否则用户极度不满（如系统稳定性）
期望需求：满足程度与用户满意度成正比（如界面美观度）
兴奋需求：超出预期，带来惊喜（如AI智能推荐）

四、其他重要分类维度

1. 产品与过程需求

产品需求：对软件本身的要求（如"验证用户输入合法性"）
过程需求：对开发过程的约束（如"必须使用Java开发"、"需通过CMMI三级评审"）

2. 接口需求

用户接口：UI/UX设计规范
硬件接口：设备、传感器连接要求
软件接口：第三方API、中间件集成
通信接口：协议、数据格式（如RESTful API）

3. 派生需求 vs 基本需求

基本需求：用户直接提出的原始需求
派生需求：从技术实现或系统约束推导出的间接需求（如"因安全要求需增加日志审计功能"）

五、中国本地化实践特点

1. 政策与合规驱动分类

监管需求：如《数据安全法》《个人信息保护法》要求的数据存储、跨境传输限制
信创适配需求：国产CPU（鲲鹏、飞腾）、操作系统（统信UOS、麒麟）、数据库适配
等保/分保需求：明确的安全等级保护要求

2. 招投标导向分类

在政企项目中，需求常被分为：

实质性需求：必须响应，否则废标（功能、性能指标）
非实质性需求：评分项（界面美观、培训服务等）

3. 敏捷开发中的需求分层

国内互联网大厂普遍采用：

Epic（史诗）：跨多个迭代的业务目标
Feature（特性）：可交付的用户价值模块
User Story（用户故事）：可在一个迭代内完成的细粒度需求
Task（任务）：开发任务

六、需求分类的最佳实践

尽早建立可追溯性：使用需求管理工具（如Jira、PingCode、Ones）建立业务需求到代码的双向追溯
量化非功能需求：避免"快速响应"等模糊描述，必须量化（如"95%请求响应小于1秒"）
分类评审机制：每类需求由不同角色评审（业务需求-客户签字，系统需求-架构师评审）
动态调整：采用敏捷模式，每迭代重新评估优先级，适应市场变化

通过清晰的需求分类，中国软件团队能有效应对需求蔓延、评审效率低、验收标准模糊等常见问题，也是通过软考高级系统分析师、CMMI/ASPICE认证的关键能力要求。

微信公众号

TODO List

2025年12月18日 · 阅读需 1 分钟

Quany

软件工程师

下拉选择 [ ] 返回头

微信公众号

React Native 中实现流畅的列表下拉刷新和上拉加载更多功能

2025年12月17日 · 阅读需 13 分钟

Quany

软件工程师

在 React Native 中实现流畅的列表下拉刷新和上拉加载更多功能，关键在于理解核心组件并合理管理状态。下面我将为你梳理最佳实践方案。

🔄 核心实现方案

实现下拉刷新和上拉加载主要有两种路径：使用 React Native 官方提供的组件，或者借助功能丰富的第三方库。

方案	核心组件/库	优点	适用场景
官方方案	`FlatList` + `RefreshControl`	稳定性高，无需额外依赖，官方维护	需要标准、轻量级的刷新加载功能，项目限制外部依赖
第三方库	`react-native-SmartRefreshLayout` 等	功能丰富，UI 定制性强，可能跨平台一致性更好	需要更精美的动画效果或更复杂交互

使用官方 FlatList 方案

这是最直接、最常用的方法。FlatList 组件自身就提供了实现这些功能的关键属性：

下拉刷新 (onRefresh & refreshing): 通过 refreshing 属性控制刷新状态指示器的显示，onRefresh 属性指定下拉时触发的函数。
上拉加载更多 (onEndReached): 当列表滚动到底部阈值时触发 onEndReached 回调函数。

一个结合 Hooks 的基本示例代码如下：

import React, { useState, useCallback } from 'react';
import { FlatList, Text, View, ActivityIndicator, RefreshControl } from 'react-native';

const AdvancedList = () => {
  const [data, setData] = useState(initialData);
  const [refreshing, setRefreshing] = useState(false);
  const [loadingMore, setLoadingMore] = useState(false);
  const [hasMore, setHasMore] = useState(true);

  // 下拉刷新
  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    // 模拟网络请求
    await new Promise(resolve => setTimeout(resolve, 2000));
    // 通常这里会获取最新数据并重置页码
    setData(initialData);
    setHasMore(true);
    setRefreshing(false);
  }, []);

  // 上拉加载更多
  const onEndReached = useCallback(async () => {
    // 防止重复请求、无更多数据时不再请求
    if (loadingMore || !hasMore) return;
    
    setLoadingMore(true);
    // 模拟网络请求
    await new Promise(resolve => setTimeout(resolve, 2000));
    // 模拟追加数据
    const newData = [...data, ...moreData];
    setData(newData);
    setLoadingMore(false);
    // 模拟数据加载完毕的情况
    if (newData.length >= 30) {
      setHasMore(false);
    }
  }, [loadingMore, hasMore, data]);

  const renderFooter = () => {
    if (!hasMore) {
      return (
        <View style={{ padding: 10, alignItems: 'center' }}>
          <Text>没有更多数据了</Text>
        </View>
      );
    }
    return loadingMore ? <ActivityIndicator style={{ padding: 10 }} /> : null;
  };

  return (
    <FlatList
      data={data}
      renderItem={({ item }) => <Text style={{ padding: 20 }}>{item.title}</Text>}
      keyExtractor={item => item.id}
      refreshControl={
        <RefreshControl
          refreshing={refreshing}
          onRefresh={onRefresh}
          // 可自定义样式，例如 tintColor (iOS), colors (Android) 等
        />
      }
      onEndReached={onEndReached}
      onEndReachedThreshold={0.2} // 调整触发灵敏度，表示距离底部 20% 时触发
      ListFooterComponent={renderFooter}
    />
  );
};

// 模拟数据
const initialData = [{id: '1', title: '初始项目1'}, {id: '2', title: '初始项目2'}];
const moreData = [{id: '3', title: '更多项目3'}, {id: '4', title: '更多项目4'}];

export default AdvancedList;

探索第三方库

如果你需要更强大的下拉动画或更精细的控制，可以考虑像 react-native-SmartRefreshLayout 这样的第三方库。它们通常提供更丰富的内置样式和开箱即用的高级功能。使用时请参考其特定文档进行安装和配置。

⚠️ 关键细节与优化

实现基本功能后，以下几点能显著提升稳定性和用户体验：

状态管理是核心：务必妥善管理 refreshing、loadingMore 和 hasMore 等状态。确保在请求开始和结束时正确更新状态，避免重复请求或状态不一致。
防止 onEndReached 重复触发：这是常见问题。可以通过设置标志位（如 loadingMore）在请求期间阻止再次触发。注意 onEndReached 可能在滚动时多次调用，需要合理设计逻辑。
优化网络请求：在实际项目中，将数据获取逻辑封装成独立的函数或服务。使用 async/await 处理异步操作，并务必添加错误处理，在请求失败时给予用户反馈并提供重试机制。
自定义视觉反馈：除了默认的 ActivityIndicator，你可以通过 ListFooterComponent 和 ListHeaderComponent 完全自定义加载中和数据加载完的界面，使其更符合应用整体设计。

💎 方案选择建议

对于大多数应用，从官方 FlatList 方案入手是最佳选择。它稳定、可靠，能满足基本需求，且社区支持丰富。

如果你的项目对下拉刷新的动画效果有特殊要求，或者你希望减少自行处理细节状态的工作量，那么探索一款维护良好的第三方库（如 react-native-SmartRefreshLayout）会是更高效的选择。

希望这些实践建议能帮助你顺利实现功能！如果你在实现过程中遇到更具体的问题，比如如何与特定状态管理库结合，欢迎随时提出。

在 React Native 应用开发中，优化 FlatList 的 onEndReached 回调以防止其重复触发，是确保列表分页加载性能和使用体验的关键。下面这张表格汇总了核心的解决方案，帮助你快速抓住要点。

优化维度	具体方案	说明
触发时机控制	合理设置 `onEndReachedThreshold`	将其设置为一个较小的值（如 `0.1` 或 `0.01`），表示滚动到距离列表底部 10% 或 1% 时触发，避免过早或意外触发。
滚动动量管理	使用 `onMomentumScrollBegin` 标志位	利用滚动动量事件，确保一次完整的滚动动作只触发一次加载。
函数执行频率控制	实现防抖（Debounce）	在连续快速触发时，只执行最后一次调用，有效避免重复请求。

💡 核心方案详解与代码实现

1. 标志位控制法

这种方法通过一个标志变量来记录是否已经开始加载，从而避免在一次滚动中重复触发。

import React, { useRef, useState, useCallback } from 'react';
import { FlatList, View, Text } from 'react-native';

const OptimizedList = () => {
  const [data, setData] = useState([...]); // 初始数据
  const [isLoadingMore, setIsLoadingMore] = useState(false);
  const [hasMore, setHasMore] = useState(true);
  // 使用 useRef 创建在渲染间保持不变的标志位
  const isOnEndReachedCalled = useRef(false);

  const loadMoreData = useCallback(async () => {
    // 如果正在加载或已无更多数据，则直接返回
    if (isLoadingMore || !hasMore) return;
    
    setIsLoadingMore(true);
    // 模拟网络请求
    const newData = await fetchMoreData();
    setData(prevData => [...prevData, ...newData]);
    setIsLoadingMore(false);
    // 根据返回数据判断是否还有更多
    setHasMore(newData.length > 0);
    // 加载完成后，重置标志位，允许下一次触发
    isOnEndReachedCalled.current = false;
  }, [isLoadingMore, hasMore]);

  const handleOnEndReached = useCallback(() => {
    // 关键：如果本次滚动还未触发加载，则执行
    if (!isOnEndReachedCalled.current) {
      loadMoreData();
      isOnEndReachedCalled.current = true; // 设置标志位，阻止重复触发
    }
  }, [loadMoreData]);

  return (
    <FlatList
      data={data}
      renderItem={({ item }) => <Text>{item.title}</Text>}
      onEndReached={handleOnEndReached}
      onEndReachedThreshold={0.1} // 设置为一个较小的阈值
      onMomentumScrollBegin={() => {
        // 当用户开始滚动时，重置标志位，为下一次触发做准备
        isOnEndReachedCalled.current = false;
      }}
      ListFooterComponent={() => (
        isLoadingMore ? <Text>加载中...</Text> : null
      )}
      // 其他优化属性
      maxToRenderPerBatch={5}
      windowSize={5}
    />
  );
};

原理：通过 onMomentumScrollBegin 和 isOnEndReachedCalled 标志位协同工作，确保一次“滚动手势”只触发一次 onEndReached。

2. 防抖函数优化

防抖技术可以确保在频繁触发事件时，只执行最后一次操作。

import { debounce } from 'lodash'; // 或者自己实现一个简单的防抖函数

// 自定义一个简单的防抖Hook
function useDebounce(callback, delay) {
  const debouncedFn = useRef(debounce(callback, delay)).current;
  return debouncedFn;
}

// 在组件中使用
const MyListComponent = () => {
  // ... 状态定义

  const loadMoreData = useCallback(async () => {
    // 加载数据的逻辑
  }, [/* 依赖 */]);

  // 创建一个防抖版本的加载函数，300毫秒内连续触发只会执行一次
  const debouncedLoadMore = useDebounce(loadMoreData, 300);

  const handleOnEndReached = useCallback(() => {
    if (!isLoadingMore && hasMore) {
      debouncedLoadMore();
    }
  }, [isLoadingMore, hasMore, debouncedLoadMore]);

  return (
    <FlatList
      // ... 其他属性
      onEndReached={handleOnEndReached}
      onEndReachedThreshold={0.2}
    />
  );
};

原理：当 onEndReached 被连续快速调用时，防抖函数会延迟执行 loadMoreData。如果在延迟时间内再次被调用，会取消之前的计时并重新计时，从而确保只有最后一次滚动操作会真正加载数据。

⚙️ 其他重要优化配置

除了防止重复触发，合理配置 FlatList 的其他属性对整体性能也至关重要。

优化渲染性能：通过 maxToRenderPerBatch（控制每批渲染的项目数）和 windowSize（控制渲染窗口大小）等属性，可以减少JS线程的负担，使滚动更加流畅。例如，可以设置 maxToRenderPerBatch={5} 和 windowSize={5}。
确保外层容器高度：有时 FlatList 的父容器高度计算异常会导致 onEndReached 在初始化时就被触发。确保父容器有明确的高度（例如设置 style={{ flex: 1 }} 或 {height: '100%'}）可以解决此问题。
使用稳定的 Key：为 keyExtractor 提供一个唯一且稳定的键（如数据项的 id），而不是数组的 index，这有助于 FlatList 更高效地识别项目变化，减少不必要的重渲染。
考虑使用性能更好的列表组件：对于超长列表或极其复杂的列表项，可以考虑使用社区提供的性能更佳的组件，如 Shopify 的 FlashList，它在底层做了大量优化。

💎 总结与建议

你可以根据项目复杂度和需求，选择最适合的方案。对于大多数场景，“标志位控制法” 因其简单有效通常是首选。如果列表滚动非常频繁，可以结合防抖函数进一步优化。同时，别忘了配置好 FlatList 的其他优化属性，并从整体上保证组件设计的合理性。

希望这些具体的方案能帮助你有效解决 onEndReached 重复触发的问题！如果你在实现过程中遇到其他难题，欢迎随时提出。

在复杂列表场景下，单纯的基础虚拟化可能仍会遇到性能瓶颈。结合虚拟化技术进行深度优化，需要像指挥一场交响乐一样，让数据加载、渲染和内存管理各个环节精准协同。下面我将从核心策略、关键技术到实践方案，为你系统梳理提升长列表刷新加载性能的方法。

📊 复杂列表的额外挑战与优化方向

首先，我们来看看复杂列表相比简单列表带来了哪些特定的性能挑战，这决定了我们的优化方向。

挑战维度	对性能的影响	基础虚拟化的不足
数据量极大	网络传输、解析耗时过长，阻塞渲染	仅优化了渲染，未优化数据到达速度
列表项结构复杂	单个项渲染成本高，即使数量不多也会卡顿	仍会尝试渲染视口内所有复杂项
交互频繁与数据实时性	频繁的状态更新导致大量组件重渲染	缺乏对更新粒度的控制
内存占用高	尤其是图片、多媒体内容易引发内存泄漏	虚拟化主要减少DOM节点，需额外内存管理

🚀 提升性能的核心策略

针对上述挑战，可以采取以下关键策略，它们共同构成了高性能虚拟列表的支柱。

数据层面的异步与分片加载 虚拟化解决了渲染量，但数据本身的加载速度也需要优化。
- 增量加载：不要等待所有数据都获取完毕再渲染。采用“无限滚动”模式，滚动到底部时自动加载下一页数据。
- 数据分片与优先级：对超大规模数据（如10万条），可在首屏优先加载前几百条，同时利用 Web Worker 在后台线程静默加载和预处理剩余数据，避免阻塞主线程。
- 智能预加载：根据滚动速度预测用户行为。快速滚动时，预加载更多数据；慢速浏览时，减少预加载以节省资源。
渲染层面的精细控制与复用 这是降低每个列表项渲染开销的关键。
- 极致复用与防重渲染：对列表项组件使用 React.memo 或 PureComponent，并结合自定义的 arePropsEqual 函数，确保只有当前项依赖的数据真正变化时才会重渲染。
- 降低组件复杂度：简化列表项组件结构，避免深层次的嵌套。对于复杂项，可考虑将交互状态提升到父组件或使用状态管理库，减少内部状态导致的更新。
- 占位符与骨架屏：数据加载过程中，先使用骨架屏占位，保持布局稳定，提升用户体验。
内存与资源管理 尤其在移动端或图片、视频多的场景，内存管理至关重要。
- 图片优化与卸载：使用专门的图片库（如 react-native-fast-image），它们能更好地处理缓存和内存。确保图片滚出视口时，其内存能被正确释放。
- 主动清理资源：在组件卸载或数据更新时，清理所有副作用，如事件监听器、定时器等，防止内存泄漏。

🛠️ 关键技术方案与代码实践

以下是一些可以直接应用的技术方案和代码思路。

虚拟化库的高级用法
- 动态高度处理：使用支持动态高度的虚拟化库（如 react-window 的 VariableSizeList 或 react-virtuoso）。关键在于提前测量或预估项高度，并缓存结果以避免重复计算。
- ** Overscan（缓冲区）配置**：合理设置 overscanCount 或类似参数。在可视区域外多渲染几行，快速滚动时避免出现空白，但设置过大会增加渲染负担。
数据获取与状态更新优化
- 防抖与节流：对搜索过滤等操作进行防抖，避免频繁发起请求和重新渲染虚拟列表。
- 不可变数据与结构共享：更新列表数据时，使用不可变数据更新方式。这样可以快速通过引用比较判断数据是否变化，优化 React.memo 的效果。

针对React Native的特定优化 如果使用 React Native 的 FlatList，以下配置尤为关键：

<FlatList
  data={data}
  keyExtractor={(item) => item.id} // 必须提供稳定的key
  initialNumToRender={10} // 初始渲染数量，不宜过大
  maxToRenderPerBatch={5} // 每批增量渲染数量，控制卡顿
  windowSize={5} // 渲染区域高度是可视区域的倍数，调小可节省内存
  removeClippedSubviews={true} // 卸载屏幕外视图（Android尤其需要）
  getItemLayout={(data, index) => ( // 提前告知项尺寸，避免测量开销
    {length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index}
  )}
  // 结合你的异步加载逻辑
  onEndReached={loadMoreData}
  onEndReachedThreshold={0.5} // 触发加载的阈值
/>

💎 总结与进阶建议

将虚拟化技术与上述策略结合，能显著提升复杂长列表的性能。关键在于理解一个核心思想：虚拟化不是一颗银弹，而是一个性能基础。在此之上，需要数据、渲染、内存多方位的协同优化。

对于追求极致性能的场景，还可以探索：

更先进的虚拟化库：如 react-virtuoso，它内置了对分组列表、自动高度测量等复杂场景的良好支持。
并发渲染：在支持 React 18+ 的环境中，考虑使用 useTransition 或 useDeferredValue 将列表渲染标记为可中断的非紧急更新，避免交互卡顿。

希望这些策略和方案能为你优化复杂列表提供清晰的路径。如果你能分享更多关于你遇到的具体场景（例如，列表项的主要复杂度来源是图片、计算还是复杂的交互？），我可以提供更有针对性的建议。

微信公众号

想通过命令行安装特定版本的 Android NDK

2025年12月17日 · 阅读需 3 分钟

Quany

软件工程师

您想通过命令行安装特定版本的 Android NDK，但需要先澄清一个关键点：adb 命令主要用于与已连接的 Android 设备通信，而安装 NDK 是在您的本地开发电脑上进行的操作。正确的工具是 Android SDK 的 sdkmanager。

下面为您详细介绍两种方案来满足您的需求。

🔧 方案一：使用 sdkmanager 安装指定版本（推荐）

这是最直接、由 Android 官方推荐的方法。sdkmanager 是一个专门用于管理 Android SDK 包（包括 NDK）的命令行工具。

定位 sdkmanager：首先，您需要找到您电脑上 Android SDK 目录下的 sdkmanager 工具。它通常位于 android-sdk/tools/bin/ 目录下。如果您设置了 ANDROID_SDK_ROOT 或 ANDROID_HOME 环境变量，会更容易定位。
执行安装命令：打开终端（或命令提示符），使用以下命令格式进行安装。请注意，sdkmanager 期望的版本字符串格式可能与您提供的略有不同，它通常遵循 major.minor.revision 的模式。
```
sdkmanager "ndk;21.0.6113669"
```
在命令执行过程中，系统会显示许可协议，您需要接受才能继续安装。您也可以在命令中直接加上 --accept_licenses 参数来自动接受。
验证安装：安装完成后，您可以在 $ANDROID_SDK_ROOT/ndk/ 目录下找到一个名为 21.0.6113669 的文件夹，这就是安装好的 NDK。

⚙️ 方案二：配置项目使用已安装的 NDK

如果您的开发环境中已经安装了多个版本的 NDK（您的错误信息显示本地有众多版本），另一个高效的策略是直接修改项目配置，使其使用一个已有的、兼容的版本，而不是重新安装。

修改项目配置：在您项目模块（通常是 app）级的 build.gradle 文件中，指定一个您本地已有的 NDK 版本。从您的错误日志看，21.3.6528147 是一个很接近的选择。
```
android {
    ndkVersion "21.3.6528147" // 指定一个本地已有的兼容版本
}
```

💎 方案对比与建议

为了让您更清晰地选择，这里有一个简单的对比表格：

方案	核心命令/操作	优点	适用场景
方案一	`sdkmanager "ndk;21.0.6113669"`	官方推荐，直接满足版本要求	需要精确匹配特定 NDK 版本时
方案二	在 `build.gradle` 中设置 `ndkVersion`	快速，无需下载，利用现有资源	项目有一定灵活性，允许使用兼容版本时

综合建议：

如果您确定项目必须使用 21.0.6113669 这个特定版本，请使用方案一。
如果希望快速解决问题，并且经过测试后确认使用一个已有的高版本（如 21.3.6528147）也能成功编译，那么方案二是更高效的选择。

⚠️ 重要注意事项

确保 sdkmanager 可用：在执行方案一的命令前，请确认 sdkmanager 在您的系统环境变量 PATH 中，或者您需要切换到其所在目录执行。
版本可用性：极老的或非常规的 NDK 版本可能已从官方仓库中移除。如果 sdkmanager 提示找不到该版本，您可能需要从其他渠道手动下载并配置。
AGP 版本：您遇到这个问题的原因可能是项目使用的 Android Gradle Plugin (AGP) 版本较老，其默认的 NDK 版本恰好是 21.0.6113669。长远考虑，升级 AGP 版本是一个更好的选择，因为它会自动管理并使用更新的、兼容性更好的 NDK。

希望这些方案能帮助您解决问题！如果您在操作中遇到任何其他情况，欢迎随时提出。

微信公众号

React Native 0.83

2025年12月16日 · 阅读需 4 分钟

Quany

软件工程师

React 19.2 的新特性确实为 React Native 开发带来了更优雅的解决方案，特别是 useEffectEvent，它能显著改善副作用管理和状态处理。下面的表格总结了这些特性的核心用途和兼容性，方便你快速了解。

特性核心用途 React Native 兼容性

useEffectEvent 从 Effect 中分离“事件逻辑”，解决闭包陷阱，简化依赖数组需 RN 0.83+（已集成 React 19.2）

Activity 组件条件渲染时隐藏而非卸载组件，以保留状态（如表单输入、滚动位置）需 RN 0.83+（已集成 React 19.2）

React Compiler 1.0 构建时自动优化重渲染，减少手动useMemo, useCallback使用需项目配置启用（目前仍为实验性）

性能工具增强新的 DevTools 提供更强大的性能追踪和网络请求调试能力需 RN 0.83+

💡 核心特性详解与应用

useEffectEvent：告别闭包陷阱

useEffectEvent 是 React 19.2 中一个解决常见副作用的 Hook，它允许你将一个包含“非响应式”逻辑（即那些不应该导致副作用重新执行的逻辑）的函数标记为 “Effect 事件”。

• 解决的问题：在以往的 React 开发中，如果一个 Effect 内部使用的函数引用了组件的 props 或 state，你必须将该函数放入 Effect 的依赖数组中。但这常常会导致 Effect 过度重复执行。使用 useRef 手动管理最新值虽然可行，但增加了代码的复杂度和出错风险。

• React Native 使用示例：一个典型的场景是处理 WebSocket 消息。你希望 WebSocket 连接只在 roomId 改变时重建，但消息处理函数又需要能访问到最新的 messages 状态。

    // 注意：此示例基于 React 19.2 的 Canary 版本，使用时请确认你的 React 版本
    import { useState, useEffect, useEffectEvent } from 'react';
    import { View, Text } from 'react-native';

    function ChatRoom({ roomId }) {
      const [messages, setMessages] = useState([]);
      
      // 使用 useEffectEvent 包裹消息处理逻辑
      const handleNewMessage = useEffectEvent((newMessage) => {
        // 此函数总能访问到最新的 messages 状态
        setMessages((currentMessages) => [...currentMessages, newMessage]);
      });

      useEffect(() => {
        const socket = new WebSocket(`wss://myapi.com/chat/${roomId}`);
        
        socket.onmessage = (event) => {
          const messageData = JSON.parse(event.data);
          handleNewMessage(messageData); // 在 Effect 内部调用
        };

        return () => socket.close();
      }, [roomId]); // 依赖数组只需包含 roomId，handleNewMessage 不需要加入

      return (
        <View>
          {messages.map(msg => <Text key={msg.id}>{msg.text}</Text>)}
        </View>
      );
    }

• 重要限制：useEffectEvent 返回的函数必须仅在 Effect 内部调用，而不能直接作为如 onPress 这类事件处理函数使用。

Activity 组件：优雅的状态保持

Activity 组件提供了一种更优雅的方式来条件性地渲染组件，其核心优势在于当组件被隐藏时，它不会被卸载，从而完美保留所有状态。

• 解决的问题：在 React Native 中，我们常用条件渲染。但当 isVisible 变为 false 时，组件会被卸载，其内部状态（如输入框的内容、滚动位置）会完全丢失。再次显示时，组件会重新挂载，状态被重置。

• React Native 使用示例：在具有多个标签页的界面中，使用 Activity 可以确保切换标签时各个标签页的状态得以保留。

    // 注意：此组件在 React 19.2 中引入
    import { Activity } from 'react';
    import { View, Text, TextInput } from 'react-native';

    function TabScreen({ isActive }) {
      const [inputValue, setInputValue] = useState(''); // 这个状态在标签隐藏时不会丢失

      return (
        <Activity mode={isActive ? 'visible' : 'hidden'}>
          <View>
            <Text>这个标签页的状态会被保留</Text>
            <TextInput
              value={inputValue}
              onChangeText={setInputValue}
              placeholder="尝试输入后切换标签..."
            />
          </View>
        </Activity>
      );
    }

🔐 使用前的重要检查

在将 React 19.2 的新特性用于 React Native 项目前，请务必确认以下两点：

React Native 版本：确保你的项目使用的是 React Native 0.83 或更高版本，因为该版本才开始集成 React 19.2。你可以通过查看 package.json 文件中的 react-native 依赖版本来确认。
React 版本：确认项目的 react 和 react-native 包版本兼容。React Native 0.83 内置了兼容的 React 版本。如果你想在更早的 RN 版本中尝试，需要手动升级 React 到 19.2，但这可能会带来风险，强烈建议通过升级 RN 版本来获取稳定支持。

希望这些具体的示例能帮助你在 React Native 项目中更好地运用 React 19.2 的新特性。如果你在升级版本或使用特定特性时遇到具体问题，我很乐意提供进一步的探讨。

微信公众号

App 系统架构设计

2025年12月15日 · 阅读需 14 分钟

Quany

软件工程师

1. 概述

本项目是一个基于 React Native 的移动端销售管理系统，模仿纷享销客 App 的功能和界面设计，主要服务于企业销售团队的日常管理工作。

1.1 技术栈

类别	技术选型	版本
框架	React Native	0.82.1
语言	TypeScript	5.8.x
状态管理	Zustand	5.x
导航	React Navigation	7.x
UI 组件库	@rneui/themed	4.x
样式方案	NativeWind (Tailwind)	4.x
HTTP 客户端	Axios	1.7.x
表单处理	Formik	2.x
国际化	react-i18next	16.x
存储	AsyncStorage + Keychain	-
热更新	CodePush	-

2. 整体架构图

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Presentation Layer                              │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                           Navigation (React Navigation)                  ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    ││
│  │  │  HomeTabs   │  │   Login     │  │   WebView   │  │   Setting   │    ││
│  │  │ (企信/工作台│  │  Register   │  │   Browser   │  │   Profile   │    ││
│  │  │  /CRM/我)   │  │             │  │             │  │             │    ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                              UI Components                               ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐      ││
│  │  │  Common  │ │   Form   │ │ Message  │ │  Layout  │ │ Business │      ││
│  │  │Components│ │Components│ │Components│ │Components│ │Components│      ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘      ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                               Business Layer                                 │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                             State Management                             ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    ││
│  │  │  AuthStore  │  │  ChatStore  │  │  UserStore  │  │ BusinessStore│    ││
│  │  │  (认证状态)  │  │  (聊天状态)  │  │  (用户状态)  │  │  (业务状态)  │    ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                               Services                                   ││
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    ││
│  │  │ AuthService │  │ UserService │  │OrderService │  │CacheService │    ││
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                Data Layer                                    │
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                              API Client                                  ││
│  │  ┌───────────────────────────────────────────────────────────────────┐  ││
│  │  │  Axios Instance (拦截器、Token管理、错误处理、Loading状态)          │  ││
│  │  └───────────────────────────────────────────────────────────────────┘  ││
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          ││
│  │  │OrderAPI │ │PartnerAPI││CustomerAPI││ApprovalAPI││EmployeeAPI│          ││
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘          ││
│  └─────────────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────────────┐│
│  │                            Local Storage                                 ││
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         ││
│  │  │  AsyncStorage   │  │     Keychain    │  │  react-native-  │         ││
│  │  │  (用户偏好/缓存) │  │  (安全凭证存储)  │  │     storage     │         ││
│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘         ││
│  └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
                                       │
                                       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             Infrastructure Layer                             │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐    │
│  │   Theme   │ │    i18n   │ │   Config  │ │   Utils   │ │   Types   │    │
│  │  (主题)    │ │  (国际化)  │ │  (配置)   │ │  (工具)   │ │  (类型)   │    │
│  └───────────┘ └───────────┘ └───────────┘ └───────────┘ └───────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘

3. 目录结构设计

src/
├── api/                          # API 层
│   ├── client.ts                 # Axios 客户端配置
│   ├── index.ts                  # API 统一导出
│   ├── sales.ts                  # 销售相关 API
│   ├── customer.ts               # 客户相关 API (建议拆分)
│   ├── order.ts                  # 订单相关 API (建议拆分)
│   └── types/                    # API 请求/响应类型定义
│       ├── request.ts
│       └── response.ts
│
├── components/                   # 通用组件
│   ├── common/                   # 基础通用组件
│   │   ├── Button/
│   │   ├── Card/
│   │   ├── Empty/
│   │   ├── ErrorBoundary/
│   │   └── index.ts
│   │
│   ├── form/                     # 表单组件
│   │   ├── FormInput.tsx
│   │   ├── PasswordInput.tsx
│   │   ├── PhoneInput.tsx
│   │   ├── AgreementCheckbox.tsx
│   │   └── index.ts
│   │
│   ├── layout/                   # 布局组件
│   │   ├── Header/
│   │   ├── TabBar/
│   │   ├── SafeContainer/
│   │   └── index.ts
│   │
│   ├── business/                 # 业务组件
│   │   ├── CustomerCard/
│   │   ├── OrderItem/
│   │   ├── ApprovalCard/
│   │   └── index.ts
│   │
│   └── message/                  # 消息相关组件
│       ├── MessageItem/
│       ├── ChatBubble/
│       └── index.ts
│
├── screens/                      # 页面/屏幕
│   ├── user/                     # 用户相关页面
│   │   ├── Login.tsx
│   │   ├── Register.tsx
│   │   └── Profile.tsx
│   │
│   ├── home/                     # 主页 Tab 页面
│   │   ├── index.tsx             # Tab 导航配置
│   │   └── tabs/
│   │       ├── CorporateMessage.tsx  # 企信
│   │       ├── Workbench.tsx         # 工作台
│   │       ├── Crm.tsx               # CRM
│   │       └── My.tsx                # 我
│   │
│   ├── crm/                      # CRM 模块页面
│   │   ├── CustomerList/
│   │   ├── CustomerDetail/
│   │   ├── OrderList/
│   │   └── OrderDetail/
│   │
│   ├── approval/                 # 审批模块页面
│   │   ├── ApprovalList/
│   │   └── ApprovalDetail/
│   │
│   └── common/                   # 通用页面
│       ├── Setting.tsx
│       ├── SplashScreen.tsx
│       ├── PDFViewer.tsx
│       └── web/
│           └── index.tsx
│
├── navigation/                   # 导航配置
│   ├── index.tsx                 # 根导航器
│   ├── types.ts                  # 导航类型定义
│   ├── linking.ts                # 深度链接配置
│   └── helpers.ts                # 导航辅助函数
│
├── store/                        # 状态管理 (Zustand)
│   ├── index.ts                  # Store 工具函数
│   ├── authStore.ts              # 认证状态
│   ├── userStore.ts              # 用户状态
│   ├── chatStore.ts              # 聊天状态
│   └── types.ts                  # Store 类型定义
│
├── services/                     # 业务服务层
│   ├── authService.ts            # 认证服务
│   ├── userService.ts            # 用户服务
│   ├── storageService.ts         # 存储服务
│   └── pushService.ts            # 推送服务
│
├── hooks/                        # 自定义 Hooks
│   ├── useAuth.ts
│   ├── useUser.ts
│   ├── useToast.ts
│   ├── useRefresh.ts
│   └── index.ts
│
├── contexts/                     # React Context
│   ├── AuthContext.tsx
│   ├── UserContext.tsx
│   ├── ChatContext.tsx
│   └── index.ts
│
├── theme/                        # 主题配置
│   ├── index.ts                  # 主题导出
│   ├── colors.ts                 # 颜色定义
│   ├── typography.ts             # 字体定义
│   ├── spacing.ts                # 间距定义
│   ├── shadows.ts                # 阴影定义
│   └── ThemeContext.tsx          # 主题 Context
│
├── constants/                    # 常量定义
│   ├── config.ts                 # 应用配置
│   ├── sizes.ts                  # 尺寸常量
│   ├── api.ts                    # API 相关常量
│   └── index.ts
│
├── types/                        # 全局类型定义
│   ├── api.ts                    # API 类型
│   ├── navigation.ts             # 导航类型
│   ├── models/                   # 数据模型类型
│   │   ├── user.ts
│   │   ├── customer.ts
│   │   ├── order.ts
│   │   └── index.ts
│   └── index.ts
│
├── utils/                        # 工具函数
│   ├── env.ts                    # 环境变量工具
│   ├── storage.ts                # 存储工具
│   ├── timezone.ts               # 时区工具
│   ├── toast.ts                  # Toast 工具
│   ├── format.ts                 # 格式化工具
│   ├── validation.ts             # 验证工具
│   └── index.ts
│
├── locales/                      # 国际化资源
│   ├── en.json
│   ├── zh.json
│   └── index.ts
│
└── index.tsx                     # 应用入口

4. 分层架构详解

4.1 表现层 (Presentation Layer)

负责 UI 渲染和用户交互。

// screens/crm/CustomerList/index.tsx
import { useCustomerList } from '@/hooks/useCustomer';
import { CustomerCard } from '@/components/business';
import { SafeContainer, EmptyState } from '@/components/layout';

export default function CustomerList() {
  const { data, loading, refresh } = useCustomerList();

  if (loading) return <Loading />;
  if (!data?.length) return <EmptyState type="customer" />;

  return (
    <SafeContainer>
      <FlatList
        data={data}
        renderItem={({ item }) => <CustomerCard customer={item} />}
        onRefresh={refresh}
      />
    </SafeContainer>
  );
}

4.2 业务逻辑层 (Business Layer)

4.2.1 状态管理 (Zustand Store)

// store/authStore.ts
import { create } from 'zustand';
import { persist, createJSONStorage } from 'zustand/middleware';
import { immer } from 'zustand/middleware/immer';
import AsyncStorage from '@react-native-async-storage/async-storage';

interface AuthState {
  isAuthenticated: boolean;
  token: string | null;
  user: UserInfo | null;
}

interface AuthActions {
  login: (email: string, password: string) => Promise<void>;
  logout: () => Promise<void>;
  refreshToken: () => Promise<void>;
  setUser: (user: UserInfo) => void;
}

export const useAuthStore = create<AuthState & AuthActions>()(
  persist(
    immer((set, get) => ({
      // State
      isAuthenticated: false,
      token: null,
      user: null,

      // Actions
      async login(email: string, password: string) {
        const { token, user } = await authService.login(email, password);
        set(state => {
          state.isAuthenticated = true;
          state.token = token;
          state.user = user;
        });
      },

      async logout() {
        await authService.logout();
        set(state => {
          state.isAuthenticated = false;
          state.token = null;
          state.user = null;
        });
      },

      async refreshToken() {
        const newToken = await authService.refreshToken(get().token);
        set(state => {
          state.token = newToken;
        });
      },

      setUser(user: UserInfo) {
        set(state => {
          state.user = user;
        });
      },
    })),
    {
      name: 'auth-storage',
      storage: createJSONStorage(() => AsyncStorage),
      partialize: (state) => ({ token: state.token, user: state.user }),
    }
  )
);

4.2.2 服务层 (Services)

// services/authService.ts
import * as Keychain from 'react-native-keychain';
import client from '@/api/client';
import Storage from '@/utils/storage';

export interface AuthService {
  login(email: string, password: string): Promise<LoginResult>;
  logout(): Promise<void>;
  refreshToken(token: string | null): Promise<string>;
  validateToken(): Promise<boolean>;
}

export const authService: AuthService = {
  async login(email: string, password: string) {
    // 1. 验证凭证
    const validateRes = await client.post('/login/validate', { email, password });
    
    // 2. 获取 Token
    const loginRes = await client.post('/login/email', {
      ...validateRes.data,
      email,
    });
    
    // 3. 安全存储 Token
    await Keychain.setGenericPassword('auth', loginRes.token);
    
    // 4. 存储用户信息
    await Storage.save({
      key: 'userInfo',
      data: loginRes.user,
    });
    
    return loginRes;
  },

  async logout() {
    await Keychain.resetGenericPassword();
    await Storage.remove({ key: 'userInfo' });
  },

  async refreshToken(token) {
    const res = await client.post('/auth/refresh', { token });
    await Keychain.setGenericPassword('auth', res.token);
    return res.token;
  },

  async validateToken() {
    try {
      const credentials = await Keychain.getGenericPassword();
      if (!credentials) return false;
      
      const res = await client.post('/auth/validate');
      return res.valid === true;
    } catch {
      return false;
    }
  },
};

4.3 数据层 (Data Layer)

4.3.1 API 客户端

// api/client.ts
import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
import Config from 'react-native-config';
import * as Keychain from 'react-native-keychain';
import { Loader } from '@/components/loading';
import { showToast } from '@/utils/toast';
import { reset } from '@/navigation';

// 创建实例
const client: AxiosInstance = axios.create({
  baseURL: Config.SALES_SERVER,
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
});

// 请求拦截器
client.interceptors.request.use(
  async (config: InternalAxiosRequestConfig) => {
    // 1. 处理 Loading
    if (!config.hideLoading) {
      Loader.current?.show();
    }
    
    // 2. 注入 Token
    const credentials = await Keychain.getGenericPassword();
    if (credentials?.password) {
      config.headers['vulcan-token'] = credentials.password;
    }
    
    // 3. 注入通用请求头
    config.headers['accept-timezone'] = await getTimezone();
    config.headers['language-code'] = 'zh-CN';
    
    return config;
  },
  (error) => Promise.reject(error)
);

// 响应拦截器
client.interceptors.response.use(
  (response) => {
    Loader.current?.hide();
    
    const { code, data, msg } = response.data;
    
    if (code === 200) {
      return data;
    }
    
    // 业务错误处理
    if (code === 401) {
      showToast('登录已过期');
      reset({ index: 0, routes: [{ name: 'Login' }] });
    } else {
      showToast(msg || '请求失败');
    }
    
    return Promise.reject(response.data);
  },
  (error) => {
    Loader.current?.hide();
    
    if (error.response?.status === 401) {
      reset({ index: 0, routes: [{ name: 'Login' }] });
    }
    
    showToast(error.message || '网络错误');
    return Promise.reject(error);
  }
);

export default client;

4.3.2 API 模块化

// api/customer.ts
import client from './client';
import type { Customer, CustomerListParams, CustomerListResponse } from '@/types/models';

export const customerApi = {
  /**
   * 获取客户列表
   */
  list(params: CustomerListParams): Promise<CustomerListResponse> {
    return client.post('/web/customer/list', params);
  },

  /**
   * 获取客户详情
   */
  detail(customerId: string): Promise<Customer> {
    return client.post('/web/customer/info', { customerId });
  },

  /**
   * 创建/更新客户
   */
  save(data: Partial<Customer>): Promise<Customer> {
    return client.post('/web/customerManagement/createOrModifyCustomer', data);
  },

  /**
   * 今日统计
   */
  todayStatistics(): Promise<CustomerStatistics> {
    return client.get('/web/customer/todayStatistics');
  },
};

5. 导航架构

5.1 导航结构图

RootNavigator (Native Stack)
├── SplashScreen                    # 启动屏
├── AuthNavigator (Stack)           # 认证流程
│   ├── Login                       # 登录
│   └── Register                    # 注册
├── MainNavigator (Stack)           # 主应用
│   ├── HomeTabs (Bottom Tab)       # 主页 Tabs
│   │   ├── CorporateMessage        # 企信
│   │   ├── Workbench               # 工作台
│   │   ├── CRM                     # CRM
│   │   └── My                      # 我
│   ├── CRMNavigator (Stack)        # CRM 模块
│   │   ├── CustomerList
│   │   ├── CustomerDetail
│   │   ├── OrderList
│   │   └── OrderDetail
│   ├── ApprovalNavigator (Stack)   # 审批模块
│   │   ├── ApprovalList
│   │   └── ApprovalDetail
│   └── CommonScreens               # 通用页面
│       ├── Setting
│       ├── WebView
│       └── PDFViewer
└── Modal Screens                   # 模态页面
    ├── ImageViewer
    └── ActionSheet

5.2 导航类型定义

// navigation/types.ts
import type { NavigatorScreenParams } from '@react-navigation/native';
import type { NativeStackScreenProps } from '@react-navigation/native-stack';

// Root Navigator
export type RootStackParamList = {
  SplashScreen: undefined;
  Login: undefined;
  Register: undefined;
  HomeTabs: NavigatorScreenParams<HomeTabParamList>;
  CustomerDetail: { customerId: string };
  OrderDetail: { orderId: string };
  Setting: undefined;
  WebView: { url: string; title?: string };
};

// Home Tab Navigator
export type HomeTabParamList = {
  CorporateMessage: undefined;
  Workbench: undefined;
  CRM: undefined;
  My: undefined;
};

// Screen Props 类型
export type RootStackScreenProps<T extends keyof RootStackParamList> =
  NativeStackScreenProps<RootStackParamList, T>;

// 扩展全局导航类型
declare global {
  namespace ReactNavigation {
    interface RootParamList extends RootStackParamList {}
  }
}

6. 数据流设计

6.1 单向数据流

┌─────────────────────────────────────────────────────────────────┐
│                          用户交互                                │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                      UI Component                         │  │
│  │  ┌────────────┐    ┌────────────┐    ┌────────────┐     │  │
│  │  │   Props    │ ←  │   Store    │ ←  │  Service   │     │  │
│  │  └────────────┘    └────────────┘    └────────────┘     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    Action Dispatch                        │  │
│  │  onClick → store.action() → API Call → Update State      │  │
│  └──────────────────────────────────────────────────────────┘  │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                      State Update                         │  │
│  │  Zustand: set(state => { state.xxx = newValue })         │  │
│  └──────────────────────────────────────────────────────────┘  │
│                             │                                    │
│                             ▼                                    │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                       Re-render                           │  │
│  │  UI Component 自动订阅状态变化，触发重新渲染               │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

6.2 异步数据流示例

// hooks/useCustomerList.ts
import { useState, useCallback } from 'react';
import { customerApi } from '@/api/customer';
import { useToast } from './useToast';

export function useCustomerList(initialParams?: CustomerListParams) {
  const [data, setData] = useState<Customer[]>([]);
  const [loading, setLoading] = useState(false);
  const [params, setParams] = useState(initialParams || { pageNum: 1, pageSize: 20 });
  const { showError } = useToast();

  const fetch = useCallback(async (newParams?: Partial<CustomerListParams>) => {
    const mergedParams = { ...params, ...newParams };
    setLoading(true);
    
    try {
      const res = await customerApi.list(mergedParams);
      
      if (mergedParams.pageNum === 1) {
        setData(res.list);
      } else {
        setData(prev => [...prev, ...res.list]);
      }
      
      setParams(mergedParams);
      return res;
    } catch (error) {
      showError('加载失败');
      throw error;
    } finally {
      setLoading(false);
    }
  }, [params]);

  const refresh = useCallback(() => fetch({ pageNum: 1 }), [fetch]);
  
  const loadMore = useCallback(() => {
    return fetch({ pageNum: params.pageNum + 1 });
  }, [fetch, params.pageNum]);

  return { data, loading, fetch, refresh, loadMore };
}

7. 核心模块设计

7.1 认证模块

┌─────────────────────────────────────────────────────────────┐
│                      Authentication Flow                     │
│                                                              │
│  ┌──────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐ │
│  │ App  │ →  │ Splash   │ →  │ Check    │ →  │ Navigate │ │
│  │ 启动 │    │ Screen   │    │ Token    │    │ to...    │ │
│  └──────┘    └──────────┘    └──────────┘    └──────────┘ │
│                                   │                         │
│                    ┌──────────────┴──────────────┐         │
│                    │                             │         │
│               Token 有效                    Token 无效      │
│                    │                             │         │
│                    ▼                             ▼         │
│              ┌──────────┐                  ┌──────────┐   │
│              │ HomeTabs │                  │  Login   │   │
│              └──────────┘                  └──────────┘   │
│                                                  │         │
│                                                  ▼         │
│                                            ┌──────────┐   │
│                                            │ Validate │   │
│                                            │ Email &  │   │
│                                            │ Password │   │
│                                            └──────────┘   │
│                                                  │         │
│                                                  ▼         │
│                                            ┌──────────┐   │
│                                            │  Login   │   │
│                                            │ with     │   │
│                                            │ VerifyCode│  │
│                                            └──────────┘   │
│                                                  │         │
│                                                  ▼         │
│                                            ┌──────────┐   │
│                                            │  Save    │   │
│                                            │  Token & │   │
│                                            │ UserInfo │   │
│                                            └──────────┘   │
└─────────────────────────────────────────────────────────────┘

7.2 CRM 模块

┌─────────────────────────────────────────────────────────────┐
│                        CRM Module                            │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                     客户管理                             ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │  │ 客户列表 │  │ 客户详情 │  │ 客户编辑 │             ││
│  │  │ - 分页   │  │ - 基本信息│  │ - 表单   │             ││
│  │  │ - 搜索   │  │ - 品牌   │  │ - 验证   │             ││
│  │  │ - 筛选   │  │ - 项目   │  │ - 提交   │             ││
│  │  └──────────┘  │ - 合同   │  └──────────┘             ││
│  │                │ - 订单   │                            ││
│  │                └──────────┘                            ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                     订单管理                             ││
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐             ││
│  │  │ 订单列表 │  │ 订单详情 │  │ 创建订单 │             ││
│  │  │ - 状态筛选│  │ - 产品   │  │ - 选客户 │             ││
│  │  │ - 时间筛选│  │ - 金额   │  │ - 选产品 │             ││
│  │  │ - 导出   │  │ - 审批流程│  │ - 提交   │             ││
│  │  └──────────┘  └──────────┘  └──────────┘             ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                     审批管理                             ││
│  │  ┌──────────┐  ┌──────────┐                            ││
│  │  │ 待办审批 │  │ 审批详情 │                            ││
│  │  │ - 我发起的│  │ - 同意   │                            ││
│  │  │ - 待我审批│  │ - 拒绝   │                            ││
│  │  │ - 我审批的│  │ - 转交   │                            ││
│  │  └──────────┘  └──────────┘                            ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

7.3 消息模块

┌─────────────────────────────────────────────────────────────┐
│                     Message Module                           │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    企业消息 (企信)                       ││
│  │                                                         ││
│  │  消息类型:                                              ││
│  │  - 待办事项通知                                         ││
│  │  - CRM 消息通知                                         ││
│  │  - 审批消息                                             ││
│  │  - 日程提醒                                             ││
│  │  - 系统通知                                             ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │                      实时通信                            ││
│  │                                                         ││
│  │  技术方案: SSE (Server-Sent Events)                    ││
│  │                                                         ││
│  │  ┌────────────────────────────────────────────────────┐││
│  │  │  Client                          Server            │││
│  │  │    │                                │              │││
│  │  │    │ ── POST /chat/msg ──────────> │              │││
│  │  │    │                                │              │││
│  │  │    │ <── GET /chat/sse?msgId=xxx ─ │              │││
│  │  │    │                                │              │││
│  │  │    │ <── [Event: message] ──────── │              │││
│  │  │    │ <── [Event: message] ──────── │              │││
│  │  │    │ <── [Event: done] ─────────── │              │││
│  │  │    │                                │              │││
│  │  └────────────────────────────────────────────────────┘││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘

8. 主题与样式系统

8.1 设计 Token

// theme/colors.ts
export const colors = {
  // 品牌色 - 纷享销客橙色系
  primary: '#FF6B35',
  primaryLight: '#FF8C5A',
  primaryDark: '#E55A2B',
  
  // 功能色
  success: '#1CC860',
  warning: '#FE7E04',
  error: '#FC5A5A',
  info: '#2196F3',
  
  // 中性色
  text: '#192A3E',
  textSecondary: '#666666',
  textLight: '#999999',
  textDisabled: '#D9D9D9',
  
  // 背景色
  background: '#F7F8FA',
  backgroundSecondary: '#FFFFFF',
  white: '#FFFFFF',
  
  // 边框色
  border: '#E5E5E5',
  divider: '#E0E0E0',
  
  // 渐变色
  backgroundGradient: ['#d6edfb', '#f6f5fa', '#f8e6da'],
};

// theme/spacing.ts
export const spacing = {
  xs: 4,
  sm: 8,
  md: 16,
  lg: 24,
  xl: 32,
  xxl: 48,
};

// theme/typography.ts
export const typography = {
  h1: { fontSize: 24, fontWeight: '700' as const },
  h2: { fontSize: 20, fontWeight: '600' as const },
  h3: { fontSize: 18, fontWeight: '600' as const },
  body: { fontSize: 16, fontWeight: '400' as const },
  bodySmall: { fontSize: 14, fontWeight: '400' as const },
  caption: { fontSize: 12, fontWeight: '400' as const },
};

8.2 样式方案

项目采用 NativeWind (Tailwind CSS) + StyleSheet 混合方案：

// 推荐方式：Tailwind 类名
function Card() {
  return (
    <View className="bg-white rounded-lg p-4 shadow-md">
      <Text className="text-lg font-semibold text-gray-800">
        标题
      </Text>
    </View>
  );
}

// 复杂样式：StyleSheet
const styles = StyleSheet.create({
  container: {
    ...shadow.md,
    backgroundColor: colors.white,
    borderRadius: borderRadius.lg,
  },
});

9. 错误处理策略

9.1 全局错误边界

// components/common/ErrorBoundary.tsx
import React, { Component, ErrorInfo, ReactNode } from 'react';
import { View, Text, Button } from 'react-native';

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    // 上报错误到 Sentry
    console.error('Error caught by boundary:', error, errorInfo);
  }

  handleRetry = () => {
    this.setState({ hasError: false, error: null });
  };

  render() {
    if (this.state.hasError) {
      return this.props.fallback || (
        <View className="flex-1 items-center justify-center p-4">
          <Text className="text-lg font-semibold mb-2">出错了</Text>
          <Text className="text-gray-500 mb-4">
            {this.state.error?.message || '未知错误'}
          </Text>
          <Button title="重试" onPress={this.handleRetry} />
        </View>
      );
    }

    return this.props.children;
  }
}

9.2 API 错误处理

// utils/errorHandler.ts
export enum ErrorCode {
  UNAUTHORIZED = 401,
  FORBIDDEN = 403,
  NOT_FOUND = 404,
  SERVER_ERROR = 500,
  NETWORK_ERROR = -1,
}

export function handleApiError(error: any): string {
  const code = error.response?.status || error.code;
  
  switch (code) {
    case ErrorCode.UNAUTHORIZED:
      // 跳转登录页
      reset({ index: 0, routes: [{ name: 'Login' }] });
      return '登录已过期，请重新登录';
      
    case ErrorCode.FORBIDDEN:
      return '您没有权限执行此操作';
      
    case ErrorCode.NOT_FOUND:
      return '请求的资源不存在';
      
    case ErrorCode.SERVER_ERROR:
      return '服务器错误，请稍后重试';
      
    case ErrorCode.NETWORK_ERROR:
      return '网络连接失败，请检查网络';
      
    default:
      return error.message || '请求失败，请稍后重试';
  }
}

10. 性能优化策略

10.1 列表性能优化

// 使用 React.memo 避免不必要的重渲染
const CustomerItem = React.memo<{ customer: Customer }>(({ customer }) => {
  return (
    <View className="p-4 bg-white border-b border-gray-100">
      <Text className="font-semibold">{customer.name}</Text>
    </View>
  );
});

// FlatList 优化配置
<FlatList
  data={customers}
  renderItem={({ item }) => <CustomerItem customer={item} />}
  keyExtractor={(item) => item.id}
  getItemLayout={(data, index) => ({
    length: ITEM_HEIGHT,
    offset: ITEM_HEIGHT * index,
    index,
  })}
  removeClippedSubviews={true}
  maxToRenderPerBatch={10}
  windowSize={5}
  initialNumToRender={10}
/>

10.2 图片优化

// 使用 FastImage 替代 Image
import FastImage from '@d11/react-native-fast-image';

<FastImage
  source={{
    uri: imageUrl,
    priority: FastImage.priority.normal,
    cache: FastImage.cacheControl.immutable,
  }}
  resizeMode={FastImage.resizeMode.cover}
  style={{ width: 100, height: 100 }}
/>

10.3 状态更新优化

// 使用 useMemo 缓存计算结果
const filteredCustomers = useMemo(() => {
  return customers.filter(c => 
    c.name.includes(searchText) || c.phone?.includes(searchText)
  );
}, [customers, searchText]);

// 使用 useCallback 缓存回调函数
const handlePress = useCallback(() => {
  navigation.navigate('CustomerDetail', { customerId: customer.id });
}, [customer.id]);

11. 安全策略

11.1 敏感数据存储

// 使用 Keychain 存储敏感信息
import * as Keychain from 'react-native-keychain';

// 存储 Token
await Keychain.setGenericPassword('auth', token, {
  accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED,
});

// 读取 Token
const credentials = await Keychain.getGenericPassword();

// 删除 Token
await Keychain.resetGenericPassword();

11.2 输入验证

// 使用 Zod 进行输入验证
import { z } from 'zod';

const loginSchema = z.object({
  email: z.string().email('请输入有效的邮箱地址'),
  password: z.string().min(6, '密码至少6位'),
});

function validateLogin(data: unknown) {
  const result = loginSchema.safeParse(data);
  if (!result.success) {
    throw new Error(result.error.errors[0].message);
  }
  return result.data;
}

12. 测试策略

12.1 单元测试

// __tests__/services/authService.test.ts
import { authService } from '@/services/authService';

describe('AuthService', () => {
  it('should login successfully with valid credentials', async () => {
    const result = await authService.login('test@example.com', 'password123');
    expect(result.token).toBeDefined();
    expect(result.user).toBeDefined();
  });

  it('should throw error with invalid credentials', async () => {
    await expect(
      authService.login('invalid@example.com', 'wrong')
    ).rejects.toThrow();
  });
});

12.2 组件测试

// __tests__/components/CustomerCard.test.tsx
import { render, fireEvent } from '@testing-library/react-native';
import { CustomerCard } from '@/components/business';

const mockCustomer = {
  id: '1',
  name: '测试客户',
  phone: '13800138000',
};

describe('CustomerCard', () => {
  it('should render customer info correctly', () => {
    const { getByText } = render(<CustomerCard customer={mockCustomer} />);
    expect(getByText('测试客户')).toBeTruthy();
    expect(getByText('13800138000')).toBeTruthy();
  });

  it('should call onPress when pressed', () => {
    const onPress = jest.fn();
    const { getByTestId } = render(
      <CustomerCard customer={mockCustomer} onPress={onPress} />
    );
    fireEvent.press(getByTestId('customer-card'));
    expect(onPress).toHaveBeenCalledWith(mockCustomer);
  });
});

13. 部署与发布

13.1 多环境配置

# .env.dev
SALES_SERVER=https://dev-api.example.com
LOGIN_SERVER=https://dev-login.example.com
BUNDLE_ENV=dev

# .env.staging
SALES_SERVER=https://staging-api.example.com
LOGIN_SERVER=https://staging-login.example.com
BUNDLE_ENV=staging

# .env.prod
SALES_SERVER=https://api.example.com
LOGIN_SERVER=https://login.example.com
BUNDLE_ENV=prod

13.2 热更新 (CodePush)

# 发布到测试环境
appcenter codepush release-react -a {app-name} -d Staging \
  --description "功能更新..." \
  -t "1.0.0 - 1.0.5"

# 发布到生产环境
appcenter codepush release-react -a {app-name} -d Production \
  --description "功能更新..." \
  -t "1.0.0"

14. 后续优化建议

14.1 短期优化 (1-2周)

API 模块拆分: 将 sales.js 拆分为独立的 API 模块 (customer.ts, order.ts, approval.ts)
类型完善: 为所有 API 请求/响应添加 TypeScript 类型定义
错误边界: 为关键页面添加 ErrorBoundary 组件
加载状态: 添加骨架屏 (Skeleton) 组件改善加载体验

14.2 中期优化 (1-2月)

离线支持: 添加数据缓存和离线访问能力
性能监控: 接入 Sentry 或 Firebase Performance
自动化测试: 完善单元测试和集成测试覆盖率
深度链接: 实现 Universal Links 和 Deep Links

14.3 长期规划

微前端架构: 考虑按业务模块拆分独立子应用
跨平台复用: 探索 React Native Web 支持
CI/CD 完善: 自动化构建、测试、发布流程
设计系统: 建立完整的组件设计系统文档

附录

A. 命名规范

类型	规范	示例
文件夹	kebab-case	`customer-list/`
组件文件	PascalCase	`CustomerCard.tsx`
工具文件	camelCase	`formatDate.ts`
常量	UPPER_SNAKE_CASE	`API_TIMEOUT`
类型/接口	PascalCase	`CustomerInfo`
变量	camelCase	`customerList`
Boolean 变量	is/has/can 前缀	`isLoading`, `hasError`

B. Git 提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式
refactor: 重构
perf: 性能优化
test: 测试
chore: 构建/工具

示例:
feat(customer): 添加客户搜索功能
fix(login): 修复登录失败无提示问题

微信公众号​

💸 理解 Cursor 的计费方式​

🧠 优化你的提问方式​

🔧 善用工具与控制上下文​

⚙️ 精细配置与模型选择​

💎 核心省钱口诀​

🛠️ 编写高质量规则的具体方法​

💾 最大化节省 Token 的实战技巧​

🔍 验证规则是否生效​

微信公众号​

核心实现原理​

完整配置步骤​

前期准备​

安装配置​

启动服务​

使用流程演示​

关键特性与优势​

注意事项​

微信公众号​

ubuntu​

网络配置:安装网卡驱动​

AI不间断运行​

微信公众号​

一、按抽象级别和来源划分（三级需求体系）​

1. 业务需求（Business Requirements）​

2. 用户需求（User Requirements）​

3. 系统需求（System Requirements）​

二、按性质划分（功能 vs 非功能）​

功能需求（Functional Requirements）​

非功能需求（Non-functional Requirements，NFR）​

三、按优先级划分（MoSCoW与Kano模型）​

1. MoSCoW方法​

2. Kano模型​

四、其他重要分类维度​

1. 产品与过程需求​

2. 接口需求​

3. 派生需求 vs 基本需求​

五、中国本地化实践特点​

1. 政策与合规驱动分类​

2. 招投标导向分类​

3. 敏捷开发中的需求分层​

六、需求分类的最佳实践​

微信公众号​

微信公众号​

🔄 核心实现方案​

使用官方 FlatList 方案​

探索第三方库​

⚠️ 关键细节与优化​

💎 方案选择建议​

💡 核心方案详解与代码实现​

1. 标志位控制法​

2. 防抖函数优化​

⚙️ 其他重要优化配置​

💎 总结与建议​

📊 复杂列表的额外挑战与优化方向​

🚀 提升性能的核心策略​

🛠️ 关键技术方案与代码实践​

💎 总结与进阶建议​

微信公众号​

🔧 方案一：使用 sdkmanager 安装指定版本（推荐）​

⚙️ 方案二：配置项目使用已安装的 NDK​

💎 方案对比与建议​

⚠️ 重要注意事项​

微信公众号​

微信公众号​

1. 概述​

1.1 技术栈​

2. 整体架构图​

3. 目录结构设计​

4. 分层架构详解​

4.1 表现层 (Presentation Layer)​

4.2 业务逻辑层 (Business Layer)​

4.2.1 状态管理 (Zustand Store)​

4.2.2 服务层 (Services)​

4.3 数据层 (Data Layer)​

4.3.1 API 客户端​

4.3.2 API 模块化​

5. 导航架构​

5.1 导航结构图​

5.2 导航类型定义​

微信公众号

💸 理解 Cursor 的计费方式

🧠 优化你的提问方式

🔧 善用工具与控制上下文

⚙️ 精细配置与模型选择

💎 核心省钱口诀

🛠️ 编写高质量规则的具体方法

💾 最大化节省 Token 的实战技巧

🔍 验证规则是否生效

微信公众号

核心实现原理

完整配置步骤

前期准备

安装配置

启动服务

使用流程演示

关键特性与优势

注意事项

微信公众号

ubuntu

网络配置:安装网卡驱动

AI不间断运行

微信公众号

一、按抽象级别和来源划分（三级需求体系）

1. 业务需求（Business Requirements）

2. 用户需求（User Requirements）

3. 系统需求（System Requirements）

二、按性质划分（功能 vs 非功能）

功能需求（Functional Requirements）

非功能需求（Non-functional Requirements，NFR）

三、按优先级划分（MoSCoW与Kano模型）

1. MoSCoW方法

2. Kano模型

四、其他重要分类维度

1. 产品与过程需求

2. 接口需求

3. 派生需求 vs 基本需求

五、中国本地化实践特点

1. 政策与合规驱动分类

2. 招投标导向分类

3. 敏捷开发中的需求分层

六、需求分类的最佳实践

微信公众号

微信公众号

🔄 核心实现方案

使用官方 FlatList 方案

探索第三方库

⚠️ 关键细节与优化

💎 方案选择建议

💡 核心方案详解与代码实现

1. 标志位控制法

2. 防抖函数优化

⚙️ 其他重要优化配置

💎 总结与建议

📊 复杂列表的额外挑战与优化方向

🚀 提升性能的核心策略

🛠️ 关键技术方案与代码实践

💎 总结与进阶建议

微信公众号

🔧 方案一：使用 sdkmanager 安装指定版本（推荐）

⚙️ 方案二：配置项目使用已安装的 NDK

💎 方案对比与建议

⚠️ 重要注意事项

微信公众号

微信公众号

1. 概述

1.1 技术栈

2. 整体架构图

3. 目录结构设计

4. 分层架构详解

4.1 表现层 (Presentation Layer)

4.2 业务逻辑层 (Business Layer)

4.2.1 状态管理 (Zustand Store)

4.2.2 服务层 (Services)

4.3 数据层 (Data Layer)

4.3.1 API 客户端

4.3.2 API 模块化

5. 导航架构

5.1 导航结构图

5.2 导航类型定义