145 lines
4.5 KiB
Markdown
145 lines
4.5 KiB
Markdown
# 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-12）**：进销存、财务、商城和扩展模块已形成可运行闭环，当前本地回归为 **510 passed / 4 skipped（SQLite）**，**514 passed（PostgreSQL 5433，含 4 并发用例）**，前端 `npm run build` ✅ + `npm test` ✅ 11/11。附录 A 后端 10 项能力前端已全接入（收款/付款/核销/流水/预警规则/打印模板/自定义报表/库存大盘/科目/价格等级联系人），见 `PROGRESS_AGI_ITERATION_6.md`。
|
||
|
||
- ✅ 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
|