# 后台附件管理模块 Spec

## Why
Xiuno BBS 后台缺少附件管理功能，无法查看、筛选、统计附件，也无法清理帖子/回复已删除后残留的孤儿附件，导致磁盘空间浪费。

## What Changes
- 新增后台附件管理页面（列表、筛选、排序、分页）
- 新增统计仪表（总附件数、总占用空间、孤儿数、按类型统计）
- 新增孤儿附件识别与批量清理功能
- 新增单个附件删除（孤儿直接删除，正常附件需确认强制删除）
- 新增 `bbs_admin_log` 表记录管理操作日志
- 新增「附件日志」tab 在日志菜单下展示操作记录
- 新增「附件管理」菜单项在侧边栏

## Impact
- Affected code: `admin/route/attach.php`（新建）、`admin/view/htm/attach_manage.htm`（新建）、`model/attach.func.php`（扩展）、`admin/menu.conf.php`（修改）、`admin/view/htm/sidebar.inc.htm`（修改）、`admin/route/log.php`（修改）、`admin/view/htm/log_attach.htm`（新建）、`install/upgrade.sql` 或 UpgradeService（新增建表语句）
- **BREAKING**: 新增 `bbs_admin_log` 数据库表（需通过后台升级页面执行）

## ADDED Requirements

### Requirement: 附件列表展示
系统 SHALL 在后台提供附件列表页面，展示以下字段：
- 附件ID（aid）
- 文件名（orgfilename 原始文件名）
- 类型（根据 filetype 或后缀自动归类为：图片/文档/音频/视频/压缩包/其他）
- 大小（格式化显示，复用 `format_filesize()`）
- 上传用户（用户名 + UID，批量获取避免 N+1）
- 上传时间（create_date 格式化）
- 关联对象：
  - `tid>0 AND pid=0`：显示"主题 #tid"，链接到 `?thread-tid`
  - `pid>0`：显示"回复 #pid"，链接到回复所在帖子（通过 pid 查 bbs_post 获取 tid）
  - `tid=0 AND pid=0`：显示"无关联"
- 孤儿状态标记（红色标签）

#### Scenario: 正常附件显示
- **WHEN** 附件的 tid>0 且 bbs_thread 中存在对应记录
- **THEN** 关联对象显示为可点击的"主题 #tid"链接，无孤儿标记

#### Scenario: 孤儿附件显示
- **WHEN** 附件关联的帖子/回复已被删除，或 tid=0 AND pid=0
- **THEN** 关联对象显示"已删除"或"无关联"，并标记红色"孤儿"标签

### Requirement: 筛选与排序
系统 SHALL 支持以下筛选和排序：
- 按类型筛选：图片/文档/音频/视频/压缩包/其他（根据 `attach.conf.php` 中的类型映射归类）
- 按孤儿状态筛选：全部 / 仅孤儿 / 仅正常
- 按大小排序：升序/降序
- 关键词搜索：附件原始文件名（orgfilename）模糊匹配
- 分页：每页 20/50/100 可调

#### Scenario: 按孤儿筛选
- **WHEN** 管理员选择"仅孤儿"筛选
- **THEN** 列表仅显示关联帖子/回复已不存在的附件

### Requirement: 统计仪表
系统 SHALL 在列表上方展示统计卡片：
- 总附件数
- 总占用空间（SUM(filesize) 格式化）
- 孤儿附件数
- 按类型统计（图片/文档/音频/视频/压缩包/其他的数量和占比，用进度条展示）

#### Scenario: 统计数据展示
- **WHEN** 管理员进入附件管理页面
- **THEN** 顶部显示4个统计卡片，类型统计区域显示各类型数量和百分比进度条

### Requirement: 批量清理孤儿附件
系统 SHALL 提供"清理孤儿附件"功能：
- 点击按钮后弹出确认对话框，显示即将删除的孤儿附件数量
- 确认后批量删除所有孤儿附件（关联帖子/回复已不存在的 bbs_attach 记录）
- 删除时同时删除服务器物理文件（`upload/attach/{filename}`）及缩略图
- 仅允许删除孤儿附件，不允许批量删除正常附件
- 操作记录写入 `bbs_admin_log`

#### Scenario: 批量清理成功
- **WHEN** 管理员点击"清理孤儿附件"并确认
- **THEN** 系统删除所有孤儿附件的数据库记录和物理文件，显示删除数量，记录操作日志

#### Scenario: 无孤儿附件
- **WHEN** 管理员点击"清理孤儿附件"但无孤儿附件
- **THEN** 提示"无孤儿附件需要清理"

### Requirement: 单个附件删除
系统 SHALL 为每条附件提供删除按钮：
- 孤儿附件：直接删除，确认后执行
- 正常附件：提示"此附件有正常关联，是否强制删除？"，确认后将 tid/pid 置0再删除物理文件和数据库记录
- 所有删除操作需 CSRF Token 验证
- 操作记录写入 `bbs_admin_log`

#### Scenario: 删除孤儿附件
- **WHEN** 管理员点击孤儿附件的删除按钮并确认
- **THEN** 删除数据库记录和物理文件，记录日志

#### Scenario: 强制删除正常附件
- **WHEN** 管理员点击正常附件的删除按钮，确认强制删除
- **THEN** 系统先将 tid/pid 置0，再删除物理文件和数据库记录，记录日志

### Requirement: 操作日志
系统 SHALL 新建 `bbs_admin_log` 表记录所有管理操作：
- 表结构：id(AI), uid(INT), action(VARCHAR 50), target_type(VARCHAR 20), target_ids(TEXT), detail(TEXT), ip(INT UNSIGNED), create_date(INT UNSIGNED)
- 所有附件删除操作写入此表
- 在后台「日志」菜单下新增「附件日志」tab 展示操作记录
- 日志列表显示：操作人、操作类型、目标ID、详情、IP、时间

#### Scenario: 删除操作记录日志
- **WHEN** 管理员执行任何附件删除操作
- **THEN** 系统在 bbs_admin_log 中插入记录，包含操作人UID、操作类型、附件ID、文件名、IP、时间

### Requirement: 侧边栏菜单
系统 SHALL 在后台侧边栏新增「附件管理」菜单项：
- 归属"内容管理"分区（content section）
- 图标：`ti-paperclip`
- 文字：「附件管理」
- 链接：`?attach-list`

系统 SHALL 在「日志」菜单下新增「附件日志」tab：
- 链接：`?log-attach`

## MODIFIED Requirements

### Requirement: 日志菜单扩展
原「日志」菜单包含"积分日志"和"登录日志"两个 tab，现新增"附件日志" tab。

### Requirement: 数据库升级
需通过 UpgradeService 添加 `bbs_admin_log` 建表语句，管理员在后台升级页面执行。

## REMOVED Requirements
（无）