# demo-codebuddy-erp-1

**Repository Path**: larntin/demo-codebuddy-erp-1

## Basic Information

- **Project Name**: demo-codebuddy-erp-1
- **Description**: muti-agents 项目的测试 erp 系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 好再来零食连锁 ERP 模拟系统（V1）

> 纯 ERP 版 · 前后端全栈示例 · 内置日志闭环可观测

## 一、项目目的

「好再来零食连锁」是一个**模拟业务**的零食零售连锁企业。本项目以它为例，实现一个最小可用的 ERP 系统，用于：

- 演示一套**标准的前后端分离全栈架构**（React + FastAPI + SQLite）；
- 验证**业务闭环**：采购入库 → 库存 → 销售出库 → 库存回补，以及库存唯一出口、状态机等核心规则；
- 落地**日志闭环可观测**：前端每一次操作都携带 `X-Request-Id`，可直接在「系统日志」面板检索到对应的后端日志，实现「前台报错 → 后台日志」一键对账；
- 为后续 **Multi-Agents** 项目准备可运行的工程基座（本版不引入 Agent，范围保持最小）。

需求原稿见 [`docs/500-好再来零食连锁_ERP模拟系统需求说明_V1.0_纯ERP版.md`](docs/500-好再来零食连锁_ERP模拟系统需求说明_V1.0_纯ERP版.md)。

## 二、基础架构

分层：**接口层 / 服务层 / 数据层 + 横切 core**，前后端严格分离。

```
┌─────────────────────────────┐         ┌──────────────────────────────────────┐
│  Frontend (React + Vite)     │  HTTP   │  Backend (FastAPI)                    │
│  127.0.0.1:5173              │ ──────▶ │  127.0.0.1:8000                       │
│                              │  /api   │                                        │
│  - 顶部标题栏 + 左侧菜单      │ ◀────── │  api/v1/                               │
│  - 通用 CRUD 表格 (元数据驱动)│  JSON   │    - resources  (通用 CRUD 路由)        │
│  - 采购/销售/库存/日志定制页  │         │    - purchase / sales / inventory       │
│  - 系统日志面板 (检索 request_id)│    │    - auth / options / logs              │
└─────────────────────────────┘         │                                        │
                                          │  service 层 (业务规则/状态机/库存)      │
                                          │  db 层 (SQLAlchemy 2.0 + SQLite)       │
                                          │  core (日志/安全/配置/上下文)            │
                                          └──────────────────────────────────────┘
```

**技术栈**

| 层 | 技术 | 说明 |
| --- | --- | --- |
| 前端 | React 18 + TypeScript + Vite | 构建工具 |
| 前端 | Tailwind CSS + shadcn/ui（源码纳入仓库） | 基于 Radix UI，原子组件在 `frontend/src/components/ui/` |
| 后端 | FastAPI + Uvicorn | 异步 Web 框架 |
| 后端 | SQLAlchemy 2.0 + Pydantic v2 | ORM + 数据校验 |
| 存储 | SQLite | 经 SQLAlchemy 抽象，库文件在 `tmp/db/erp.db` |
| 可观测 | 结构化单行 JSON 日志 + `request_id` 透传 | 详见 `docs/04` |

**核心业务规则（详见 `docs/01`、`docs/02`）**

- 库存唯一出口：所有出入库只经 `inventory_service.apply_movement`，结存与流水同一事务双写；
- 采购状态机：`draft → submitted → approved → ordered → received → completed`，`received` 触发入库；
- 销售：创建即 `confirmed` 并扣库存，取消按原出库流水批次回补；
- 统一日志：滚动切割（5MB×10 份）+ 运行时调级 + 日志回读接口。

## 三、默认登录账号

系统内置种子用户（首次启动自动建库并写入）：

| 用户名 | 密码 | 角色 | 权限 |
| --- | --- | --- | --- |
| `admin` | `admin123` | 系统管理员 | 全部功能，含用户管理与日志级别调整 |
| `operator` | `operator123` | 业务操作员 | 业务功能；**不能**访问用户管理、不能调整日志级别 |

> 仅用于本地模拟环境，生产务必替换为环境变量注入的密钥（见 `backend/app/core/config.py`）。

## 四、本地开发

### 0. 仓库结构（要点）

```
demo-codebuddy-erp-1/
├── backend/            # FastAPI 后端
│   ├── app/            # 应用代码（core / db / models / schemas / services / api）
│   ├── requirements.txt
│   └── run.py          # 启动入口
├── frontend/           # React 前端
│   ├── src/
│   │   ├── components/ # AppLayout / ResourceTable / ui 原子组件
│   │   ├── pages/      # 登录 / 采购 / 销售 / 库存 / 流水 / 日志
│   │   ├── lib/        # api / auth / types / status / utils
│   │   └── config/     # resources.ts 资源元数据 + 菜单
│   └── vite.config.ts  # /api 代理到 127.0.0.1:8000
├── docs/               # 00~06 设计/规范文档（单一事实源）
└── tmp/                # 运行产物（日志/数据库/冒烟），不入库
```

### 1. 启动后端（8000）

```bash
cd backend

# 建议用虚拟环境（Python 3.11+）
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 启动（首次会自动创建 tmp/db/erp.db 并写入种子数据）
python run.py
# 监听 http://127.0.0.1:8000
```

健康检查：`GET http://127.0.0.1:8000/api/v1/health`

### 2. 启动前端（5173）

```bash
cd frontend

# 安装依赖
# 提示：部分镜像对 tarball 限速严重，建议用官方源
npm install --registry=https://registry.npmjs.org/

# 开发模式
npm run dev
# 打开 http://127.0.0.1:5173
```

Vite 已将 `/api` 代理到后端 `127.0.0.1:8000`，开发时无需额外配置跨域。

### 3. 构建前端（可选）

```bash
cd frontend
npm run build        # 产物在 frontend/dist/
```

## 五、文档导航

设计/规范文档是项目的**单一事实源**，跨模块引用均以「相对路径 + 段落编号」：

- `docs/00-系统总体需求.md`
- `docs/01-总体架构设计.md`
- `docs/02-数据模型设计.md`
- `docs/03-后端API契约.md`
- `docs/04-日志与可观测性规范.md`
- `docs/05-前端设计规范.md`
- `docs/06-测试与冒烟验收.md`

## 六、提交与协作

- 源码、文档入库；`tmp/`、`node_modules/`、`*.db`、`.workbuddy/` **不入库**（见 `.gitignore`）。
- 远程仓库：`https://gitee.com/larntin/demo-codebuddy-erp-1`