Nexora · Mobile Migration Tracker

手机端接口迁移
五批次滚动追踪

囍铺原 Kotlin/Spring Boot 手机后端向 Nexora PHP 单后端的完整迁移。以真实前端调用的 137 个接口为契约事实源，Kotlin Controller / Service / Mapper 为参考实现。在 claw-bot (192.168.1.235) 上派 CC（claude-opus-4.7 · eagle 网关）按批次严格复刻，每批完成即真实浏览器 E2E 验收，再更新本页与派下一批。

Active Endpoints
137
前端 createUrl 归一后 · Kotlin 侧 133 个可对应
已实现
137
路由 + 方法 + selftest 全绿
路由空壳
0
route 有 · 实现无 · 会 500
完全缺失
0
route 和实现均无
覆盖率
100%
137 / 137 · 每批完成后即刷新
§ 01 · Verified · 2026-07-10
已验收链路

囍铺租户已跑通登录 → 首页 → 报表 → 菜单入口完整链路。业务数据取自 2026-07-09 结账（当天为最新完整营业日）。

Tenant · Xipu
109 位真实用户
囍铺生产镜像 xipuerp 完整导入到 nexora_xipu · 中心库 xipu_ 前缀双写
Operations · 2026-07-09
¥434.44 万营业额
187 单真实销售订单 · 利润 117.30 万 · 1499.73g 工费重量
Home Icons · Restored
10 个常用功能入口
货品销售 / 回收 / 预售 / 盘点 / 入库 / 调拨 / 款号查询 / 图片上传 / 收银汇总 / 全部应用
§ 02 · Batch Plan
五批次迁移编排

按业务链聚合，每批一个独立 worktree + 一份 spec + 一次 CC 会话。禁止跨批干扰。分片 commit + selftest + contract gate 三门验收后再合入 main。

批次
模块
范围
接口
状态
B1
销售链
Outbound（销售出库） · Retreat（回收） · Presale（预售） · RetreatTitle · print 占位
Outbound × 11 · Retreat × 6 · Presale × 4 · print × 2
23接口
Done
B2
库存与扫码
Inbound（入库） · Transfer（调拨） · Stocktaking（盘点） · Shop · Config · ksiamges / iamges / category / about / MenuApp
库房库存查询 · 盘点临时单 · 调拨明细 · 款号 / 图片 / 分类元数据
32接口
Done
B3
会员与财务
Member · MemberCq · MemberV2 · Finance · FinanceV1
会员完整 CRUD 与销售明细 · 财务销售汇总 / 明细列表
10接口
Done
B4
报表明细
reportforms / v3Reportforms 详情 · OrderSales / OrderGuideSales / OrderKufangSales / OrderCategorySales / OrderRetreat · LskcReportSales(V1/Vs) · OutboundNetweightOrder · UserSales · gridReport
员工绩效 · 导购销售 · 库房销售 · 品类销售 · 回收统计 · 静态报表配置
44接口
Done
B5
告警与辅助
Alert · AlertNot · Label · KsiamgesAlert · Receipt · login 补齐
告警订阅与通知 · 标签打印 · 售后凭证 · 登录辅助字段
10接口
Done
§ 03 · Execution Flow
执行流水

每批 = 独立 worktree + 独立分支 + CC opus-4.7 会话。完成 → 主 agent 亲验 selftest + contract gate + 浏览器 E2E → 更新本追踪页 → 派下一批。链接不变，就地翻新。

B1 · 销售链 Done
Outbound × 11 · Retreat × 6 · Presale × 4 · print × 2
Spec docs/phases/mobile-b1-spec.md
Branch feat/mobile-b1-sales
模型 claude-opus-4.7
已合入 main · 41 implemented
B2 · 库存与扫码 Done
库房库存查询 · 盘点临时单 · 调拨明细 · 款号 / 图片 / 分类元数据
Spec docs/phases/mobile-b2-spec.md
Branch feat/mobile-b2-stock
模型 claude-opus-4.7
已合入 main · 73 implemented
B3 · 会员与财务 Done
会员完整 CRUD 与销售明细 · 财务销售汇总 / 明细列表
Spec docs/phases/mobile-b3-spec.md
Branch feat/mobile-b3-member-finance
模型 claude-opus-4.7
已合入 main · 83 implemented
B4 · 报表明细 Done
员工绩效 · 导购销售 · 库房销售 · 品类销售 · 回收统计 · 静态报表配置
Spec docs/phases/mobile-b4-spec.md
Branch feat/mobile-b4-reports
模型 claude-opus-4.7
已合入 main · 127 implemented
B5 · 告警与辅助 Done
告警订阅与通知 · 标签打印 · 售后凭证 · 登录辅助字段
Spec docs/phases/mobile-b5-spec.md
Branch feat/mobile-b5-alerts
模型 claude-opus-4.7
已合入 main · 137 implemented
§ 04 · Acceptance Rules
验收铁律

从「代码写完」到「真能用」之间还有很长的路。以下每条都由过往踩过的坑推出。任何一条不满足即整批打回。

01
Kotlin 契约为唯一事实源
每个接口都必须读对应 Kotlin Controller / Service / Mapper XML，按字段 / 时间 / 权限 / 精度精确复刻。禁止凭前端调用签名反推实现。
02
禁止空数组冒充实现
未完成接口必须显式 err(501, 'contract not ported')，不许返 [] / {code:200,data:{}} 假装成功。前端拿到 501 会跳错，比默默为空好一百倍。
03
三道门验收
php -l 语法门 + selftest.php 契约门 + bin/check-mobile-api-contract.py 覆盖门。三门全绿才允许 commit。gate 数字变化写进 docs/phases/mobile-api-matrix.json。
04
主 agent 亲验浏览器 E2E
每批合并 main 之后，主 agent 用 headless Chrome 覆盖该批直接对应的页面，vision 复核截图。禁止只信 CC 自报的 selftest 结果。
05
生产源代码只读
禁止改 pyerp_php / xylferp / baijianerp / app_xiao_shou_kotlin 等生产源。禁止改中心认证 / Tenant 层。所有改动落在 modules/mobile-api/。
06
追踪页与代码同步
每批完成后立即更新本追踪页的 KPI / 状态 / 进度条。链接不换，就地翻新。直到 137/137 全绿才算这个任务完成。