docs(fe&mobile): 完成前端与移动端核心工程结构、API规范与弱网交互策略建设

开发者文档/04-前端开发/01-前端工程结构与协作边界.md

@@ -1,48 +1,20 @@
-# 🖥️ 前端工程结构与协作边界
+# 01-前端工程结构与协作边界
 
-前端仓库当前是一个 Vue 3 monorepo。它最重要的不是页面组件细节，而是应用层和共享层的边界。
+本系统 Web 管理端基于 `Vue3 + TypeScript + Vben Admin`，采用 `pnpm monorepo` 架构进行组织。
+前端团队的协作核心不仅是“画页面”，而是**严守应用层与共享层的依赖边界，以及与后端业务域的严格对齐**。
 
-## 1. 当前关键目录
-
-- `apps/`
-- `packages/`
-- `internal/`
-- `scripts/`
-- `docs/`
-
-## 2. `apps` 的意义
-
-当前可见应用包括：
+## 一、工程目录架构与红线
 
+### 1. `apps` 应用层
+应用层包含实际可部署的终端应用：
 - `web-antd`
 - `web-ele`
 - `web-naive`
 - `web-tdesign`
+（具体启用的 UI 框架包视项目配置而定）
 
-它们代表可运行应用层，而不是共享层。
-
-## 3. `packages` 的意义
-
-当前可见共享层包括：
-
-- `constants`
-- `effects`
-- `icons`
-- `locales`
-- `preferences`
-- `stores`
-- `styles`
-- `types`
-- `utils`
-
-这说明前端已具备明确的共享能力抽象。
-
-## 4. 与后端的关系
-
-前端文档不应只按页面分组，更应围绕后端业务域组织：
-
-- system
-- infra
-- iot
-- ops
+**红线规定：**
+- **应用层只能向下依赖**：`apps` 里的代码可以依赖 `packages/*` 里的代码，但 `packages` 里的代码绝对不能反向依赖 `apps` 里的任何东西。
 
+### 2. `packages` 共享层
+共享层是沉淀业务无关

开发者文档/05-移动端开发/01-移动端工程结构与页面分域.md

@@ -1,41 +1,35 @@
-# 📱 移动端工程结构与页面分域
+# 01-移动端工程结构与页面分域
 
-移动端当前不是简单页面合集，而是按业务域拆分的 uni-app 项目。
+移动端作业工具基于 `aiot-uniapp` 构建，主要服务于一线保安、保洁员和维修人员。
+与 Web 管理端大而全的思路不同，移动端受限于小程序包体积限制与弱网现场环境，其工程结构必须保持高度克制。
 
-## 1. 当前关键目录
+## 一、小程序主包分包策略（核心红线）
 
-- `src/api`
-- `src/pages`
-- `src/pages-bpm`
-- `src/pages-core`
-- `src/pages-infra`
-- `src/pages-ops`
-- `src/pages-system`
-- `src/store`
-- `src/router`
+微信小程序有严格的单包体积限制（通常为 2MB）。随着 Ops 业务与 IoT 设备接入的增多，不分包必定导致后期打包失败。
 
-## 2. 页面分域说明
+### 1. 主包 (Main Package) 的定位
+**主包必须“极简”**。它只允许包含应用启动的第一顺位页面：
+- `/pages/login/`：登录、验证码、静默授权页
+- `/pages/index/`：工作台首页（Tab Bar）
+- `/pages/user/`：个人中心基础设置
+- 全局共享的基础 UI 组件库。
 
-### `pages-ops`
+**严禁将具体的业务流程（如填写工单、扫描设备）塞入主包。**
 
-直接对应 Ops 现场执行域，当前已可见：
+### 2. 业务分域（SubPackages）
+按照后端的业务领域，建立独立的分包。用户只有在点击首页特定入口时，才会按需加载：
+- `pages-ops/`：保洁、安保、维修的现场作业页面（如 `ticket-detail`, `inspection-scan`）。
+- `pages-iot/`：查看设备详情、设备告警的独立模块。
+- `pages-system/`：组织架构、通讯录查阅。
 
-- `inspection`
-- `work-order`
+### 3. 跨包协作红线
+- **禁止硬引用**：主包的页面绝对禁止直接 `import` 分包里的组件或 JS 文件，否则打包时分包内容会被强制拉入主包，失去分包意义。
+- **通信靠路由**：跨包之间只能通过 `uni.navigateTo({ url: '/pages-ops/ticket/detail?id=123' })` 进行跳转与传参。
 
-### `pages-system`
+## 二、页面状态与生命周期规约
 
-对应用户、角色、通知、租户等系统能力。
-
-### `pages-infra`
-
-对应配置、日志、任务、文件等基础设施能力。
-
-### `pages-bpm`
-
-对应流程能力。
-
-## 3. 为什么移动端文档要强调分域
-
-因为它最终消费的是后端领域能力，而不是单纯页面组件。
+移动端页面的生命周期（`onLoad`, `onShow`, `onReady`）与 Vue 组件（`created`, `mounted`）有重叠，必须规范使用：
 
+- **`onLoad`**：只做初始化（解析 options 参数、拉取首次接口数据），绝不操作 DOM 节点。
+- **`onShow`**：处理从后台切回前台的数据刷新。**注意**：如果是填写表单的中途切出再切回，不要粗暴地在 `onShow` 里重置表单清空用户输入！
+- **清理动作**：如果在页面注册了 WebSocket 或全局 EventBus，必须在 `onUnload` 或 `onHide` 中卸载，防止内存泄漏。