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 路线图里的东西,默认不做。

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

11.1 战略决策记录

11.2 保留 vs 弃用清单

基于 pyerp_app(274 vue)+ pyerp_shop_wx/h5/php(5600 文件)+ pyerp_php/eperp SPA + pyerp_php/app 后端 四层真实引用扫描

✅ 保留 46 个 controller · 归入 4 模块

❌ 弃用 12 个孤儿 controller

弃用理由:上述 12 个 controller 在妈祖 SPA / App / 商城 / 后端均零引用,是历史遗留死代码。

同名 52 controller 处理方针

• 默认:用龙凤版本覆盖(即 nexora-erp 主干已有版本)
• 例外:妈祖独家「贵金属专属字段」改造迁到 ymetal 模块
• 执行:Step 1 用脚本 diff 52 文件,产出「妈祖独有改造清单」→ 人工判断哪些迁到 ymetal

11.3 用户体系迁移策略

• 保留老 is_user 表(archive · 不 DROP)· 保留业务单据外键完整性
• 建 mapping 表 pyerp_user_id_migration(old_is_user_id, new_xipunum_erp_user_id)
• 老单据"创建人"字段查询时先查新表,fallback archive 表显示"(离职) 张三"
• 密码统一到龙凤盐 bwqinr · 单重 md5
• 27 妈祖员工重建 xipunum_erp_user schema 新账号 · 用户方 mike 已确认可接受

11.4 妈祖生态"暂不动"清单

理由:降低单次改造风险 · 商城/App 通过 mall-sync 桥接 · 不影响妈祖客户

11.5 三阶段执行清单

11.6 成功判据(必过)

1. 妈祖客户 admin 在 https://nexora-erp.nexora.restry.cn/?tenant=pyerp 用新密码登进 dashboard
2. 侧边栏出现:龙凤 7 大顶级菜单(账户/成品/销售/会员/资产/报表/首页)+ 「贵金属」模块 + 「电商对接」模块
3. 老业务表(is_ymerp_* / is_ep_*)数据完整可查 · 老单据"创建人"字段能显示员工名或 "(离职) 张三" fallback
4. 妈祖手机 App(pyerp_app)登录后能拿 AppReport/AppStat 数据(通过 myhw-shop 模块新暴露的接口)
5. 妈祖商城(pyerp_shop_wx)客户下单能通过 mall-sync 推到 Nexora ERP 生成销售单

Platform Admin · 从任一租户 admin 升级

12.1 战略决策

• 一个入口:平台超管复用 ERP 登录页 · 不做独立 URL
• 升级模式:某租户 admin 被授予 platform_admin 角色 → 侧栏多出"平台管理"顶级菜单
• 默认授权:龙凤 admin(总部自留)自动是 platform_admin
• 横向越权防护:普通租户 admin 看不到平台管理入口 · 也调不到相应 API

12.2 权限模型

nexora_platform.user_tenants (中心库)
├── user_id → nexora_platform.users.id
│              (跨租户的全局账号池 · 目前只放平台超管)
├── tenant_id → nexora_platform.tenants.id
│              (超管所属"总部租户" · 默认龙凤)
└── role: 'platform_admin' | 'admin' | 'user'

判定逻辑:

1. 租户 admin 登录后,Nexora 后端反查中心库 user_tenants 是否有该用户的 platform_admin 记录
2. 有 → 侧栏注入"平台管理"菜单节点 · API 路由允许访问 PlatformAdmin controller
3. 无 → 一切照旧(和当前 4 家 admin 一模一样)

12.3 平台管理菜单结构

12.4 新做的东西

后端(nexora-erp 主干)

