system_design.md 34 KB

CFC 后台多小程序对接架构方案

作者:架构师 高见远(Bob) | 项目:E:/cfc | 2026-11-10 范围:仅做方案设计 + 任务分解,不含实现代码。后续可转 TDD 任务(能力键三段式 <unit>.<domain>.<action>)。


0. 现状复核(实证)

维度 现状
配置 application.yml wechat: 单实例硬编码,25 项:appid/secret/mch-id/mch-key/api-v3-key/mch-serial-no/private-key-path/notify-url/login-url/phone-url/test-mode/fulfillment-enabled/appkey/sandbox-appkey/virtual-pay-env/virtual-pay-token/offer-id/test-phone/alert-template-id/promotion-tier-template-id/env-version/wxacode-login-page
注入 @Value("${wechat.*}") 字段注入;核心服务 WechatService 单例,被十余处 @Resource 共享
appid 引用 远不止 3 个文件。除 WechatService / PaymentService / HealthExerciseController 外,还有 VirtualPayService(appkey/sandbox-appkey/offer-id/virtual-pay-env)、VirtualPayController(virtual-pay-token 回调验签)、WechatAlertTemplateService、PromotionTierEvalService、WechatWebLoginService(wxacode-login-page)、多个 @Value("${wechat.test-mode:false}") 消费者
缓存 WechatService 用 固定 key wechat:stable_access_token 写 Redis(多 appid 会串号);另有进程内 cachedStableAccessToken volatile 单值
数据层 实体无 appid 维度;users.openid 唯一索引(无 appid);package_orders/product_orders 无 appid;迁移唯一入口 DatabaseInitializer.runMigrations()(ensureColumn 幂等模式成熟)
鉴权 JwtInterceptor 解析 JWT 后写入 request.setAttribute(userId/role/roles/familyId/...);登录接口在 PUBLIC_PATHS 白名单
回调 支付回调 /api/payment/wechat/v3-notify(WebConfig 已排除鉴权);虚拟支付回调 /api/internal/virtual-pay/notify(GET 验证 + POST 推送,SHA1(token,timestamp,nonce) 验签,token 取自 wechat.virtual-pay-token);中间层 wechat.iwintrue.com 通过 etotem.webhook.wait-msg.url 与后端协作

核心风险:同一微信账号下 6 个小程序,openid 各不相同(同一用户在 6 个小程序有 6 个不同 openid)。若不加 appid 维度,users.openid 会跨小程序串号(后登录者绑定到同一 user 行,session_key/openid 相互覆盖),登录/支付/虚拟支付全会串台。这是本方案的第一优先级问题。


Part A:系统设计

1. 方案选型对比

维度 ①纯 yml 多维(map 结构) ②纯 DB 配置表(动态热更) ③混合:DB 为主 + yml 兜底 + env 存密钥 ✅
典型形态 wechat.apps.<code>.appid yml map,启动期一次性绑定 新表 miniapp_config,启动/定时/手动刷新加载,改配置不重启 非敏感路由/模板项存 DB;敏感项(secret/mch-key/api-v3-key/私钥路径/appkey)存环境变量引用,DB 只存引用名
新增小程序 改 yml + 重启 管理端/SQL 插一行即可 管理端插一行 + 配置环境变量(密钥)
配置变更生效 需重启 热更(缓存 TTL 或主动失效) 非敏感项热更;密钥变更需重启/重新触发刷新
多实例部署 yml 随镜像分发,一致 共享 DB,天然一致 共享 DB,密钥走 env 统一注入
安全 密钥明文进 yml(现状已如此,靠 env 覆盖缓解) 密钥落 DB,泄库即泄密 ❌ 密钥不落 DB 明文 ✅
改造成本 低 中(需表 + 加载 + 缓存 + 管理端) 中(同②,但脱敏处理稍复杂)
兼容现状 直接把现 wechat: 块改为 wechat.apps.default 需先迁移 默认 app 保持 yml 行为,新 app 走 DB
数量级适配(6 个) 够用但臃肿 合适 合适

推荐:方案③ 混合(DB 为主 + yml 兜底 + 敏感项走环境变量引用)

理由:

  1. 6 个数量级已不适合塞 yml;运营/管理端会频繁调整模板 ID、env-version、notify-url、offer-id 等非敏感项,DB 热更避免反复发版。
  2. 安全敏感项(secret/mch-key/api-v3-key/私钥/appkey)绝不落 DB 明文:DB 存"env 引用名",运行时从环境变量解析;默认 app 继续兼容现 ${WECHAT_SECRET:...} 行为。
  3. 默认 app 零回归:miniapp_config 中 mp_code='default' 的一行由 yml wechat: 播种,未指定小程序标识的请求一律回落 default,完全保持现状。
  4. 多实例部署一致:配置共享 DB,密钥靠部署层 env 注入。
  5. 与既有 wechat.iwintrue.com 中间层并存:中间层配置不受影响,回调 URL 按小程序维度区分即可。

