本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月12日的备份/update/9/README-部署说明.md。
SoSite 附件权限更新包（2026-08-09）
本目录包含 1 个新增 + 8 个修改 的文件，按原目录结构放置。
覆盖方式：将本目录内所有文件按相同路径上传覆盖到站点根目录（如 D:/phpstudy_pro/WWW 或服务器对应路径）。
生成环境：PHP 8.2 / MySQL 5.7.26。
一、本包功能说明
- 附件上传权限：
category_permissions表新增can_attach列，后台"版块权限"矩阵新增"附件"列——可逐用户组控制某版块能否上传附件（发帖/回帖/编辑时校验）。 - 附件下载权限：新增
GET /attachment/{id}下载入口（替代原/assets/uploads/静态直链），权限跟随版块can_view——能浏览该版块才能下载其附件（未登录按游客组判定）。 - 预留插件扩展点：下载控制器输出文件前触发
attachment_download_before钩子（供后续积分下载等插件拦截，约定$GLOBALS['attachment_download_error']非空即 403）。
二、数据库变更（1 条，幂等，无需手动执行）
ALTER TABLE category_permissions ADD COLUMN can_attach TINYINT(1) NOT NULL DEFAULT 1- 由后台首次保存"版块权限"时自动执行（
Permission::ensureCanAttachColumn()幂等），列已存在时静默忽略。 - ⚠️ 加列默认值 1 = 所有存量记录自动放行附件，不破坏现有站点行为；只有后台重新保存权限（取消勾选"附件"）后对应组才受限。
三、覆盖前必须做的事
备份服务器现状
把服务器上以下文件/目录整体备份一份（zip 即可）：
app/Helpers/Permission.phpapp/Controllers/（PostController.php、ThreadController.php、AttachmentController.php、Admin/GroupController.php）app/Views/thread/show.php、app/Views/admin/permissions.phpindex.php
四、本包包含的文件清单（9 个）
新增（1）
app/Controllers/AttachmentController.php—— 附件下载控制器（canView 权限校验 +attachment_download_before钩子 + 路径穿越防护）
修改（8）
| 文件 | 改动 |
|---|---|
app/Helpers/Permission.php | check() 白名单加 can_attach；新增 canAttach() / ensureCanAttachColumn() / canAttachColumnExists()；saveCategoryPermission() 加 $canAttach 参数 |
app/Controllers/Admin/GroupController.php | 权限保存时调用 ensureCanAttachColumn() 并传 can_attach |
app/Views/admin/permissions.php | 权限矩阵新增"附件"列（默认勾选） |
index.php | 注册 GET /attachment/{id} 路由 + AttachmentController use |
app/Controllers/PostController.php | 发帖 create() / 编辑 edit() 携带附件时校验 canAttach |
app/Controllers/ThreadController.php | 回帖 reply() / 编辑 edit() 携带附件时校验 canAttach |
app/Views/thread/show.php | 主帖+回帖附件链接改为 /attachment/{id}；附件容器加 data-attachment-id（插件铺路） |
sosite-plugin-dev/references/02-hooks-catalog.md | 登记 attachment_download_before 钩子文档 |
五、部署步骤（推荐顺序）
- 备份（见第三节）
- 上传本 update 包全部文件，按路径覆盖
- 进入后台"版块权限"页随便保存一次（触发
can_attach列幂等创建，若此前未创建） - 清空模板编译缓存：
protected/cache/templates/目录下文件（模板引擎会自动重建） - 浏览器回归验证（见下）
六、回归验证清单
| 页面/场景 | 检查点 |
|---|---|
/admin/permissions?category_id=1 | 矩阵出现"附件"列，默认勾选；取消某组附件勾选保存后刷新保持未勾选 |
帖子详情（有附件帖，如 /thread/96） | 附件链接为 /attachment/{id}，容器带 data-attachment-id |
未登录访问 /attachment/{id} | 游客组可浏览的版块 → 200；游客不可见的版块 → 403 |
登录态访问 /attachment/{id} | 有权限 → 200 正常下载；图片内联展示、zip 等强制下载 |
| 无附件权限组上传附件 | 发帖/回帖提示"您没有权限在该版块上传附件" |
七、注意事项
- 历史直链
/assets/uploads/xxx仍可访问（无法追溯），本次未强制迁移；新链接全部走/attachment/{id} - 正文内嵌图片（发帖内容里的 uploads 图）仍为直链，不受本次权限控制
- 图片附件走权限路由后，若管理员关闭了某组/游客的
can_view，该组将连帖子内附件图片都无法查看（跟随 can_view 的自然结果）
本包由 2026-08-09 会话生成（附件上传/下载权限 + 下载前钩子预留）。
