# APS 计划排产智能体

> 左手自然语言对话、右手可视化排产盘的计划排产智能体。  
> **文档入口（大管家）**：[docs/README.md](docs/README.md)  
> 架构蓝图：[plan.md](plan.md)（目标态多，落地以 `docs/` 分类文档为准）  
> 交互验证原型：[poc/workbench.html](poc/workbench.html)

## 仓库结构

```
aps-agent/
├─ apps/web/           # React 18 + TS + Vite（左说右动 UI）
├─ server/             # FastAPI（Gateway + Agent Core + 规则引擎 + 世界状态）
├─ shared/             # 跨语言契约（JSON Schema）
├─ tests/golden/       # 黄金测试（pytest）
├─ docs/               # 活文档（大管家 + 产品/架构/算法）
├─ aps-frontend/       # 早期静态原型（对照用）
├─ poc/                # 「左说右动」POC
└─ plan.md             # 架构蓝图
```

## 文档怎么找

| 你是谁 | 从哪读 |
| --- | --- |
| 产品 / 业务 | [docs/product/](docs/product/) |
| 架构 / 研发 | [docs/architecture/](docs/architecture/) |
| 算法 | [docs/algorithm/](docs/algorithm/) |
| 每次改动记账 | [docs/CHANGELOG.md](docs/CHANGELOG.md) |

## 快速开始

### 1. 后端（Python 3.11+）

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows；Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

copy .env.example .env          # 可选：不配 LLM 也能跑（规则降级）

python -m uvicorn server.main:app --reload --port 8000
```

### 2. 前端（Node 18+）

```bash
cd apps/web
npm install
npm run dev                     # http://localhost:5173，/api 代理到 8000
```

### 3. 验收路径（摘录）

打开 http://localhost:5173 ：

1. 「对比几种策略」→ 方案卡 → 采用 → 右侧甘特刷新  
2. 「存个档」→ 时间线检查点 → 点检查点回滚（P2 确认卡）  
3. 「试排一版交期优先」/ 「发布这个版本」  
4. `pytest tests/golden -q`（当前期望全绿，见 CHANGELOG 最新验证数）

完整旅程说明：[docs/product/journeys.md](docs/product/journeys.md)

## 大模型接入

DeepSeek / KIMI（OpenAI 兼容），`.env` 配置 `LLM_PROVIDER` / `LLM_API_KEY` 等。  
意图：正则快路 → LLM JSON；失败自动降级。详见 plan.md §9.6。

## 代码规范

遵循 plan.md §12：中文意图注释、权力等级、moduleId、**文档同轮同步**（见 docs 大管家）。