# g3soft-erp

G3Soft ERP 前后端同仓。业务域：海运 / 空运 / 箱管 / 财务 / CRM。

> **当前状态：前端骨架已搭好并可运行；后端尚未开始。**
> 元数据驱动引擎（通用查询 / 保存 / 权限）**未开始设计**，属后续独立立项。

## 目录结构

```
g3soft-erp/
├── pnpm-workspace.yaml      # 仓库唯一配置文件：overrides + allowBuilds
├── web/                     # 前端应用（前端唯一的 package.json 在这里）
│   ├── package.json
│   ├── vite.config.ts
│   ├── vitest.config.ts
│   ├── tsconfig.json
│   ├── .oxlintrc.json
│   ├── .oxfmtrc.json
│   └── src/
├── server/                  # 后端占位（Maven + Spring Boot，未开始）
├── docs/                    # 设计文档
└── README.md
```

**根目录刻意不放 `package.json`** —— 前端可交付物只有 `web/` 一个包，那个 `package.json` 就是 `web/package.json`。根目录只有 `pnpm-workspace.yaml` 一个配置文件。

## 环境要求

- Node.js >= 20.19
- pnpm 11
- **`g3soft-libs` 需与 `g3soft-erp` 平级**（同在 `D:\workspace\code\` 下），因为 `overrides` 用相对路径 link 组件库

## 快速开始

```bash
# 1) 先构建组件库（@g3soft/ui 的 exports 指向 dist，必须先有产物）
cd ../g3soft-libs && pnpm --filter @g3soft/tokens build && pnpm --filter @g3soft/ui build

# 2) 回到本项目
cd ../g3soft-erp/web
pnpm install
pnpm dev          # http://localhost:5090
```

> **命令都在 `web/` 下跑**，根目录没有 `package.json`，所以根目录敲不了 `pnpm dev`。

## 脚本（在 `web/` 下执行）

| 命令 | 说明 |
|---|---|
| `pnpm dev` | 开发服务器（端口 5090，`/api` 代理到 8088） |
| `pnpm build` | 类型检查 + 生产构建 |
| `pnpm typecheck` | 仅 `vue-tsc --noEmit` |
| `pnpm test` | Vitest |
| `pnpm lint` / `pnpm fmt` | oxlint / oxfmt |
| `pnpm check` | lint + fmt:check + build（提交前跑这个） |

## `@g3soft/ui` 接入方式

组件库的 `exports` 指向 `dist/`，所以**改完组件库必须重新 build**。

开发期通过 `pnpm-workspace.yaml` 的 `overrides` 指向本地包：

```yaml
overrides:
  '@g3soft/tokens': link:../g3soft-libs/packages/tokens
  '@g3soft/ui': link:../g3soft-libs/packages/ui
```

**三个注意点**：

1. **`overrides` 只在 workspace 根生效**，写在 `web/package.json` 里无效。
2. **`vite.config.ts` 必须保留 `dedupe: ['vue', ...]`**。link 进来的包会带自己的 Vue 副本，不去重会导致组件内响应式失效（组件内部 ref 变化不触发外部渲染）——link 方案最经典的坑。
3. **CI / 其他机器**：相对路径依赖目录层级。私库就绪后应把开发期 `link:` 换成私库版本号。

### 想要组件库热更新？

`link:` 指向**已构建的 `dist/`**，改源码不会即时生效。若要像 `g3soft-libs/docs` 那样直连源码，在 `vite.config.ts` 里加 alias：

```ts
resolve: {
  alias: {
    '@g3soft/ui': fileURLToPath(new URL('../../g3soft-libs/packages/ui/src/index.ts', import.meta.url)),
  },
}
```

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `VITE_PROXY_TARGET` | `http://127.0.0.1:8088` | 开发环境 `/api` 代理目标 |
| `VITE_API_BASE` | `/api` | 接口基础路径 |
| `VITE_APP_TITLE` | `G3Soft ERP` | 应用标题 |

## 将来加 H5 端

**`@g3soft/ui` 只给 web 用，H5 不用。** 所以两端是基本独立的应用，只是碰巧同仓，**不需要抽任何共享层**。

加 H5 时的步骤：

1. 建 `h5/` 目录（与 `web/` 平级），它有自己的 `package.json`
2. `pnpm-workspace.yaml` 的 `packages` 改为 `['web', 'h5']`
3. 若 H5 也要用某个 g3soft 包，在 `overrides` 里加一条；不用就不用加
4. 各端独立构建、独立部署

## 仓库纪律（重要）

前后端同仓，但**必须各自独立**：

1. **独立构建** —— 前端 `pnpm build` 不管后端，后端 `mvn package` 不管前端，**任何一方都不触发另一方构建**（不要引入 `frontend-maven-plugin` 这类东西）。
2. **独立版本** —— tag 分开打（`web-v1.2.0` / `api-v1.2.0`）。
3. **唯一契约是 HTTP 接口** —— 前端不读后端源码，后端不管前端怎么调；契约写进 `docs/`。

破坏这三条，同仓的好处立刻变成耦合的代价。

## 相关仓库

- **`g3soft-libs`** —— `@g3soft/ui`（组件库）、`@g3soft/tokens`（设计变量）。web 端 UI 一律用组件库，不另起一套。