# dealerhub · 经销商 SaaS

> 类似管家婆的进销存+财务+分销管理 SaaS。技术栈：**Django 5.2 + DRF + adrf + Granian + PostgreSQL**。

## 目录结构

```
dealerhub/
├── PLAN.md            # 总体实施计划（5 个阶段）
├── README.md          # 本文件
└── backend/           # Django 后端
    ├── manage.py
    ├── requirements.in
    ├── pytest.ini
    ├── conftest.py
    ├── config/        # 项目配置（settings/{base,dev,prod,test}.py + asgi.py）
    ├── apps/          # 业务应用
    │   ├── core/      # 多租户/多组织/审计日志
    │   └── catalog/   # 商品中心
    ├── tests/         # 集成测试
    └── .env
```

## 快速开始

### 1. 安装依赖（本机已有 Django 5.2.16 + DRF + adrf + Granian 2.8）

```bash
pip install -r backend/requirements.txt
```

### 2. 初始化数据库（SQLite）

```bash
cd backend
python manage.py migrate
python manage.py seed_initial_data
python manage.py createsuperuser
```

### 3. 启动 Granian（ASGI）

```bash
cd backend
sh infra/scripts/run_dev.sh
# 或直接：
DJANGO_SETTINGS_MODULE=config.settings.dev granian config.asgi:application \
    --interface asgi --host 0.0.0.0 --port 8000 --reload
```

### 4. 验证

```bash
curl http://127.0.0.1:8000/api/v1/ping/
```

返回示例：
```json
{
  "ok": true,
  "service": "dealerhub",
  "ts": "2026-09-07T00:30:00+00:00",
  "versions": {
    "python": "3.12.x",
    "django": "5.2.x",
    "granian": "2.8.x"
  }
}
```

### 5. 运行测试

```bash
cd backend
pytest
```

### 6. 构建生产镜像（自包含前端）

生产镜像使用仓库根目录作为构建上下文，Docker 多阶段构建会自动编译 Vue 前端并把产物交给 Django：

```bash
# 在仓库根目录执行
DJANGO_SECRET_KEY='replace-me' POSTGRES_PASSWORD='replace-me' \\
  docker compose -f backend/infra/docker/docker-compose.yml config
DJANGO_SECRET_KEY='replace-me' POSTGRES_PASSWORD='replace-me' \\
  docker compose -f backend/infra/docker/docker-compose.yml build backend
```

本地演示账套：

```bash
cd backend
python manage.py seed_demo --reset
python manage.py seed_full_finance
```

`seed_demo --reset` 会重建商城、库存、销售、采购、应收和六档账龄数据；`seed_full_finance` 为全部启用租户初始化科目和会计期间。生产环境请通过部署密钥注入 `DJANGO_SECRET_KEY` 与 `POSTGRES_PASSWORD`，不要把凭据写进仓库。

## 当前阶段

**AGI 迭代基线（2026-09-11）**：进销存、财务、商城和扩展模块已形成可运行闭环，当前本地回归为 **460 passed / 4 skipped**。

- ✅ Django + DRF + adrf + Granian 异步链路打通
- ✅ 多租户数据过滤、JWT 鉴权与审计日志
- ✅ 商品、批次、单位换算、自动取价、最低售价、抹零、信用额度
- ✅ 销售/采购开单、过账、库存 FEFO、应收应付与财务报表
- ✅ 商城、渠道、通知预警、开放 API、打印和 AI 录单
- ✅ Docker 多阶段构建：自动编译前端并复制到 Django 静态目录
- ✅ 前端交易金额/单位换算回归测试与 `npm test`
- ⏳ PostgreSQL 并发用例需在可用的 PG 环境执行（本地 SQLite 回归跳过 4 项）

## 多租户调用示例

```bash
# 1. 拿 token
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/token/ \
    -H "Content-Type: application/json" \
    -d '{"username":"alice","password":"alice12345"}' | jq -r .access)

# 2. 带 X-Tenant-Id 调业务 API
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Tenant-Id: default" \
     http://127.0.0.1:8000/api/v1/catalog/products/
```

## 架构预留点

详见 `PLAN.md` §"关键架构决策记录"。已落地：
- ✅ 多租户单数据库（`tenant_id` 列隔离）
- ✅ 多组织预留（`Org` 模型 + `org_path`）
- ✅ 软删除（`is_deleted`）
- ✅ 扩展 JSON（`ext_data`）
- ✅ 来源渠道（`source_channel`，预留 AI/电商对接）

待落地（阶段 3）：
- ⏳ 多币种/多税率
- ⏳ 财务模块对接接口（LedgerAdapter）
- ⏳ 电商平台对接（ChannelAdapter）
- ⏳ 工作流引擎（StateMachine 服务化）
- ⏳ 插件钩子（HookRegistry）
- ⏳ 报表元数据
- ⏳ AI Agent 接入点
- ⏳ 开放 API + Webhook