• app/controller/PlatformAdmin.php · 5 个 action(tenantList / tenantCreate / moduleToggle / adminList / adminGrant)
• app/common.php · getBaseRoot() 里检查 platform_admin · 注入平台管理菜单
• app/nexora/PlatformAuth.php · 新工具类 · isPlatformAdmin(userId, tenantSlug)
• route/app.php · 平台管理路由前缀 /platform-admin/*

前端(nexora-erp-web SPA)

• src/views/platform/TenantList.vue · 租户列表页
• src/views/platform/TenantCreate.vue · 新建租户表单
• src/views/platform/ModuleMatrix.vue · 模块启停矩阵
• src/views/platform/AdminGrant.vue · 平台超管授权页
• src/router/index.js · 加 /platform/* 路由

中心库数据

• nexora_platform.users 新增一行:username=platform-admin-xylferp · 关联龙凤 admin
• nexora_platform.user_tenants 新增一行:role=platform_admin
• nexora_platform.platform_admin_log 新表 · 审计日志

12.5 安全边界(硬约束)

1. 前端隐藏 ≠ 权限控制 · 后端每个 PlatformAdmin action 都必须调 PlatformAuth::assert() · 通不过 return 403
2. 不允许普通租户 admin 通过 API 硬调 · 就算他知道 URL 也 403
3. 审计日志 · 所有 PlatformAdmin 操作写 platform_admin_log 表(who + when + what + before/after)
4. 不允许 platform_admin 停用自己 · 防误操作锁死
5. 不允许停用"最后一个" platform_admin · 至少保留一位

12.6 三阶段执行清单

总计约 9h · 一天工作量。

12.7 成功判据(必过)

1. ✅ 龙凤 admin 登进去 · 侧栏第 9 项显示"平台管理" · 展开有 5 项子菜单
2. ✅ 摆件/囍铺/妈祖 admin 登进去 · 不显示"平台管理"入口
3. ✅ 平台管理 → 租户列表 · 显示 4 家现状
4. ✅ 平台管理 → 新建租户 · 提交后真的建库 + 中心库注册 · SPA 立即能切过去登
5. ✅ 平台管理 → 模块启停 · 切换 ymetal 后 · 妈祖 admin 重登侧栏"贵金属"消失
6. ✅ 摆件 admin 直接 curl PlatformAdmin API · 返 403
7. ✅ 所有平台超管操作在 platform_admin_log 有记录

12.8 教训条

Multi-tenant unfold · v9 错 · v11 补

13.1 pyerp 老 DB 真实客户清单

扫 nexora_pyerp.is_user(v9 dump 自老 pyerp_php 生产)· 按 aid 聚合 · 关联 is_goods / is_ymerp_* 业务表 · 得真实图景:

13.2 拆分方案 · 只做活跃的 6 家

按 Mike 决策 "方便已经确认了 · 只要有活跃的租户":

空壳不建: aid=1/18/34/41 · 数据全 0 · 无用户实际登录 · 直接丢弃(老库继续保留归档)。

13.3 v9 nexora_pyerp 的处置

v9 建的 nexora_pyerp 一个库跑 10 aid 混合 · 不能直接用。选定选项 C(archive + 6 家全新建):

• nexora_pyerp 库保留 · rename 为 nexora_pyerp_archive_20260707 · 供追溯
• 中心库 tenants slug=pyerp 记录标 archive · db_dsn 指向 archive 库
• 6 家新租户从老 pyerp_php 生产 按 aid 独立 dump · 建 6 个 nexora_<slug> 库
• 老 pyerp-php 容器继续运行 · 客户切换窗口另定

13.4 三阶段执行清单

Step 1 · 前置(1h)

• 确认老 pyerp_php 生产在跑 · 从生产 mysqldump 老 is_* 表
• Nexora 主干模块启用矩阵: pymetal 启 ymetal · 其他 5 家不启
• nexora_pyerp → nexora_pyerp_archive_20260707 rename

Step 2 · 逐家独立 dump 迁移(3-6h)

按 P0/P1/P2 顺序 · 每家 6 步:

1. mysqldump nexora_pyerp is_* --where "aid=<N>" → nexora_<slug>.sql
2. 建 nexora_<slug> 库 · restore · 转 is_* → xipunum_erp_* · aid 全部改为新租户 tid
3. 中心库 nexora_platform.tenants 注册 · db_dsn/aid/status=active
4. 密码盐重算(is_user pwd 双 md5 erpsm → xipunum_erp_user password 单 md5 bwqinr)
5. 登录测试: <slug> admin/xxx 能登 · dashboard 商品数与老 aid 数据一致
6. pymetal 侧栏应有"贵金属"菜单 · 其他 5 家不应有

Step 3 · 出口验收(1h)

• 6 家 admin 全部能登 · dashboard 商品数与老 aid 一致(fjfl=472 · qywh=351 · pymetal=18 贵金属记录 · ftgf=11 · qyxs=5 · heian=3)
• pymetal 侧栏有"贵金属"菜单 · 其他 5 家无
• 老 pyerp-php 容器 read-only 归档运行 · 客户切换窗口另定
• v11 平台管理 → 租户列表显示 10 家(4 原 + 6 新;pyerp 保留 archive 标记)

13.5 成功判据

1. ✅ 6 家 aid 独立成 6 个 tenant slug · 各自独立 DB
2. ✅ 4 个空壳 aid 不建 · 数据丢弃(生产老库还在归档)
3. ✅ 只 pymetal 启 ymetal 模块 · 其他 5 家侧栏无贵金属
4. ✅ 6 家 admin 密码全部 123456(dev)· 或按老密码继承(生产 · 待客户切换时定)
5. ✅ 各家 dashboard 商品数与老 aid 数据一致
6. ✅ nexora_platform.tenants 有 10 家(4 原 + 6 新)· pyerp 标 archive
7. ✅ 老 pyerp_php 容器保持运行(read-only 归档)· 客户未真切流量

13.6 v11 的 Phase 序列

• Phase 1 ✅ 龙凤单租户
• Phase 2A ✅ 摆件加入
• Phase 2B v2 ⚠️ 妈祖并入 · v9 做的是错的 · 需 v11 §13 补正
• Phase 2C(v11 新增) · pyerp SaaS 拆 6 租户 (2C 已执行)
• Phase 3 · 手机端 / Kotlin / 商城 · 未启动
• Phase 3D · 囍铺(已提前 done)

13.7 明确不做

• 空壳 aid(1/18/34/41)不建租户 · 不做迁移
• 老 pyerp_php 代码不重构 · 客户切换前保持原样
• 湄洲妈祖 aid=41 不建独立租户 · 客户方无实际业务(即使名字听起来是主客户)
• 客户切换动作 · Phase 2C 完成 dev 后由 vol 决定切换窗口

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 涉及组件