daiyongkang
76f266645d
含 Phase 1.1 IM seq 排序、断线重连、多端已读同步与微信式语音转文字 UI。 排除 node_modules、构建产物、安装包与 .env 密钥。 Co-authored-by: Cursor <cursoragent@cursor.com>
78 lines
6.1 KiB
Markdown
78 lines
6.1 KiB
Markdown
# 风影OA跨平台原生架构优化与演进指南 (Cursor 任务清单)
|
||
|
||
> **Cursor AI 角色设定**：你现在是一位顶级的企业级跨平台架构师，精通 Flutter、NestJS 架构，深谙微信底部通讯架构与钉钉工作台底层逻辑。请严格按照以下阶段（Phase）逐步读取、分析并修改当前项目代码。请务必在完成并验证一个 Phase 的所有任务后，再进入下一个 Phase。遇到不确定的业务逻辑，请主动向开发者提问，绝不盲目伪造代码。
|
||
|
||
---
|
||
|
||
## Phase 1: 核心基础重构与排雷 (Bug 修复与底层优化)
|
||
**目标：稳定底层通讯，消灭跨平台不一致性，彻底切断端侧的重度业务逻辑。**
|
||
|
||
### 1.1 IM 底层通讯与消息漫游重构
|
||
- **离线与断线重连补全**：排查现有的 IM TCP 服务端与 Flutter 客户端连接层。补全心跳保活机制，处理网络切换（如 Wi-Fi 到 4G）时的极速重连。
|
||
- **消息时序与去重**：参考微信底层架构的消息同步逻辑，严格依赖服务端下发的全局唯一 Sequence ID 进行消息排序与本地去重，绝不依赖客户端本地时间戳。
|
||
- **多端状态互斥与同步**：实现 Windows 端与 Android 端同时在线时的消息互传与未读角标实时清除逻辑。
|
||
|
||
### 1.2 客户端重度逻辑剥离 (极度重要)
|
||
- **薪资与考勤逻辑脱水**：全局搜索客户端代码，排查是否存在考勤工时计算、中国劳动法假勤扣减规则、薪资计算的残留代码。如果有，立即全部迁移至 NestJS 后端，客户端仅保留只读渲染与状态流转。
|
||
- **高频大表重构**：排查“在职员工”、“项目台账”等页面。如果客户端尝试全量拉取并本地缓存这些数据，修改为带条件的游标分页（Cursor Pagination）加载。
|
||
|
||
### 1.3 跨平台基建对齐
|
||
- **补齐 iOS 端与 Linux 端构建**：在 Flutter 工程中初始化 iOS 与 Linux 平台支持。确保原生包名、签名文件配置结构搭建完毕。
|
||
- **系统级 API 接入**：在 Windows 桌面端实现系统托盘（Tray）消息闪烁与全局快捷键（截屏/唤起）；在移动端接入原生推送通道。
|
||
|
||
---
|
||
|
||
## Phase 2: 原生工作台痛点攻坚 (动态表单与协作基建)
|
||
**目标：让 OA 摆脱硬编码的泥潭，实现灵活、原生的业务流转。**
|
||
|
||
### 2.1 JSON 驱动的动态 Widget 表单引擎 (核心)
|
||
- **Schema 定义**：在前端提取一套通用的 JSON Schema 规范，用于描述所有的 OA 申请表单（采购、用章、离职等）。
|
||
- **渲染器开发**：在 Flutter 端开发一个纯原生的动态表单渲染器。通过解析 JSON，动态生成 `TextField`、`DropdownButton`、`DatePicker`、`FileUpload` 等 Widget 树。
|
||
- **逻辑剥离**：将硬编码的表单页面重构为通过接口下发 Schema 的动态页面。
|
||
|
||
### 2.2 考勤与协同防伪体系
|
||
- **反作弊打卡**：在原生打卡逻辑中，增加对虚拟定位工具、Hook 框架、Wi-Fi MAC 地址伪造的基础环境安全检测策略。
|
||
- **日历深度联动**：接入原生 Calendar API，将“我的日程”和“会议预定”双向同步至 iOS/Android 的系统自带日历中。
|
||
|
||
### 2.3 音视频通话硬件级优化
|
||
- **LiveKit 原生集成深度优化**：结合底层视频流解析与硬件加速能力（如适配高性能显卡的编解码），降低四宫格或多人视频会议时的移动端发热与 CPU 占用。调用 CallKit / ConnectionService 实现息屏下的原生来电全屏通知。
|
||
|
||
---
|
||
|
||
## Phase 3: 移动端 UI/UX 设计准则与交互规范
|
||
**目标：打造媲美头部大厂的“秒开”体验与严谨视觉。**
|
||
|
||
### 3.1 视觉与排版规范
|
||
- **克制色彩**：禁止大面积使用高饱和度色彩。以品牌色（如深蓝/蓝灰）作为图标与按钮的主色调，背景使用纯白与浅灰（#F5F5F5）进行层级区分。
|
||
- **全局字体缩放适配**：所有文本 Widget 必须支持跟随系统字体大小缩放（但不允许破坏布局，需设置 `maxLines` 和 `TextOverflow`）。
|
||
- **深色模式完整适配**：定义全局的主题变量（ThemeData），确保日间/夜间模式的无缝切换。
|
||
|
||
### 3.2 交互与性能标准
|
||
- **冷启动极致优化**：剔除启动阶段非必要的同步接口请求。利用骨架屏（Skeleton）覆盖所有列表和表单的数据加载真空期，绝对禁止全屏白屏 Loading。
|
||
- **长列表内存回收**：IM 消息页面与万人组织架构树，强制要求使用支持自动回收机制的列表组件，避免内存泄漏。
|
||
- **重型操作的降级处理**：对于报表导出、超大附件上传，必须采用后台任务队列+系统通知的方式，不可阻塞主线程 UI。
|
||
|
||
---
|
||
|
||
## Phase 4: 扩展功能与企业级进阶 (新功能矩阵)
|
||
**目标：在核心稳定后，填补企业级协同的高频需求。**
|
||
|
||
- **[全局聚类搜索]**：在应用顶部提供统一入口，一键穿透搜索“联系人、群聊记录、各类审批单、云盘文件”。
|
||
- **[文档安全与水印]**：实现基于移动端与桌面端的文档在线防泄密体系。包含不可见的全局数字暗水印，以及可自定义浓度的明水印覆盖。
|
||
- **[工作台卡片化配置]**：支持普通员工、部门主管、企业高管根据自身关注点，自定义工作台首页的数据卡片排版（如高管关注利润漏斗，员工关注待办与考勤）。
|
||
|
||
---
|
||
|
||
## Phase 5: 自动化构建与交付 (CI/CD)
|
||
**目标：一次提交，五端齐发。**
|
||
|
||
### 5.1 CI/CD 脚本编写
|
||
- 配置 GitHub Actions 或 Gitlab CI，设置自动化流水线。
|
||
- **移动端产物**：自动生成 Android APK/AAB，iOS IPA，以及 HarmonyOS 的 HAP/APP 结构。
|
||
- **桌面端产物**：自动打包生成 Windows EXE（支持增量更新）和 Linux 的 AppImage/Deb 包。
|
||
- **环境变量隔离**：剥离开发、测试、生产环境的 API 域名、IM 端口、OSS 地址，确保打包时自动注入。
|
||
|
||
---
|
||
**Cursor 执行指令**：
|
||
收到此文档后，请先回复“已了解系统架构与演进目标”。随后请从 Phase 1 开始，扫描项目目录下的对应代码，并向我输出 1.1 阶段的具体修改代码。
|