2. 配置模型

2.1 新表 miniapp_config(DB 迁移)

CREATE TABLE IF NOT EXISTS miniapp_config (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    mp_code VARCHAR(32) NOT NULL UNIQUE COMMENT '小程序路由标识(稳定短码,路由/回调/日志用),如 xiaoyi/zhishao',
    display_name VARCHAR(64) COMMENT '展示名,如 AI小亿管理',
    app_id VARCHAR(32) NOT NULL UNIQUE COMMENT '微信 appid(区分配置的自然键)',
    secret_ref VARCHAR(128) COMMENT 'secret 的 env 引用名(如 WECHAT_SECRET_XIAOYI);NULL=回落 wechat.secret',
    mch_id VARCHAR(32) COMMENT '微信支付商户号;NULL=不启用支付',
    mch_key_ref VARCHAR(128) COMMENT 'mch-key 的 env 引用名',
    api_v3_key_ref VARCHAR(128) COMMENT 'api-v3-key 的 env 引用名',
    mch_serial_no VARCHAR(64) COMMENT '商户 API 证书序列号',
    private_key_path VARCHAR(256) COMMENT 'apiclient_key.pem classpath 路径(每 appid 一份)',
    notify_url VARCHAR(256) COMMENT '支付回调 URL(可带 /{mpCode} 路径)',
    login_url VARCHAR(256) DEFAULT 'https://api.weixin.qq.com/sns/jscode2session',
    phone_url VARCHAR(256) DEFAULT 'https://api.weixin.qq.com/wxa/business/getuserphonenumber',
    test_mode TINYINT(1) DEFAULT 0 COMMENT '测试模式:1=跳过微信 API',
    fulfillment_enabled TINYINT(1) DEFAULT 1,
    virtual_pay_enabled TINYINT(1) DEFAULT 0,
    appkey_ref VARCHAR(128) COMMENT '虚拟支付现网 appkey 的 env 引用名',
    sandbox_appkey_ref VARCHAR(128) COMMENT '虚拟支付沙箱 appkey 的 env 引用名',
    virtual_pay_env TINYINT(1) DEFAULT 0 COMMENT '0=现网 1=沙箱',
    virtual_pay_token_ref VARCHAR(128) COMMENT '虚拟支付消息推送 Token 的 env 引用名',
    offer_id VARCHAR(32) COMMENT '虚拟支付应用 ID(每个小程序专属)',
    alert_template_id VARCHAR(64) COMMENT '订阅消息模板 ID',
    promotion_tier_template_id VARCHAR(64) COMMENT '促销档位模板 ID',
    env_version VARCHAR(16) DEFAULT 'release' COMMENT '小程序码环境:dev/test/release',
    wxacode_login_page VARCHAR(128) DEFAULT 'pages/login/scan-login',
    enabled TINYINT(1) DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_app_id (app_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='多小程序配置表(密钥只存 env 引用名,不存明文)';
  • 敏感项只存引用名(secret_ref 等),运行时由 MiniAppConfigService.resolveSecret(ref) 从 System.getenv(ref) / System.getProperty(ref) 解析,未配置即抛错并 fail-fast。
  • 播种:DatabaseInitializer.runMigrations() 中幂等 INSERT IGNORE INTO miniapp_config(mp_code, display_name, app_id, ...) VALUES('default','CFC主小程序','${WECHAT_APPID:wx5ba8038ef16fb245}', ...),从 yml wechat: 读初始值,保证升级后默认 app 行为不变。
  • 默认 app 兜底:当 MiniAppContext.mpCode() 无值时,返回 default,加载 yml 播种的那行,行为与现状 100% 一致。

2.2 Java 配置模型(核心类)

classDiagram
    class MiniAppProperties {
        <<@ConfigurationProperties(prefix="wechat")>>
        +String defaultCode
        +Map~String, MiniAppStaticConfig~ apps
    }
    class MiniAppStaticConfig {
        +String appId
        +String displayName
    }
    class MiniAppConfig {
        <<entity, table=miniapp_config>>
        +Long id
        +String mpCode
        +String displayName
        +String appId
        +String secretRef
        +String mchId
        +String mchKeyRef
        +String apiV3KeyRef
        +String mchSerialNo
        +String privateKeyPath
        +String notifyUrl
        +String loginUrl
        +String phoneUrl
        +boolean testMode
        +boolean fulfillmentEnabled
        +boolean virtualPayEnabled
        +String appkeyRef
        +String sandboxAppkeyRef
        +int virtualPayEnv
        +String virtualPayTokenRef
        +String offerId
        +String alertTemplateId
        +String promotionTierTemplateId
        +String envVersion
        +String wxacodeLoginPage
        +boolean enabled
    }
    class MiniAppMapper {
        <<BaseMapper~MiniAppConfig~>>
    }
    class MiniAppConfigService {
        -ConcurrentHashMap~String, MiniAppConfig~ byCode
        -ConcurrentHashMap~String, MiniAppConfig~ byAppId
        +reload()
        +getByCode(String mpCode) MiniAppConfig
        +getByAppId(String appId) MiniAppConfig
        +getDefault() MiniAppConfig
        +resolveSecret(MiniAppConfig c) String
        +resolveMchKey(MiniAppConfig c) String
        +resolveApiV3Key(MiniAppConfig c) String
        +resolveVirtualPayToken(MiniAppConfig c) String
        +resolveAppkey(MiniAppConfig c, boolean sandbox) String
    }
    class MiniAppContext {
        +String mpCode
        +String appId
        +MiniAppConfig config
        +String resolve()
    }
    MiniAppProperties *-- MiniAppStaticConfig
    MiniAppConfigService --> MiniAppMapper : loads
    MiniAppConfigService ..> MiniAppConfig : caches
    MiniAppContext ..> MiniAppConfigService : uses
  • MiniAppProperties(yml wechat.apps.<code>)只承载静态兜底(当前 default app),启动期与 DB 行合并:DB 有值以 DB 为准,DB 无值回落 yml,DB 与 yml 都无则启动报错(fail-fast)。
  • MiniAppConfigService.reload() 在 @PostConstruct、管理端变更、定时(如 5 分钟)时刷新内存 ConcurrentHashMap;不重启。

2.3 缓存策略(appid 维度)

缓存对象 Key TTL 说明
access_token(stable_token) wechat:stable_token:{appId}(default app 兼容保留旧 key wechat:stable_access_token) 7000s 复用现 getStableAccessToken() 逻辑,仅 key 加 appid 后缀;Redis 多实例共享
进程内 token ConcurrentHashMap<appId, TokenEntry> 7000s 双层缓存,进程内优先
jsapi_ticket / wxacode 等 同规则 wechat:{kind}:{appId} 各自官方 TTL 后续扩展
miniapp_config 进程内 ConcurrentHashMap<mpCode, MiniAppConfig> 主动失效 + 5min 兜底 见 §2.2
  • invalidateAccessToken(appId) 同步删除对应 Redis key;回调 42001/40001 触发。
  • 提前刷新:命中但剩余 TTL < 200s 时后台异步刷新,避免临界阻塞。

3. 请求路由识别机制

三种候选方案对比

方案 登录前可用 支付回调可用 改造成本 风险
①Header 显式传 X-MP-Code(小程序端 wx.request 拦截器统一带) ✅ ❌(微信服务器回调不带自定义 Header) 低(前端 + Interceptor) 需前端配合
②JWT 载荷携带 mpCode(登录时根据 Header 写入 claim) ❌(登录前无 JWT) ❌(回调无 JWT) 中(JwtInterceptor/JwtConfig) 仅适用于已登录普通业务
③路径前缀 / 域名分流(如 /api/mp/{mpCode}/... 或每 appid 独立子域) ✅ ✅(回调 URL 含 mpCode) 高(改所有路由 or 域名解析) 路由改造大

推荐组合策略(按场景分别取上下文,互为兜底):

MiniAppContextResolver.resolve(request, jwtClaims) -> MiniAppContext
  优先级:
  1) request.getAttribute("mpCode")  —— 由 MiniAppInterceptor 提前写入
  2) request.getHeader("X-MP-Code")  —— 前端/回调 URL 显式传
  3) jwtClaims.get("mpCode")         —— 已登录业务请求兜底
  4) request.getParameter("mpCode")  —— 极少数 GET 验证请求兜底
  5) "default"                       —— 全部缺失时兜底,保持旧 app 行为
