# 未成年人智能管控中枢 - 总体设计文档

> 项目名称：未成年人智能管控中枢  
> 主题：打击预防未成年人侵财  
> 定位：刑侦方向数字侦查平台，赛后纳入单位"孵化室"长期孵化  
> 版本：v1.0  
> 日期：2026-05-17  

---

## 一、系统定位与演进路线

### 1.1 总体定位

以"前端感知→智能研判→精准打击→闭环管控"为核心链路，构建面向未成年人侵财犯罪的全流程智能化平台。

### 1.2 三阶段演进

```
Phase 1: 比赛版 (2026.05.30前)          Phase 2: 孵化版 (赛后2月)           Phase 3: 长期演进
─────────────────────────────────────────────────────────────────────────────────────────────
SQL直查 + NetworkX                      图数据库 + GNN                      GraphRAG + 时序图
规则评分(5维度)                          GNN评分(取代规则)                    自适应评分
AntV G6 静态图谱                         动态图谱 + 社区发现                  预测性图谱
ECharts统计面板                          实时流式面板                         AI辅助研判
手动串并案                               自动团伙检测                         跨区域串并
现有YOLO + 人脸                          + ReID模型                          多模态融合
```

---

## 二、整体架构

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────────────────────┐
│                            前端展示层                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     │
│  │ 态势面板 │ │ 个人画像 │ │ 关系图谱 │ │ 检测工作台│ │ 任务管理 │     │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘     │
├─────────────────────────────────────────────────────────────────────────┤
│                            API网关层                                      │
│  Flask Blueprint路由 + 会话管理 + 权限控制                                │
├─────────────────────────────────────────────────────────────────────────┤
│                            业务逻辑层                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     │
│  │ 评分引擎 │ │ 图谱引擎 │ │ 画像引擎 │ │ 预警引擎 │ │ 建议引擎 │     │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│  │ YOLO检测 │ │ 人脸识别 │ │ 任务派发 │ │ 模型训练 │  ← 现有模块      │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                  │
├─────────────────────────────────────────────────────────────────────────┤
│                            数据访问层                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │
│  │ KingBase(ywdata) │  │ KingBase(stdata) │  │ SQLite(本地状态) │        │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘        │
│  ┌─────────────────┐  ┌─────────────────┐                             │
│  │ KingBase(jcgkzx) │  │  Oracle(图片源)  │   ← 现有                   │
│  └─────────────────┘  └─────────────────┘                             │
├─────────────────────────────────────────────────────────────────────────┤
│                         AI/ML模型层（Phase 2+）                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│  │ GNN模型  │ │ ReID模型 │ │ LLM推理  │ │ YOLO模型 │                  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘                  │
└─────────────────────────────────────────────────────────────────────────┘
```

### 2.2 模块依赖关系

```
                         ┌─────────────┐
                         │  Dashboard  │
                         │  (统计面板)  │
                         └──────┬──────┘
                                │
               ┌────────────────┼────────────────┐
               ▼                ▼                ▼
       ┌──────────────┐ ┌──────────┐ ┌──────────────┐
       │    Score     │ │  Graph   │ │   Profile    │
       │   (评分)     │ │  (图谱)  │ │   (画像)     │
       └──────┬───────┘ └────┬─────┘ └──────┬───────┘
              │              │               │
              └──────────────┼───────────────┘
                             ▼
                  ┌─────────────────────┐
                  │   shared/db/        │
                  │  kingbase.py        │
                  │  (ywdata/stdata/    │
                  │   jcgkzx_monitor)  │
                  └─────────────────────┘
                             ▲
              ┌──────────────┼───────────────┐
              │              │               │
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │Detection │  │   Face   │  │ Dispatch │   ← 现有模块
       │  (YOLO)  │  │  (人脸)  │  │  (派发)  │
       └──────────┘  └──────────┘  └──────────┘
