# syk

**Repository Path**: lang_junnan_admin/syk

## Basic Information

- **Project Name**: syk
- **Description**: 测运控
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-18
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 测运控自诊断与智能决策系统 — 智能任务规划

基于 LangGraph 工作流编排的卫星任务规划系统。用户通过自然语言描述任务需求，系统自动编排 10 个外部 API 调用，生成 20 列卫星任务配置 Excel 表，通过 SSE 流式推送到 Vue 前端，支持在线预览、导出下载和自然语言修改。

## 业务背景

航天测运控领域中的**卫星任务规划**是典型的多步骤、有条件分支的复杂流程。传统方式需要操作员手动登录多个系统，按固定顺序执行 API 调用，填写参数、等待结果、处理异常，一条任务配置可能需要 10-30 分钟。

本系统将任务规划流程抽象为 **LangGraph 状态图**，利用 LLM 从自然语言中提取任务参数，自动编排 API 调用序列，处理常规/应急两条分支、权限占用重试、备用测站回退等业务场景，最终生成标准 20 列 Excel 配置表。

### 核心业务流程

```
用户输入自然语言需求
  → LLM 提取: 星座、时间窗口、任务类型
  → 查询本地任务配置规则 (cyk_task_config)
  → 遍历每条配置:
      ├── 应急任务: 获取空闲弧段 → 过滤 → 检查最低圈次 → 提交应急任务
      └── 非应急任务: 清空规划池 → 查询可用弧段 → 提交规划池 → 冲突消解 → 查询结果
  → 弧段申请 → 等待2分钟 → 查询申请结果
  → 累积弧段数据 → 生成 20 列 Excel
  → 释放权限 → SSE 推送完成
```

### 关键业务场景

| 场景 | 处理方式 |
|---|---|
| 权限被占用 | 暂停等待，前端显示重试按钮，用户点击后从 checkpoint 恢复 |
| 最低圈次不满足 | 自动切换备用测站重试一次，仍不满足则跳过该配置 |
| 规划池被占用 | 跳过当前配置，记录失败日志 |
| 信息缺失（缺少时间/星座） | 暂停并提示用户补充信息 |
| 自然语言修改 Excel | 支持按行号+列名定位修改，重新生成 Excel |

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│  Vue 3 前端 (localhost:9527)                              │
│  ┌──────────┐ ┌──────────────┐ ┌────────────────────┐   │
│  │ 会话列表  │ │  SSE 聊天面板  │ │  已保存方案列表     │   │
│  │ 新建/切换 │ │  日志+表格+   │ │  下载入口          │   │
│  │ 删除/改名 │ │  下载卡片     │ │                    │   │
│  └──────────┘ └──────────────┘ └────────────────────┘   │
└────────────────────┬────────────────────────────────────┘
                     │ SSE + HTTP (Vite proxy)
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Python FastAPI (localhost:8000)                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  LangGraph 工作流引擎 (33 节点, 11 条件分支)       │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────────────┐  │   │
│  │  │ 参数提取  │→│ 权限检查  │→│  配置遍历循环     │  │   │
│  │  │  (LLM)   │ │ (+重试)  │ │  ┌────────────┐  │  │   │
│  │  └──────────┘ └──────────┘ │  │ 应急/非应急  │  │  │   │
│  │                             │  │ 分支处理    │  │  │   │
│  │  ┌──────────┐ ┌──────────┐ │  └────────────┘  │  │   │
│  │  │ Excel    │←│ 弧段累积  │ │  ┌────────────┐  │  │   │
│  │  │ 生成     │ │ (reducer)│ │  │ 弧段申请+    │  │  │   │
│  │  └──────────┘ └──────────┘ │  │ 等待查询     │  │  │   │
│  │       │                     │  └────────────┘  │  │   │
│  │       ▼                     └──────────────────┘  │   │
│  │  MySQL Checkpoint 持久化 (断点恢复)                │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────┐   │
│  │ httpx    │  │ openpyxl │  │ SSE Service        │   │
│  │ 外部API  │  │ Excel    │  │ (asyncio.Queue     │   │
│  │ 客户端   │  │ 生成     │  │  + ContextVar)     │   │
│  └──────────┘  └──────────┘  └────────────────────┘   │
└──────────┬──────────────────────┬──────────────────────┘
           │                      │
           ▼                      ▼
┌──────────────────┐  ┌──────────────────────────┐
│  Mock Server     │  │  MySQL (192.168.1.38)     │
│  (localhost:9000)│  │  ┌──────────────────────┐ │
│  10 个模拟 API    │  │  │ cyk_session          │ │
│  42字段弧段数据    │  │  │ cyk_chat             │ │
│                  │  │  │ cyk_plan_scheme      │ │
│                  │  │  │ cyk_task_config      │ │
│                  │  │  │ cyk_arc_accumulator  │ │
│                  │  │  │ cyk_checkpoints      │ │
│                  │  │  │ cyk_checkpoint_writes│ │
└──────────────────┘  │  └──────────────────────┘ │
                      └──────────────────────────┘
