aps-agent/README.md

# 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，Web/桌面共用）
├─ apps/desktop/       # Electron 壳（数据落 ~/.aps，对标 Codex）
├─ server/             # FastAPI（Gateway + Agent Core + 规则引擎 + 世界状态）
├─ scripts/            # dev:web / dev:desktop 启动脚本
├─ 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) |

## 快速开始

### 形态说明

| 形态 | 用户数据 | 开发命令 | 打包 | 部署 |
| --- | --- | --- | --- | --- |
| **Web** | 仓库 `server/data/`（或 `APS_HOME`） | `npm run dev:web` | `npm run build:web` | 静态前端 + 后端服务 |
| **桌面** | `~/.aps/`（skills/sessions/data…，对标 Codex） | `npm run dev:desktop` | `npm run build:desktop` | 发安装包，无需服务器托管 UI |

详见 [docs/architecture/desktop.md](docs/architecture/desktop.md)。

### 1. 依赖

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

npm run bootstrap                   # 安装 apps/web + apps/desktop 依赖
```

### 2. 开发运行

本地联调用户与项目分享功能前，在 `.env` 中显式设置：

```bash
APS_AUTH_PROVIDER=mock
APS_LICENSE_PROVIDER=mock
APS_MOCK_TENANT_UUID=demo0000000000000000000000000001
```

默认 `APS_AUTH_PROVIDER=unconfigured` 会关闭全部业务 API，直到正式用户管理接口完成配置。
Web 开发账号可使用 `planner` / `collaborator` / `viewer`（密码任意非空）；桌面端不使用账号，
开发授权码为 `APS-HOUR-DEMO`、`APS-DAY-DEMO`、`APS-WEEK-DEMO`、`APS-MONTH-DEMO`、
`APS-YEAR-DEMO`、`APS-PERP-DEMO`。

```bash
# Web（浏览器 http://localhost:5173 ，API :8000）
npm run dev:web

# 桌面（Electron 窗口；数据写入 %USERPROFILE%\.aps）
npm run dev:desktop
```

### 3. 打包

```bash
npm run build:web               # apps/web/dist → 部署静态站
npm run build:desktop           # Electron 安装包 → apps/desktop/release
```

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

打开 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 大管家）。