# tradeSys

**Repository Path**: M_Fisher/trade-sys

## Basic Information

- **Project Name**: tradeSys
- **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-02-26
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tradeSys

大宗商品贸易管理系统（Monorepo）。

## 技术栈

- 前端：Vue 3 + Element Plus + Vue Router（JavaScript）
- 后端：Fastify（JavaScript）
- 数据库：PostgreSQL + Knex

## 目录结构

```text
.
├─ apps/
│  ├─ web/
│  │  └─ src/
│  │     ├─ layouts/
│  │     ├─ modules/
│  │     │  ├─ auth/
│  │     │  ├─ contracts/
│  │     │  └─ rbac/
│  │     ├─ router/
│  │     └─ shared/
│  └─ api/
│     └─ src/
│        ├─ bootstrap/
│        ├─ plugins/
│        ├─ modules/
│        │  ├─ auth/
│        │  ├─ contracts/
│        │  ├─ rbac/
│        │  └─ system/
│        └─ db/
├─ packages/
│  └─ shared/
│     └─ src/
│        ├─ contracts/
│        └─ utils/
├─ infra/
│  └─ db/
│     ├─ migrations/
│     └─ seeds/
└─ docs/
```

## 快速启动

1. 安装依赖

```bash
npm install
```

2. 准备数据库（连接本地 PostgreSQL）

```bash
npm run db:ensure
npm run db:migrate
npm run db:seed
```

3. 启动前后端

```bash
npm run dev:all
```

- Web: `http://localhost:5173`
- API: `http://localhost:9001`

## 默认账号

- username: `admin`
- password: `123456`

## 核心接口

- 认证：
  - `POST /api/v1/auth/login`
  - `POST /api/v1/auth/refresh`
  - `POST /api/v1/auth/logout`
  - `GET /api/v1/auth/me`
- 合同：
  - `GET /api/v1/contracts`（需要 `contracts:read`）
  - `POST /api/v1/contracts`（需要 `contracts:write`）
  - `PUT /api/v1/contracts/:contractNo`（需要 `contracts:write`）
  - `POST /api/v1/exports/contracts/tasks`（需要 `contracts:read`）
  - `GET /api/v1/exports/contracts/tasks/:taskId`（需要 `contracts:read`）
  - `GET /api/v1/exports/contracts/tasks/:taskId/file`（需要 `contracts:read`）
- 银行流水：
  - `GET /api/v1/payments`（需要 `contracts:read`）
  - `POST /api/v1/payments`（需要 `contracts:write`）
  - `PUT /api/v1/payments/:recordId`（需要 `contracts:write`）
  - `POST /api/v1/payments/:recordId/delete`（需要 `contracts:write`）
- 提货流水：
  - `GET /api/v1/deliveries`（需要 `contracts:read`）
  - `POST /api/v1/deliveries`（需要 `contracts:write`）
  - `PUT /api/v1/deliveries/:recordId`（需要 `contracts:write`）
  - `POST /api/v1/deliveries/:recordId/delete`（需要 `contracts:write`）
- 合同匹配：
  - `GET /api/v1/matchings`（需要 `contracts:read`）
  - `POST /api/v1/matchings`（需要 `contracts:write`）
  - `PUT /api/v1/matchings/:recordId`（需要 `contracts:write`）
  - `POST /api/v1/matchings/:recordId/delete`（需要 `contracts:write`）
- 发票流水：
  - `GET /api/v1/invoices`（需要 `contracts:read`）
  - `POST /api/v1/invoices`（需要 `contracts:write`）
  - `PUT /api/v1/invoices/:recordId`（需要 `contracts:write`）
  - `POST /api/v1/invoices/:recordId/delete`（需要 `contracts:write`）
- 看板汇总：
  - `GET /api/v1/dashboard/summary`（需要 `contracts:read`）
- RBAC：
  - `GET /api/v1/rbac/users`
  - `POST /api/v1/rbac/users`
  - `GET /api/v1/rbac/roles`
  - `POST /api/v1/rbac/roles`
  - `GET /api/v1/rbac/permissions`
  - `POST /api/v1/rbac/permissions`
  - `POST /api/v1/rbac/assignments`
- 系统：
  - `GET /api/v1/ping`
  - `GET /healthz`

## 权限模型

- 采用 `user -> role -> permission`。
- 权限点格式：`resource:action`，示例：`contracts:read`、`rbac:write`。
- 数据域采用 `rbac_user_district`，`*` 表示全片区。

## 环境变量

- API：`apps/api/.env.example`
- Web：`apps/web/.env.example`

数据库连接优先使用 `DATABASE_URL`。

看板刷新相关可选环境变量：
- `DASHBOARD_EVENT_BATCH_DELAY_MS`：事件打标到触发批量刷新前的延迟（默认 `5000`）。
- `DASHBOARD_EVENT_POLL_INTERVAL_MS`：事件刷新轮询间隔（默认 `1000`）。
- `DASHBOARD_FALLBACK_REFRESH_MS`：兜底强制重算周期（默认 `600000`，即 10 分钟）。

## 验证脚本

- `npm run verify:t2-1`：合同版本化写入回归验证
- `npm run verify:t3-1`：银行流水追加模型与已收付回写验证
- `npm run verify:t3-3`：提货流水双表与已提货回写验证
- `npm run verify:t4-1`：采购销售映射追加模型与已匹配回写验证
- `npm run verify:t4-3`：发票流水追加模型与已开票回写验证
- `npm run verify:t4-5`：异步导出任务接口与前端导出入口验证
- `npm run verify:t5-1`：看板汇总事件刷新与定时兜底恢复验证
- `npm run verify:t5-3`：规则内核与 RULE_PENDING 阻断路径验证