场景 识别方式
登录换 token(/api/auth/wechat-login / wechat-phone-login / silent-login) 前端在登录请求带 X-MP-Code Header;MiniAppInterceptor 解析后写入 request attr;UserService.wechatLogin 据此取配置调 code2Session(code, mpCode),并将 mpCode 写入新签 JWT claim 与 users.appid
普通业务请求 JWT claim 中的 mpCode 为主;MiniAppInterceptor 优先用 Header 校正,写入 request.setAttribute("mpCode", ...);下游 service 通过 MiniAppContextHolder.get() 取
支付下单(/v3/pay/...) 已登录,JWT/Header 都可;PaymentService 用 MiniAppContext.config 中的 mchId/apiV3Key/serialNo/privateKey/notifyUrl 组装订单
支付回调 /api/payment/wechat/v3-notify 无 Header 无 JWT。回调 URL 携带 mpCode 段:现 default app 保持原 URL 不变;新 app 配置 notifyUrl=https://.../api/payment/wechat/v3-notify/{mpCode}。Controller 从 @PathVariable 或 fallback 用 out_trade_no 反查订单 → 订单上有 appid 维度(§5),双保险
虚拟支付回调 /api/internal/virtual-pay/notify 同上:回调 URL 带 mpCode(在微信后台"消息推送"配置时填带 mpCode 的 URL);VirtualPayController 从 URL 解出 mpCode,验签用该 app 的 virtual_pay_token;若 URL 无 mpCode,遍历所有启用虚拟支付的小程序按 token 逐个验签(数量小、可接受)
wxacode 生成 已登录,走 JWT/Header

