本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：20260806备份/给下一个AI的接手说明.md。

给下一个 AI 的接手说明

项目背景

SoSite 轻量级 PHP 社区系统，位于 D:\phpstudy_pro\WWW。

两套模板：默认模板（app/Views/）+ Modern 主题（assets/themes/modern/templates/）。

你的任务

只引入 Alpine.js 和 htmx，替换原有的零散 JS 交互和 AJAX 请求。不引入 Tailwind CSS，不动现有 CSS 体系。

详细计划

完整计划文档在 htmx+Alpine.js 重构计划（修正版）.md，请先阅读。

核心原则（必须遵守）

1. 不改 CSS 类名——所有 mn-、c-、fs-* 类名保留不动
2. 不改内联样式——动态 PHP 颜色（style="color:<?php...?>"）保留不动
3. 不改编辑器——CKEditor 保持独立，不修改
4. 不改图标系统——FontAwesome 保持原样
5. 不要引入 Tailwind CSS——不要生成 SoCSS，不要构建任何 CSS 工具链
6. 不要引入任何构建工具——不需要 npm/Webpack/Vite
7. 每次改完做语法检查——php -l 文件名 确保无语法错误

改造范围

要改的（Alpine.js）

• confirm 确认弹窗（~30 处，admin 后台为主）
• 模态框显隐（~10 处，插件后台为主）
• 导航切换（4 处，两个 layout 的 main.php）
• Tab 切换（3 处，profile/index.php）
• 全选/取消（4 处，admin 后台）

要改的（htmx）

• 骰子游戏 AJAX（1 处，plugins/dice）
• 猜题对决 AJAX（2 处，plugins/quiz_duel）
• 每日签到 AJAX（1 处，plugins/daily_checkin）
• 投票 AJAX（1 处，thread/show.php）

不改的

• 所有 CSS 文件（8 个旧 CSS 文件不动）
• 所有 mn- / c- / fs-* 类名
• 所有动态 PHP 内联样式
• 编辑器（CKEditor）
• 图标系统（FontAwesome）
• 图标生成器插件（交互复杂，不动）

注意的坑

1. CSP 安全策略：Alpine 需要 'unsafe-eval'，如果服务器有 CSP 头必须在 app/Core/Controller.php 中添加
2. x-show 与 CSS 冲突：如果现有 CSS 用 display:none 控制显隐（如下拉菜单），不能用 x-show，要用 :class 绑定模式
3. htmx 投票：后端接口需要返回 HTML 片段而非 JSON，Vote.php 或 ApiController.php 可能需要调整
4. htmx 的 hx-vals 中必须包含 csrf token，否则投票二次点击无效

起始状态

Alpine.js 和 htmx 的库文件已经在 assets/lib/ 目录中，layouts 的 main.php 中也已引入。

从改造计划文档的第 5 章（Alpine.js 替换交互）开始执行即可。