docs(M08-D): 回填加盟申请与跟进运营

README.md

@@ -121,8 +121,8 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running
 项目已开发部分模块。具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。
 
 - 当前执行游标：`M08-D`（DOING）；`M08-C` 的可独立工程内容已完成，真实团购商家授权、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。
-- 最近工程提交：`c1c0242` / `M08-D广告与装修管理`，Vue 后台已接入媒体素材、装修版本与广告投放闭环，并补齐门店素材隔离、广告更新和素材作用域去重迁移。
+- 最近工程提交：`aa4a6bd` / `M08-D加盟申请与跟进运营`，小程序可幂等提交加盟意向，Vue 后台可筛选、分派、跟进和受控流转，完整历史与审计按租户隔离。
-- 下一工程目标：继续 M08-D，补加盟申请与跟进运营页面。
+- 下一工程目标：继续 M08-D，补审计日志与系统配置运营页面。
 
 ## 版本递进
 

docs/api-changelog/2026-08-10-M08-D-admin-overview.md

@@ -73,3 +73,15 @@
 | GET/POST/PUT | `/admin-api/advertisements[/:id]` | 新增广告更新；写入同时校验原广告范围、目标范围和图片素材范围，门店管理员只能维护授权门店广告。 |
 
 响应新增广告 `imageAssetId`，用于无损编辑既有记录；素材和装修列表上限分别为 200/100 条，均按租户和授权门店裁剪。
+
+## 加盟申请与跟进运营增量
+
+| 方法 | 路径 | 权限与变更 |
+|---|---|---|
+| POST | `/app-api/franchise-applications` | 按 `x-wechat-appid`/可选 `tenant-id` 解析有效租户，支持匿名或当前租户登录用户提交，`clientRequestId` 幂等。 |
+| GET | `/admin-api/franchise-applications` | `tenant.manage` 或平台管理权限；支持状态、负责人、关键字和分页，平台跨租户必须显式请求 tenantId。 |
+| GET | `/admin-api/franchise-applications/:id` | 返回申请详情与实际操作人跟进历史，严格按目标租户读取。 |
+| PATCH | `/admin-api/franchise-applications/:id/assignee` | 负责人必须是线索所属租户的有效 STAFF 用户；支持取消分派。 |
+| POST | `/admin-api/franchise-applications/:id/follow-ups` | 新增电话、微信、面谈或备注记录，更新下次跟进时间，并执行 `NEW → CONTACTED → QUALIFIED → CONVERTED/REJECTED` 受控流转。 |
+
+联系电话只进入受权限保护的业务表和响应，不写入审计 metadata；`CONVERTED` 表示已签约待开通，不创建租户，真实开通编排留在 M10-C。

docs/db-changelog/2026-08-10-M08-D-franchise-leads.md

@@ -0,0 +1,8 @@
+# 2026-08-10 M08-D 加盟申请与跟进记录
+
+- 版本：`2026081003_m08d_franchise_leads`
+- 新增 `qipai_franchise_applications`：租户、申请编号、幂等号、城市、联系人、电话、留言、来源、状态、负责人、提交用户和下次跟进时间。
+- 新增 `qipai_franchise_follow_ups`：申请、实际操作人、跟进类型、前后状态、备注和下次跟进时间。
+- 唯一键：租户 + 申请编号、租户 + clientRequestId；队列索引覆盖租户、状态、负责人和创建时间。
+- down：先删除跟进表，再删除申请表和迁移记录。
+- WSL MySQL 8.4.10 已完成 141 up、120 verify、137 down 的完整往返。

docs/devlogs/2026-08-10-M08-D-Vue平台后台.md

@@ -231,3 +231,29 @@ M08-D 保持 `DOING`。多小程序与租户配置增量完成；下一工程增
 ### 状态
 
 M08-D 保持 `DOING`。广告与装修管理增量完成；下一工程增量补加盟申请、分派和跟进运营。
