评估漏测检查 — 数据取值规则

系统定义了 12种必查评估类型（代码常量 REQUIRED_TYPES），每位在住老人每年均需完成全部12项。任何一项缺失即记为"漏评"。

# analyze_assessment.py 第31-36行
REQUIRED_TYPES = [
    "能力评估", "压疮风险评估", "食品药品误食风险评估",
    "坠床风险评估", "噎食风险评估", "烫伤风险评估",
    "他伤自伤风险评估", "走失风险评估", "跌倒风险评估",
    "文娱活动风险评估", "误吸", "营养",
]

2.1 分析总流程（3步）

2.2 在住老人的完成判定（最关键逻辑）

# analyze_assessment.py 第183-193行 — 核心判定伪代码

if is_discharged:
    completed = set()                    # ← 离院：强制清空
else:
    latest_date = 该人的最新评估日期
    latest_year = latest_date 的前4位

    if latest_year == 当前分析年份:
        completed = year_types           # ✓ 最新评估是当年的 → 认可
    else:
        completed = set()               # ✗ 最新评估不是当年 → 清空！

missing = [t for t in REQUIRED_TYPES if t not in completed]

2.3 同一人同类型的多次评估

• 同一人在同一年内对同一评估类型可能有多条记录
• 使用 Set 集合 去重——只要该类型至少有一条当年记录，就计入已完成
• 取最新一条记录的 assessor、score、assessment_date 作为展示信息（后续覆盖先前的）

3.1 涉及的数据表

3.2 人员范围规则

• 只分析 resident_info 表中存在的老人（以身份证号为唯一匹配条件）
• assessment_records 中身份证号不在 resident_info 中的记录 → 直接跳过（视为脏数据）
• resident_info 中有但 assessment_records 完全没有的人 → 补充进来，标记为12项全缺

4.1 判断标准

# analyze_assessment.py 第132行
_is_discharged = info["status"] == "离院"

当 resident_info.status == "离院" 时，判定该老人已离院。

4.2 离院的特殊处理

5.1 什么是"当年未评估"？

指老人在住、且历史上有过评估记录，但最近一次评估的年份 ≠ 当前分析年份。

# 核心逻辑（第188-193行）
latest_year = latest_date[:4]   # 如 "2025"

if latest_year == str(year):     # year=2026
    completed = year_types        # 认可
else:
    completed = set()             # 全部清空!
    not_this_year_count += 1      # 计入"当年未评估"统计

5.2 具体场景举例

6.1 "同步"按钮（两步合一）

点击页面上的「同步」按钮，会依次执行两个步骤：

6.2 "重新分析"按钮（仅第2步）

点击「重新分析」按钮，只执行 Step 2（跳过数据同步），直接基于当前数据库内容重新运行分析脚本。

6.3 异步任务机制

• 同步和分析都在后台线程中异步执行，不阻塞HTTP响应
• 前端通过轮询 /api/assessment/task/status 获取进度
• 如果已有任务正在运行，再次点击会被拒绝并提示"任务正在进行中"
• 状态写入 .assessment_task 文件持久化

7.1 API返回结构 (/api/assessment/result)

{
  "success": true,
  "data": {
    "year": "2026",
    "total": 113,              // 协议内总人数
    "page": 1,
    "page_size": 50,
    "total_pages": 3,
    "stats": {
      "active": 113,            // 在住人数
      "complete": 0,            // 12项全部完成
      "missed": 113,            // 有漏评的在住人数
      "not_this_year": 55       // 最新评估非本年度
    },
    "filters": {
      "institutions": [...],    // 可选机构
      "areas": [...],           // 可选区域
      "care_levels": [...]     // 护理等级选项
    },
    "people": [                // 每人的详情数组
      {
        "caregiver_name": "范素英",
        "id_number": "320106...",
        "institution": "梅苑颐养中心",
        "area": "康养楼3区5层",
        "bed_number": "康505-1床",
        "check_in_date": "2020-03-15",
        "care_level": "3",
        "age": "85",
        "completed_types": [],   // 已完成的类型列表
        "completed_count": 0,
        "expected_count": 12,
        "missing_types": [...],  // 缺失的类型列表
        "missing_count": 12,
        "is_complete": false,
        "is_discharged": false,
        "discharge_date": "",
        "status_summary": "漏评12项",
        "type_details": {},      // 各类型详情(评分/评估师)
        "assessors": []
      },
      ...
    ]
  }
}

7.2 数据库写入方式

使用 INSERT ... ON DUPLICATE KEY UPDATE，以 (analysis_year, id_number) 为唯一键。每次分析都会完全覆写该人当年的记录。

8.1 示例A：完全未评估（最常见）

8.2 示例B：部分完成（完成1项）

8.3 示例C：离院老人

8.4 示例D：评估记录类型分布（全局统计）

以下为 assessment_records 表中各类型的记录数量（含非必查类型）：

9.1 手动修改 DB 会被覆盖

9.2 非必查类型的存在

assessment_records 中存在约 1690 条非必查类型的记录（管路滑脱、约束、精神、疼痛、抑郁、血栓、睡眠），这些记录被分析脚本静默忽略——不影响12项必查统计，也不出现在漏评列表中。

9.3 身份证号为唯一匹配键

• 所有关联都通过 id_number（身份证号）进行
• 如果 resident_info 和 assessment_records 中的身份证号格式不一致（如大小写、空格），会导致匹配失败，该人的评估记录被跳过

9.4 expected_count 固定为12

当前版本中 expected_count 硬编码为 12。未来如果某些护理等级的老人只需要做部分评估（如特级护理只需做6项），则需要在此处增加按护理等级的条件分支。

9.5 care_level 字段的来源

care_level 和 age 字段不存在于 assessment_analysis 表中。它们来自 resident_info 表的实时 JOIN 查询，在 API 返回时动态附加到每条人员记录上。

9.6 排序规则

# analyze_assessment.py 第227-231行
results.sort(key=lambda x: (
    0 if x["is_discharged"] else 1,   # 离院排前面
    -x["missing_count"],                 # 缺最多的排前面
    x.get("bed_number", "zzz")              # 床位号升序
))