refactor: modularize frontend flows

ARCHITECTURE.md

@@ -0,0 +1,95 @@
+# 前端架构说明
+
+本文档记录前端代码的分层边界和导入规则，用于保持框架稳定、可扩展。
+
+## 目录职责
+
+- `src/views/`：页面编排层，只负责布局、组件组合和事件绑定。
+- `src/components/`：可复用 UI 组件，只接收 props、触发 emits，不直接访问接口。
+- `src/composables/`：业务流程层，承载页面状态、业务校验、服务调用和视图模型转换。
+- `src/services/`：API 访问层，只封装请求路径、请求参数和响应类型；`client.ts` 是统一 HTTP 客户端入口，`upload-client.ts` 只处理外部直传，`upload-strategy.ts` 承载上传协议编排。
+- `src/stores/`：跨页面共享状态。局部页面状态应优先放在对应 composable。
+- `src/types/`：领域类型定义，按 `api/auth/config/dashboard/file/presign-upload/ui` 拆分。
+- `src/utils/`：纯工具、存储 helper、URL 构造、剪贴板、格式化等无页面状态能力，不直接依赖 store。
+
+## 导入规则
+
+- 页面层统一从 `@/composables` 引入业务流程。
+- composable 内部引用同目录 composable 时使用相对路径，不通过 `@/composables/*` 绕回统一出口。
+- composable 统一从 `@/services` 引入 API 服务。
+- service 内部统一使用 `./client`，不要从 `@/utils/api` 或页面层创建请求客户端。
+- 裸 `axios` 只能出现在 `services/client.ts` 与 `services/upload-client.ts` 这类客户端封装内。
+- 类型默认从 `@/types` 引入；需要领域内复用时可在 `src/types/*` 内部相对引入。
+- 不在页面或组件中直接调用 `axios`、`fetch`、`FileService`、`ConfigService` 等服务。
+- 不在页面中直接读写 `localStorage`，持久化逻辑放在 `utils/*-storage.ts`。
+- 页面和组件不直接导入剪贴板 helper，复制动作由对应 composable 暴露。
+
+## 状态归属
+
+- 发送流程状态归 `useSendFlow`；路由跳转、返回首页等页面编排放在 view。
+- 发送记录列表归 `SentRecordList`，发送记录详情归 `SentRecordDetailModal`，发送页不内联记录抽屉明细模板。
+- 发送记录视图模型、过期时间校验和过期时间展示归 `utils/send-record.ts`，`useSendFlow` 不内联日期格式化和记录构造。
+- 发送记录复制和二维码取值动作归 `utils/sent-record-actions.ts`，`useSendFlow` 不直接调用底层剪贴板和二维码 URL helper。
+- 发送提交策略归 `useSendSubmit`，切片上传、预签名上传、文本上传和多文件打包不回流到 `useSendFlow`。
+- 取件流程状态归 `useRetrieveFlow`；路由参数读取、自动提交、页面跳转等页面编排放在 view。
+- 取件详情和内容预览的打开/关闭动作归 `useRetrieveFlow`，取件页不直接改内部状态 ref。
+- 管理文件列表状态归 `useAdminFiles`。
+- 文件管理编辑弹窗字段统一使用 `FileEditField`，页面不手写重复输入字段结构。
+- 仪表盘数据状态归 `useDashboardStats`，加载时机由 `DashboardView` 显式触发。
+- 登录表单和认证请求归 `useAdminLogin`，登录成功后的页面跳转放在 `LoginView`。
+- 可复用的底层 composable 不直接读取全局 store 或弹提示，应通过参数注入配置读取和通知回调。
+- 系统配置编辑状态归 `useSystemConfig`，公共配置缓存归 `configStore`。
+- 系统配置页的布尔/数字开关由 `useSystemConfig` 暴露语义动作，模板不直接写切换表达式。
+- 系统配置页的二值开关统一使用 `SettingSwitch`，页面不手写 switch 样式结构。
+- 系统配置页的简单数字项统一使用 `SettingNumberInput`，带单位下拉的复合输入可保留在页面编排层。
+- 系统配置页的单位表单状态和提交 payload 构造归 `useSystemConfig`，单位换算纯函数归 `utils/config-form.ts`。
+- 发送/接收历史记录归 `fileData` store。
+- Alert 计时和进度归 `alertStore`，`AlertComponent` 只负责渲染。
+
+## 工具边界
+
+- URL 构造统一放在 `utils/share-url.ts`。
+- 剪贴板能力统一放在 `utils/clipboard.ts`，复制结果提示通过调用方注入回调。
+- 粘贴事件的纯解析和文本插入计算统一放在 `utils/clipboard-paste.ts`。
+- 文件 hash、zip 打包等浏览器文件处理统一放在 `utils/file-processing.ts`。
+- Markdown 预览渲染与 HTML 清洗统一放在 `utils/content-preview.ts`。
+- 文件下载、文本另存等浏览器下载动作统一放在 `utils/download-action.ts`。
+- 配置表单单位转换统一放在 `utils/config-form.ts`。
+- 配置缓存读写统一放在 `utils/config-storage.ts`。
+- 认证缓存读写统一放在 `utils/auth-storage.ts`。
+
+## 维护约束
+
+- 新页面应先创建对应 composable，再由 view 绑定 composable 输出。
+- composable 默认不在初始化阶段自动发起远程请求，页面或上层流程应显式触发加载。
+- 新接口应先进入 `services/`，不要在 composable 中拼接散落的底层请求细节。
+- Blob、文件下载等需要保留响应头的接口使用 `rawApiClient`，普通 JSON 接口使用默认 `apiClient`。
+- 上传协议、断点续传、外部直传等流程优先放在 `services/*strategy*` 或客户端封装，composable 只传入状态、回调和文案。
+- 文件打包依赖 `JSZip` 只能出现在 `utils/file-processing.ts`，页面和 composable 不直接依赖打包库。
+- 预览渲染依赖 `marked` / `DOMPurify` 只能出现在 `utils/content-preview.ts`。
+- 下载动作依赖 `file-saver` 或 `window.open` 时，只能出现在 `utils/download-action.ts`。
+- 新共享状态进入 store 前，需要确认它确实跨页面使用。
+- 新类型应放入对应领域类型文件，再由 `types/index.ts` 汇总导出。
+- 删除旧代码优先于保留兼容别名，除非已有明确外部调用方。
+
+## 验证
+
+每次结构性改动后至少运行：
+
+```sh
+pnpm build
+```
+
+`pnpm build` 会先执行 `pnpm check:architecture`，再执行类型检查和生产构建。
+
+快速验证架构边界时可单独运行：
+
+```sh
+pnpm check:architecture
+```
+
+必要时补充：
+
+```sh
+pnpm lint
+```