作者:架构师 高见远(Bob) | 项目:E:/cfc | 2026-11-10 范围:仅做方案设计 + 任务分解,不含实现代码。后续可转 TDD 任务(能力键三段式
<unit>.<domain>.<action>)。
| 维度 | 现状 |
|---|---|
| 配置 | 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 相互覆盖),登录/支付/虚拟支付全会串台。这是本方案的第一优先级问题。
| 维度 | ①纯 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 兜底 + 敏感项走环境变量引用)
理由:
${WECHAT_SECRET:...} 行为。miniapp_config 中 mp_code='default' 的一行由 yml wechat: 播种,未指定小程序标识的请求一律回落 default,完全保持现状。wechat.iwintrue.com 中间层并存:中间层配置不受影响,回调 URL 按小程序维度区分即可。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 行为不变。MiniAppContext.mpCode() 无值时,返回 default,加载 yml 播种的那行,行为与现状 100% 一致。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;不重启。| 缓存对象 | 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 触发。三种候选方案对比
| 方案 | 登录前可用 | 支付回调可用 | 改造成本 | 风险 |
|---|---|---|---|---|
①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 快照。
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 的重载。
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)。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,正确。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() |
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)。MiniAppConfigService 取凭据,密钥解密后只在内存短暂存在,不落日志。JwtInterceptor / Context 透传MiniAppInterceptor(在 JwtInterceptor 之前注册,WebConfig.addInterceptors 调序):
X-MP-Code Header / mpCode 参数 / URL path 变量(如 /v3-notify/{mpCode})解析;request.setAttribute("mpCode", code) 与 MiniAppContextHolder.set(...);JwtConfig.generateToken(userId, roles, mpCode) 增加 claim;JwtInterceptor.parseToken 后把 mpCode 补写到 request.setAttribute("mpCode", ...)(若 Header 未带则从 JWT 取,双兜底)。mpCode,前端写入 storage 并在后续请求带 Header(前端配合项)。miniapp_config 只存 env 引用名(secret_ref、mch_key_ref、api_v3_key_ref、appkey_ref、virtual_pay_token_ref),运行时从环境变量解析。MiniAppConfigService.resolveSecret 若 env 未设置,抛 IllegalStateException("密钥未配置: " + ref),绝不静默回落,避免用错 app 密钥。mpCode/appId,禁止打印 secret/mch-key/api-v3-key/token/session_key;建议加 Logback masking pattern 兜底。miniapp_config 表只读通过 MiniAppConfigService,不暴露写接口给业务侧;管理端写接口另起 AdminMiniAppConfigController(/api/admin-auth/** 鉴权),变更后调用 reload()。cert/{mpCode}/apiclient_key.pem,private_key_path 配置区分;不进 git(.gitignore 已有 cert/ 约定需复核)。xiao/huawei encrypt-key 同思路:如未来必须落库密钥,复用现有 AES-128 加密方案,密钥由环境变量注入;本期先采用 env 引用方案(更简单,无需密钥管理服务)。原则:默认 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/参数兜底兼容其存在。MiniAppConfigService.reload()(管理端触发)或等 5min 兜底刷新,无需重启。spring-boot-starter-web、mybatis-plus、spring-boot-starter-data-redis、okhttp(已在 PaymentService 使用)、jjwt、fastjson。能力键命名:
<unit>.<domain>.<action>,如wechat.multiapp.config.load、wechat.multiapp.context.resolve。
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 建表)wechat.multiapp.config.migrate、wechat.multiapp.config.seed-defaultminiapp_config 表存在;含 mp_code='default' 行,app_id 与现 yml 一致;MiniAppProperties.apps.default.appId 注入成功;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)wechat.multiapp.context.resolve、wechat.multiapp.context.fallback-default、wechat.multiapp.config.load、wechat.multiapp.config.secret-resolve、wechat.multiapp.token.isolateX-MP-Code: xiaoyi Header 的请求,MiniAppContextHolder.get().mpCode() == "xiaoyi";default;JwtInterceptor 能写入 attr;MiniAppConfigService.getByCode("default") 返回与 yml 一致的配置;resolveSecret 在 env 未设置时抛 IllegalStateException;MiniAppContextResolver 优先级链、MiniAppConfigService.reload、token 隔离。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)wechat.multiapp.user.appid-migrate、wechat.multiapp.user.openid-isolate、wechat.multiapp.order.appid-writeappid 列,存量行 appid=现 appid;order.appid 非空,与登录 appid 一致;uk_openid_appid(openid, appid) 生效(同 appid 内不重复)。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)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-codewechatService.code2Session(code, mpCode) 用各自 appid/secret;paymentService.createWechatPrepay(..., mpCode) 用该 app 的 mchId/serialNo/私钥签名;不同 mpCode 订单签名独立;v3-notify 在带 mpCode 路径时按该 app 解密;不带时通过 orderNo 反查订单 appid;virtual-pay/notify 在 URL 带 mpCode 时用对应 token 验签;不带时遍历 token 兜底;HealthExerciseController.decryptWeRunData 用当前请求 appid 校验 watermark;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、密钥环境变量清单、灰度开关)wechat.multiapp.admin.crud、wechat.multiapp.admin.reload、wechat.multiapp.e2e.login-pay-notifymp_code='xiaoyi' 行;新增后调 reload(),无需重启即可用 X-MP-Code: xiaoyi 登录;mpCode == null || "default".equals(mpCode) 一律走 default app,保持现状。Result<T>;错误码遵循现有 code/message/data。/api/auth/** 登录接口已在 PUBLIC_PATHS,但仍需 MiniAppInterceptor 解析 Header;/api/payment/wechat/v3-notify 与 /api/internal/virtual-pay/notify 走 WebConfig 排除鉴权,依赖回调 URL 的 mpCode 段 + 签名校验防伪造。AiGateway 并把 mpCode 作为上下文透传。@Async/taskExecutor)捕获 MiniAppContextHolder 快照传递,禁止跨线程裸读 ThreadLocal。DatabaseInitializer 追加迁移,必须同步 schema.sql(项目铁律)。CREATE TABLE IF NOT EXISTS / ensureColumn;数据播种用 INSERT IGNORE 或先 SELECT。mpCode/appId。graph TD
T01[T01 基础设施: 配置模型+yml兜底+迁移] --> T02[T02 上下文识别+配置服务+token隔离]
T01 --> T03[T03 数据维度: users/orders加appid+登录修复]
T02 --> T03
T02 --> T04[T04 三大核心服务+扩展消费者改造]
T03 --> T04
T04 --> T05[T05 管理端+热更+端到端联调]
wechat.iwintrue.com 中间层细节:当前 WechatWaitMsgService 调用的 etotem.webhook.wait-msg.url 是否需要按小程序区分?假定中间层会按 appid 路由消息,本方案通过回调 URL/Header 的 mpCode 兼容其存在;若中间层本身不分 appid,需要单独评估。users 表唯一索引:现 users.openid 无唯一索引(只是 INDEX idx_openid)。多小程序下不同 appid 可产生不同 openid;同 appid 内是否允许同 openid 多行?本方案假设不允许(同 appid 内 openid 唯一),需 DBA 复核存量是否有重复。handleWechatNotify 未校验 Wechatpay-Signature,本方案 P1 阶段补齐 per-appid 校验;如时间紧可暂保持 fail-open,但需在文档标记。wechat.multiapp.strict-mode: true,本方案未默认开启。