```

---

## 三、数据架构

### 3.1 数据分层

```
┌─────────────────────────────────────────────────────────┐
│ 展示层    Dashboard / Profile / Graph 前端渲染            │
├─────────────────────────────────────────────────────────┤
│ 应用层    jcgkzx_monitor.wcnr_* 项目专属表              │
│           (预计算、抽取、聚合后的业务数据)                 │
├─────────────────────────────────────────────────────────┤
│ 基础层    ywdata.* / stdata.* 原始业务数据               │
│           (全量数据，按需查询补充)                        │
└─────────────────────────────────────────────────────────┘
```

### 3.2 项目专属表（jcgkzx_monitor schema）

| 表名 | 用途 | 数据来源 | 更新策略 |
|------|------|----------|----------|
| `wcnr_target_pool` | 管控对象池 | 多表去重合并 | 每日增量 |
| `wcnr_ryrl_gj` | 人脸轨迹 | t_spy_ryrlgj_xx | 每小时增量 |
| `wcnr_ly_checkin` | 旅馆入住 | t_ly_checkin_gn_merge | 每日增量 |
| `wcnr_rk_zp` | 人口照片 | t_dsfb_rk_zpxx / t_ap_czrk_zp | 一次性+新增 |
| `wcnr_czrk` | 常住人口信息 | t_ap_czrk_jbxx | 一次性+变更 |
| `wcnr_score` | 风险评分 | 计算生成 | 实时+每日全量 |
| `wcnr_score_history` | 评分历史 | 评分快照 | 每次评分追加 |
| `wcnr_alert` | 预警记录 | 规则触发 | 实时 |
| `wcnr_graph_cache` | 图谱缓存(Phase2) | 预计算 | 每日 |
| `wcnr_gnn_embedding` | GNN嵌入(Phase2) | 模型推理 | 训练后更新 |

### 3.3 数据源全景（已有数据）

#### 核心业务表（ywdata schema）

| 分类 | 表名 | 数据量 | 关键用途 |
|------|------|--------|----------|
| **案件** | zq_zfba_wcnr_ajxx | 2,488 | 未成年人案件 |
| | zq_zfba_ajxx | 31,607 | 全量案件 |
| | b_evt_jjzdbczjajxx | 15,825 | 飙车治理案件 |
| **嫌疑人** | zq_zfba_wcnr_xyr | 4,905 | 未成年嫌疑人 |
| | zq_zfba_xyrxx | 57,772 | 全量嫌疑人 |
| | zq_zfba_qsryxx | 6,523 | 取保人员 |
| **管控人员** | b_per_qscxwcnr | 1,921 | 辍学 |
| | b_per_qskjwcnr | 18,812 | 旷课(含详细) |
| | b_per_qslswcnr | 36,659 | 流失 |
| | b_per_qswcnrbczj | 300 | 飙车治理 |
| | b_per_qsyzjszawcnr | 302 | 矫正/戒毒 |
| **行为记录** | t_wcnrxwjl_xx | 1,634 | 行为记录 |
| | t_jj_bczjwcnr_xx | 1,581 | 飙车静态库 |
| | t_jj_bczjwcnrwf_xx | 2,567 | 飙车违法 |
| | t_jj_bczjhfb_xx | 2,030 | 回访记录 |
| **轨迹** | t_spy_ryrlgj_xx | 53,851,207 | 人脸轨迹 |
| | t_ly_checkin_gn_merge | 17,434,974 | 旅馆入住 |
| | b_per_dqqkrygj | 317,858 | 前科人员轨迹 |
| **人口** | t_ap_czrk_jbxx | 3,828,435 | 常住人口 |
| | t_dsfb_rk_zpxx | 6,903,956 | 照片 |
| **教育** | b_yfszxxxsxx | 433,945 | 小学学生 |
| | sh_gd_zxxxsxj_xx | 547,217 | 中小学学籍 |

#### 专项管理表（stdata schema）

| 表名 | 数据量 | 用途 |
|------|--------|------|
| b_per_yfblqxwcnrcj | 1,809 | 不良倾向采集 |
| b_per_yfblqxwcnrcj_xwqk | 1,126 | 行为情况 |
| b_per_yfblqxwcnrcj_jhrxx | 3,685 | 监护人信息 |
| b_per_yfblqxwcnrcj_asjqk | 2,181 | 案事件情况 |
| b_per_yzblxwwcnrhc | 3,109 | 不良行为核查 |
| b_dic_zzjgdm | 68 | 组织机构字典 |

---

## 四、功能模块详细设计

### 4.1 风险评分系统

#### 设计目标

多维度量化未成年人犯罪风险（0-100分），支撑优先处置决策。

#### 评分维度

| 维度 | 权重 | 满分 | 数据源 |
|------|------|------|--------|
| 案件关联 | 30% | 30 | zq_zfba_wcnr_ajxx + b_evt_jjzdbczjajxx |
| 行为记录 | 25% | 25 | t_wcnrxwjl_xx + b_per_qswcnrbczj |
| 家庭环境 | 20% | 20 | b_per_qskjwcnr |
| 教育状态 | 15% | 15 | b_per_qscxwcnr + b_per_qskjwcnr + b_per_qslswcnr |
| 社交网络 | 10% | 10 | 共犯关系 + 轨迹共现 |

#### Phase 1: 规则评分引擎

```
案件维度: 涉案次数(0-22) + 案由严重度(0-8) → cap 30
行为维度: Σ(行为严重度 × 时间衰减) → cap 25
家庭维度: 监护缺失(0-10) + 经济困难(0-5) + 外出务工(0-8) → cap 20
教育维度: 辍学15 / 流失13 / 旷课频繁10 / 旷课偶尔6 / 在校0
社交维度: 高风险关联人×3(max7) + 团伙+3 → cap 10
```

#### Phase 2: GNN评分模型

```
输入特征:
  - 节点特征: [年龄, 性别, 涉案数, 行为次数, 家庭评分, 教育状态, 户籍区域]
  - 边特征: [关系类型, 共现次数, 时间跨度]
  - 图结构: 邻接矩阵(共犯+同校+同区域+轨迹共现)

