药学眼家庭健康档案管理系统 - 产品需求文档

一、产品概述

1.1 产品定位

药学眼家庭健康档案管理系统是一个专注于记录和管理家庭成员健康信息的在线平台。系统支持记录家庭成员的体检记录、身高体重数据以及其他健康信息，帮助用户建立完整的家庭健康档案。

1.2 核心功能

家庭成员管理：添加、编辑、删除家庭成员，记录基础信息
体检记录管理：上传、预览、下载体检报告，支持多文件上传
身高体重记录：记录身高体重数据，自动计算BMI，生成可视化趋势图表
其他健康信息：记录疫苗接种、过敏史、门诊记录等，支持富文本编辑

二、功能详细设计

2.1 家庭成员管理

2.1.1 添加家庭成员

功能描述：用户可以为自己的账户添加家庭成员，记录每个成员的基础信息。

字段设计：

姓名（必填）：字符串，最大长度50字符
性别（必填）：枚举值，"男" 或 "女"
公历出生年月日（必填）：日期类型，格式 YYYY-MM-DD

交互设计：

点击"添加家庭成员"按钮，弹出添加弹框
日期选择控件要求：
- 左侧显示公历日期选择器（默认当前日期前20年）
- 右侧实时显示对应的农历日期（如"农历庚辰年正月初五"）
- 使用 lunar-javascript 库实现公历转农历功能
年龄自动计算（前端计算）：
- 公式：当前年份 - 出生年份，如果当前日期未过生日则减1
- 年龄不存储，仅用于展示
提交时，前端将公历日期转换为农历日期，一并提交到后端

数据存储：

公历日期存储在 birthday_gregorian 字段
农历日期存储在 birthday_lunar 字段（由前端转换后提交）

2.1.2 家庭成员列表

页面布局：

页面标题："家庭成员管理"
顶部操作区：显示"添加家庭成员"按钮
列表区域：显示所有家庭成员

列表字段：

成员姓名：显示成员的姓名
成员性别：显示"男"或"女"
成员年龄：动态计算显示（不存储）

操作按钮（每行4个按钮）：

体检记录：跳转到该成员的体检记录列表页
身高体重记录：跳转到该成员的身高体重详情页
其他信息记录：跳转到该成员的其他信息记录列表页
编辑成员：弹出编辑弹框，字段同添加弹框

列表排序：按创建时间倒序排列

2.1.3 编辑家庭成员

功能描述：修改家庭成员的基础信息。

交互设计：

点击"编辑成员"按钮，弹出编辑弹框
弹框预填当前成员的所有信息
日期选择控件同添加功能，支持修改
提交后更新数据库记录

2.1.4 删除家庭成员

功能描述：软删除家庭成员及其所有关联的健康记录。

交互设计：

点击"删除"按钮（可在编辑弹框中或列表操作列）
弹出二次确认弹框："确认删除该成员？删除后其所有健康记录将被隐藏（可恢复）。"
确认后执行软删除：
- 将成员状态改为"已删除"
- 同步将该成员的所有健康记录状态改为"已删除"（体检记录、身高体重记录、其他信息记录）

2.2 体检记录管理

2.2.1 体检记录列表

页面布局：

页面标题："体检记录 - [成员姓名]"
顶部操作区：显示"上传体检记录"按钮
列表区域：显示该成员的所有体检记录

列表字段：

体检时间：显示体检日期（格式：YYYY-MM-DD）
体检报告：显示文件数量（如"3个文件"），点击可预览和下载
备注：显示备注内容，为空时显示"--"

操作按钮（每行2个）：

编辑：弹出编辑弹框
删除：二次确认后软删除

列表排序：按体检日期倒序排列

2.2.2 上传/编辑体检记录

功能描述：新增或编辑体检记录，支持上传多个体检报告文件。

字段设计：

体检日期（必填）：日期选择器，格式 YYYY-MM-DD
备注（可选）：文本输入框，最大长度500字符
文件上传（可选）：支持多文件上传
- 支持格式：jpg、png、pdf
- 单文件最大10MB
- 支持拖拽上传
- 显示上传进度

交互设计：

