docs: split tech docs into backend/patient/doctor, add prod roadmap, improve upload UI, fix report list for doctors, auto-start frontends in bat

2026-05-21 11:21:43 +08:00
parent 5d89dcceeb
commit 51c7c89ec5
5 changed files with 1570 additions and 1517 deletions
--- a/上线规划文档.md
+++ b/上线规划文档.md
@@ -0,0 +1,553 @@
+# 上线全流程规划文档
+
+> 当前项目是一个跑在本地的 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
+// 页面进入：从右滑入 + 淡入
+// 页面离开：向左滑出 + 淡出
+// 返回时：从左滑入
+
+<AnimatePresence mode="wait">
+  <motion.div
+    key={location.pathname}
+    initial={{ opacity: 0, x: 50 }}
+    animate={{ opacity: 1, x: 0 }}
+    exit={{ opacity: 0, x: -50 }}
+    transition={{ duration: 0.25 }}
+  >
+    <Outlet />
+  </motion.div>
+</AnimatePresence>
+```
+
+#### 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 + 真实短信