模型选择:
  - GraphSAGE: 归纳学习，新节点可直接推理
  - GAT: 注意力机制，自动学习关系重要度

训练数据:
  - 正样本: 已知高风险对象(涉案+高频违法)
  - 负样本: 无违法记录的在校学生
  - 标签: 6个月内是否新增案件（二分类/回归）

优势:
  - 捕获"近朱者赤"效应（社交传染）
  - 自动学习特征权重，无需人工调参
  - 发现规则无法覆盖的隐性高风险对象
```

#### Phase 3: 时序动态评分

```
- Temporal GNN: 考虑时间维度的图演化
- 实时评分更新: 新事件触发即时重算
- 预测窗口: 预测未来30天犯罪概率
```

---

### 4.2 关系图谱系统

#### 设计目标

构建以未成年嫌疑人为中心的多层关系网络，支持串并案分析和团伙识别。

#### 图谱数据模型

**节点类型:**

| 类型 | 标识前缀 | 核心属性 |
|------|----------|----------|
| Person(人) | P_ | zjhm, xm, age, risk_score |
| Case(案件) | C_ | ajbh, ajmc, ay, fasj |
| Location(地点) | L_ | name, jd, wd, type |
| School(学校) | S_ | name, address, level |
| Guardian(监护人) | G_ | xm, zjhm, gx, lxdh |
| Organization(机构) | O_ | name, type, address |

**边类型:**

| 关系 | 方向 | 数据源 | 权重计算 |
|------|------|--------|----------|
| SUSPECTED_IN | Person→Case | zq_zfba_wcnr_xyr | 1.0 |
| VICTIM_OF | Person→Case | zq_zfba_saryxx | 1.0 |
| CO_SUSPECT | Person↔Person | 同案件号 | 共犯案件数 |
| GUARDIAN_OF | Person→Person | jhr字段 | 1.0 |
| STUDIES_AT | Person→School | 学籍/辍学表 | 1.0 |
| APPEARED_AT | Person→Location | 人脸轨迹 | 出现次数 |
| CHECKED_IN | Person→Organization | 旅馆入住 | 入住次数 |
| SAME_SCHOOL | Person↔Person | 同校 | 1.0 |
| TEMPORAL_CO_OCCUR | Person↔Person | 轨迹时空共现 | 共现次数 |

#### Phase 1: SQL + NetworkX

```python
# 技术栈
- SQL联表查询构建子图
- NetworkX内存图计算
- AntV G6前端渲染

# 能力范围
- 1-2层关系扩展
- 最短路径(BFS)
- 度中心性排序
- 共犯关系聚类
```

#### Phase 2: 图数据库 + GNN

```python
# 技术栈选型
- 图数据库: Neo4j Community Edition (Apache协议，可离线部署)
  - 备选: NebulaGraph (国产，如需要)
- GNN框架: PyTorch Geometric (PyG)

# 新增能力
- 全量图持久化存储（无需每次SQL重建）
- Cypher查询（声明式图查询语言）
- 实时图更新（流式写入新关系）
- GNN节点分类（风险预测）
- 社区发现（自动团伙识别）
  - Louvain算法: 全局社区划分
  - Label Propagation: 局部传播