线程上下文:新增 MiniAppContextHolder(ThreadLocal<MiniAppContext>);MiniAppInterceptor.preHandle 写入、afterCompletion 清理(与现 JwtInterceptor 的 SecurityContext 清理策略对齐,避免线程池复用串号)。异步任务(如发货、订阅消息推送)显式传 mpCode 参数或捕获 Context 快照。


4. 改造落点

4.1 WechatService 改造(最大落点)

现状 改造后
@Value 字段注入 appid/secret/login-url/phone-url/env-version/mch-id/alert-template-id/fulfillment-enabled 全部删除,改为方法入参 mpCode 或 MiniAppConfig,从 MiniAppConfigService 取
code2Session(code) 用固定 appid/secret code2Session(code, mpCode):cfg = configService.getByCode(mpCode); url = cfg.loginUrl + "?appid=" + cfg.appId + "&secret=" + configService.resolveSecret(cfg) + ...
getAccessToken() 单 key 缓存 getAccessToken(mpCode) → 内部 getStableAccessToken(cfg);缓存 key wechat:stable_token:{cfg.appId}
getOAuth2Openid/getOAuth2Url/getPhoneNumber/checkText/checkImage/generateWxacode/sendTemplateMessage/uploadShippingInfo/decryptWeRunData 全部增加 mpCode 首参(或新增重载,旧签名默认 mpCode="default",向后兼容,不破坏既有调用点)
invalidateAccessToken() 单值 invalidateAccessToken(mpCode) 删对应 Redis key + 进程内 entry
WechatServiceInterface 同步加 mpCode 参数版本;旧签名 @Deprecated 但保留

兼容技巧:保留旧无参方法签名(默认委托 default app),这样十余个 @Resource WechatService 的调用点不必一次性全改;按场景逐步切换到带 mpCode 的重载。

4.2 PaymentService 改造

  • 删除 @Value appid/mchId/apiV3Key/mchSerialNo/privateKeyPath/notifyUrl/test-mode 字段。
  • 新增 Map<appId, PrivateKey> 私钥缓存(@PostConstruct 只预加载 default,其他 appid 懒加载)。
  • createWechatPrepay(orderNo, desc, totalFee, openid, detail, mpCode):从 MiniAppConfigService 取该 app 的全部支付凭据。
  • handleWechatNotify(body, signature, mpCode):用该 app 的 apiV3Key 解密 AES-256-GCM;用其私钥验证回调签名(现实现未校验签名,本方案补齐到 appid 维度)。
  • buildAuthHeader/doGet/doPost 改为实例化"per-appid"的签名参数(建议抽 WxPayClient helper,见 §4.5)。

4.3 HealthExerciseController 改造

  • 现状 @Value("${wechat.appid}") String appid 用于 decryptWeRunData 返回的 watermark.appid 校验。
  • 改为:String appid = miniAppContext.appId();(从 Context 取当前请求的 appid)。
  • decryptWeRunData 用用户登录时的 session_key,本身已隐含 appid(session_key 是 code2Session 时按 appid 换的);watermark 校验用当前请求 appid,正确。

4.4 其他 wechat.* 消费者改造

