lislgosms/docs/admin-prototype-recovery-scope.md

运营端企业配置原型恢复范围

背景

本次排查定位到页面与原型出现明显差异的关键提交为：

• 提交：131f344ac4da5e3b610e4fd32596d4546a1cf9de
• 时间：2026-07-02 19:30:04 +0800
• 标题：fix: connect remaining sms pages to real backend

该提交的目标是把剩余短信页面从 mock/localStorage 接到真实后端，但执行方式把部分原型页面重写为最小真实 API 表格/表单，导致原型字段、弹窗、Tab、引流信息和新增/编辑动作大量丢失。

后续修复原则：

1. 以 131f344a^ 中的原型页面结构和字段命名为视觉与交互基准。
2. 保留当前真实 API 接入方向，不回退到 mock/localStorage/static 数组。
3. 前端缺入口时恢复入口；后端缺字段或接口时补 NestJS API 与 Prisma 模型/服务。
4. 彩信能力仍按第一版待开发边界处理；短信能力不得用彩信待开发作为阻塞理由。

差异清单

企业管理：列表、新增、编辑、详情

相关文件：

• src/apps/admin/AdminCustomersPage.tsx
• src/apps/admin/AdminCustomerFormPage.tsx
• src/apps/admin/AdminCustomerDetailPage.tsx
• api/src/tenants/tenants.service.ts

状态：阶段 4-1 已修复。

原型能力：

• 企业照片上传占位。
• 统一社会信用代码。
• 省/直辖市、市/区。
• 通讯地址。
• 联系人姓名。
• 联系人身份证号。
• 联系人手机号。
• 企业主体、证照、地址、联系人分区。
• 本地原型通过 adminEnterpriseMock 保存完整企业档案。

当前实现：

• 表单只保留 企业名称、企业编码、企业状态。
• 保存只写 Tenant.name、Tenant.code、Tenant.status。
• 企业档案、证照、地址和联系人信息没有真实保存入口。
• 删除是软删除 status=deleted，但不存在或过期 ID 会由 Prisma update 抛 500。

需要恢复/补齐：

• 已恢复企业表单的主体、证照地址、联系人区块和主要字段。
• 已复用 EnterpriseCertification 保存真实企业档案，并在租户接口返回 enterpriseProfile。
• 已修复企业删除/更新/状态变更的不存在 ID 处理，返回 404，不再由 Prisma update 抛 500。
• 已在企业列表和详情展示真实企业档案字段。

企业应用管理

相关文件：

• src/apps/admin/AdminEnterpriseApplicationsPage.tsx
• src/apps/admin/AdminSmsApplicationFormPage.tsx
• src/api/adminApi.ts
• api/src/sms-config/admin-sms-config.controller.ts
• api/src/sms-config/client-sms-config.controller.ts
• api/src/sms-config/sms-config.service.ts

状态：阶段 4-2 已修复短信应用新增/编辑闭环；彩信仍为待开发边界。

原型/预期能力：

• 运营端企业应用页可新增、编辑、启用/停用、删除应用。
• 新增/编辑必须作用于真实企业。
• 短信应用保存时可配置移动、联通、电信通道组。
• 彩信应用 Tab 是待开发边界，不计入短信验收。

当前实现：

• 短信应用列表接了真实 GET /api/admin/enterprise-applications。
• 新增时先选择真实企业，再进入 /admin/customers/{tenantId}/sms-apps/new。
• 编辑入口使用应用自身 tenantId，不再硬编码企业 ID。
• 运营端已补 GET/POST/PUT /api/admin/enterprise-applications。
• 编辑表单会加载真实应用详情和已有三网路由规则。
• 保存时调用 PUT /api/admin/enterprise-applications/{id}/route-rules 事务替换应用级运营商通道组绑定。
• 彩信 Tab 只显示待开发空态，不再渲染 initialMmsApps 演示数组。

需要恢复/补齐：

• 已删除企业应用页硬编码企业 ID。
• 已实现企业应用页新增选择真实企业。
• 已补运营端应用创建/编辑 API。
• 已实现编辑页加载真实应用详情并可保存。
• 已强制短信应用保存时至少配置一个运营商通道组。
• 已校验应用路由 carrier 与通道组 carrier 一致。
• 彩信 Tab 标记为待开发，不得作为短信功能验收项。

企业签名与引流信息

相关文件：

• src/apps/admin/AdminEnterpriseSignaturesPage.tsx
• src/api/adminApi.ts
• api/src/sms-config/admin-sms-config.controller.ts
• api/src/sms-config/client-sms-config.controller.ts
• api/src/sms-config/sms-config.service.ts
• api/prisma/schema.prisma