- 链接预测（预测未来共犯关系）
  - 方法: Node2Vec embedding → cosine similarity
  - 输出: "张某与李某未来3月成为共犯的概率: 0.73"

# 图数据库Schema (Cypher)
CREATE (:Person {zjhm, xm, age, risk_score, embedding})
CREATE (:Case {ajbh, ajmc, ay, fasj, severity})
CREATE (:Location {id, name, lng, lat, type})
CREATE (p:Person)-[:SUSPECTED_IN {time}]->(c:Case)
CREATE (p1:Person)-[:CO_SUSPECT {case_count, first_time}]->(p2:Person)
```

#### Phase 3: 高级图技术

| 技术 | 用途 | 原理 | 落地价值 |
|------|------|------|----------|
| **GraphRAG** | 自然语言图谱问答 | 图结构 + LLM检索增强 | "分析张某的社交圈谁最危险" |
| **GraphAny** | 跨区域迁移推理 | 预训练图基础模型 | A区训练模型→B区直接用 |
| **Temporal GNN** | 时序图预测 | 时间感知图网络 | 预测下月高危团伙活动 |
| **Graph Transformer** | 复杂模式发现 | 自注意力+图结构 | 发现隐性犯罪网络 |

**GraphRAG架构设计（Phase 3）：**

```
用户提问: "张某的团伙近期有什么异常活动？"
     │
     ▼
┌────────────────┐
│ 问题理解(LLM)  │  → 实体识别: 张某, 团伙, 近期, 异常
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ 图谱检索       │  → Cypher: MATCH (p)-[:CO_SUSPECT*1..2]-(q)
│ (Graph Query)  │     WHERE p.xm='张某'
└───────┬────────┘     RETURN q, relationships
        │
        ▼
┌────────────────┐
│ 上下文组装     │  → 图谱子图 + 轨迹数据 + 预警记录
│ (Context)      │
└───────┬────────┘
        │
        ▼
┌────────────────┐
│ LLM生成回答    │  → "张某团伙(张某/李某/赵某)近2周..."
└────────────────┘

部署要求: 内网LLM (如ChatGLM/Qwen本地部署)
```

---

### 4.3 个人画像系统

#### 设计目标

多维度融合展示管控对象全貌，"一人一档"式综合研判。

#### 画像数据维度

| 维度 | 数据源 | 内容 |
|------|--------|------|
| 基本信息 | wcnr_czrk + wcnr_rk_zp | 身份、照片、户籍、住址 |
| 家庭环境 | b_per_qskjwcnr | 监护人、家庭经济、父母外出 |
| 教育状态 | 辍学/旷课/流失表 | 就学情况、学校、班级 |
| 涉案记录 | zq_zfba_wcnr_ajxx | 案件列表、案由、时间 |
| 行为记录 | t_wcnrxwjl_xx | 违法/不良行为、时间、地点 |
| 轨迹分析 | wcnr_ryrl_gj | 热点地点、活动时段、最近出现 |
| 旅馆入住 | wcnr_ly_checkin | 入住记录、同房人 |
| 关系网络 | 图谱模块 | 共犯、监护人、同校 |
| 风险评分 | wcnr_score + history | 当前评分、趋势、各维度 |
| 管控建议 | 规则引擎 | 处置建议列表 |

#### Phase 2增强: AI生成画像摘要

```
基于画像数据，用LLM生成自然语言摘要:

