---
date: 2026-05-18
context: 平台改名 PR（FFOA → FF AI Workspace）品牌名 sweep
severity: medium
---

# 现象

第一轮 `grep -rn 'FFOA\|FFAI' frontend/src backend/src docs/standards` 找到 ~50 处用户面命中，全部改完。`/simplify` review 阶段又发现 **20+ 处用户可见漏 fix**，全部在 sweep 范围之外的"非源代码"表层：

- `scripts/backend/init/init-notification-templates.ts` —— 邮件主题 `【FFOA】` 和 footer `此邮件由 FFOA 系统自动发送`（**最严重**：员工 Outlook 直接看到旧品牌）
- `frontend/src/locales/dashboard/{zh,en}.ts:welcome` —— dashboard 欢迎语 `欢迎使用 FFWorkspace 系统`（用了过时的 shortName 字面值，没引用 `brand.brandName`）
- `scripts/{README.md, backend/README.md, dev/dev.ps1, dev/dev.bat, env/README.md}` —— 脚本 banner / 维护者署名（开发者 CLI 输出可见）
- `scripts/deploy/{deploy.sh, setup-production.sh}` —— 部署脚本 banner 输出 + 写入生产 `.env.production.template` 的 `APP_NAME=FFOA Platform`（**也严重**：生产环境 brand.appName 显示旧名）
- `frontend/src/app/globals*.css` 顶部注释 `FFOA Design System`
- `package-lock.json` 的 root `name` 字段（package.json 改了 lockfile 没同步）

# 根因

"用户面"远不止 `src/` 源代码。改名 sweep 第一轮通常只扫 frontend/src + backend/src + docs/standards，覆盖率 ~70%。剩下 30% 散落在：

1. **种子 / 模板代码**（`scripts/backend/init/*.ts`）—— 内容是字符串模板，最终落到生产数据库的 notification 表里，用户邮件直接读
2. **shell / PowerShell / .bat 脚本 banner**（`scripts/**`）—— `echo` / `Write-Host` 输出给运行脚本的开发者和运维
3. **deploy heredoc**（`scripts/deploy/*.sh` 的 `cat > .env.production << EOF`）—— 写入生产 env，最终 backend 读
4. **README 维护者署名 + 项目介绍段** —— 开发者文档 banner
5. **CSS 文件顶部注释** —— 内部，但顺手清
6. **lockfile** —— npm `name` 字段跟 `package.json` 同步

# 解决（本次 PR 应用）

1. 先正常做第一轮 sweep（frontend/src + backend/src + docs/standards）
2. **跑 `/simplify`** —— 它的 sweep agent 会扫 scripts/ + README + deploy + 模板代码，列出第二轮漏点
3. 按 simplify finding 批量 fix
4. 最后一次 `grep -rn` 验证只剩"按规则保留"的技术标识符（env 变量名、容器前缀、Gitea org/repo、URL hostname、User-Agent header、数据库用户名 / 队列名 / bucket 名、文件路径、npm 包名）

# 推荐工程化保险

未来类似的"全局文本替换" PR 建议增加 sweep checklist（写到 `.agents/skills/contract-check` 或新 skill）：

```
改名/品牌/文本替换 PR sweep 范围（在 frontend/src + backend/src 之外）：
□ scripts/backend/init/*.ts      （种子模板 → 生产数据 → 用户邮件）
□ scripts/deploy/*.sh             （deploy heredoc → 生产 .env → 后端读）
□ scripts/{README.md, backend/README.md, env/README.md}  （文档署名）
□ scripts/dev/dev.{ps1,bat,sh}    （CLI banner）
□ frontend/src/app/globals*.css   （CSS 顶部注释）
□ package-lock.json               （npm name 字段）
□ frontend/src/locales/**/*.ts    （所有 i18n 文件，不只 auth / agent）
```

通用规则：**任何会被 `echo` / 邮件渲染 / 写入生产 env / 显示给运维的字符串都算"用户面"**，不限于 React/Vue 组件里的 JSX 文本。