文件 现状 改造
VirtualPayService @Value appkey/sandbox-appkey/offer-id/virtual-pay-env/test-mode 改为入参 mpCode/MiniAppConfig,调 configService.resolveAppkey(cfg, sandbox) / cfg.offerId
VirtualPayController @Value wechat.virtual-pay-token 从 URL/参数 mpCode 解出 config → configService.resolveVirtualPayToken(cfg)
WechatAlertTemplateService @Value wechat.alert-template-id 从 Context 取 cfg.alertTemplateId
PromotionTierEvalService @Value wechat.promotion-tier-template-id 同上,cfg.promotionTierTemplateId
WechatWebLoginService @Value wechat.wxacode-login-page cfg.wxacodeLoginPage
多处 @Value wechat.test-mode VerificationCodeService/DanAssessmentController/MembershipController/SubscriptionController/WechatWebLoginService 等 统一改为 wechatService.isTestMode(mpCode) 或 configService.getByCode(mpCode).isTestMode()

4.5 通用凭证/签名组件 appid 维度化

  • 抽 WxPayClient(per-appid 签名/请求客户端),持有 MiniAppConfig + 懒加载 PrivateKey,提供 post(path, body) / get(path) / verifySignature(headers, body) / decryptAes256Gcm(...);PaymentService 委托它。
  • WechatService 内部抽 WxApiClient(per-appid access_token 管理器),统一 token 缓存与刷新,暴露 getAccessToken(cfg) / invalidate(cfg)。
  • 两 client 都用 MiniAppConfigService 取凭据,密钥解密后只在内存短暂存在,不落日志。

4.6 JwtInterceptor / Context 透传

  • 新增 MiniAppInterceptor(在 JwtInterceptor 之前注册,WebConfig.addInterceptors 调序):
    1. 从 X-MP-Code Header / mpCode 参数 / URL path 变量(如 /v3-notify/{mpCode})解析;
    2. 写入 request.setAttribute("mpCode", code) 与 MiniAppContextHolder.set(...);
    3. 对未识别的 code 直接拒绝(400)防串号;
    4. afterCompletion 清理 ThreadLocal。
  • JwtConfig.generateToken(userId, roles, mpCode) 增加 claim;JwtInterceptor.parseToken 后把 mpCode 补写到 request.setAttribute("mpCode", ...)(若 Header 未带则从 JWT 取,双兜底)。
  • 登录成功响应中可回传 mpCode,前端写入 storage 并在后续请求带 Header(前端配合项)。

