WPS 完全移除·两阶段计划 / Complete WPS removal · two-phase plan

[zeweihan]

WPS 完全移除 · 两阶段计划 / Complete WPS removal · two-phase plan

自 #13 确立 LibreOffice 迁移方向以来，v0.3.0/v0.3.1 已交付完整的内置 LibreOffice 编辑器（自建 zh-CN 引擎、真实文档加载、保存回后端、AI 拟人式动作原语、离线可用）。WPS WebOffice 自 v0.2.3 起仅是 UI 隐藏、代码全在。维护者定调：完全移除 WPS。

Since #13 set the LibreOffice migration direction, v0.3.0/v0.3.1 delivered the full embedded LibreOffice editor (self-built zh-CN engine, real document loading, save-to-backend, humanlike AI action primitives, offline). WPS WebOffice has been UI-hidden-only since v0.2.3 — all code remains. Maintainer's decision: remove WPS entirely.

全仓 grep -ril wps 盘点后按「WPS 专属 / 共享引用」分为两阶段。
Full-repo grep -ril wps inventory, split into two phases: "WPS-exclusive" vs "shared references".

---

第一阶段（本切片，与 v0.3.1 并行开发零重叠）/ Phase 1 (this slice, zero overlap with the parallel v0.3.1 work)

删除 WPS 专属、且无任何存活调用链的代码。
Remove WPS-exclusive code with no live call chain.

后端 / Backend

文件 / File	说明 / Notes
controller/WpsApiController.java	WPS 编辑链接/会话 token API。前端 api.js 对应函数 generateWpsEditUrl/getWpsCallbackBaseUrl 已无任何调用者，删除不断链 / WPS edit-URL & session-token API; the matching api.js functions have no callers left
controller/WpsController.java	WPS WebOffice /v3/3rd 回调协议实现（729 行）/ WPS WebOffice /v3/3rd callback protocol (729 lines)
controller/WpsPublicController.java	/api/wps/config 公开配置 / public config endpoint
service/WpsService.java	WPS 签名/配置服务，仅被上述三个控制器使用 / WPS signing/config service, only used by the 3 controllers above
AdminConfigController.java	删 WPS 配置项（KEY_WPS_*、@Value 默认值、WpsConfig DTO）；OCR publicBaseUrl 原回退到 WPS callbackBaseUrl，改为独立配置 / drop WPS config keys & DTO; OCR publicBaseUrl no longer falls back to the WPS callback URL
application.yml / application-prod.yml(+.example)	删 external.wps 配置段 / remove external.wps section
backend/.env.example	删 WPS_APP_ID/WPS_APP_SECRET
backend/CPOLAR_STATUS.md、check-cpolar-url.sh、get-cpolar-url.sh	WPS 回调内网穿透调试工具，仅服务 WPS 回调 / cpolar tunnel debug utilities that only served the WPS callback URL

前端 / Frontend

文件 / File	说明 / Notes
components/WpsEditor.example.vue	无人引用 / no importers
config/wps.js	无人引用 / no importers
static/web-office-sdk-solution-v2.0.7.{cjs.js,es.js,zip}、static/index.d.ts	WPS SDK 未被引用的变体与类型定义（umd 变体暂留，因 wps-sdk.js 仍加载它，见第二阶段）/ unreferenced SDK variants & typings (umd kept for now — still loaded by wps-sdk.js, see Phase 2)
pages/admin/admin.vue	删 WPS WebOffice 配置区块 / remove WPS config block
pages/wizard/wizard.vue	删「文档在线编辑（WPS）」步骤（v0.2.3 起桌面端已隐藏）/ remove the WPS wizard step (already hidden on desktop since v0.2.3)
.env.local.example / .env.production.example	删 VITE_WPS_WEB_OFFICE_DEMO_URL

文档 / Docs

• README.md：WPS WebOffice 集成描述改为内置 LibreOffice 编辑器 / update WPS WebOffice mentions to the embedded LibreOffice editor

---

第二阶段（等 v0.3.1 合入 master 后 rebase 另开切片）/ Phase 2 (separate slice after v0.3.1 lands on master)

共享文件解耦 — 这些文件被 v0.3.1 并行开发触碰或与其红线重叠，本阶段不动：
Shared-file decoupling — these files are touched by (or overlap the red lines of) the parallel v0.3.1 work:

前端共享引用 / Frontend shared references