+
+## 2026-08-10 加盟申请与跟进运营
+
+- `ENGINEERING_DELTA=YES`
+- 小程序首页新增加盟入口和申请页，按品牌 AppID 对应租户提交城市、联系人、电话、留言和客户端幂等号；重复提交返回原申请编号。
+- Vue 后台新增加盟队列，支持关键字/状态/负责人筛选、分页、详情、同租户有效员工分派、下次跟进、电话/微信/面谈/备注记录和完整历史。
+- 后端新增公开提交与管理员读取/分派/跟进 API；租户管理员跨租户请求拒绝，平台管理员跨租户必须显式指定 tenantId，状态跳级在事务内拒绝。
+- 新增 `2026081003_m08d_franchise_leads` 两表迁移；业务联系电话不进入审计 metadata，签约状态不冒充真实租户开通。
+
+### 测试证据
+
+- Windows `scripts/dev/windows/test-all.ps1`：66.3 秒退出码 0；后端全测、加盟路由、M08-A/B/C/D 静态门禁、Vue 生产构建与仓库门禁通过。
+- WSL 原生临时副本 + MySQL 8.4.10：23.7 秒退出码 0；141 条 up、120 条 verify、137 条 down 完成 `up → verify → down → up → verify`。
+- MySQL 实测重复申请幂等、有效员工分派、无效负责人拒绝、首次联系流转、非法跳级回滚、跟进历史和审计不含联系电话。
+- 既有 Element Plus 大 chunk、参考 xjar 超过 100MB 和 npm audit 提示保持非阻塞。
+
+### 变更影响
+
+- 数据库：新增加盟申请与跟进历史表及可逆迁移。
+- API：新增 1 个小程序提交、2 个后台读取和 2 个后台写接口。
+- 小程序/后台：新增加盟申请页与响应式加盟运营工作区；未自动部署生产。
+- 工程提交：`aa4a6bd`，已推送并验证 `HEAD == origin/main`。
+
+### 状态
+
+M08-D 保持 `DOING`。加盟申请与跟进运营完成；下一工程增量补审计日志与系统配置。

docs/feature-status.md

@@ -32,6 +32,8 @@
 
 > 2026-08-10 M08-D 增量：工程提交 `c1c0242` 为 `ADV-001`、`UI-001`、`BKG-001` 建立 Vue 后台媒体素材、装修版本与广告投放工作区；新增安全列表和广告更新 API，门店运营不能上传租户公共素材或编辑其他范围广告，广告图片仅可引用租户公共或当前门店素材。`2026081002` 将素材去重键修正为租户、作用域和 checksum，Windows 全量与 WSL MySQL 8.4.10 的 138 up、117 verify、134 down 往返通过，M08-D 继续加盟申请与跟进运营。
 
+> 2026-08-10 M08-D 增量：工程提交 `aa4a6bd` 为 `BKG-008`、`FRN-001` 建立小程序加盟申请和 Vue 后台跟进队列；申请按 AppID/tenant 解析、clientRequestId 幂等，后台支持状态/负责人/关键字筛选、详情、同租户有效员工分派、下次跟进和受控状态机，跟进人与审计完整且联系电话不进入审计元数据。Windows 全量与 WSL MySQL 8.4.10 的 141 up、120 verify、137 down 往返通过，M08-D 继续审计日志与系统配置。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
@@ -78,7 +80,8 @@
 | GRP-003 | 管理员验券 | M05-C/M08 | PARTIAL | `7b97808` | 已提供管理员小程序与 Vue 后台扫码/手输券码、在线核销、显式人工确认、待支付订单选择和脱敏核销记录；金额由服务端订单未付金额推导，写权限叠加授权门店，记录保留操作人/门店/平台结果，券码仅存 SHA-256 和掩码；后台凭据只接受环境引用，敏感设置键不从读取接口返回。 | 缺美团/抖音/快手真实商家 API 授权，未执行厂商真实核销。 | 取得授权后配置 API 模式并执行真实验券。 |
 | ADM-001 | 管理员小程序模式 | M08/M06 | PARTIAL | `ce52f07` | 已完成角色入口、授权门店概况/房态、订单处置与代下单、会员/员工概况、保洁验收、设备状态、临时开门/电控、管理员验券和门店经营统计；按钮按 capability 展示，服务端重复校验租户、门店与写权限，关键写操作保留实际操作人审计。 | 真实团购商家、微信和硬件现场验收条件未提供。 | M08-D 继续平台后台；具备外部条件后补真机与现场验收。 |
 | REP-001 | 数据统计报表 | M10/M08 | PARTIAL | `65f2e7c` | 门店 7/30/90 日经营统计已同时接入管理员小程序与 Vue 后台，返回订单总量/状态/预订额、OWNER 下单会员、成功支付实收与渠道、每日收入、当前房态、验券成功/失败；最长查询 93 天，租户与门店范围由服务端校验，后台支持授权门店切换、趋势条和明确口径提示，MySQL 实测 `GROUP_BUY` 渠道与成功支付口径。 | 尚缺全门店汇总、自定义导出、使用率/使用时长和生产数据复算验收。 | M08-D/M10 扩展平台统计、导出和指标口径文档。 |
-| FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `4eac99d` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；Vue 后台已接入账户、接收方、策略、记录和执行入口，未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | 取得权限后执行真实分账与对账；M10 补完整加盟流程。 |
+| FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `aa4a6bd` | 已实现加盟意向幂等提交、租户隔离跟进、负责人分派、受控状态流转，以及收款账户、环境凭据引用、分账授权、脱敏接收方、比例校验、幂等分账和明细查询；Vue 后台覆盖线索与资金运营。 | 真实租户开通、门店创建、微信服务商分账权限和生产对账仍属于 M10-C/外部联调。 | M10-C 接入签约后的租户开通编排；取得权限后执行真实分账。 |
+| BKG-008 | 后台加盟信息管理 | M08/M10 | PARTIAL | `aa4a6bd` | 小程序可提交城市、联系人、电话和留言；后台支持分页筛选、详情、同租户员工分派、电话/微信/面谈/备注跟进、下次跟进、状态机和完整操作历史。 | 尚缺签约后的租户开通编排、附件与生产隐私合规验收。 | M10-C 衔接租户/门店/支付配置开通流程。 |
 | BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `4eac99d` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；Vue 后台支持环境引用配置、授权状态、脱敏接收方、比例策略、分账记录、微信退款、对账单请求和分账执行；私钥/APIv3 Key 不读取或回显。M08-B 保洁转账预检仍提供商户资料与转账前阻断。 | 真实商户与服务商授权、微信后台场景报备和生产小额退款/分账仍需现场联调。 | 授权后完成生产退款、对账与分账验收。 |
 | DEV-003 | 设备管理 | M06-B/M08 | PARTIAL | `5c9fd69` | 已实现并在管理员小程序/Vue 后台展示 DeviceID、IMEI/ICCID、型号、固件、信号、能力、状态快照、控制通道、Sub-1G 父子拓扑、开放告警和维护记录；后台可按授权门店入库、绑定、维护并下发门锁/控电/插座命令。 | 真实硬件在线、ACK、计量和保护断电仍需 M06-G 实物更新。 | 取得实物和生产 MQTT 条件后执行硬件矩阵并回填命令 ACK 证据。 |
 | BKG-004 | 后台设备管理 | M06-B/M08 | PARTIAL | `5c9fd69` | Vue 后台已接入设备入库、列表、拓扑、通道绑定、Sub-1G 绑定、告警、维护和现场控制；同一房间控制目标唯一，危险命令二次确认，并明确“发布不等于 ACK”。 | 真实设备扫码输入和现场结果未验证。 | M06-G/M10 以真实控制箱、门锁和插座完成扫码入库与控制验收。 |

docs/module-status.md

@@ -7,11 +7,11 @@ execution_cursor:
   stage_status: DOING
   last_completed_stage: M08-C
   next_stage: M08-D
-  last_engineering_commit: `c1c0242`
+  last_engineering_commit: `aa4a6bd`
   last_push_verified: true
   base_branch: main
   blocked_reason: "M08-A 真机合法域名、真实微信支付和实物开门验证缺微信后台/商户/硬件现场条件；M08-B 可独立工程内容已完成，真实商户凭据、微信后台配置、生产小额转账和实物硬件结果保持 BLOCKED_EXTERNAL；M08-C 可独立工程内容已完成，真实美团/抖音/快手商家授权与真机验券保持 BLOCKED_EXTERNAL，已按规则旁路进入 M08-D。M06-G 真实硬件联调仍缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线。"
-  updated_at: 2026-08-10T12:58:06+08:00
+  updated_at: 2026-08-10T13:17:35+08:00
 ```
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -24,7 +24,7 @@ execution_cursor:
 | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 |
 | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `d01f771` | docs/devlogs/2026-06-24-M06-G-真实硬件联调.md | M06-A 至 F 已完成 MQTT、拓扑、协议幂等、控制箱、Sub-1G 门锁、智慧插座和订单自动联动任务；M06-G 已补真实硬件烟测运行器，缺生产 MQTT 账号/ACL、DeviceID 和实物配线，保持 BLOCKED_EXTERNAL。 |
 | M07 会员、余额、充值、优惠券和套餐营销 | DONE | `ed0d455` | docs/devlogs/2026-06-24-M07-D-会员管理.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；M07-D 已完成会员画像、订单、消费、余额、充值、优惠券和套餐聚合查询。 |
-| M08 微信原生小程序完整业务 | PARTIAL | `c1c0242` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览及门店、订单、资金、渠道、用户、保洁、设备、多应用租户、媒体素材、装修版本和广告投放工作区；继续加盟申请与跟进运营。 |
+| M08 微信原生小程序完整业务 | PARTIAL | `aa4a6bd` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览及门店、订单、资金、渠道、用户、保洁、设备、多应用租户、媒体装修广告和加盟跟进工作区；继续审计日志与系统配置。 |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |