家谱管理系统 - 前端技术详细文档

📋 文档概述

本文档提供家谱管理系统前端模块的详细技术说明，涵盖所有类、方法的功能描述、参数说明和实现逻辑。

🏗️ 系统架构概览

模块依赖关系

main.js (应用入口)                                       # 统一初始化和管理所有模块
├── core/ (核心工具模块)                                 # 提供基础工具和服务
│   ├── utils.js (DateUtils, FormUtils, DomUtils)       # 日期、表单、DOM工具类
│   ├── apiService.js                                   # API请求服务封装
│   ├── simpleValidator.js                              # 表单验证器
│   └── messageManager.js                               # 消息提示管理器
├── components/ (UI组件库)                              # 可复用UI组件
│   ├── dateInputManager.js                             # 日期输入管理组件
│   ├── personSearch.js                                 # 人员搜索组件
│   ├── dataTable.js                                    # 数据表格组件
│   ├── pagination.js                                   # 分页组件
│   ├── tabManager.js                                   # 标签管理器
│   └── relationshipInputManager.js                     # 关系输入组件
└── pages/ (页面逻辑模块)                               # 具体页面功能实现
    ├── personAdd.js                                    # 人员添加页面
    ├── personList.js                                   # 人员列表页面
    ├── personDetail.js                                 # 人员详情页面
    ├── personEdit.js                                   # 人员编辑页面
    └── relationshipAdd.js                              # 关系添加页面

🔧 核心模块 (core/)

1. utils.js - 通用工具模块

DateUtils 日期工具类

功能: 处理日期数据的解析、格式化、显示和输入框渲染

方法列表:

FormUtils 表单工具类

功能: 处理表单数据的收集和变更检测

方法列表:

DomUtils DOM工具类

功能: 提供DOM操作和界面状态管理

方法列表:

2. apiService.js - API服务封装

功能: 统一管理所有后端API调用，提供标准的请求处理

类方法列表:

3. simpleValidator.js - 简化验证器

功能: 提供基础的表单数据验证功能

类方法列表:

4. messageManager.js - 消息管理器

功能: 统一管理用户提示消息的显示和隐藏

构造函数:

• constructor(containerSelector = 'body', messageId = 'form-message')

方法列表:

🎨 UI组件库 (components/)

1. dateInputManager.js - 日期输入管理器

功能: 管理不同精度的日期输入（精确到日/月/年）

构造函数:

• constructor(prefix, accuracySelectId, containers)

方法列表:

2. personSearch.js - 人员搜索组件

功能: 提供人员搜索和选择功能

构造函数:

• constructor(containerId, options = {})

方法列表:

3. dataTable.js - 数据表格组件

功能: 渲染和操作人员数据表格

构造函数:

• constructor(containerId, options = {})

方法列表:

4. pagination.js - 分页组件

功能: 处理数据分页显示和导航

构造函数:

• constructor(container, options = {})

方法列表:

5. tabManager.js - 标签管理器

功能: 管理页面标签切换功能

构造函数:

• constructor()

方法列表:

6. relationshipInputManager.js - 关系输入组件

功能: 提供关系建立的表单输入功能

构造函数:

• constructor(containerId, options = {})

方法列表:

📄 页面逻辑模块 (pages/)

1. personAdd.js - 人员添加页面

功能: 处理人员添加表单的渲染、验证和提交

构造函数:

• constructor()

方法列表:

2. personList.js - 人员列表页面

功能: 管理人员列表的显示、搜索、分页和操作

构造函数:

• constructor()

方法列表:

3. personDetail.js - 人员详情页面

功能: 显示人员详细信息模态框

构造函数:

• constructor()

方法列表:

4. personEdit.js - 人员编辑页面

功能: 处理人员信息编辑功能

构造函数:

• constructor()

方法列表:

5. relationshipAdd.js - 关系添加页面

功能: 处理亲属关系建立功能

构造函数:

• constructor()

方法列表:

🚀 应用入口 (main.js)

功能: 统一管理应用初始化和模块加载

构造函数:

• constructor()

方法列表:

🔄 数据流与状态管理

数据流架构

用户操作 → 事件监听器 → 数据处理 → API调用 → 后端服务
    ↓
后端响应 → 状态更新 → UI渲染 → 用户反馈

状态管理