"张某某，男，16岁，XX市XX区人。2025年8月以来累计涉案3起（盗窃2起、寻衅滋事1起），
评分72分（高风险）。主要风险因素：辍学在家、父母外出务工、与已知飙车团伙（李某、赵某）
关联密切。近30天夜间活跃度高（22:00-02:00占比45%），高频出现于XX路口和XX网吧周边。
建议：联合教育部门劝返复学，加强夜间巡逻，每周走访监护人（祖父）。"
```

---

### 4.4 统计面板系统

#### 设计目标

宏观态势感知，支撑指挥决策和资源调配。

#### 指标体系

| 类别 | 指标 | 更新频率 |
|------|------|----------|
| **总量** | 管控总人数、高风险数、本月新增案件、本月走访 | 实时 |
| **分布** | 案件类型、风险等级、辖区、年龄、性别 | 每小时 |
| **趋势** | 月度案件数、涉案人数、平均评分 | 每日 |
| **预警** | 实时预警列表 | 实时 |
| **排名** | 辖区高风险人数排名、学校风险排名 | 每日 |

#### 预警规则

| 预警类型 | 触发条件 | 级别 |
|----------|----------|------|
| 高风险人员出现 | score>=80的人出现在人脸抓拍 | critical |
| 夜间聚集 | 22:00后同设备周边3+高风险人 | critical |
| 异常旅馆入住 | 未成年人无监护人陪同入住 | warning |
| 飙车预警 | YOLO检测到飙车行为 | warning |
| 学校周边异常 | 高风险人员出现在学校200m范围 | warning |
| 评分跃升 | 单次评分上升超过15分 | info |

#### Phase 2增强

- WebSocket实时推送（替代轮询）
- 大屏模式（全屏+自动轮播）
- 钻取能力（面板→辖区→派出所→个人）
- 同比/环比对比

---

## 五、技术架构详细设计

### 5.1 后端架构

```
app.py (Flask入口)
├── modules/
│   ├── detection/       # 现有 - YOLO检测
│   ├── face/            # 现有 - 人脸识别
│   ├── dispatch/        # 现有 - 任务派发
│   ├── training/        # 现有 - 模型训练
│   ├── score/           # 新增 - 风险评分
│   │   ├── routes.py
│   │   └── services/
│   │       ├── score_engine.py
│   │       ├── dim_case.py
│   │       ├── dim_behavior.py
│   │       ├── dim_family.py
│   │       ├── dim_education.py
│   │       ├── dim_social.py
│   │       └── score_store.py
│   ├── profile/         # 新增 - 个人画像
│   │   ├── routes.py
│   │   └── services/
│   │       ├── profile_assembler.py
│   │       ├── trajectory_service.py
│   │       └── suggestion_engine.py
│   ├── dashboard/       # 新增 - 统计面板
│   │   ├── routes.py
│   │   └── services/
│   │       ├── summary_service.py
│   │       ├── trend_service.py
│   │       ├── distribution_service.py
│   │       └── alert_service.py
│   └── graph/           # 新增 - 关系图谱
│       ├── routes.py
│       └── services/
│           ├── graph_builder.py
│           ├── path_finder.py
│           └── community_detector.py  (Phase 2)
├── shared/
│   ├── config/
│   ├── db/
│   │   ├── oracle.py       # 现有
│   │   ├── sqlite.py       # 现有
│   │   └── kingbase.py     # 新增 - KingBase连接
│   ├── inference/
│   └── utils/
├── templates/modules/
│   ├── dashboard/
│   ├── profile/
│   └── graph/
└── static/modules/
    ├── dashboard/
    ├── profile/
    └── graph/
```

### 5.2 前端技术栈

| 功能 | Phase 1 | Phase 2 |
|------|---------|---------|
| 图谱可视化 | AntV G6 (离线) | G6 + 3D模式 |
| 统计图表 | ECharts (离线) | ECharts + 实时流 |
| 地图 | ECharts内置map | 离线瓦片/矢量地图 |
| 画像页面 | HTML + Tailwind | + 组件化 |
| 实时通信 | 轮询(5s) | WebSocket/SSE |
| 大屏适配 | rem/vh/vw | + 自适应布局引擎 |

### 5.3 数据库连接配置

```env
# KingBase (业务数据)
KINGBASE_HOST=xxx
KINGBASE_PORT=54321
KINGBASE_DB=xxx
KINGBASE_USER=xxx
KINGBASE_PASSWORD=xxx

