docs(M08-D): 回填广告与装修运营

2026-08-10 12:59:22 +08:00
parent c1c02421a1
commit e0e17159a7
6 changed files with 54 additions and 7 deletions
@@ -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`。
- 最近工程提交：`c7f27bc` / `M08-D多小程序与租户配置`，Vue 后台已接入应用绑定、启停、默认应用、品牌/主题/分享/默认门店配置，并按平台/租户权限分层。
- 下一工程目标：继续 M08-D，补后台广告与装修管理页面。
+- 最近工程提交：`c1c0242` / `M08-D广告与装修管理`，Vue 后台已接入媒体素材、装修版本与广告投放闭环，并补齐门店素材隔离、广告更新和素材作用域去重迁移。
+- 下一工程目标：继续 M08-D，补加盟申请与跟进运营页面。

 ## 版本递进

@@ -62,3 +62,14 @@
 | POST | `/admin-api/platform-apps/bind` | 仅 `platform.manage`/平台管理员可新增逻辑应用或当前租户绑定。 |

 所有 schema 均不接受或返回 AppSecret、支付密钥和证书。
+
+## 广告与装修管理增量
+
+| 方法 | 路径 | 权限与变更 |
+|---|---|---|
+| GET/POST | `/admin-api/media/images` | 新增素材安全列表；上传继续校验图片并压缩，门店运营必须指定授权门店，只有租户/平台管理员可创建租户公共素材。 |
+| GET/POST | `/admin-api/decorations` | 新增指定门店的装修版本列表；创建继续生成不可变草稿版本并校验组件白名单。 |
+| POST | `/admin-api/decorations/:id/publish` | 发布指定门店版本并自动归档上一发布版，支持历史版本重新发布。 |
+| GET/POST/PUT | `/admin-api/advertisements[/:id]` | 新增广告更新；写入同时校验原广告范围、目标范围和图片素材范围，门店管理员只能维护授权门店广告。 |
+
+响应新增广告 `imageAssetId`，用于无损编辑既有记录；素材和装修列表上限分别为 200/100 条，均按租户和授权门店裁剪。
@@ -0,0 +1,8 @@
+# 2026-08-10 M08-D 素材作用域去重
+
+- 版本：`2026081002_m08d_content_asset_scope`
+- up：新增生成列 `scope_store_id = IFNULL(store_id, 0)`，把素材唯一键改为 `(tenant_id, scope_store_id, checksum_sha256)`。
+- 结果：同一租户的公共素材和各门店可独立保存相同图片；同一公共/门店作用域内仍按 checksum 幂等复用。
+- down：先将广告图片引用归并到同租户 checksum 的最小资产 ID，删除重复资产，再恢复历史租户级唯一键。
+- verify：检查生成列表达式、唯一键列顺序和迁移版本。
+- WSL MySQL 8.4.10 已完成 138 up、117 verify、134 down 的 `up → verify → down → up → verify` 往返。
@@ -206,3 +206,28 @@ M08-D 保持 `DOING`。设备运营增量完成；下一工程增量补多小程
 ### 状态

 M08-D 保持 `DOING`。多小程序与租户配置增量完成；下一工程增量补广告与装修管理页面。
+
+## 2026-08-10 广告与装修管理
+
+- `ENGINEERING_DELTA=YES`
+- 新增媒体素材、门店装修和广告投放三工作区；支持图片上传/预览、公共/门店范围、组件化装修草稿、版本回看、发布/历史回滚，以及广告新增、编辑、排期、排序和上下架。
+- 新增素材与装修列表、广告更新 API；门店运营不能创建租户公共素材，不能编辑租户/平台或其他门店广告，门店广告只能引用租户公共或当前门店素材。
+- 新增 `2026081002_m08d_content_asset_scope`，以生成列把素材唯一键从租户级修正为租户 + 公共/门店作用域 + checksum；同作用域继续去重，不同门店不再错误复用资产。
+
+### 测试证据
+
+- Windows `scripts/dev/windows/test-all.ps1`：89.7 秒退出码 0；后端全测、M08-D 静态门禁、Vue TypeScript/生产构建、仓库完整性与密钥扫描通过。
+- WSL 原生临时副本 + MySQL 8.4.10：23.5 秒退出码 0；`up → verify → down → up → verify` 完成，138 条 up、117 条 verify、134 条 down。
+- MySQL 实测同门店同 checksum 幂等去重、同 checksum 公共/门店素材独立、装修列表/发布归档、广告更新和素材 ID 回读。
+- 既有 Element Plus 大 chunk、参考 xjar 超过 100MB 和 WSL npm audit 提示保持非阻塞，未执行破坏性自动升级。
+
+### 变更影响
+
+- 数据库：新增可逆素材作用域唯一键迁移；down 先把广告引用归并到保留资产，再恢复历史租户级唯一键。
+- API：新增素材/装修读取和广告更新，广告列表补 `imageAssetId`。
+- 后台：新增响应式广告装修入口；部署包含后端、后台静态产物和迁移变化，未自动部署生产。
+- 工程提交：`c1c0242`，已推送并验证 `HEAD == origin/main`。
+
+### 状态
+
+M08-D 保持 `DOING`。广告与装修管理增量完成；下一工程增量补加盟申请、分派和跟进运营。
@@ -30,6 +30,8 @@

 > 2026-08-10 M08-D 增量：工程提交 `c7f27bc` 为 `BKG-010`、`CFG-001` 建立 Vue 后台多小程序/租户配置工作区；租户管理员仅可维护本租户已有绑定，新增逻辑应用或绑定要求平台管理权限，默认门店强制同租户，品牌/主题/分享/扩展配置写入审计，AppSecret、支付密钥和证书不进入 API。Windows 全量、Vue 生产构建与 WSL MySQL 8.4.10 往返通过，M08-D 继续广告与装修管理。

+> 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 继续加盟申请与跟进运营。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
@@ -59,8 +61,9 @@
 | TEN-001 | 多门店支持 | M02/M03 | PARTIAL | `15139b3` | 门店 CRUD 与门店管理员数据范围已实现；跨门店写操作在 Windows 和 WSL MySQL 实测被拒绝。 | 地图选店、前端切换与完整订单数据范围待后续阶段。 | M03-C 接入地图选店，M04 起业务资源继承门店范围。 |
 | STORE-001 | 门店运营配置 | M03-A/M08 | PARTIAL | `1ca783e` | 已实现地址、经纬度、营业状态、每周营业时间、时区、客服电话、Wi-Fi、通知地址和排序；Vue 后台支持授权范围内门店筛选、详情、新增、编辑和归档，列表只返回 Wi-Fi 是否已配置，编辑留空不会清除原密码。 | 通宵场、延时关灯和清洁策略仍需与订单/设备联动补齐。 | M08-D 后续页面继续复用门店选择；M10 做生产配置验收。 |
 | ROOM-001 | 房间配置 | M03-A/M04/M08 | PARTIAL | `1ca783e` | 已实现房型、整数分价格、工作日/节假日/通宵/全天价、最低消费、押金、最低时长、提前规则、禁用时段、标签、图片和软删除；Vue 后台支持筛选、新增、完整编辑、配置启停、运营房态、停用时段和归档。 | 节假日日历与真实运营价格复算仍需生产验收。 | M08-D 订单页复用房间信息；M10 做生产数据验收。 |
-| ADV-001 | 广告管理 | M03-B/M08 | PARTIAL | `f746242` | 已实现平台、租户、门店三级广告，素材租户归属、投放时间、跳转、排序和范围权限均由后端校验。 | 后台编辑页面和小程序展示待 M08。 | M08 接入广告管理和前端投放。 |
-| UI-001 | 门店装修和多套模板 | M03-B/M08 | PARTIAL | `f746242` | 已实现装修草稿版本、Schema 版本、组件白名单、发布和旧版本归档。 | 可视化编辑器及小程序模板渲染待 M08。 | M08 实现编辑器与渲染组件。 |
+| ADV-001 | 广告管理 | M03-B/M08 | PARTIAL | `c1c0242` | 已实现平台、租户、门店三级广告，素材归属、投放时间、跳转、排序和范围权限均由后端校验；Vue 后台可新增、编辑、排期、排序、上下架并预览图片，门店广告只能引用公共或本店素材。 | 小程序有效期投放展示和加盟广告落地页待继续。 | M08-A/M08-D 接入小程序投放与加盟内容。 |
+| BKG-001 | 后台广告管理 | M08 | PARTIAL | `c1c0242` | Vue 后台已提供素材上传/预览、平台/租户/门店广告新增编辑、投放排期、排序和状态管理；门店运营不能创建租户公共素材或越权修改广告。 | 小程序实际展示与真实运营素材验收待补。 | 接入小程序有效广告读取与页面渲染。 |
+| UI-001 | 门店装修和多套模板 | M03-B/M08 | PARTIAL | `c1c0242` | 已实现装修草稿版本、Schema 版本、组件白名单、发布和旧版本归档；Vue 后台可按门店创建组件化草稿、回看 JSON 和发布/回滚历史版本。 | 尚缺拖拽式可视化预览及小程序模板渲染。 | M08-A/M08-D 接入装修读取和组件渲染。 |
 | MAP-001 | 地图选店和最近门店 | M03-C/M08 | PARTIAL | `4ac2c96` | 已实现 AppID/tenant 隔离门店发现、城市/营业筛选、按门店时区判断营业中、后端 Haversine 距离排序；小程序支持定位和手工城市降级，并可从门店卡片进入公开门店详情与房间列表。 | 地图 SDK 可视化和真机定位授权尚未验收。 | M08-A 继续补真机定位、地图展示和门店装修渲染。 |
 | QR-001 | 门店/房间场景码与 NFC | M03-D/M08 | PARTIAL | `d563078` | 已实现场景码生成、重建失效、撤销、扫码统计和二维码/NFC 统一页面解析；返回权限固定为空，旧码失效已在 MySQL 8.4.9 实测。 | 真实微信小程序码图片生成依赖可用 AppSecret 与真机环境。 | M08 接入微信小程序码接口并完成真机扫描验收。 |
 | WIFI-001 | 受控 Wi-Fi 凭据 | M03-D/M04/M08 | PARTIAL | `4ac2c96` | 正式订单与分享令牌均执行最小权限；M08-A 门店详情新增登录后受控 Wi-Fi 请求入口，不在未鉴权页面暴露密码。 | 真实到店权限、真机 Wi-Fi 连接和设备权限仍需现场联调。 | M08-A 补有效订单下的 Wi-Fi 真机连接验证。 |
@@ -7,11 +7,11 @@ execution_cursor:
  stage_status: DOING
  last_completed_stage: M08-C
  next_stage: M08-D
-  last_engineering_commit: `c7f27bc`
+  last_engineering_commit: `c1c0242`
  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:38:03+08:00
+  updated_at: 2026-08-10T12:58:06+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 | `c7f27bc` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览及门店、订单、资金、渠道、用户、保洁、设备和多应用租户配置；平台/租户权限分层且不读写 AppSecret，继续广告与装修管理。 |
+| M08 微信原生小程序完整业务 | PARTIAL | `c1c0242` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览及门店、订单、资金、渠道、用户、保洁、设备、多应用租户、媒体素材、装修版本和广告投放工作区；继续加盟申请与跟进运营。 |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |