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

## 背景

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

- 提交：`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 失败时展示错误态，不静默回退到假数据。