点击"上传体检记录"或"编辑"按钮，弹出弹框
文件上传控件：
- 使用 Element Plus 的 el-upload 组件
- 支持多文件选择
- 显示已选择的文件列表
- 支持删除已选择的文件（未上传前）
编辑时：
- 预填当前记录的数据
- 显示已上传的文件列表
- 支持删除已上传的附件（软删除）
- 支持新增附件
提交时：
- 先上传文件到七牛云
- 获取文件URL后，调用后端接口创建/更新记录
- 文件信息存储在 health_physical_exam_attachment 表

2.2.3 预览和下载体检报告

功能描述：在线预览或下载体检报告文件。

交互设计：

点击"体检报告"字段（如"3个文件"），弹出预览窗口
预览窗口显示：
- 文件列表（按上传顺序）
- 每个文件显示文件名
- 每个文件提供"预览"和"下载"按钮
预览功能：
- 图片：直接使用 <img> 标签显示
- PDF：使用 pdf.js 插件渲染
下载功能：
- 调用后端下载接口或直接使用文件URL下载

2.2.4 删除体检记录

功能描述：软删除体检记录及其所有附件。

交互设计：

点击"删除"按钮
弹出二次确认弹框："确认删除该体检记录？删除后将无法恢复。"
确认后：
- 将体检记录状态改为"已删除"
- 同步将所有附件状态改为"已删除"

2.3 身高体重记录管理

2.3.1 身高体重详情页

页面布局：

页面标题："身高体重记录 - [成员姓名]"
顶部操作区：显示"新增数据"和"编辑数据"按钮
主体内容：ECharts 折线图

图表设计：

X轴：记录日期（按时间顺序排列）
Y轴：数值（最小值为0，最大值为该成员所有记录中"身高、体重、BMI"的最大值+10）
数据系列（3条线）：
- 身高（蓝色线）：单位 cm
- 体重（橙色线）：单位 kg
- BMI（绿色线）：无单位
交互功能：
- 鼠标悬停显示具体数值（如"2023-10-01：身高175cm，体重65kg，BMI 21.2"）
- 支持缩放、拖拽查看

技术实现：

使用 ECharts 库
动态计算Y轴最大值：Math.max(...所有记录的身高、体重、BMI值) + 10

2.3.2 新增身高体重数据

功能描述：添加新的身高体重记录。

字段设计：

记录日期（必填）：日期选择器，默认当前日期
身高（必填）：数字输入框，单位 cm，保留1位小数
体重（必填）：数字输入框，单位 kg，保留1位小数
BMI值（自动计算）：不允许手动输入
- 计算公式：体重(kg) / (身高(m))^2
- 保留1位小数

交互设计：

点击"新增数据"按钮，弹出弹框
如果该成员有历史记录，在身高和体重输入框右侧显示"填入最近的历史数据"按钮
点击"填入最近的历史数据"按钮：
- 自动填充最近一条正常状态记录的身高和体重值
- "最近"指记录日期最晚的正常状态数据
输入身高和体重后，自动计算BMI值并显示
提交时，BMI值由前端计算后一并提交到后端

2.3.3 编辑身高体重数据

功能描述：查看和编辑历史身高体重记录。

交互设计：

点击"编辑数据"按钮，显示历史数据列表
列表字段：
- 记录日期
- 身高（cm）
- 体重（kg）
- BMI值
每行操作按钮：
- 编辑：弹出编辑弹框，字段同新增弹框
- 删除：二次确认后软删除
列表排序：按记录日期倒序排列
编辑时：
- 预填当前记录的数据
- 修改身高或体重后，BMI自动重新计算
- 支持修改记录日期

2.3.4 删除身高体重数据

功能描述：软删除身高体重记录。

交互设计：

点击"删除"按钮
弹出二次确认弹框："确认删除该条记录？"
确认后，将记录状态改为"已删除"
图表自动更新，不再显示已删除的数据

2.4 其他信息记录管理

2.4.1 其他信息记录列表

页面布局：

页面标题："其他信息记录 - [成员姓名]"
顶部操作区：显示"新增记录"按钮
列表区域：显示该成员的所有其他信息记录

列表字段：

