# 头程 GitLab 建仓清单

## 1. 建仓结论

头程项目创建一个 GitLab 仓库，不按服务拆成多个 Git 仓库。

原因：当前是一个 Maven Reactor 多模块工程，公共组件、平台 BOM、事件契约和 11 个可运行服务共享根父工程并统一构建。此时按服务拆仓会破坏父 POM、公共版本管理和现有流水线。服务仍然可以独立打包、独立镜像和独立部署，Git 仓库数量不等于微服务数量。

GitLab 创建参数：

| 字段 | 填写内容 |
| --- | --- |
| 项目名称 | 百悦头程平台 |
| 项目标识 | `baiyue-firstleg` |
| 项目描述 | 百悦物流国内头程微服务平台，包含统一登录、租户权限、订单、头程履约、国内仓储、文件、打印、审计、外部集成与跨区域事件桥。 |
| 可见性 | 私有 |
| 默认分支 | `main` |
| 使用 README 初始化 | 否，本地项目已有 README |
| Git 忽略模板 | 不选择，本地已有 `.gitignore` |
| 许可证 | 不选择，内部商业项目 |

本地目录：`D:\baiyue-firstleg`。

## 2. 每个可运行服务的描述

以下 11 个模块都是独立运行服务，但属于同一个 GitLab 仓库。

| 模块 | 建议制品或镜像名 | 默认端口 | 中文描述 |
| --- | --- | ---: | --- |
| `gateway` | `firstleg-gateway` | 9000 | 头程统一 API 入口，负责路由、跨域、统一鉴权入口、限流与 Swagger 聚合。 |
| `auth` | `auth-service` | 9100 | 统一认证服务，负责注册、登录、Access Token、Refresh Token、退出、修改密码和会话撤销。 |
| `iam` | `iam-service` | 9201 | 租户与权限服务，负责企业、成员、角色、菜单、按钮权限、数据隔离和企业资质审核。 |
| `firstleg` | `firstleg-service` | 9202 | 头程履约服务，负责揽收、入仓、装载、发运和国内到海外的交接事实。 |
| `order` | `order-service` | 9204 | 订单服务，负责头程订单草稿、提交、状态编排、主数据快照、快递履约信息和订单事件。 |
| `warehouse` | `warehouse-service` | 9205 | 国内仓储服务，负责仓库、地址、收货能力和往来单位配置；往来单位表位于 `baiyue_warehouse.wh_partner`。 |
| `file` | `file-service` | 9206 | 文件中心，负责企业资质和业务文件的上传、下载、元数据、授权与后续对象存储适配。 |
| `print` | `print-service` | 9207 | 打印中心，负责打印模板、打印任务、状态记录及生成文件关联。 |
| `audit-service` | `audit-service` | 按配置 | 审计服务，负责关键操作、租户、操作者、业务对象和追踪号的审计留痕。 |
| `integration-service` | `integration-service` | 按配置 | 外部集成服务，负责承运商、渠道和第三方接口的适配、映射、回调与幂等。 |
| `event-bridge-service` | `event-bridge-service` | 按配置 | 跨区域事件桥，负责版本化事件、Inbox 幂等、投递记录、重试和后续国内外通信。 |

## 3. 不单独创建 GitLab 仓库的公共模块

| 模块 | 说明 |
| --- | --- |
| `platform-bom` | 统一公共制品版本清单。 |
| `common-core` | 统一返回、错误码和核心基础模型。 |
| `common-web` | 全局异常、请求追踪和 Web 公共能力。 |
| `common-security` | JWT、安全上下文、租户和审计操作者能力。 |
| `common-openapi` | Swagger/OpenAPI 公共配置。 |
| `common-audit` | 审计事件公共模型与切面。 |
| `common-event-contract` | 国内与海外共享的版本化事件契约。 |

这些模块随头程仓发布到 Maven 私有仓库，尾程只能按固定版本引用，不能复制源码或再次发布同一坐标。

## 4. GitLab 仓库设置建议

1. 保护 `main` 分支，禁止直接推送和强制推送。
2. 合并必须通过流水线，并至少由一名维护者审核。
3. 开启提交记录、合并请求和发布标签保护。
4. CI/CD 变量中保存测试或部署环境密码，不提交 `.env`、本地配置或密钥。
5. 制品保留 7 天；正式发布通过版本标签长期保留。
6. 服务使用独立镜像标签和部署版本，但共同关联同一个 Git 提交号。

## 5. 第一次推送命令

先在 GitLab 创建空项目，不要勾选 README 初始化。将下面地址中的组织名替换为实际 GitLab 组：

```powershell
Set-Location D:\baiyue-firstleg
git status
git add .
git commit -m "初始化百悦头程微服务平台"
git branch -M main
git remote add origin https://gitlab.example.com/你的组织/baiyue-firstleg.git
git push -u origin main
```

如果本地已经存在 `origin`：

```powershell
git remote set-url origin https://gitlab.example.com/你的组织/baiyue-firstleg.git
git push -u origin main
```

推送前必须确认 `git status` 中没有 `target`、`.idea`、日志、上传文件、数据库导出或包含密码的本地配置。

## 6. 后续确需按服务拆仓时的前置条件

只有满足以下条件后，才建议把 11 个服务拆成独立 Git 仓库：

1. `platform-bom` 和全部 `common-*` 已发布到可用的 Maven 私有仓库。
2. 每个服务拥有独立父 POM 或只依赖已发布父 POM。
3. 服务间 DTO 已替换为版本化 API 或事件契约，不存在源码级依赖。
4. 每个服务都有独立流水线、镜像、配置、数据库迁移和负责人。
5. 已完成跨仓版本兼容和回滚演练。

当前不满足全部前置条件，因此本次只创建 `baiyue-firstleg` 一个 GitLab 仓库。