# ams

**Repository Path**: doublez99/ams

## Basic Information

- **Project Name**: ams
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 亚马逊运营自动化与智能预警

将 Amazon 运营数据（关键词、价格、库存）自动采集、分析，以**飞书多维表格**为业务操作台，实现从「人工巡检」到「自动发现→通知→认领→处置→关闭」的异常预警闭环。

> 方案硬约束：不建设独立后台。飞书多维表格就是业务数据平台、操作台和协作中心。

## 🚀 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 生成模拟数据（1店铺 × 1站点 × 30SKU × 20关键词）
PYTHONPATH=src python3 -m amazon_ops.cli mock

# 3. 运行分析管道（13 条异常规则）
PYTHONPATH=src python3 -m amazon_ops.cli run

# 4. 查看结果
PYTHONPATH=src python3 -m amazon_ops.cli status
PYTHONPATH=src python3 -m amazon_ops.cli list

# 5. 同步到飞书 Bitable
PYTHONPATH=src python3 src/amazon_ops/sync_to_bitable.py
```

**无需 Amazon 账号**即可完成全部开发和验证。

## 📊 飞书多维表格

**[🔗 打开 Base](https://my.feishu.cn/base/KDfpbHwPpaq8issAuyqcThxln1b)**

| 12 张数据表 | 4 个仪表盘 |
|---|---|
| 商品主数据 · 关键词监控 · 关键词日指标 | 🔑 关键词分析（含词云） |
| 价格最新状态 · 价格日汇总 | 💰 价格监控 |
| 库存最新状态 · 库存日汇总 | 📦 库存风险 |
| 预警工单 · 任务台账 · 效益台账 · 报告索引 · 配置中心 | 🏢 管理驾驶舱 |

## 🔔 告警闭环

```
自动采集 → 分析管道（13条规则）→ 生成工单 → 飞书消息通知
                                            ↓
                              关闭 ← 复核 ← 处理 ← 认领
```

CLI 命令：`claim` | `close` | `ignore` | `reassign` | `list`

## 🧪 测试

```bash
PYTHONPATH=src python3 -m pytest tests/ -v
# 44 tests passed — 覆盖全部 13 条管道规则
```

## 🐳 Docker

```bash
# 开发模式（一键：mock + run + sync）
docker compose --profile dev up app-dev

# 生产模式（PostgreSQL + scheduler）
docker compose --profile prod up -d
```

## 📖 文档

| 文档 | 读者 | 内容 |
|---|---|---|
| [00-产品总览](docs/00-产品总览.md) | **先读我** — 所有人 | 项目完整说明书，架构、规则、开发、交付 |
| [CLAUDE.md](CLAUDE.md) | AI Agent / 新成员 | 命令速查、开发约定 |
| [01-需求说明](docs/01-需求说明.md) | 产品 / 业务 | 业务需求、验收标准、效益目标 |
| [02-技术方案](docs/02-技术方案.md) | 开发 / 架构 | 架构设计、12张表、规则公式、安全规范 |
| [03-飞书CLI环境搭建](docs/03-飞书CLI环境搭建.md) | 新成员搭环境 | lark-cli 安装、Base 创建、字段配置 |
| [04-影刀RPA接入](docs/04-影刀RPA接入.md) | RPA 配置 | 影刀工作流、CSV格式、去重策略 |
| [05-Amazon SP-API接入](docs/05-Amazon%20SP-API接入.md) | 后端对接 | SP-API 注册、连接器架构、mock 替换 |

## 🏗️ 技术栈

| 层级 | 选型 | 说明 |
|---|---|---|
| 语言 | Python ≥ 3.11 | |
| 数据库 | SQLite(开发) → PostgreSQL 16(生产) | SQLAlchemy 抽象，一行切换 |
| 数据校验 | Pydantic v2 | |
| CLI | Rich + Typer | 美化的终端输出 |
| 飞书集成 | lark-cli + IM OpenAPI | CLI 开发运维，SDK + 消息卡片生产链路 |
| 调度 | APScheduler | 轻量级，本地开发零依赖 |
| RPA 兜底 | 影刀 → CSV → `rpa_ingest.py` | 仅用于无 API 的数据缺口 |
| 部署 | Docker Compose | 开发 + 生产一体 |

## 📁 项目结构

```
src/amazon_ops/
├── config.py              # .env 配置 + logging
├── cli.py                 # CLI: mock|run|status|list|claim|close|ignore|reassign
├── scheduler.py           # 定时调度（APScheduler）
├── notifier.py            # 飞书消息通知（卡片 + 日报）
├── rpa_ingest.py          # 影刀 CSV/JSON → DB
├── sync_to_bitable.py     # DB → 飞书 Bitable
├── db/models.py           # 10 张表 ORM
├── schemas/               # Pydantic 校验（9 个 schema）
├── mock/                  # 模拟数据（seed=42，确定性）
├── pipeline/              # 分析管道（13 条异常规则）
│   ├── keyword_analysis.py   # 4 条关键词规则
│   ├── price_monitor.py      # 5 条价格规则
│   └── inventory_check.py    # 4 条库存规则
└── connectors/            # (待实现) SP-API / WMS 连接器
```

## 📌 当前状态

- **v0.2** — 本地 SQLite + mock 数据 + 飞书 Bitable + 调度器 + 通知
- 管道 13 条规则全部可运行，幂等去重
- 44 个单元测试，覆盖全部规则
- 飞书消息卡片通知（lark-cli 模式）
- Docker Compose 一键部署
- **无需 Amazon 账号即可开发全流程**
- 待补：真实 Amazon SP-API 对接、Celery/Redis 分布式调度