## Aurask

Aurask 首版已按 `Aurask_Technical_Operations_Plan.md` 落地为一个可运行的模块化单体后端，覆盖以下核心边界：

- `Auth + API Gateway`
- `Billing + Quota + TBU Ledger`
- `Workflow Orchestrator`
- `Langflow` 模板化运行适配层
- `AnythingLLM` Workspace / 文档接入适配层
- `USDT-TRC20` 订单与支付匹配
- `Audit / Usage / Observability` 基础留痕

当前实现是 **MVP 版本**：

- 使用本地 JSON 文件持久化，便于开发和演示
- 保留了租户、订单、额度、模板、知识库、支付等核心领域边界
- 后续可以自然迁移到 PostgreSQL、任务队列、Runtime Pool 和真实外部服务

### Quick start

运行演示：

```bash
uv run aurask demo --reset
```

启动本地网关：

```bash
uv run aurask serve --reset --host 127.0.0.1 --port 8080
```

### Demo flow

`aurask demo` 会自动完成：

1. 创建租户与 owner 用户
2. 分配基础套餐
3. 创建默认知识库 Workspace
4. 执行一个安全模板工作流
5. 输出 API Key、工作流结果和剩余额度

### HTTP API

公开接口：

- `GET /health`
- `GET /plans`
- `POST /demo/bootstrap`
- `POST /tenants`

鉴权后接口：

- `GET /quota`
- `GET /workflow-templates`
- `POST /workspaces`
- `POST /documents`
- `POST /orders`
- `POST /payments/match`
- `POST /workflow-runs`
- `GET /workflow-runs/{run_id}`

鉴权方式：

```http
Authorization: Bearer <api_key>
```

### Example

1. 创建演示租户：

```bash
curl -X POST http://127.0.0.1:8080/demo/bootstrap ^
  -H "Content-Type: application/json" ^
  -d "{}"
```

2. 使用返回的 `api_key` 查询模板：

```bash
curl http://127.0.0.1:8080/workflow-templates ^
  -H "Authorization: Bearer <api_key>"
```

3. 创建 Workspace：

```bash
curl -X POST http://127.0.0.1:8080/workspaces ^
  -H "Authorization: Bearer <api_key>" ^
  -H "Content-Type: application/json" ^
  -d "{\"name\":\"Support KB\"}"
```

4. 运行模板工作流：

```bash
curl -X POST http://127.0.0.1:8080/workflow-runs ^
  -H "Authorization: Bearer <api_key>" ^
  -H "Content-Type: application/json" ^
  -d "{\"template_id\":\"tpl_email_assistant\",\"inputs\":{\"topic\":\"refund policy reply\"}}"
```

### Testing

```bash
python -m unittest discover -s tests -v
```

### Deployment

- `deploy/k3s/README.md`: 面向 `300` 名月度活跃用户的 `k3s` 部署方案

### Project layout

- `AGENTS.md`: 项目级实现约束
- `Aurask_Technical_Operations_Plan.md`: 技术与运营方案
- `src/aurask/app.py`: 应用装配
- `src/aurask/api.py`: HTTP 网关
- `src/aurask/auth.py`: 租户、用户与 API Key
- `src/aurask/billing.py`: 套餐、订单与权益发放
- `src/aurask/quota.py`: TBU 预扣、结算与额度账本
- `src/aurask/orchestrator.py`: 模板工作流编排
- `src/aurask/knowledge_base.py`: Workspace 与文档接入
- `src/aurask/payments.py`: USDT-TRC20 支付匹配
- `tests/`: 单元测试