```

## 项目结构

```
syk/
├── main.py                          # FastAPI 入口 (含 init_db 自动建表)
├── pyproject.toml                   # uv 依赖管理 (Python 3.12)
├── mock_server.py                   # 10 个外部 API 模拟器 (:9000)
├── start.bat / stop.bat             # Windows 一键启停脚本
├── app/
│   ├── config.py                    # 全部配置 (DB、LLM、API URL、文件存储)
│   ├── database.py                  # SQLAlchemy 异步引擎 (pool=20)
│   ├── models/                      # ORM 模型 (7 张表, cyk_ 前缀)
│   ├── schemas/                     # Pydantic: request, response, arc_record
│   ├── routers/                     # FastAPI 路由: chat, session, plan_scheme, file
│   ├── services/                    # 业务逻辑: sse, session, plan_scheme, excel, llm
│   ├── tools/                       # httpx 客户端 + 10 个外部 API 封装
│   └── workflow/                    # LangGraph 工作流
│       ├── state.py                 # TaskPlanningState (40+ 字段)
│       ├── edges.py                 # 11 个条件边函数
│       ├── graph.py                 # 图组装 + checkpoint 编译
│       ├── checkpoint_saver.py      # MySQL Checkpoint 持久化
│       └── nodes/                   # 20 个节点函数 (12 个文件)
├── web/                             # Vue 3 前端
│   └── src/
│       ├── views/task-planning.vue  # 主页面 (聊天面板 + 会话列表 + 方案列表)
│       ├── api/chat.js              # API 调用 (axios + SSE fetch)
│       ├── api/request.js           # axios 实例 (baseURL=/api, timeout=60s)
│       ├── store/user.js            # Pinia 用户 store
│       └── utils/markdown.js        # Markdown 渲染
├── prompt/                          # LLM 提示词模板
├── db/schema.sql                    # 参考 DDL
└── storage/upload/                  # 生成的 Excel 文件
```

## 快速开始

### 环境要求

- Python 3.12 + uv
- Node.js 18+
- MySQL (192.168.1.38:3307, 库名 syk)

### 启动

```bash
# 1. 安装 Python 依赖
uv sync

# 2. 启动 Mock 外部 API 模拟器 (端口 9000)
uv run uvicorn mock_server:app --reload --port 9000

# 3. 启动 FastAPI 后端 (端口 8000)
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 4. 启动 Vue 前端 (端口 9527, 代理 /api → :8000)
cd web && npm install && npm run dev
```

或 Windows 下一键启动: `start.bat`

### 使用流程

1. 打开 `http://localhost:9527`
2. 点击左侧"新建会话"
3. 输入自然语言需求，例如：
   - `编排连连看星座2026年9月14日的常规测试规划方案`
   - `编排铱星星座在2026年5月20日到5月22日的应急任务`
4. 等待 SSE 实时推送执行日志和步骤进度
5. 生成完成后在聊天框底部看到 Excel 表格预览和下载按钮
6. 可通过自然语言修改 Excel，例如：
   - `卫星任务配置表里的第3行仰角修改成200`
   - `把第5行的设备名称改成北京密云站`
7. 点击"保存方案"将 Excel 持久化到右侧方案列表

## API 端点

| Method | Path | 用途 |
|---|---|---|
| POST | `/api/chat/stream` | 发起 SSE 任务规划流 |
| POST | `/api/chat/retry` | 权限获取重试 (从 checkpoint 恢复) |
| POST | `/api/chat/modify` | 自然语言修改已生成 Excel |
| POST | `/api/sessions` | 创建会话 |
| GET | `/api/sessions?user_id=` | 用户会话列表 |
| GET | `/api/sessions/{id}` | 会话详情 + 聊天记录 |
| PATCH | `/api/sessions/{id}` | 修改会话标题 |
| DELETE | `/api/sessions/{id}` | 删除会话 |
| GET | `/api/sessions/{id}/schemes` | 会话已保存方案 |
| POST | `/api/schemes` | 保存方案 |
| DELETE | `/api/schemes/{id}` | 删除方案 |
| GET | `/api/file/task-download/{filename}` | Excel 下载 |
| GET | `/api/health` | 健康检查 |

## SSE 事件类型

| token_type | 用途 | 前端表现 |
|---|---|---|
| `status` | 终端日志行 | 深色终端块，等宽字体实时追加 |
| `progress` | 步骤进度 | 可折叠步骤列表，含勾/叉/转圈状态 |
| `answer` | AI 文本回复 | Markdown 渲染气泡 |
| `table` | Excel 表格数据 | 表格预览 + 下载/保存方案卡片 |
| `error` | 错误信息 | 红色错误提示 |
| `retry_prompt` | 需用户操作 | 显示重试按钮 |

## 数据表

| 表名 | 用途 | 关键字段 |
|---|---|---|
| `cyk_session` | 会话管理 | id, user_id, title, status, thread_id |
| `cyk_chat` | 聊天消息 | id, session_id, role, content, token_type |
| `cyk_plan_scheme` | 保存的方案 | id, session_id, scheme_name, excel_url |
| `cyk_task_config` | 任务配置规则 | id, task_type, satellite_group, min_orbit_count, backup_stations |
| `cyk_arc_accumulator` | 弧段累积 | id, session_id, config_index, arc_data_json |
| `cyk_checkpoints` | LangGraph checkpoint | thread_id, checkpoint, metadata |
| `cyk_checkpoint_writes` | checkpoint 写入 | thread_id, channel, value |

## 技术选型

| 组件 | 选型 | 原因 |
|---|---|---|
| 工作流引擎 | LangGraph | 支持条件分支、循环、checkpoint 持久化，适合多步骤 API 编排 |
| LLM | Qwen3.5-9b (本地) | 参数提取任务无需超大模型，本地部署低延迟 |
| 实时推送 | SSE (Server-Sent Events) | 单向流式推送，比 WebSocket 更轻量，浏览器原生支持 |
| 前端框架 | Vue 3 + Element Plus | 成熟的企业级 UI 组件库，中文生态完善 |
| Excel 生成 | openpyxl | 支持样式、合并单元格，社区活跃 |
| Checkpoint | MySQL (自定义 Saver) | 与业务数据库统一，避免引入 Redis 等额外组件 |