状态：阶段 4-3 已修复短信签名和引流信息新增/编辑/删除闭环；彩信签名仍为待开发边界。

原型能力：

• 短信/彩信签名 Tab。
• 添加签名、编辑签名、删除签名。
• 资质凭证、法人身份证、责任人身份证上传占位。
• 三网报备状态：移动、联通、电信。
• 签名报备详情。
• 引流信息列表。
• 添加/编辑/删除引流链接。
• 引流信息报备详情。

当前实现：

• 运营端签名页恢复短信/彩信 Tab，其中彩信签名显示待开发空态，不展示演示数据。
• 短信签名列表使用真实 GET /api/admin/enterprise-signatures，返回企业、应用、材料和 drainageInfo。
• 已补运营端 POST /api/admin/enterprise-signatures、PUT /api/admin/enterprise-signatures/{id}。
• 添加/编辑签名可选择真实企业和应用；签名名称必须填写完整中文黑括号格式 【签名】，后端以相同格式校验和保存，所有页面只展示一层括号。三网报备状态保存到 SmsSignature.drainageInfo.carrierStatus。
• 引流信息列表、添加、编辑、删除保存到 SmsSignature.drainageInfo.links。
• 删除签名调用真实状态变更接口写 auditStatus=deleted，列表默认排除 deleted。

需要恢复/补齐：

• 已恢复短信签名的卡片列表、报备详情和引流信息区块。
• 已补运营端代企业新增/编辑签名 API。
• 已提供企业选择、应用选择、用途和三网状态真实保存。
• 已将引流信息真实保存到 drainageInfo，不再使用本地数组。
• 彩信签名能力继续标记待开发。

企业模板

相关文件：

• src/apps/admin/AdminEnterpriseTemplatesPage.tsx
• src/api/adminApi.ts
• api/src/sms-config/admin-sms-config.controller.ts
• api/src/sms-config/client-sms-config.controller.ts
• api/src/sms-config/sms-config.service.ts
• api/prisma/schema.prisma

状态：阶段 4-4 已修复短信模板新增/编辑/删除和变量真实保存闭环；彩信模板仍为待开发边界。

原型能力：

• 短信/彩信模板 Tab。
• 添加模板、编辑模板、删除模板。
• 应用选择。
• 签名选择。
• 模板内容编辑。
• 推荐变量与自定义变量。
• 自动提取变量。
• 字数与计费条数提示。
• 彩信模板多帧编辑和预览。

当前实现：

• 运营端模板页恢复短信/彩信 Tab，其中彩信模板显示待开发空态，不展示演示数据。
• 短信模板列表使用真实 GET /api/admin/enterprise-templates，返回企业、应用、签名和变量。
• 已补运营端 POST /api/admin/enterprise-templates、PUT /api/admin/enterprise-templates/{id}。
• 添加/编辑模板可选择真实企业、应用、签名，模板内容和分类写入真实 SmsTemplate。
• 变量从 ${name} 语法自动提取，也支持推荐变量和自定义变量插入，保存时写入真实 TemplateVariable。
• 编辑模板时后端事务删除旧变量并重建新变量。
• 删除模板调用真实状态变更接口写 auditStatus=deleted，列表默认排除 deleted。

需要恢复/补齐：

• 已恢复短信模板新增/编辑弹窗和变量交互。
• 已补运营端代企业新增/编辑模板 API。
• 应用和签名下拉来自真实 API，并按企业过滤。
• 变量已写入真实 TemplateVariable，不能只在前端展示。
• 彩信模板能力继续标记待开发。

后续执行顺序

1. 修企业删除接口健壮性。
2. 恢复企业管理原型表单，并补真实企业档案保存。
3. 修企业应用新增/编辑，移除硬编码 2763。（阶段 4-2 已完成）
4. 恢复企业签名与引流信息，并补真实保存接口。（阶段 4-3 已完成）
5. 恢复企业模板新增/编辑，并补变量真实保存。（阶段 4-4 已完成）
6. 补 API 单测和真实环境 smoke。
7. 跑 npm --prefix api test、npm --prefix api run build、npm run build。

验收口径

页面验收时需要同时满足：

• 页面结构、字段、按钮和弹窗接近 131f344a^ 的原型。
• 所有非彩信短信能力调用真实 API。
• 清空业务数据后，页面应为空态或可从 0 创建数据，不出现原型残留记录。
• 不存在硬编码企业 ID、initial* 短信业务数组、mock/localStorage 业务兜底。
• API 失败时展示错误态，不静默回退到假数据。