128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
# Client Bootstrap（技术计划）
|
||
|
||
## 1. 计划目标
|
||
|
||
基于 `spec.md` 的约束，落地一套可执行的客户端工程初始化方案，保证：
|
||
|
||
- 开发者可本地启动与联调
|
||
- dev/prod 环境区分清晰
|
||
- i18n 支持 CN/EN/ES/PT/TC 并支持动态切换
|
||
- 目录结构标准化，可持续扩展
|
||
- EAS Build iOS 打包流程可执行
|
||
|
||
## 2. 默认技术决策（本计划采用）
|
||
|
||
- **Node.js**：建议 **20.x LTS**（最低 **18.x LTS**）
|
||
- **包管理器**：pnpm（建议 **9.x**，最低 **8.x**）
|
||
- **路由**：优先采用 `expo-router`（使用 `app/` 目录）
|
||
- 若项目已使用 React Navigation，则保留 `src/navigation/` + `src/screens/` 的方案（见“可替代方案”）
|
||
- **i18n**：`i18next` + `react-i18next` + `expo-localization`
|
||
- **环境变量**：`.env.dev` / `.env.prod` + `EXPO_PUBLIC_` 前缀
|
||
- **网络层**：统一封装 `src/services/`（Axios 或 Fetch 二选一，先按 Axios 预留结构）
|
||
- **状态管理**：Zustand（与现有 `spec.md` 一致）
|
||
|
||
## 3. 目录与模块规划
|
||
|
||
### 3.1 顶层目录（目标态）
|
||
|
||
- `app/`：路由入口（expo-router）
|
||
- `src/`：业务代码
|
||
- `src/features/`：按功能域拆分（push/widget/cards）
|
||
- `src/services/`：API 封装
|
||
- `src/store/`：状态管理
|
||
- `src/i18n/`：多语言资源与初始化
|
||
- `src/components/`、`src/hooks/`、`src/utils/`、`src/constants/`、`src/types/`
|
||
- `assets/`：静态资源
|
||
- `app.json` 或 `app.config.ts`：Expo 配置与环境区分入口
|
||
- `eas.json`：EAS 配置（如启用）
|
||
|
||
### 3.2 关键模块拆分
|
||
|
||
- **i18n 模块**（`src/i18n/`）
|
||
- `index.ts`：初始化（默认语言、回退语言、资源注册、与系统语言对齐）
|
||
- `locales/*.json`：`zh-CN/en/es/pt/zh-TW` 五份资源
|
||
- （可选）`types.ts`：语言码类型与 key 约束
|
||
- **Push 模块**（`src/features/push/`）
|
||
- 权限申请
|
||
- Token 获取与上报（接口对齐点在联调阶段确认）
|
||
- **Widget 模块**（`src/features/widget/`）
|
||
- 数据读取与缓存策略（先定义接口与缓存层，再落地 iOS 扩展实现）
|
||
- **Cards 模块**（`src/features/cards/`）
|
||
- 卡片滑动交互组件与数据模型
|
||
|
||
## 4. 环境区分与配置计划
|
||
|
||
### 4.1 环境变量与模板
|
||
|
||
- 提供 `.env.example`（至少包含 `EXPO_PUBLIC_API_BASE_URL`、`EXPO_PUBLIC_ENV`）
|
||
- 本地开发使用 `.env.dev`，生产构建使用 `.env.prod`
|
||
- README 明确：
|
||
- 真机联调时 `localhost` 替换为局域网 IP
|
||
- 环境变量不入库
|
||
|
||
### 4.2 Bundle ID 与构建标识
|
||
|
||
- dev：`com.damer.mindfulness.dev`
|
||
- prod：`com.damer.mindfulness`
|
||
- 在 `eas.json` 中按 profile 区分环境变量注入与 bundle id（当工程文件落地后执行）
|
||
|
||
## 5. 多语言（i18n）落地计划
|
||
|
||
### 5.1 语言码与策略
|
||
|
||
- 支持：`zh-CN` / `en` / `es` / `pt` / `zh-TW`
|
||
- 默认：优先使用用户当前**设备语言**（在支持列表内时生效）
|
||
- 回退：设备语言不在支持列表时，回退到 `zh-CN`（或团队指定的默认语言）
|
||
|
||
### 5.2 动态切换与持久化
|
||
|
||
- 提供“语言设置”入口（后续 UI 落地），允许用户手动切换语言
|
||
- 切换语言后写入本地存储（例如 AsyncStorage）
|
||
- App 启动时语言选择优先级：
|
||
- ① 用户设置（若存在）
|
||
- ② 设备语言（在支持列表内）
|
||
- ③ 默认回退（`zh-CN` 或团队指定默认）
|
||
|
||
### 5.3 文案规范
|
||
|
||
- key 点分层：`common.*`、`push.*`、`cards.*`、`widget.*`
|
||
- 插值：`{{name}}` 等形式统一
|
||
- 禁止代码内拼接长句（降低翻译成本）
|
||
|
||
## 6. 推送与小组件（一期能力）计划
|
||
|
||
### 6.1 推送
|
||
|
||
- 客户端：权限 -> token -> 上报
|
||
- 后端：保存 token -> 定时任务 -> 推送内容配置
|
||
- 联调产出：token 上报接口、字段、鉴权、错误码约定（后续任务阶段细化）
|
||
|
||
### 6.2 小组件
|
||
|
||
- 先定义“数据模型 + 缓存策略 + 刷新策略”的规范
|
||
- 明确限制：刷新频率受 iOS 系统控制，文档中强调体验目标为“尽力而为”
|
||
|
||
## 7. 执行步骤（落地顺序）
|
||
|
||
1. **补齐客户端 README**：确保启动/环境/i18n/目录/EAS 指引完整（已完成基础版本）
|
||
2. **初始化 Expo 工程（如尚未提交）**：生成 `package.json`、`app.json/app.config.*`、`assets/` 等
|
||
3. **建立标准目录结构**：创建 `app/`、`src/` 与各子目录
|
||
4. **接入 i18n 基座**：完成语言码、资源文件、初始化与切换策略
|
||
5. **接入环境变量读取**：确保 dev/prod 可影响 API Base URL
|
||
6. **预留 push/widget/cards 的模块骨架**：先放类型与接口占位，等待业务实现
|
||
7. **EAS 配置与 iOS 构建跑通**：编写 `eas.json` 并验证 development profile 构建链路
|
||
|
||
## 8. 可替代方案（不影响目标的变体）
|
||
|
||
- **路由不使用 expo-router**：使用 React Navigation
|
||
- 目录：`src/navigation/` + `src/screens/`
|
||
- 仍保留 `src/features/`、`src/services/`、`src/i18n/` 等不变
|
||
- **网络层使用 Fetch**：保持 `src/services/` 统一封装，替换实现即可
|
||
|
||
## 9. 风险与回滚策略
|
||
|
||
- **真机联调失败**：优先排查局域网 IP、代理/防火墙、后端端口映射；必要时使用内网穿透
|
||
- **推送配置复杂**：先在 dev profile 跑通 token->推送最小闭环，再扩展定时策略
|
||
- **小组件刷新不稳定**：在 UI/产品层面接受系统限制，并通过缓存提升体验
|
||
|