5. 数据安全

  1. 密钥不落 DB 明文:miniapp_config 只存 env 引用名(secret_ref、mch_key_ref、api_v3_key_ref、appkey_ref、virtual_pay_token_ref),运行时从环境变量解析。
  2. 解析失败 fail-fast:MiniAppConfigService.resolveSecret 若 env 未设置,抛 IllegalStateException("密钥未配置: " + ref),绝不静默回落,避免用错 app 密钥。
  3. 日志脱敏:所有日志只打印 mpCode/appId,禁止打印 secret/mch-key/api-v3-key/token/session_key;建议加 Logback masking pattern 兜底。
  4. DB 访问:miniapp_config 表只读通过 MiniAppConfigService,不暴露写接口给业务侧;管理端写接口另起 AdminMiniAppConfigController(/api/admin-auth/** 鉴权),变更后调用 reload()。
  5. 私钥文件:每 appid 一份 cert/{mpCode}/apiclient_key.pem,private_key_path 配置区分;不进 git(.gitignore 已有 cert/ 约定需复核)。
  6. 与现 xiao/huawei encrypt-key 同思路:如未来必须落库密钥,复用现有 AES-128 加密方案,密钥由环境变量注入;本期先采用 env 引用方案(更简单,无需密钥管理服务)。

6. 兼容与迁移路径

原则:默认 app(现 wx5ba8038ef16fb245)行为 100% 不变,零回归。

阶段 内容 验收
P0 基础设施(无行为变化) 新增 MiniAppConfig 实体/Mapper/miniapp_config 表;播种 default 行(从 yml 读初始值);新增 MiniAppProperties、MiniAppContextHolder、MiniAppContextResolver、MiniAppInterceptor(默认全回落 default) 老接口全部回归通过;miniapp_config 已播种 default
P1 配置服务 MiniAppConfigService 加载/缓存/密钥解析;WechatService.getAccessToken 改为按 appId 缓存(default 沿用旧 Redis key 兼容存量 token) 老接口回归;多 appid 下 access_token 各自隔离
P2 三个核心引用点改造 WechatService/PaymentService/HealthExerciseController 增加带 mpCode 重载,旧签名委托 default 现网 default 调用全部走 default 分支;不传 mpCode 的请求回归通过
P3 数据维度 users 增加 appid 列(默认现 appid)+ 唯一索引 uk_openid_appid(openid, appid)(先去重);package_orders/product_orders 增加 appid 列;UserService.wechatLogin 改为按 (openid, appid) 查询,新签 JWT 携带 mpCode 不同小程序登录同一微信号产生独立 user 行;老用户 appid 回填后仍能登录
P4 扩展消费者 VirtualPayService/VirtualPayController/WechatAlertTemplateService/PromotionTierEvalService/WechatWebLoginService + 各 wechat.test-mode 消费者切到 MiniAppConfig 各业务按 mpCode 取对应模板/凭据
P5 管理端 + 回调路由 AdminMiniAppConfigController CRUD + reload;支付/虚拟支付回调 URL 支持带 mpCode 段;中间层 wechat.iwintrue.com 适配新路由 可在线新增小程序并跑通登录/支付/虚拟支付

向后兼容细节:

  • 旧无参 wechatService.code2Session(code) 等方法保留并 @Deprecated,默认走 default;不强制一次改完所有调用点。
  • 未携带 X-MP-Code 的请求一律 default;前端按节奏升级。
  • 中间层 wechat.iwintrue.com 若向多小程序推送,需在消息体/URL 带 mpCode,本方案通过 Header/参数兜底兼容其存在。
  • 配置变更:DB 行变更后调 MiniAppConfigService.reload()(管理端触发)或等 5min 兜底刷新,无需重启。

Part B:任务分解

6. 所需依赖(无新增第三方,全部用现有 Spring/MyBatis-Plus/Redis/OkHttp)

  • 无需引入新依赖。全部基于现有 spring-boot-starter-web、mybatis-plus、spring-boot-starter-data-redis、okhttp(已在 PaymentService 使用)、jjwt、fastjson。

7. 任务列表(5 个任务,按依赖排序,每任务 ≥ 3 文件)

能力键命名:<unit>.<domain>.<action>,如 wechat.multiapp.config.load、wechat.multiapp.context.resolve。


T01 | 基础设施:多小程序配置模型 + yml 兜底 + 表迁移

  • Source Files(≥ 3):
    • cfc-backend/src/main/java/com/etotem/cfc/entity/MiniAppConfig.java(新增)
    • cfc-backend/src/main/java/com/etotem/cfc/mapper/MiniAppMapper.java(新增)
    • cfc-backend/src/main/java/com/etotem/cfc/config/MiniAppProperties.java(新增,@ConfigurationProperties(prefix="wechat") 含 defaultCode + apps map)
    • cfc-backend/src/main/resources/application.yml(改造:wechat: 块加 default-code: default 与 apps.default: { app-id: wx5ba8038ef16fb245 } 兜底)
    • cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java(在 runMigrations() 追加建表 + 播种 default 行 + 加列)
    • cfc-backend/src/main/resources/schema.sql(追加 miniapp_config 建表)
  • Dependencies:无
  • Priority:P0
  • TDD 能力键:wechat.multiapp.config.migrate、wechat.multiapp.config.seed-default
  • 验收判据:
    1. 启动后 miniapp_config 表存在;含 mp_code='default' 行,app_id 与现 yml 一致;
    2. 二次启动迁移幂等(不报 Duplicate);
    3. MiniAppProperties.apps.default.appId 注入成功;
    4. 现有单测全绿,无行为回归。

T02 | 上下文识别 + 配置服务 + access_token 隔离缓存

  • Source Files(≥ 3):
    • cfc-backend/src/main/java/com/etotem/cfc/context/MiniAppContext.java(新增)
    • cfc-backend/src/main/java/com/etotem/cfc/context/MiniAppContextHolder.java(新增 ThreadLocal)
    • cfc-backend/src/main/java/com/etotem/cfc/context/MiniAppContextResolver.java(新增,优先级链)
    • cfc-backend/src/main/java/com/etotem/cfc/config/MiniAppInterceptor.java(新增,注册到 WebConfig)
    • cfc-backend/src/main/java/com/etotem/cfc/config/WebConfig.java(改造:注册拦截器)
    • cfc-backend/src/main/java/com/etotem/cfc/config/JwtConfig.java(改造:generateToken/parseToken 增 mpCode claim)
    • cfc-backend/src/main/java/com/etotem/cfc/config/JwtInterceptor.java(改造:解析 mpCode 写入 request attr)
    • cfc-backend/src/main/java/com/etotem/cfc/service/MiniAppConfigService.java(新增:加载/缓存/密钥解析/reload)
    • cfc-backend/src/main/java/com/etotem/cfc/service/WechatService.java(改造:getAccessToken(mpCode)、Redis key 加 appId 后缀、default 沿用旧 key)
  • Dependencies:T01
  • Priority:P0
  • TDD 能力键:wechat.multiapp.context.resolve、wechat.multiapp.context.fallback-default、wechat.multiapp.config.load、wechat.multiapp.config.secret-resolve、wechat.multiapp.token.isolate
  • 验收判据:
    1. 带 X-MP-Code: xiaoyi Header 的请求,MiniAppContextHolder.get().mpCode() == "xiaoyi";
    2. 不带 Header 时回落 default;
    3. JWT 携带 mpCode claim,JwtInterceptor 能写入 attr;
    4. MiniAppConfigService.getByCode("default") 返回与 yml 一致的配置;
    5. resolveSecret 在 env 未设置时抛 IllegalStateException;
    6. 多 appid 并发取 access_token,Redis 中 key 各自独立,互不覆盖;
    7. 单测覆盖 MiniAppContextResolver 优先级链、MiniAppConfigService.reload、token 隔离。

T03 | 数据维度:users/orders 增加 appid + 登录流程串号修复

  • Source Files(≥ 3):
    • cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java(新增迁移:users/product_orders/package_orders 加 appid 列 + 索引)
    • cfc-backend/src/main/resources/schema.sql(同步列定义)
    • cfc-backend/src/main/java/com/etotem/cfc/entity/User.java(新增 appid 字段)
    • cfc-backend/src/main/java/com/etotem/cfc/entity/ProductOrder.java(新增 appid 字段)
    • cfc-backend/src/main/java/com/etotem/cfc/entity/PackageOrder.java(新增 appid 字段)
    • cfc-backend/src/main/java/com/etotem/cfc/service/UserService.java(改造:wechatLogin/silentLogin 按 (openid, appid) 查询,写入 appid,签 JWT 带 mpCode)
    • cfc-backend/src/main/java/com/etotem/cfc/service/PaymentService.java(下单时写入 order.appid)
  • Dependencies:T01, T02
  • Priority:P0(核心防串号)
  • TDD 能力键:wechat.multiapp.user.appid-migrate、wechat.multiapp.user.openid-isolate、wechat.multiapp.order.appid-write
  • 验收判据:
    1. 迁移后 users/product_orders/package_orders 含 appid 列,存量行 appid=现 appid;
    2. 同一微信号在两个不同 appid 登录,产生两个独立 user 行,各自 session_key/openid 独立;
    3. 老用户(appid=default)仍能正常登录;
    4. 下单后 order.appid 非空,与登录 appid 一致;
    5. 唯一索引 uk_openid_appid(openid, appid) 生效(同 appid 内不重复)。

T04 | 三大核心服务改造 + 扩展消费者

  • Source Files(≥ 3):
    • cfc-backend/src/main/java/com/etotem/cfc/service/WechatService.java + service/api/WechatServiceInterface.java(增加 mpCode 重载,旧签名 @Deprecated 默认 default)
    • cfc-backend/src/main/java/com/etotem/cfc/service/PaymentService.java + service/api/PaymentServiceInterface.java(per-appid 凭据 + notify 解密 + 签名按 appid)
    • cfc-backend/src/main/java/com/etotem/cfc/controller/HealthExerciseController.java(appid 从 Context 取)
    • cfc-backend/src/main/java/com/etotem/cfc/controller/guide/PaymentController.java(v3-notify 支持路径变量 /{mpCode} + 订单反查兜底)
    • cfc-backend/src/main/java/com/etotem/cfc/controller/VirtualPayController.java(URL/参数解 mpCode,per-appid token 验签)
    • cfc-backend/src/main/java/com/etotem/cfc/service/VirtualPayService.java(appkey/offer-id/env 从 config 取)
    • cfc-backend/src/main/java/com/etotem/cfc/service/WechatAlertTemplateService.java、PromotionTierEvalService.java、WechatWebLoginService.java(模板 ID / wxacode page 从 config)
  • Dependencies:T02, T03
  • Priority:P1
  • TDD 能力键:wechat.multiapp.wechat.service-isolation、wechat.multiapp.pay.credential-isolation、wechat.multiapp.pay.notify-route、wechat.multiapp.virtualpay.credential、wechat.multiapp.virtualpay.notify-verify、wechat.multiapp.wxacode.isolation、wechat.multiapp.alert.template-by-code
  • 验收判据:
    1. 不同 mpCode 调 wechatService.code2Session(code, mpCode) 用各自 appid/secret;
    2. paymentService.createWechatPrepay(..., mpCode) 用该 app 的 mchId/serialNo/私钥签名;不同 mpCode 订单签名独立;
    3. v3-notify 在带 mpCode 路径时按该 app 解密;不带时通过 orderNo 反查订单 appid;
    4. virtual-pay/notify 在 URL 带 mpCode 时用对应 token 验签;不带时遍历 token 兜底;
    5. HealthExerciseController.decryptWeRunData 用当前请求 appid 校验 watermark;
    6. 现网 default app 全链路回归通过(旧调用点零修改仍工作)。

T05 | 管理端 + 配置变更热更 + 端到端联调

  • Source Files(≥ 3):
    • cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminMiniAppConfigController.java(新增:CRUD + reload)
    • cfc-backend/src/main/java/com/etotem/cfc/service/MiniAppConfigService.java(增强:变更失效、定时兜底刷新)
    • cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java(如需追加种子/索引微调)
    • cfc-backend/src/test/java/com/etotem/cfc/service/MiniAppConfigServiceTest.java(新增集成测试)
    • cfc-backend/src/test/java/com/etotem/cfc/integration/MultiAppEndToEndTest.java(新增端到端:多 appid 登录 + 支付下单 + 回调路由)
    • docs/multiapp-rollout.md(新增:新小程序上线 SOP、密钥环境变量清单、灰度开关)
  • Dependencies:T04
  • Priority:P1
  • TDD 能力键:wechat.multiapp.admin.crud、wechat.multiapp.admin.reload、wechat.multiapp.e2e.login-pay-notify
  • 验收判据:
    1. 管理端可新增 mp_code='xiaoyi' 行;新增后调 reload(),无需重启即可用 X-MP-Code: xiaoyi 登录;
    2. 端到端测试覆盖 2 个小程序:独立登录 → 独立下单 → 独立回调路由,互不串号;
    3. 密钥环境变量缺失时启动/调用有明确错误提示;
    4. 回滚策略:清空非 default 行 + 去掉前端 Header,可一键回到单 app 行为。

8. 共享约定(工程师须知)

  • 默认 app:mpCode == null || "default".equals(mpCode) 一律走 default app,保持现状。
  • Result 响应:所有新接口 Result<T>;错误码遵循现有 code/message/data。
  • 鉴权:/api/auth/** 登录接口已在 PUBLIC_PATHS,但仍需 MiniAppInterceptor 解析 Header;/api/payment/wechat/v3-notify 与 /api/internal/virtual-pay/notify 走 WebConfig 排除鉴权,依赖回调 URL 的 mpCode 段 + 签名校验防伪造。
  • AI 能力:本方案不涉及 LLM;如未来需按小程序区分 AI prompt,复用 AiGateway 并把 mpCode 作为上下文透传。
  • 线程池:异步任务(@Async/taskExecutor)捕获 MiniAppContextHolder 快照传递,禁止跨线程裸读 ThreadLocal。
  • schema.sql 同步:每次 DatabaseInitializer 追加迁移,必须同步 schema.sql(项目铁律)。
  • 迁移幂等:所有 DDL 用 CREATE TABLE IF NOT EXISTS / ensureColumn;数据播种用 INSERT IGNORE 或先 SELECT。
  • 日志脱敏:禁止打印 secret/mch-key/api-v3-key/appkey/token/session_key,只打 mpCode/appId。

9. 任务依赖图

graph TD
    T01[T01 基础设施: 配置模型+yml兜底+迁移] --> T02[T02 上下文识别+配置服务+token隔离]
    T01 --> T03[T03 数据维度: users/orders加appid+登录修复]
    T02 --> T03
    T02 --> T04[T04 三大核心服务+扩展消费者改造]
    T03 --> T04
    T04 --> T05[T05 管理端+热更+端到端联调]

5'. UNCLEAR / 待确认

  1. wechat.iwintrue.com 中间层细节:当前 WechatWaitMsgService 调用的 etotem.webhook.wait-msg.url 是否需要按小程序区分?假定中间层会按 appid 路由消息,本方案通过回调 URL/Header 的 mpCode 兼容其存在;若中间层本身不分 appid,需要单独评估。
  2. users 表唯一索引:现 users.openid 无唯一索引(只是 INDEX idx_openid)。多小程序下不同 appid 可产生不同 openid;同 appid 内是否允许同 openid 多行?本方案假设不允许(同 appid 内 openid 唯一),需 DBA 复核存量是否有重复。
  3. 支付回调签名校验:现 handleWechatNotify 未校验 Wechatpay-Signature,本方案 P1 阶段补齐 per-appid 校验;如时间紧可暂保持 fail-open,但需在文档标记。
  4. 管理端配置页 UI:T05 只做后端 CRUD + reload;前端管理界面本方案未展开,可独立排期。
  5. 默认 app 兜底与灰度开关:本方案默认无 Header 即 default;若未来要强制所有请求带 Header(关闭兜底),可加配置项 wechat.multiapp.strict-mode: true,本方案未默认开启。