• components/WpsEditor.vue — 被 FilePreview.vue、project-overview.vue import；随二者解耦后删除，连带 utils/wps-sdk.js 与 static/web-office-sdk-solution-v2.0.7.umd.js / imported by FilePreview.vue & project-overview.vue; delete after decoupling, together with wps-sdk.js and the umd SDK
• composables/useWpsBridge.js — 被 useEditorBridge.js（v0.3.1 红线文件）、useAgentStream.js、project-overview.vue import / imported by useEditorBridge.js (v0.3.1 red-line file) and others
• FilePreview.vue WPS 回退分支（web 端 xls/ppt 预览的故事需先定：LOWA Calc/Impress 还是只读预览）/ WPS fallback branch — decide the xls/ppt story first (LOWA Calc/Impress vs read-only preview)
• ChatInterface.vue（WPS 提示文案、wpsFileId）、project-overview.vue（+ .backup、WPS_IMPLEMENTATION.md）、services/api.js（generateWpsEditUrl/getWpsCallbackBaseUrl，已无调用者）、useAgentStream.js（wps_stream_data 事件名）、config/workbenchActions.js（WPS 内部超链接协议）
• FileTree.vue / FileStagingArea.vue / SearchPanel.vue / MarkdownPreview.vue / VariablePanel.vue — 多为 wpsFileId 通用契约引用，随改名处理 / mostly generic wpsFileId contract usages, handle with the rename
• desktop：main/main.js（WPS 域名 cookie/Accept-Language workaround、window.open 拦截注释）、zetaoffice-session.js/zetaoffice-verify.js（注释）

后端：借 WPS 命名的通用管线（保留 + 改名债）/ Backend: generic plumbing wearing WPS names (keep + rename debt)

以下不是 WPS 集成，是 AI→前端 client_action SSE 通用命令管线，嵌入式 LibreOffice 路径（#59、v0.3.1 拟人式原语）正在使用，只欠改名：
These are not WPS integration — they are the generic AI→frontend client_action SSE command pipeline, actively used by the embedded LibreOffice path (#59, v0.3.1 primitives). They only need renaming:

• WpsResultController（/api/ai/agent/wps-result 结果回传契约）、WpsActionService、WpsTools → 建议改名 DocActionService/DocTools 等，前后端契约（SSE 事件、端点、工具名）需同步改
• PptxTools / PptxEditTools / FileTools / AgentOrchestrator / AgentStreamHandler（wps_stream 过滤逻辑）— 引用上述管线
• prompts/system_prompt.md — wps_open_file/wps_find_text 等是活的工具名，与工具改名同步
• WpsReplaceIntentTest — 纯意图逻辑测试，随工具改名

数据契约改名债 / Data-contract rename debt

• ProjectFile.wpsFileId → fileId：这是通用文件 ID 契约（download/upload 端点、前端全链路都用它），本次保留字段只删 WPS API 集成。改名涉及 DB 列迁移 + 前后端全链路，单独切片 / generic file-ID contract used by download/upload endpoints; kept as-is in Phase 1. Renaming needs a DB migration + full-stack sweep, its own slice
• 同族 / same family: DocFileLink.docWpsFileId、SearchResult.wpsFileId、ProjectFileRepository.findByWpsFileId、各 controller DTO 字段
• StorageProperties 默认路径 data/wps-files 与 OSS 前缀 wps-files/：既有部署的数据在这些路径下，改名需迁移方案，不能直接改默认值 / existing deployments store data under these paths — renaming requires a migration plan
• 运营面 / ops-facing: GROWTH_PLAYBOOK.md 文案、GitHub topics 中的 wps — 单独处理

---

排序依据 / Sequencing rationale

第一阶段与 v0.3.1 发版列车（zetaoffice/**、useEditorBridge.js、LibreOfficeEditor.vue 等）文件级零交集，可并行；第二阶段涉及共享文件与前后端契约改名，等 v0.3.1 合入 master 后 rebase 再动，避免合并冲突与管线破坏。

Phase 1 has zero file-level intersection with the v0.3.1 release train (zetaoffice/**, useEditorBridge.js, LibreOfficeEditor.vue, …) and can proceed in parallel. Phase 2 touches shared files and cross-stack contract renames — it waits for v0.3.1 to land on master, then rebases, to avoid merge conflicts and pipeline breakage.

Refs #13