记录时间：显示记录日期（格式：YYYY-MM-DD）
记录内容：显示内容前50字，超出显示"..."
附件：显示文件数量（如"2个文件"），点击可预览和下载

操作按钮（每行2个）：

编辑：弹出编辑弹框
删除：二次确认后软删除

列表排序：按记录日期倒序排列

2.4.2 新增/编辑其他信息记录

功能描述：新增或编辑其他健康信息记录，支持富文本编辑和多附件上传。

字段设计：

记录日期（必填）：日期选择器，格式 YYYY-MM-DD
记录内容（必填）：富文本编辑器
- 使用 wangEditor 库
- 支持加粗、列表、换行等基础格式
- 内容存储为HTML格式
附件（可选）：支持多文件上传
- 格式不限（但建议限制为常见格式）
- 单文件最大10MB
- 支持拖拽上传

交互设计：

点击"新增记录"或"编辑"按钮，弹出弹框
富文本编辑器：
- 使用 wangEditor 组件
- 提供基础格式化工具栏
- 支持插入图片（上传到七牛云）
文件上传控件：
- 同体检记录的文件上传功能
- 支持多文件上传
编辑时：
- 预填当前记录的数据
- 显示已上传的附件列表
- 支持删除已上传的附件（软删除）
- 支持新增附件

2.4.3 预览记录内容和附件

功能描述：在线预览记录内容和附件。

交互设计：

点击"记录内容"字段，弹出预览窗口
- 显示完整的富文本内容（HTML渲染）
点击"附件"字段（如"2个文件"），弹出预览窗口
- 文件列表（按上传顺序）
- 每个文件提供"预览"和"下载"按钮
- 预览功能同体检记录

2.4.4 删除其他信息记录

功能描述：软删除其他信息记录及其所有附件。

交互设计：

点击"删除"按钮
弹出二次确认弹框："确认删除该记录？"
确认后：
- 将记录状态改为"已删除"
- 同步将所有附件状态改为"已删除"

三、技术实现要点

3.1 前端技术栈

框架：Vue3 + TypeScript
UI组件库：Element Plus
状态管理：Pinia
路由：Vue Router
图表库：ECharts
富文本编辑器：wangEditor
公历转农历：lunar-javascript
文件上传：qiniu-js（七牛云SDK）

3.2 后端技术栈

框架：Express.js + TypeScript
数据库：MySQL（使用 Knex.js）
文件存储：七牛云OSS
参数验证：Zod

3.3 关键功能实现

3.3.1 公历转农历

typescript

import { Lunar } from "lunar-javascript";

// 将公历日期转换为农历
function gregorianToLunar(date: string): string {
  const [year, month, day] = date.split("-").map(Number);
  const lunar = Lunar.fromDate(new Date(year, month - 1, day));
  return lunar.toString(); // 返回如"二零零零年正月初五"
}

3.3.2 年龄计算

typescript

function calculateAge(birthday: string): number {
  const birthDate = new Date(birthday);
  const today = new Date();
  let age = today.getFullYear() - birthDate.getFullYear();
  const monthDiff = today.getMonth() - birthDate.getMonth();
  if (
    monthDiff < 0 ||
    (monthDiff === 0 && today.getDate() < birthDate.getDate())
  ) {
    age--;
  }
  return age;
}

3.3.3 BMI计算

typescript

function calculateBMI(height: number, weight: number): number {
  // height 单位：cm，weight 单位：kg
  const heightInMeters = height / 100;
  const bmi = weight / (heightInMeters * heightInMeters);
  return Math.round(bmi * 10) / 10; // 保留1位小数
}

3.3.4 文件上传到七牛云

参考 apps/admin/src/views/FilesView/FilesView.vue 的实现，使用 qiniu-js 库进行文件上传。

3.3.5 ECharts 折线图

参考 apps/bugs/src/views/PvListView/PvListView.vue 的实现，使用 ECharts 绘制折线图。

四、数据安全

4.1 软删除机制

所有删除操作都是软删除：

将记录的 status 字段改为"已删除"
查询时默认过滤 status = "正常" 的记录
已删除的记录可以通过数据库直接恢复

4.2 数据权限

