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 不同 ⚠️ 此处「pyerp 独立演进」结论已被 2026-07-10 血缘再核实修正 —— 妈祖与龙凤实为同源 fork(54 同名 controller + Sell 10/12 同名函数),见下方蓝框
• 龙凤代码覆盖度: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 · 2026-07-07 修正版

14.1 Nexora 已承载租户(珠宝线)

14.2 未承载租户(原料线 · 生产在 myhw_py99999_com)

这 6 家客户按 aid 共存于 myhw_py99999_com 单库(2026-06-14 唐润辉合并方案上线)· schema 是 is_*(原料 ERP)· 与珠宝线 xipunum_erp_* 完全不同。需要 §18 阶段 B 让 Nexora 平台接管这条线。

14.3 已实现的平台能力

• ✅ Caddy 通配 *.erp.nexora.restry.cn · on_demand_tls · 新租户 0 配置
• ✅ frpc 通配 *.erp.nexora.restry.cn · SNI 白名单已加
• ✅ 中心库 nexora_platform(tenants / tenant_modules / platform_admin_log / users 等 6 表)
• ✅ Tenant::resolve · 从 host / header / query 动态切库
• ✅ ModuleRegistry · 模块化菜单/路由/守卫
• ✅ 平台超管 UI · https://xylferp.erp.nexora.restry.cn/platform-admin.html · 8 action controller
• ✅ tenantUpdate 接口 · 编辑 name / sys.name / company / icp / notice / status
• ⚠️ Tenant.php 目前只支持 xipunum_ 单前缀 · 中心库 table_prefix 字段未接入代码

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 · 一份代码架构落地

17.1 Y1-Y5 已完成

6 家原料客户 dashboard · 一份代码 · 6 家独立 nexora_<slug> · pymetal 独有"贵金属"菜单

17.2 遇到的坑

17.3 Y6-Y7(仍未做 · 需客户切流量窗口)

• Y6 · 6 家客户业务数据人工迁到新库(pyerp is_user.pwd → nexora xipunum_erp_user.password 加盐 + is_user.role → department 值近似)
• Y7 · 灰度切流量:darkgroup(3 商品) → qyxs(5) → ftgf(11) → qywh(351) → fjfl(472) → pymetal(贵金属)· 各家客户配合
• Y7 完 + 1 周稳定 → pyerp-php 容器下线 · repo 归档

17.4 珠宝线状态

• 3 家珠宝(xylferp / baijian / xipu)· schema 与生产 100% 一致 · login 冒烟无回归
• 囍铺业务数据(56 表滞后)· vol 说不用做

One Codebase · 通用同 schema · 业务分模块

18.1 通用层(所有租户 · 一份 schema)

18.2 业务模块层(按 tenant_modules 启用)

18.3 运行时决策

Milestones · M1 → M6 交付节奏

规则:每个"建完"里程碑必有对应"测完"里程碑(外部独立子代理无本次会话记忆验证)· 避免自己干活自己测。

Page Audit · 逐页可用性审计与修复

方法:登录每家 ERP · 逐个打开左侧菜单每个功能页 · headless chrome + vision 判读是否 404 / 空白 / 报错。 教训:审计脚本一度手动映射路由,掩盖了"从菜单点会 404"的真问题 —— 后续改为用菜单里的 resource 直接跳转(模拟真实点击),9 家全部重审。

✅ 9 家全部审计完成 · 318 个功能页全绿

本轮修复的 8 类 bug

Mobile Merge · 手机端合并实施方案

目标:把手机端收敛为唯一 App 单体 app_xiao_shou_kotlin + 唯一后端 nexora-erp PHP(多租户),与 ERP 后端"一份代码 + 通用 schema + X-Tenant-Slug 租户头分流"对齐。基准 commit 9b5f67d(Phase 3B.1)。

22.1 现状定性 · 合并已完成大半

深度侦察(/tmp/mobile-recon/REPORT.md)结论:主力 app_xiao_shou_kotlin 已是多 ERP 分流单体,靠登录用户 pt_type 运行时分流到不同业务模块 + 不同后端。

22.2 收敛终态

22.3 四阶段方案

22.4 各阶段交付物与验收标准

P0 · 清理归档

• P0.1 kotlinapi xylf/* 逐页 diff 主力 xerp · 交付逐页对照表 · 验收:每页标"已覆盖/需补"
• P0.2 pyerp_app jerp/serp md5 复核 · 验收:SAME=共有页数,DIFF=0(报告 55/55)
• P0.3 GitLab 归档两 repo · 先备份 pyerp_app merp 素材(P3 用) · 验收:archived=true

P1 · 打通租户头(最高优先级)

• P1.1 http.js 拦截器:backend==='nexora' 时注入 X-Tenant-Slug + 缺 slug 断言拒发 · 验收:grep 有实际代码非注释,pt_type=1 不受影响
• P1.2 龙凤 Nexora entry 端到端登录 · 验收:带 X-Tenant-Slug: xylferp 登录 success + 数据确属 nexora_xylferp 库 + 错 slug 后端拒绝
• P1.3 串库防护回归 · 验收:选中 host 不可达时登录失败(不 fallback)

P2 · 珠宝线后端收编(最高工作量/风险)

• P2.0 Kotlin 7782 endpoint 盘点 · 交付 endpoint×PHP 对等三态表(已有/需补/特殊)
• P2.1 普通接口 PHP 补齐 · 验收:curl 打 PHP 版结构与 Kotlin 一致,前端不改仅切 host
• P2.2 特殊能力专项:WebSocket /rwy / gridReport 报表 / netweight 网络秤 · 验收:各有落地方案 + POC 实测
• P2.3 SERVER_LIST 切 nexora + fastify 7780 退役评估 · 验收:囍铺/龙凤走 nexora 功能无缺失

P3 · 妈祖 merp 并入 + 请求栈统一

• P3.1 搬 merp 页面 + 解开 envPathUtil.js PagePath[2] 占位 · 验收:pages.json 注册 merp,pt_type=2 能进妈祖首页
• P3.2 妈祖独立请求栈(pub_utils/http)改走主链路 + backend=nexora tenant=pyerp · 验收:妈祖请求不再走第二套栈
• P3.3 妈祖端到端回归 + pyerp_app 最终归档 · 验收:独立子代理逐页审计妈祖 merp(仿 ERP 318 页法)

22.5 贯穿红线与执行顺序

建议执行顺序:P0 → P1 → P3 → P2(不是 P0→1→2→3)。理由:P2 后端收编工作量/风险最大(WebSocket / gridReport 报表 / netweight 网络秤 PHP 无对等实现),放最后持续演进;先做 P3 让"App 一份代码"先落地。