// 应用状态示例
{
    currentPage: 1,                    // 当前页码
    pageSize: 10,                      // 每页数量
    totalPersons: 0,                   // 总人员数
    searchKeyword: '',                 // 搜索关键词
    searchGender: '',                  // 性别筛选
    currentPerson: null,               // 当前选中人员
    originalData: null,                // 原始数据（用于比较变更）
    activeTab: 'add-person',           // 激活标签
    formData: {},                      // 表单数据
    validationErrors: [],              // 验证错误
    isLoading: false,                  // 加载状态
    isProcessing: false                // 处理中状态
}

🛡️ 错误处理机制

1. 网络错误处理

try {
    const result = await ApiService.request(endpoint, options);
    // 处理成功响应
} catch (error) {
    // 统一错误处理
    MessageManager.showError(error.message);
    // 恢复界面状态
    this.showLoading(false);
    this.enableAllDeleteButtons?.();
}

2. 表单验证流程

// 分步骤验证
1. 基础非空验证 → 即时反馈（实时验证）
2. 格式验证 → 失焦时验证（字段级验证）
3. 业务逻辑验证 → 提交时验证（表单级验证）
4. 服务端验证 → API返回验证（最终验证）

📊 性能优化策略

1. 加载优化

• 按需加载: 组件按需初始化，避免不必要的资源消耗

• 数据分页: 每页10条数据，减少初始加载数据量

• 延迟搜索: 输入时延迟搜索，避免频繁API请求

• 组件缓存: 重复使用的组件实例化一次

2. 用户体验优化

• 即时反馈: 所有操作都有明确的加载状态和结果提示

• 状态保持: 搜索条件、分页状态在操作间保持连续性

• 错误恢复: 操作失败后自动恢复可操作状态

• 渐进式验证: 分步骤验证，提供清晰的错误指引

🎯 核心业务逻辑

1. 人员信息验证规则

// 必填字段验证
1. 姓名 → 非空验证（trim后长度 > 0）
2. 性别 → 选项验证 (M/F)
3. 出生日期 → 日期格式验证 + 范围验证（1900-2100）
4. 在世状态 → 逻辑验证

// 条件验证
if (!isLiving) {
    // 不在世人员必须填写逝世日期
    validateDeathDate()
    // 逝世日期不能早于出生日期
    validateDeathAfterBirth()
}

2. 日期处理逻辑

// 日期精度处理
switch(accuracy) {
    case 'exact':      // 精确到日 → 年+月+日（全部必填）
    case 'year_month': // 精确到月 → 年+月（日默认为01）  
    case 'year_only':  // 精确到年 → 年（月日默认为01-01）
}

// 日期类型处理
switch(dateType) {
    case 'solar': // 公历日期 → 直接显示
    case 'lunar': // 农历日期 → 转换为中文显示
}

3. 关系建立逻辑

// 关系类型映射
关系类型: {
    'parent': '父母关系',  // A是B的父母
    'spouse': '配偶关系',  // A是B的配偶  
    'child': '子女关系'    // A是B的子女
}

// 关系验证规则
1. 不能选择同一人员（from_person_id ≠ to_person_id）
2. 关系类型必须选择
3. 人员必须存在（通过ID验证）
4. 防止重复关系（后端唯一性约束）

✅ 系统运行状态

已验证功能

• ✅ 标签切换功能: 新增成员 ↔ 添加关系 正常切换

• ✅ 人员CRUD操作: 添加、查看、编辑、删除功能完整

• ✅ 关系建立: 亲属关系创建和自动反向关系生成

• ✅ 搜索筛选: 按姓名、性别组合搜索正常

• ✅ 分页显示: 数据分页和导航功能完善

• ✅ 日期管理: 多精度日期输入和验证

• ✅ 消息提示: 统一的消息反馈机制

• ✅ 错误处理: 完善的错误处理和状态恢复

技术特点

• 模块化设计: 功能清晰分离，便于维护和测试

• 统一管理: API、消息、验证统一处理，减少重复代码

• 用户体验优先: 即时反馈、状态指示、渐进式交互

• 错误恢复: 完善的错误处理和状态恢复机制

• 性能优化: 按需加载、分页处理、延迟搜索

• 安全性: XSS防护、输入验证、API安全调用

🔧 部署说明

环境要求

• 现代浏览器支持 ES6+（Chrome 60+, Firefox 55+, Safari 11+）

• 后端API服务运行在端口 8000

• Web服务运行在端口 5000

启动流程

1. 启动后端FastAPI服务 (localhost:8000)

2. 启动前端Flask服务 (localhost:5000)

3. 浏览器访问 https://localhost:5000

这套前端架构确保了系统的稳定性、可用性和可维护性，为用户提供了流畅的家谱管理体验。