用户只能查看和管理自己添加的家庭成员及其健康记录
后端接口需要验证 user_id，确保数据安全

4.3 文件安全

文件上传前验证文件类型和大小
文件存储在七牛云OSS，不占用服务器空间
支持文件预览和下载，但需要权限验证

五、用户体验优化

5.1 加载状态

所有异步操作显示加载动画
列表加载时显示骨架屏

5.2 错误处理

网络错误提示
表单验证错误提示
操作失败提示

5.3 操作反馈

成功操作显示成功提示
删除操作需要二次确认
重要操作提供撤销功能（软删除可恢复）

六、开发优先级

第一阶段（核心功能）

家庭成员管理（添加、列表、编辑、删除）
体检记录管理（上传、列表、预览、下载）

第二阶段（扩展功能）

身高体重记录（新增、编辑、图表展示）
其他信息记录（新增、编辑、富文本）

第三阶段（优化完善）

数据导入导出
健康报告生成
数据统计分析

药学眼家庭健康档案管理系统 - 产品需求文档 ​

一、产品概述 ​

1.1 产品定位 ​

1.2 核心功能 ​

二、功能详细设计 ​

2.1 家庭成员管理 ​

2.1.1 添加家庭成员 ​

2.1.2 家庭成员列表 ​

2.1.3 编辑家庭成员 ​

2.1.4 删除家庭成员 ​

2.2 体检记录管理 ​

2.2.1 体检记录列表 ​

2.2.2 上传/编辑体检记录 ​

2.2.3 预览和下载体检报告 ​

2.2.4 删除体检记录 ​

2.3 身高体重记录管理 ​

2.3.1 身高体重详情页 ​

2.3.2 新增身高体重数据 ​

2.3.3 编辑身高体重数据 ​

2.3.4 删除身高体重数据 ​

2.4 其他信息记录管理 ​

2.4.1 其他信息记录列表 ​

2.4.2 新增/编辑其他信息记录 ​

2.4.3 预览记录内容和附件 ​

2.4.4 删除其他信息记录 ​

三、技术实现要点 ​

3.1 前端技术栈 ​

3.2 后端技术栈 ​

3.3 关键功能实现 ​

3.3.1 公历转农历 ​

3.3.2 年龄计算 ​

3.3.3 BMI计算 ​

3.3.4 文件上传到七牛云 ​

3.3.5 ECharts 折线图 ​

四、数据安全 ​

4.1 软删除机制 ​

4.2 数据权限 ​

4.3 文件安全 ​

五、用户体验优化 ​

5.1 加载状态 ​

5.2 错误处理 ​

5.3 操作反馈 ​

六、开发优先级 ​

第一阶段（核心功能） ​

第二阶段（扩展功能） ​

第三阶段（优化完善） ​

药学眼家庭健康档案管理系统 - 产品需求文档

一、产品概述

1.1 产品定位

1.2 核心功能

二、功能详细设计

2.1 家庭成员管理

2.1.1 添加家庭成员

2.1.2 家庭成员列表

2.1.3 编辑家庭成员

2.1.4 删除家庭成员

2.2 体检记录管理

2.2.1 体检记录列表

2.2.2 上传/编辑体检记录

2.2.3 预览和下载体检报告

2.2.4 删除体检记录

2.3 身高体重记录管理

2.3.1 身高体重详情页

2.3.2 新增身高体重数据

2.3.3 编辑身高体重数据

2.3.4 删除身高体重数据

2.4 其他信息记录管理

2.4.1 其他信息记录列表

2.4.2 新增/编辑其他信息记录

2.4.3 预览记录内容和附件

2.4.4 删除其他信息记录

三、技术实现要点

3.1 前端技术栈

3.2 后端技术栈

3.3 关键功能实现

3.3.1 公历转农历

3.3.2 年龄计算

3.3.3 BMI计算

3.3.4 文件上传到七牛云

3.3.5 ECharts 折线图

四、数据安全

4.1 软删除机制

4.2 数据权限

4.3 文件安全

五、用户体验优化

5.1 加载状态

5.2 错误处理

5.3 操作反馈

六、开发优先级

第一阶段（核心功能）

第二阶段（扩展功能）

第三阶段（优化完善）