# 上线全流程规划文档 > 当前项目是一个跑在本地的 Demo。本文档说明要成为一个**真正可上线运营的产品**，还需要做哪些工作。 --- ## 目录 1. [文件上传与存储](#1-文件上传与存储) 2. [医生端查看与解读](#2-医生端查看与解读) 3. [历史记录与数据持久化](#3-历史记录与数据持久化) 4. [页面过渡动画](#4-页面过渡动画) 5. [联网与 App 化](#5-联网与-app-化) 6. [安全与鉴权](#6-安全与鉴权) 7. [消息推送](#7-消息推送) 8. [运维与监控](#8-运维与监控) 9. [开发流程规范化](#9-开发流程规范化) 10. [完整上线检查清单](#10-完整上线检查清单) --- ## 1. 文件上传与存储 ### 现状 - 患者点"上传报告"，选了文件但**没有真正存到服务器** - 后端只记录了空的 `imageUrls: []` - 没有文件存储服务对接 ### 需要做的事 #### 1.1 MinIO 对接（已在本地装了，没接代码） MinIO 是一个兼容 AWS S3 的对象存储服务，适合存图片、PDF 等文件。 **后端需要新增：** ``` backend/src/HealthManager.Infrastructure/Services/FileStorageService.cs ← 新建 ``` 核心功能： - `UploadAsync(Stream fileStream, string fileName)` → 上传到 MinIO，返回文件 URL - `GetFileUrl(string objectKey)` → 获取文件访问地址 - `DeleteAsync(string objectKey)` → 删除文件 **流程：** ``` 患者选图片 → 前端调 POST /api/files/upload → 后端接收文件流 → 上传到 MinIO → 得到 URL → 报告保存时把 URL 存入 imageUrls → 医生点查看 → 前端直接通过 URL 加载图片 ``` #### 1.2 新增文件上传接口 ``` POST /api/files/upload ← 上传单个文件，返回 { url, key } POST /api/files/upload-multiple ← 上传多个文件 GET /api/files/{key} ← 下载/预览文件 DELETE /api/files/{key} ← 删除文件 ``` #### 1.3 前端改造 ``` ReportUploadPage.tsx: 选文件 → 调上传接口 → 拿到 URL 数组 → 调创建报告接口 { title, category, imageUrls: ["url1", "url2"] } → 显示上传进度条 ``` #### 1.4 文件大小和类型限制 | 限制项 | 建议值 | |--------|--------| | 单文件最大 | 10MB | | 允许格式 | jpg, png, pdf | | 每人每天上限 | 20 个文件 | --- ## 2. 医生端查看与解读 ### 现状 - 医生能看到报告标题和状态 - 但看不到图片（因为根本没存图） - 解读功能比较简陋 ### 需要做的事 #### 2.1 图片查看器 医生点报告后，应该能看到所有上传的图片： ``` ReportDetailPage.tsx: - 图片缩略图列表（来自 imageUrls） - 点击放大查看 - 支持左右翻页 ``` #### 2.2 报告解读界面增强 ``` 当前：只有一个文本框，写一句话 需要： - 逐项填写检查结果（血压、血糖、血脂...） - 异常项自动标红 - 风险等级（正常/关注/异常） - 建议措施的富文本编辑器 - 解读完成后自动通知患者 ``` #### 2.3 报告历史 医生端需要： - 按患者查看历史报告列表 - 按时间/类型筛选 - 对比不同时间点的报告变化趋势 --- ## 3. 历史记录与数据持久化 ### 现状 - 数据存在本地 PostgreSQL - 没有定期备份 - 健康数据会无限增长 ### 需要做的事 #### 3.1 数据库备份 ```bash # 自动备份脚本（Linux 服务器上跑） pg_dump HealthManager > /backup/health_$(date +%Y%m%d).sql # 每天凌晨 3 点自动执行（crontab） 0 3 * * * /opt/scripts/backup-db.sh # 保留最近 30 天，旧自动删除 ``` #### 3.2 历史数据归档 健康记录表会越来越大，需要归档策略： - 1 年以上的健康数据 → 移到归档表或压缩存储 - 3 年以上的 → 可选择性清理 - 报告和相关文件 → 永久保留 #### 3.3 数据导出 患者应该能导出自己的数据： ``` GET /api/health-records/export?format=csv GET /api/health-records/export?format=pdf ``` --- ## 4. 页面过渡动画 ### 现状 - 有 CSS 动画定义但未完全启用 - 页面切换比较生硬 ### 需要做的事 #### 4.1 路由过渡动画 使用 `framer-motion`（已安装）实现： ```tsx // 页面进入：从右滑入 + 淡入 // 页面离开：向左滑出 + 淡出 // 返回时：从左滑入 ``` #### 4.2 组件级动画 | 场景 | 动画 | |------|------| | 列表加载 | 骨架屏（Skeleton）闪烁，数据来到后列表项依次弹出 | | 卡片点击 | 缩放+阴影变化，给"按下去"的反馈 | | 数字变化 | 健康数据变化时数字滚动动画 | | 按钮点击 | 涟漪效果（ripple effect） | | 消息发送 | 气泡从输入框弹入对话区 | | 下拉刷新 | 顶部旋转加载指示器 | | Toast 提示 | 从顶部滑入，2.5 秒后滑出 | #### 4.3 页面切换保留状态 当前切换到别的 Tab 再回来，数据会重新加载。需要： - 首页数据缓存 30 秒，切回来直接用 - 列表页记住滚动位置 --- ## 5. 联网与 App 化 ### 现状 - 前端 `npm run dev` 跑在本地 - 后端 `dotnet run` 跑在本地 - 只能用 `localhost` 访问 ### 需要做的事 #### 5.1 部署到服务器 **最简单方案：一台 Linux 云服务器（阿里云/腾讯云）** ``` 服务器配置建议： - 2核 CPU - 4GB 内存 - 40GB SSD - Ubuntu 22.04 ``` 需要安装的东西和本地一样： - PostgreSQL 18 - Redis - MinIO - .NET 10 Runtime - Nginx（作为反代和静态文件服务） #### 5.2 Nginx 配置 ``` 把所有服务统一到一个域名下： https://api.chatmed.online → 后端 API (5000端口) https://patient.chatmed.online → 患者前端 (打包成静态文件) https://doctor.chatmed.online → 医生前端 (打包成静态文件) https://files.chatmed.online → MinIO (9000端口) ``` #### 5.3 前端打包部署 现在跑的是开发模式（Vite dev server），上线要用生产模式： ```bash # 患者端 cd frontend-patient npm run build # 生成 dist/ 文件夹 # 把 dist/ 里的文件放到 Nginx 的目录下 # 医生端同理 cd frontend-doctor npm run build ``` #### 5.4 打包成手机 App 如果要在手机上像 App 一样用（不是浏览器打开），两种方案： **方案 A：PWA（推荐，最简单）** 在网页基础上加个配置文件，用户浏览器打开后可以"添加到主屏幕"，就像真的 App： ```json // public/manifest.json { "name": "健康管家", "short_name": "健康管家", "start_url": "/", "display": "standalone", // 全屏，没有浏览器地址栏 "background_color": "#F2F5FA", "theme_color": "#1E6BFF", "icons": [ { "src": "/icon-192.png", "sizes": "192x192" }, { "src": "/icon-512.png", "sizes": "512x512" } ] } ``` 再加一个 Service Worker 实现**离线缓存**——没网也能看历史数据。 **方案 B：套壳 App（推荐给小白用户）** 用 Capacitor 把网页包成一个真实的 APK/IPA： ```bash npm install @capacitor/core @capacitor/cli npx cap init npx cap add android # 生成 Android 项目 npx cap add ios # 生成 iOS 项目 npx cap sync # 把前端代码同步进去 ``` 然后分别在 Android Studio 和 Xcode 里打包成 `.apk` 和 `.ipa`，可以上传到应用商店。 | 对比 | PWA | Capacitor 套壳 | |------|-----|---------------| | 开发成本 | 低（只需配置） | 中（需原生打包环境） | | 用户安装方式 | 网页上点"添加到桌面" | 应用商店下载 | | 离线支持 | 有 | 有 | | 推送通知 | iOS 支持有限 | 完整支持 | | 应用商店上架 | 不能 | 能 | | **建议** | **先做这个，快速验证** | **验证完再做这个** | --- ## 6. 安全与鉴权 ### 现状 - JWT 登录，30 分钟过期 - 密码是 SHA256（Demo 够用，上线不够） - 没有 HTTPS - 没有接口限流 - 手机验证码是假的（不验证） ### 需要做的事 #### 6.1 HTTPS + 域名 ```bash # 用 Let's Encrypt 免费申请 SSL 证书 # 所有请求强制走 HTTPS # 后端、前端、MinIO 全部 HTTPS ``` #### 6.2 密码安全 ``` 当前方案：SHA256(password) 上线方案：bcrypt 或 Argon2（加盐哈希，防彩虹表攻击） ``` #### 6.3 真实短信验证码 接腾讯云短信 / 阿里云短信： ``` POST /api/auth/send-sms → 调短信平台API → 用户手机收到验证码 验证码 5 分钟过期 同一号码 60 秒内不能重复发送 ``` #### 6.4 接口安全 | 措施 | 说明 | |------|------| | 限流 | 同一 IP 每分钟最多 60 次请求 | | 登录限流 | 同一手机号 5 次失败后锁定 15 分钟 | | 敏感操作二次验证 | 修改手机号、删除数据需要再输入验证码 | | SQL 注入防护 | EF Core 已自带参数化查询 | | XSS 防护 | 前端 React 已自带转义 | | CORS | 只允许自己域名 | #### 6.5 数据脱敏 ``` 日志里不能记录手机号、密码、真实姓名 显示时手机号中间四位打星号：138****8000 ``` --- ## 7. 消息推送 ### 现状 - 通知存在数据库里，前端轮询拉取 - 用户不打开 App 就看不到新消息 ### 需要做的事 #### 7.1 WebSocket 实时推送 当前已有 SignalR（`/hubs/chat`），需要扩展到： - 新消息实时弹窗 - 医生解读完成 → 患者立即收到通知 - 用药提醒时间到了 → 推送通知 #### 7.2 App 推送（离线也能收到） | 平台 | 推送服务 | |------|---------| | Android | Firebase Cloud Messaging (FCM) | | iOS | Apple Push Notification Service (APNs) | | 国内 Android | 华为/小米/OPPO 推送（不用 FCM） | 后端需要新增一个 PushService，统一处理各类推送。 --- ## 8. 运维与监控 ### 需要做的事 #### 8.1 日志系统 ``` 当前：控制台输出 需要：Serilog 写入文件 + 集中收集 ├── 请求日志（谁、什么时候、调了什么接口） ├── 错误日志（哪出错了、堆栈信息） └── 慢查询日志（哪些 SQL 耗时超过 500ms） ``` #### 8.2 健康检查 ``` GET /health → 检查数据库连接、Redis连接、MinIO连接 返回 { status: "healthy", db: "ok", redis: "ok", minio: "ok" } ``` 自动化监控：每 30 秒检查一次，挂了自动发短信/邮件报警。 #### 8.3 性能监控 ``` .NET: Application Insights 或 Prometheus PostgreSQL: pg_stat_statements 插件 前端: Web Vitals (LCP, FID, CLS) ``` #### 8.4 自动部署 ```bash # 当 git push 到 main 分支时，服务器自动： 1. git pull 拉取最新代码 2. dotnet build 编译后端 3. npm run build 编译前端 4. 重启服务 ``` 用 GitHub Actions 或 Jenkins 实现。 --- ## 9. 开发流程规范化 ### 当前 - 直接在 main 分支上改代码 - 没有测试 - 没有代码审查 ### 需要建立 #### 9.1 分支管理 ``` main ← 生产环境，只有经过测试的代码才合并进来 develop ← 开发环境 feature/* ← 每个新功能一个分支（如 feature/file-upload） bugfix/* ← 修 Bug 的分支 release/* ← 准备上线的版本 ``` #### 9.2 提交规范 ``` feat: 文件上传功能 fix: 修复医生看不到报告的bug docs: 更新使用手册 style: 调整首页配色 refactor: 重构健康数据服务 test: 添加登录接口测试 ``` #### 9.3 自动化测试 ``` 单元测试：关键业务逻辑（如风险等级计算） 集成测试：API 接口（用 xUnit + WebApplicationFactory） E2E 测试：核心用户流程（用 Playwright） ``` #### 9.4 代码审查 每个 PR 至少一个人 Review 后才能合并。 --- ## 10. 完整上线检查清单 ### 阶段一：Demo 完善（当前 → 2周内） - [x] 后端 API 全功能 - [x] 患者前端全功能 - [x] 医生前端全功能 - [ ] 文件上传到 MinIO - [ ] 医生端图片查看 - [ ] 页面过渡动画 - [ ] 上报 Bug 修复 ### 阶段二：内部测试（2-4周） - [ ] 部署到测试服务器 - [ ] 配置 HTTPS + 域名 - [ ] 手机号验证码真实对接 - [ ] 密码改用 bcrypt - [ ] 接口限流 - [ ] 3-5 个真实用户测试 - [ ] 收集反馈，修复问题 ### 阶段三：上线准备（4-6周） - [ ] 部署到生产服务器（2核4G起步） - [ ] 数据库自动备份 - [ ] 日志和监控就位 - [ ] PWA 配置（可添加到手机桌面） - [ ] 性能压测（模拟 100 个用户同时用） - [ ] 隐私协议 + 用户协议页面 - [ ] 操作手册终稿 ### 阶段四：正式运营（6-8周+） - [ ] 上线运营 - [ ] 用户反馈渠道 - [ ] 定期数据备份验证 - [ ] 根据数据做功能迭代 - [ ] 考虑 App 应用商店上架（Capacitor 打包） - [ ] 如果需要，接微信小程序 --- ## 总结：Demo vs 上线 差异一览 | 维度 | 当前 Demo | 上线产品 | |------|----------|---------| | 文件存储 | 没存，imageUrls 为空 | MinIO 存储，返回真实 URL | | 网络 | localhost | 域名 + HTTPS | | 鉴权 | JWT + SHA256 密码 | JWT + bcrypt + 短信验证码 | | 推送 | 前端轮询 | SignalR 实时 + App 离线推送 | | 前端 | Vite dev server | Nginx 静态文件 / PWA / App | | 数据库 | 本地 PostgreSQL | 服务器 PostgreSQL + 每日备份 | | 日志 | 控制台 | 文件 + 集中收集 | | 测试 | 无 | 单元 + 集成 + E2E | | 部署 | 手动 dotnet run | 自动化 CI/CD | | 监控 | 无 | 健康检查 + 性能 + 报警 | | 动画 | 基础 CSS | framer-motion 全页面动画 | | 安全 | CORS | 限流 + HTTPS + 脱敏 + 审计 | **最优先要做的三件事**：① 文件上传存 MinIO → ② 部署到服务器 → ③ HTTPS + 真实短信