132 lines
5.3 KiB
Markdown
132 lines
5.3 KiB
Markdown
# 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. 开发运行
|
||
|
||
联调 Web 用户登录前，在 `.env` 中设置 JMS 地址与本地会话密钥：
|
||
|
||
```bash
|
||
APS_AUTH_PROVIDER=jms
|
||
JMS_AUTH_BASE_URL=https://<your-jms-host>
|
||
JMS_AUTH_SESSION_SECRET=至少32个随机字符
|
||
APS_LICENSE_PROVIDER=mock
|
||
APS_MOCK_LICENSE_SECRET=至少32个随机字符
|
||
APS_MOCK_LICENSE_TENANT_UUID=本地开发租户标识
|
||
```
|
||
|
||
Web 端会从 JMS 读取启用企业，用户选择所属企业后使用真实账号密码登录；如需限制为单一企业，
|
||
可配置 `JMS_AUTH_TENANT_CODE` 与 `JMS_AUTH_TENANT_NAME`。JMS 当前没有自助注册或未登录自助
|
||
找回密码接口，账号创建与密码重置由所属企业管理员处理。
|
||
桌面端不使用账号，开发授权码为
|
||
`APS-HOUR-DEMO`、`APS-DAY-DEMO`、`APS-WEEK-DEMO`、`APS-MONTH-DEMO`、
|
||
`APS-YEAR-DEMO`、`APS-PERP-DEMO`。
|
||
|
||
### 授权码部署（codes 模式：授权码即用户身份）
|
||
|
||
独立 Web 交付（不走 JMS）时可改用授权码认证：用户打开系统即看到"请提供授权码"，
|
||
激活后智能体会话、项目、主数据全部绑定到该授权码；每个授权码只能看到自己的数据，
|
||
同一授权码换浏览器/设备激活可找回同一份数据。配置示例：
|
||
|
||
```bash
|
||
APS_LICENSE_PROVIDER=codes
|
||
APS_LICENSE_SECRET=至少32个随机字符
|
||
APS_LICENSE_CLIENTS=web,desktop
|
||
# 发放给用户的一一对应的授权码（类型：hour/day/week/month/year/permanent）
|
||
APS_LICENSE_CODES={"APS-USER-001":"year","APS-USER-002":{"type":"month","name":"张三"}}
|
||
```
|
||
|
||
内置超级管理员授权码 `aps@Z@Agent@Admin`（永久授权 + 全功能角色），无需配置即可使用；
|
||
用管理员码登录后，可在「设置 → 用户与授权」面板直接发放/停用/删除用户授权码
|
||
（登记姓名、手机号、公司、有效时间，系统自动生成授权码），无需重启服务；
|
||
`APS_AUTH_PROVIDER=jms` 同时存在时 JMS 优先，授权码模式不生效。
|
||
|
||
```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 最新验证数）
|
||
|
||
Web 端读取本机数据文件：在项目面板「文件」区点「上传」，选择本机的
|
||
`.xlsx/.xlsm/.csv/.txt/.sql`（可多选）；上传后自动作为该项目的工程目录，
|
||
对话中说「分析一下数据文件」即可走同一套目录分析与排产链路。
|
||
|
||
完整旅程说明：[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 大管家）。
|