# 连接池配置
KB_POOL_MIN=2
KB_POOL_MAX=10
KB_POOL_TIMEOUT=30
```

### 5.4 离线部署约束

- 所有前端库必须本地化（static/vendor/）
- 无外网API调用（地图、字体、CDN均离线）
- Python依赖通过wheels/目录离线安装
- 图数据库（Phase 2）随Docker镜像打包

---

## 六、AI/ML模型规划

### 6.1 模型清单

| 模型 | Phase | 用途 | 框架 | 部署方式 |
|------|-------|------|------|----------|
| YOLO-World | 现有 | 视频/图片检测 | Ultralytics | Docker内CPU/GPU |
| 飙车检测 | 现有 | 飙车炸街识别 | Ultralytics | Docker内 |
| 人脸识别 | 现有 | 身份确认 | InsightFace | Docker内 |
| GNN风险评分 | Phase 2 | 节点分类 | PyG | Docker内GPU |
| 社区发现 | Phase 2 | 团伙识别 | NetworkX/PyG | Docker内 |
| ReID | Phase 2+ | 跨摄像头行人追踪 | - | Docker内GPU |
| LLM | Phase 3 | 画像摘要/GraphRAG | ChatGLM/Qwen | 独立GPU服务 |

### 6.2 GNN模型设计（Phase 2）

```
┌─────────────────────────────────────────────────────┐
│                  GNN训练流程                          │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. 图构建                                          │
│     ┌─────────────────────────────────────────┐    │
│     │ 节点: 管控对象(~5万)                     │    │
│     │ 边:   共犯/同校/同区域/轨迹共现(~50万)   │    │
│     │ 特征: 7维节点特征 + 3维边特征             │    │
│     └─────────────────────────────────────────┘    │
│                                                     │
│  2. 标签构造                                        │
│     - 正样本: 6个月内新增案件的对象(~500人/批)   │
│     - 负样本: 同期无案件的对象(按比例采样)       │
│     - 训练/验证/测试: 7:1.5:1.5                  │
│                                                     │
│  3. 模型结构                                        │
│     GraphSAGE(2层, hidden=128)                      │
│       → ReLU → Dropout(0.3)                        │
│       → Linear(128→1) → Sigmoid                    │
│                                                     │
│  4. 训练策略                                        │
│     - Loss: BCELoss (正负样本加权)                  │
│     - Optimizer: Adam, lr=0.001                     │
│     - 早停: patience=10, metric=AUC                │
│                                                     │
│  5. 推理                                            │
│     - 全量节点推理 → 风险概率 → 映射到0-100分     │
│     - 与规则评分加权融合: 0.6*GNN + 0.4*Rule      │
│                                                     │
└─────────────────────────────────────────────────────┘
```

### 6.3 GraphRAG设计（Phase 3）

```
前提: 内网部署LLM (如Qwen-14B或ChatGLM-6B)

核心流程:
1. 离线: 将图谱数据转为文本描述，建立向量索引
2. 在线: 用户自然语言提问 → 向量检索相关子图 → LLM生成回答

索引构建:
- 每个实体生成描述: "张某，16岁，辍学，涉案3起(盗窃x2,寻衅x1)，与李某共犯2次"
- 每个社区生成摘要: "XX路飙车团伙，3人，核心人物张某，近3月活跃"
- 使用sentence-transformers生成embedding，存入FAISS

查询流程:
- 问题embedding → FAISS top-k → 组装context → LLM回答
- 支持追问和多轮对话
```

---

## 七、API总览

### 7.1 评分模块 `/api/score`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/score/{zjhm}` | 个人评分详情 |
| GET | `/api/score/list` | 评分列表(分页/筛选) |
| GET | `/api/score/trend/{zjhm}` | 评分趋势 |
| POST | `/api/score/recalculate` | 触发重算 |

### 7.2 画像模块 `/api/profile`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/profile/{zjhm}` | 完整画像 |
| GET | `/api/profile/{zjhm}/trajectory` | 轨迹详情 |
| GET | `/api/profile/{zjhm}/timeline` | 时间轴 |
| GET | `/api/profile/{zjhm}/photo` | 照片 |

### 7.3 面板模块 `/api/dashboard`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/dashboard/summary` | 核心指标 |
| GET | `/api/dashboard/trend` | 趋势 |
| GET | `/api/dashboard/distribution` | 分布 |
| GET | `/api/dashboard/alerts` | 预警 |
| GET | `/api/dashboard/ranking` | 排名 |

### 7.4 图谱模块 `/api/graph`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/graph/person/{zjhm}` | 人为中心子图 |
| GET | `/api/graph/case/{ajbh}` | 案件为中心子图 |
| GET | `/api/graph/search` | 搜索节点 |
| POST | `/api/graph/expand` | 扩展关系 |
| GET | `/api/graph/paths` | 最短路径 |
| GET | `/api/graph/community/{zjhm}` | 所属社区(Phase 2) |

---

## 八、数据同步与ETL

### 8.1 同步策略

| 数据 | 策略 | 频率 | 方式 |
|------|------|------|------|
| target_pool | 增量合并 | 每日 | 多表UNION去重 |
| ryrl_gj(轨迹) | 按shot_time增量 | 每小时 | WHERE shot_time > last_sync |
| ly_checkin(旅馆) | 按rzsj增量 | 每日 | WHERE rzsj > last_sync |
| score | 全量重算 | 每日凌晨 | Python批量执行 |
| score_history | 追加 | 每次重算后 | INSERT快照 |
| alert | 实时 | 事件触发 | 规则引擎 |

