Nexora ERP
合并执行方案

一句话说清楚要做什么

以 龙凤 ERP(xylferp_php)为骨架起点建立 nexora/nexora-erp 主干 · 通过 3 个阶段依次接入龙凤(未启用客户,验证用)、摆件(已停,验证加租户流程)、妈祖(主战场,深度并入并抽模块) · 每个租户独立一个 DB(物理隔离) · 老的 xipugold/* repo 在完成迁移前原样保留 · 迁移完成后归档 read-only。

3 条硬约束

从哪里出发

2.1 客户与主干仓库

2.2 关键实证数据

• 血缘:xylferp / baijian / xipu 三家 73 个共有 controller 里 55 个 md5 完全一致(73% 同源)· pyerp 独立演进,BaseController 已与其他家 md5 不同
• 龙凤代码覆盖度:18 个和囍铺 md5 不同的 controller 里,13 个龙凤更大(Buy +89 · Goodslog +186 · Goodsoutbound +319 · Category +113 · Index +211)· 龙凤有零售能力,囍铺没有
• 多租户已有:业务代码里 where('aid') 用了 1896~2285 次(pyerp 最多)· BaseController 里 define('aid', $aid) 从 token 回填 · 妈祖还有 bid(门店/业务)+ pt_type(产品线)三层
• 手机端:app_xiao_shou_kotlin(UniApp,669 commits)已经在做多客户 App 壳 · SERVER_LIST 已定义"周锦记(Kotlin 后端)"和"妈祖(PHP 后端)"两种类型 · 但 pyerp_app 和它 md5 完全不同,是两个独立项目
• Kotlin 后端:sprin-boot-kotlin219 有 52 个 controller,6 模块(api / member / order / print / shop / user),命名空间 rn.rw.erp

2.3 关键漏洞·数据契约差异(v9 补)

一张图看懂 Nexora

• 一份代码:所有租户跑同一份 PHP 主干 + Kotlin 变薄后端
• 租户目录集中管理:中心库 nexora_platform 存 tenants / modules / users(跨租户账号)
• 业务数据分散:每个租户独立业务库(nexora_<slug>)· 备份/升级/隔离独立
• Kotlin 明确职责:只保留 WS / 打印 / 推送,业务 CRUD 全归 PHP

34 个仓库 · 每个一个动作

执行时遇到"这个 repo 要不要动 / 怎么动"的问题,以本表为准。Action 列 = 强制约束。

• MERGE 合并到 nexora/nexora-erp,原 repo 完成后归档 read-only
• KEEP 原样保留 · 该 Phase 内不动 · 后续 Phase 才处置
• LATER Phase 3 末择机 · 视客户情况决定合并或退役
• ARCHIVE 归档 · 不做迁移不做合并 · GitLab 标 archived 即完成
• DROP 弃用 · 客户不再用 · 不投入任何工作
• OUT-OF-SCOPE 战略无关 · 无需处置

ERP 主干仓库

商城仓库

手机端仓库

弃用仓库(不投入工作)

其他(战略无关)

Nexora 主干由核心+可选模块组成

5.1 核心模块(所有租户必装)

5.2 可选模块(按租户启用)

5.3 模块生命周期规范

每个模块目录 modules/<name>/ 自包含:

• 路由声明 — 模块启用时才动态注册
• 控制器 — 只在模块内,不允许被主干直接引用
• 数据表 migrations — 独立,启用时执行,禁用时不执行(表保留可回滚)
• 菜单声明 — 启用时才注入前端菜单树
• 权限声明 — 自定义权限点
• 服务接口 Facade — 模块对外提供的唯一入口,主干只能通过 Facade 调用

Phase 1 · 龙凤先入

ssh://git@gitlab.nexora.restry.cn:18826/nexora/nexora-erp.git
# 从本地 clone xylferp,推到 nexora-erp
git clone ssh://git@gitlab.nexora.restry.cn:18826/xipugold/xylferp_php.git nexora-erp
cd nexora-erp
git remote set-url origin ssh://git@gitlab.nexora.restry.cn:18826/nexora/nexora-erp.git
git push -u origin main --tags

git clone ssh://git@gitlab.nexora.restry.cn:18826/xipugold/xylferp_web.git nexora-erp-web
cd nexora-erp-web
git remote set-url origin ssh://git@gitlab.nexora.restry.cn:18826/nexora/nexora-erp-web.git
git push -u origin main --tags

CREATE DATABASE nexora_platform DEFAULT CHARSET utf8mb4;
USE nexora_platform;

CREATE TABLE tenants (
  id INT PRIMARY KEY AUTO_INCREMENT,
  slug VARCHAR(32) UNIQUE NOT NULL,   -- xylferp / baijian / pyerp / xipu
  name VARCHAR(128) NOT NULL,          -- 龙凤 / 摆件 / 妈祖 / 囍铺
  db_dsn VARCHAR(255) NOT NULL,        -- mysql://user:pass@host:port/nexora_xylferp
  aid INT NOT NULL,                    -- 该租户在业务库的 aid 值(防呆参考)
  bid INT DEFAULT 0,
  pt_type TINYINT DEFAULT 1,
  status ENUM('active','paused','archived') DEFAULT 'active',
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE tenant_modules (
  tenant_id INT,
  module VARCHAR(64),   -- aliyun-image / ymetal / myhw-shop / gold-price / mall-sync / mobile-api
  enabled TINYINT DEFAULT 1,
  PRIMARY KEY (tenant_id, module)
);

CREATE TABLE users (
  id INT PRIMARY KEY AUTO_INCREMENT,
  username VARCHAR(64) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  name VARCHAR(128)
);

CREATE TABLE user_tenants (
  user_id INT,
  tenant_id INT,
  role VARCHAR(32),
  PRIMARY KEY (user_id, tenant_id)
);

CREATE TABLE schema_migrations (
  version VARCHAR(64) PRIMARY KEY,
  applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

# 备份龙凤当前 DB
mysqldump -u<user> -p xylferp | gzip > xylferp_$(date +%Y%m%d).sql.gz

# 恢复到 nexora_xylferp
gunzip -c xylferp_*.sql.gz | mysql -u<user> -p nexora_xylferp

# 中心库注册龙凤租户
INSERT INTO nexora_platform.tenants (slug, name, db_dsn, aid, bid, pt_type)
VALUES ('xylferp', '龙凤', 'mysql://...@.../nexora_xylferp', 1, 0, 1);

Phase 2 · 摆件 + 妈祖并入

bin/tenant-onboard.sh baijian --name "摆件" --aid 2

mysqldump -u<user> -p baijian > baijian.sql
mysql -u<user> -p nexora_baijian < baijian.sql
# 校验 aid 一致
UPDATE nexora_baijian.is_user SET aid=2 WHERE aid != 2;  -- 全部对齐到租户 id

bin/tenant-onboard.sh pyerp --name "妈祖" --aid 1 \
  --modules ymetal,myhw-shop

# 生产 pyerp DB → nexora_pyerp(选低峰,冻结原库)
mysqldump -u<user> -p pyerp | gzip > pyerp_$(date +%Y%m%d).sql.gz
gunzip -c pyerp_*.sql.gz | mysql -u<user> -p nexora_pyerp

Phase 3 · 手机端 + 商城 + Kotlin变薄 + 囍铺择机

cd sprin-boot-kotlin219
grep -rl "@RestController" --include="*.kt" | while read f; do
  echo "== $f =="
  grep -E "@GetMapping|@PostMapping" "$f" | head -20
done > kotlin-audit.md

一租户一库的必备基础设施

一租户一库的代价 = 运维成本随客户数线性增长。必须把每个环节脚本化。Phase 1 就要落地最小可用版,后续 Phase 持续增强。

9.1 tenant-onboard(新租户开通)

位置:nexora-erp/bin/tenant-onboard.sh

tenant-onboard.sh <slug> \
  --name "<中文名>" \
  --aid <租户 id> \
  [--modules module1,module2,...]

# 一次做 4 件事:
# 1. 建 nexora_<slug> DB
# 2. 跑核心模块 migrations
# 3. 按 --modules 跑可选模块 migrations
# 4. 中心库 tenants + tenant_modules 注册

验证:执行完 30 秒内新租户能登录,前台菜单只显示启用的模块。

9.2 migrate-all(migrations 分发)

位置:nexora-erp/bin/migrate-all.sh

migrate-all.sh [--dry-run]

# 遍历中心库 tenants,对每个租户 DB:
# 1. 检查 schema_migrations 表
# 2. 执行未跑过的 migration
# 3. 失败即停,输出报错(不允许"跑了一半就走人")
# 4. 只跑该租户启用模块的 migrations

验证:主干加 1 张新表,跑 migrate-all,所有租户 DB 都出现该表。

9.3 backup-tenants(备份轮询)

位置:nexora-erp/bin/backup-tenants.sh(cron 每晚 03:00)

backup-tenants.sh

# 遍历中心库 tenants,每个租户:
# 1. mysqldump | gzip → /backup/tenant/<slug>/<date>.sql.gz
# 2. 保留策略:daily 7 天 · weekly 4 周 · monthly 6 月
# 3. 校验:大小比昨天缩水 >20% 报警
# 4. 校验:gunzip -t 能完整解压

验证:任一租户 ls /backup/tenant/<slug>/ 有当日备份文件。

9.4 monitor(部署监控)

位置:nexora-erp/bin/monitor.sh(cron 每 5 分钟)

monitor.sh

# 按租户视角检查:
# - 各租户 DB 可连接
# - 各租户前台 /api/health 返回 200
# - 备份状态(最近 24h 内有成功备份)
# - 慢查询(> 1s)计数
# - 磁盘用量 > 80% 报警
# 异常发飞书告警

验证:手动停一个租户 DB,5 分钟内收到告警。

负范围 · 防止scope creep

执行时任何"顺便把 X 也做了"的问题,以本节为准。不在 §04 总表 + §06-08 路线图里的东西,默认不做。

妈祖「以龙凤为准」合并方案

v10 决策:妈祖 pyerp 客户端账号迁到龙凤主干(schema 冲突时以龙凤为准)· 商城代码不动 · ERP 换 Nexora 前端。 拆分方案由 v11 §13 迭代 · 已由 §14 落地 (6 家独立租户)。

Platform Admin · 从任一租户 admin 升级

v10 决策:平台超管入口复用龙凤 admin(platform_admin 标记)· 不建独立后台。 已由 §14/§15 落地 · PlatformAdmin 8 action controller · /platform-admin.html UI 完备。

Multi-tenant unfold · v9 错 · v11 补

v9 假设 pyerp 单租户 · 建单库合并 → v10 review 发现 is_goods.aid 有 10 个租户 → v11 §13 决策拆 6 家独立租户。 拆分方案已由 §14 落地(Phase 2C 执行完成)· 详见 §14 现状快照。

Live State · Phase 2C 之后 · 10 家租户

14.1 中心库租户清单(nexora_platform.tenants)

14.2 权限 & 模块矩阵 · 谁能看什么

侧栏基础菜单(所有 active 租户共 8 项): 首页 / 账户管理 / 成品管理 / 销售管理 / 会员管理 / 资产管理 / 报表管理 / 系统配置。
以下是每家的 特殊菜单差异(启用模块后由 ModuleRegistry 注入):

侧栏效果: 龙凤 9 项(基础 8 + 平台管理) · 摆件 8 项(纯基础) · 囍铺 11 项(基础 8 + 图像搜索/OSS/金价 3) · pymetal 9 项(基础 8 + 贵金属) · fjfl/qywh/ftgf/qyxs/heian 8 项(纯基础)

14.3 数据量分布

14.4 账号密码清单(dev 环境)

登录入口 https://nexora-erp.nexora.restry.cn/?tenant=<slug> · 全部 admin/123456

14.5 端到端验证(2026-07-07)

• ✅ 9 家 login success · headless chrome + vision 判读通过
• ✅ 9 家品牌名(sys.name)正确渲染
• ✅ 龙凤独家显示"平台管理"入口(9 菜单)
• ✅ pymetal 独家显示"贵金属"菜单(独启 ymetal 模块)
• ✅ 囍铺独家显示"图像搜索/OSS/金价" 三菜单
• ✅ 6 家新租户基础菜单齐全(85 行 xipunum_menu clone 龙凤)
• ✅ 摆件 admin 硬调 /PlatformAdmin/tenantList → HTTP 403 · PLATFORM_ADMIN_REQUIRED
• ✅ pyerp(archived)admin 登录 → TENANT_NOT_RESOLVED
• ✅ 平台管理 5 tab(租户/新建/模块/超管/监控)全部渲染

14.6 剩余待办

1. P0: 从老 pyerp_php 生产按 aid 独立 dump 数据 → 迁入 6 家新库(v11 §13.4 Step 2)· 需要客户切换窗口
2. P0: fjfl(472 商品)/ qywh(351 商品)/ pymetal(18 贵金属流水)/ ftgf/qyxs/heian 业务数据未迁
3. P1: Phase 1 判据 1&2(5 单据走通 + Nexora vs xylferp 数据一致)· dev 无业务数据 · 待客户切换
4. P2: migrate-all / backup-tenants 脚本从未真跑一次
5. P3: Phase 3(Kotlin 变薄 / 手机端归口 / 老 repo 归档)未启动
6. P4: 生产切流量后 · 老 xylferp/baijian/xipu/pyerp -php 容器可下线

Subdomain Routing + 平台超管改租户信息

15.1 URL 格式

9 家全部使用子域名 · 每家独立 host · localStorage 天然按域名隔离(多 tab 不串号)。老 URL 保留兼容。

15.2 后台改租户信息

平台超管在「租户列表」每行「编辑」按钮打开 modal · 可改以下 6 字段。

不可改:slug / db_dsn / table_prefix / aid(锚点字段 · 改了要迁库)。
硬约束:xylferp 不能归档(平台超管账号所在租户)。

15.3 涉及组件

Lessons · 做 Nexora 学到的可复用经验

16.1 架构层

16.2 工程层

16.3 可复用到别的项目

• 多客户 ERP/CRM 合并 → 先跑 SELECT COUNT(DISTINCT tenant_key) FROM main_tables 判断是不是 SaaS
• SaaS 平台 URL → <slug>.app.example.com + 通配 cert + on_demand_tls + ask endpoint
• 平台超管入口 → 复用主品牌租户 admin + platform_admin 标记 · 不建独立后台(避免账号双系统)
• 模块差异化 → 中心库 tenant_modules(tenant_id, module, enabled) · ModuleRegistry 注入菜单/路由/守卫
• 反代通配 → frpc custom_domains 提前加 *.<subzone>.example.com · 不然每加一家改一次

Next · P0/P1/P2 待办

17.1 P0 · 必须做

17.2 P1 · 应该做

17.3 P2 · 可以做

• 老 xylferp_web / baijian_php / xipu_erp_php / pyerp_php 容器下线(客户切流量后)
• Phase 3 · 34 个仓库归档整理 · Kotlin 老 repo 归档
• 租户级配置(税率 / 币种 / 时区)· 目前全部硬编码人民币
• 子域名自定义(客户想用 erp.客户品牌.com 而不是 xxx.erp.nexora.restry.cn)