### 8.2 ETL脚本规划

```
scripts/
├── etl_init.py              # 全量初始化(首次运行)
├── etl_sync_trajectory.py   # 轨迹增量同步
├── etl_sync_checkin.py      # 旅馆增量同步
├── etl_sync_target_pool.py  # 对象池刷新
├── score_batch_calc.py      # 全量评分计算
└── schedule.py              # 定时调度(APScheduler)
```

---

## 九、安全与权限

### 9.1 数据安全

- 所有API要求登录态（复用现有jcgkzx_user/jcgkzx_permission）
- 身份证号在前端脱敏展示（中间6位*号）
- 照片访问需鉴权
- 日志记录查询行为（谁查了谁）

### 9.2 权限模型

| 角色 | 面板 | 画像 | 图谱 | 评分 |
|------|------|------|------|------|
| 管理员 | 全市 | 全部 | 全部 | 读写 |
| 分局用户 | 本辖区 | 本辖区 | 本辖区+关联 | 只读 |
| 派出所用户 | 本辖区 | 本辖区 | 1层 | 只读 |

---

## 十、部署架构

### Phase 1 (单机Docker)

```
┌─────────────────────────────────┐
│          Docker Host            │
│  ┌─────────────────────────┐   │
│  │  multi-rider容器         │   │
│  │  Flask + 评分/画像/面板  │   │
│  │  + NetworkX              │   │
│  │  Port: 5001              │   │
│  └─────────────────────────┘   │
│              │                  │
│              ▼                  │
│  ┌─────────────────────────┐   │
│  │  KingBase (已有)         │   │
│  │  ywdata / stdata /       │   │
│  │  jcgkzx_monitor        │   │
│  └─────────────────────────┘   │
└─────────────────────────────────┘
```

### Phase 2 (多容器)

```
┌─────────────────────────────────────────────┐
│              Docker Compose                   │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │Flask App │  │  Neo4j   │  │  Redis   │  │
│  │ :5001    │  │  :7474   │  │  :6379   │  │
│  └──────────┘  └──────────┘  └──────────┘  │
│                                              │
│  ┌──────────┐  ┌──────────┐                 │
│  │GNN推理   │  │ETL Worker│                 │
│  │(GPU可选) │  │(定时任务)│                 │
│  └──────────┘  └──────────┘                 │
│                     │                        │
│                     ▼                        │
│  ┌──────────────────────────────────────┐   │
│  │           KingBase                    │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
```

---

## 十一、项目里程碑

| 阶段 | 时间 | 交付物 |
|------|------|--------|
| **Phase 1a** | 5/17-5/20 | 数据层建表+ETL完成 |
| **Phase 1b** | 5/20-5/23 | 评分+画像模块完成 |
| **Phase 1c** | 5/23-5/26 | 面板+图谱模块完成 |
| **Phase 1d** | 5/26-5/29 | 串联调试+演示准备 |
| **比赛** | 5/30 | 演示 |
| **Phase 2a** | 6月 | Neo4j集成+GNN训练 |
| **Phase 2b** | 7月 | 社区发现+ReID评估 |
| **Phase 3** | Q3 2026 | GraphRAG+LLM集成 |

---

## 十二、比赛演示路径

```
1. 【态势总览】展示全市管控态势
   → "全市管控未成年人4.5万人，高风险127人，本月新增侵财案件23起"

2. 点击高风险预警 → 进入【个人画像】
   → "张某，16岁，辍学，涉案3起，评分72分，高风险"

3. 点击"展开关系" → 进入【关系图谱】
   → 发现3人飙车盗窃团伙

4. 从图谱"下发任务" → 对接【任务派发】
   → 走访+劝返+夜间巡逻

5. 回到面板展示整体效果
   → "本月评分下降5.2%，管控初见成效"
```

**比赛亮点话术:**
- "5300万条视频轨迹数据驱动的风险预测"
- "多维数据融合的全息画像"
- "关系图谱辅助串并案和团伙识别"
- "前端感知→智能研判→精准打击的完整闭环"
- "GNN图神经网络的风险传播分析"（如Phase 2已有成果）