NextEdu/docs/architecture/audit/archive/files-audit-report.md

文件模块审计报告

审查日期：2026-06-25 审查范围：src/modules/files/**、src/app/api/upload/**、src/app/api/files/**、src/app/(dashboard)/admin/files/**、src/modules/settings/actions-avatar.ts、src/modules/settings/components/avatar-upload.tsx 架构图参考：docs/architecture/004_architecture_impact_map.md §2.17、docs/architecture/005_architecture_data.json

---

一、现有实现概要

1.1 文件分布

层	路径	文件数	说明
路由层 - 上传	src/app/api/upload/route.ts	1	FormData 接收 + 直接写磁盘 + DB 落库
路由层 - 单文件	src/app/api/files/[id]/route.ts	1	GET 查询单文件、DELETE 删除单文件
路由层 - 批量删除	src/app/api/files/batch-delete/route.ts	1	POST 批量删除
路由层 - 管理页	src/app/(dashboard)/admin/files/page.tsx	1	Server Component，调用 data-access 渲染 AdminFilesView
模块层 - data-access	src/modules/files/data-access.ts	1（305 行）	11 个函数 + mapRow
模块层 - types	src/modules/files/types.ts	1（63 行）	7 个接口/类型
模块层 - 组件	src/modules/files/components/	6 文件	FileUpload / FileList / FilePreview / FilePreviewDialog / FileIcon / AdminFilesView
i18n	messages/{en,zh-CN}/files.json	2	仅 2 个键（title、description）
Schema	src/shared/db/schema.ts §12	-	file_attachments 表 + 3 个索引
权限点	src/shared/types/permissions.ts	-	FILE_UPLOAD / FILE_READ / FILE_DELETE

1.2 数据流

浏览器 (AdminFilesView/FileUpload/AvatarUpload)
   │  fetch /api/upload (POST FormData)
   │  fetch /api/files/[id] (DELETE)
   │  fetch /api/files/batch-delete (POST JSON)
   ▼
API 路由层（requireAuth / requirePermission）
   │  直接调用 files/data-access 函数
   ▼
files/data-access.ts → shared/db → file_attachments 表
   │  存储抽象：/api/upload 与 /api/files/[id] 直接用 fs/promises
   │            /api/files/batch-delete 用 storageProvider

1.3 架构图记录情况

004_architecture_impact_map.md §2.17 与 005_architecture_data.json 的 modules.files 节点对 data-access 的导出函数签名、依赖关系记录基本完整。但发现以下遗漏（详见 §五）：

• getFileByUrl 函数未在 005 JSON 的 dataAccess 列表中记录（实际代码存在，被 settings/actions-avatar.ts 使用）。
• 被依赖方遗漏 settings 模块：004 §2.17 仅记录 app/api/upload / app/api/files/[id] / app/api/files/batch-delete / homework，遗漏 settings/actions-avatar.ts 通过 getFileByUrl + deleteFileAttachment 调用清理头像文件。
• FilePreviewDialog 组件未在 005 JSON 的 components 列表中记录。

---

二、现存问题与原因分析

2.1 三层架构违反：缺少 actions.ts 编排层（P0）

位置	问题	违反规则
src/modules/files/ 目录	无 actions.ts 文件	"每个模块标准结构：actions.ts（编排层）"
src/app/api/upload/route.ts L13	import { createFileAttachment } from "@/modules/files/data-access"	"app/ 只能调用 modules/ 的 Server Actions 和 data-access" — API 路由虽可直调 data-access，但项目规范要求所有写操作通过 actions 编排
src/app/api/files/batch-delete/route.ts L6-9	直接 import 两个 data-access 函数	同上
src/app/(dashboard)/admin/files/page.tsx L7-10	page.tsx 直接调用 data-access 函数	同上（应通过 actions 编排权限与数据获取）

原因：模块创建时未遵循标准结构，所有数据访问被路由层与页面层直接调用，跳过 actions 编排层。

后果：

1. 权限校验分散在路由层，无法集中管理；
2. 无法在 actions 层统一埋点、审计日志、缓存策略；
3. 与项目其他模块（如 announcements、settings、grades 等）的 actions.ts 模式不一致，破坏一致性；
4. 无法被其他模块以 actions 形式复用（settings 模块只能 import data-access）。

2.2 i18n 严重缺失：UI 文本全部硬编码英文（P0）

位置	问题	违反规则
messages/en/files.json、messages/zh-CN/files.json	仅 title、description 2 个键	"所有用户可见文本必须适配 i18n"
components/file-upload.tsx L48-51、L188-191、L218、L230	"File is empty" / "Click to upload or drag and drop" / "Uploaded" 等硬编码	同上
components/file-list.tsx L27-28、L37、L40、L84、L104、L117	"No files" / "File deleted" / "Download" / "Delete" 等硬编码	同上
components/file-preview.tsx L71、L113-119、L207、L215	"Download" / "Office file preview not available" / "Load preview" 等硬编码	同上
components/file-preview-dialog.tsx L29、L47	"Preview" / "File preview ·" 硬编码	同上
components/admin-files-view.tsx L33-45、L121、L135-139、L147、L154、L177、L199、L217、L261、L271	TYPE_OPTIONS 标签 + "Files"/"Total Files"/"Total Size"/"Filter by type"/"Search by file name..."/"Delete Selected"/"Deleting..." 等几十处硬编码	同上

原因：组件开发时直接用英文字面量，未提取翻译键；i18n 文件仅 placeholder。

后果：

1. 中文用户看到全英文界面（与系统其他模块本地化不一致）；
2. 切换语言无效；
3. 翻译协作无法进行；
4. 违反项目硬约束。

2.3 权限校验缺失：上传路由仅 requireAuth 未走 requirePermission（P0）

位置	问题	违反规则
src/app/api/upload/route.ts L31	const ctx = await requireAuth()	"所有 Server Action 必须调用 requirePermission() 进行权限校验"
同文件 L18-24	已定义 FILE_UPLOAD 权限点（permissions.ts L123），但路由层未使用	同上

原因：上传路由创建时仅考虑登录态校验，未将 FILE_UPLOAD 权限点接入；项目已定义该权限点但未消费。

后果：

1. 任何登录用户（含无上传权限的角色）均可调用上传接口；
2. 与 RBAC 设计意图相悖；
3. FILE_UPLOAD 权限点形同虚设。

2.4 横向越权：GET /api/files/[id] 仅 requireAuth（P0）

位置	问题	违反规则
src/app/api/files/[id]/route.ts L24	await requireAuth() 后直接返回任意 id 的文件元数据	"Server Action 二次校验" + 数据级别权限过滤要求
同文件 L52-58	DELETE 仅校验 FILE_DELETE，未校验调用者是否拥有该文件	同上

原因：GET 路由未做权限分级，DELETE 未做所有权或所属 target 关联校验。

后果：

1. 学生可通过枚举 ID 拉取他人上传的考试附件元数据（含 mimeType、url、uploaderId 等）；
2. 通过返回的 url 即可访问文件本体（文件存储在 /public/uploads/...，无签名机制）；
3. 任何 FILE_DELETE 权限者可删除他人上传的文件；
4. 安全风险：违反 FERPA/GDPR 学生数据保护原则。

2.5 缺少 loading.tsx 和 error.tsx（P1）

位置	问题	违反规则
src/app/(dashboard)/admin/files/	仅 page.tsx，缺 loading.tsx / error.tsx	"All student routes must include loading.tsx and error.tsx for error boundaries"（admin 同样遵循，参考 admin/users、admin/roles）

原因：路由未补齐标准文件。

后果：

1. 无骨架屏 → 用户首次进入白屏时间长；
2. data-access 抛错 → 整个 dashboard 布局错误（无 error boundary 隔离）。

2.6 类型安全：API 路由存在 as 断言（P1）

位置	问题	违反规则
src/app/api/upload/route.ts L100-102	targetType: isTargetType(...) ? (targetType as string) : null	"禁止 as 断言（除类型收窄外）"
src/app/api/files/batch-delete/route.ts L23	const body = (await req.json().catch(() => null)) as { ids?: unknown } | null	同上
src/app/api/files/batch-delete/route.ts L23	body!.ids 非空断言	"可选链后禁止跟非空断言 !"（同类违规）

原因：缺少 Zod schema 校验，只能用 as 转换未验证输入。

后果：类型不安全的输入直接进入业务逻辑，运行时仍可能爆炸；tsc 严格模式被绕过。

2.7 缺少 Zod schema 验证（P1）

位置	问题	违反规则
src/modules/files/	无 schema.ts	"模块标准结构：schema.ts（Zod 验证）"
src/app/api/upload/route.ts L44-47	formData.get("file") / formData.get("targetType") 未做 Zod 校验	"输入使用 Zod 验证，验证失败返回结构化错误"
src/app/api/files/batch-delete/route.ts L22	body.ids 仅做 Array.isArray + typeof === "string" 简单过滤，无长度上限/格式约束	同上

原因：路由层手写最小校验，未引入 Zod schema。

后果：

1. 大量恶意 ids 可导致 inArray 查询超长 SQL；
2. targetType 可注入任意字符串进入 DB；
3. 与项目其他模块（如 announcements、classes）的 schema.ts 模式不一致。

2.8 存储抽象使用不一致（P1）

位置	问题
src/app/api/upload/route.ts L3-4、L80-85	直接 import { mkdir, writeFile } from "fs/promises" + path.join(process.cwd(), "public", ...) 写文件
src/app/api/files/[id]/route.ts L2-3、L61-66	直接 import { unlink } from "fs/promises" 删文件
src/app/api/files/batch-delete/route.ts L5、L37	使用 storageProvider.delete() 抽象
src/modules/settings/actions-avatar.ts L2-3、L27-34	又一次直接 import { unlink } from "fs/promises"

原因：storageProvider 抽象存在但只在批量删除处使用，单文件上传/删除路径未迁移。

后果：

1. 切换到 OSS/S3 时需要修改 3 处代码；
2. 4 个调用点对路径解析逻辑重复实现（DRY 违反）；
3. actions-avatar.ts 中的 path.join(process.cwd(), "public", fileRecord.storagePath) 与 storageProvider 的 delete() 行为重复，且未处理 storagePath 以 / 开头的情况。

2.9 FileList 组件死代码（P2）

位置	问题
src/modules/files/components/file-list.tsx（125 行）	全代码库无任何文件 import 该组件（grep from "@/modules/files/components/file-list" 为 0 结果）；admin-files-view.tsx 自行实现列表，未使用 FileList

原因：早期创建后未接入；AdminFilesView 复刻了类似 UI。

后果：

1. 死代码维护负担；
2. 误导后续维护者以为有消费者；
3. 125 行无测试覆盖。

2.10 缺少自定义 hooks（P1）

位置	问题	违反规则
src/modules/files/	无 hooks/ 目录	"模块标准结构：hooks/（可选）" + "逻辑复用一律抽取为自定义 hooks"
components/file-upload.tsx L43-159	上传逻辑（XHR + 进度 + 状态机）全部内联在组件中	"逻辑复用一律抽取为自定义 hooks"
components/file-preview.tsx L180-233	TextPreview 内部 load 逻辑（fetch + 错误处理）内联	同上
components/admin-files-view.tsx L49-128	客户端筛选、批量选择、批量删除逻辑全部内联	同上

原因：未抽取 useFileUpload / useFilePreview / useFileBatchOperations 等 hooks。

后果：

1. 组件无法独立测试；
2. 逻辑无法在多个组件间复用（如 FileUpload 的进度逻辑无法被 AvatarUpload 复用）；
3. 单组件行数膨胀风险。

2.11 缺少 React Error Boundary 和 Suspense 骨架屏（P1）

位置	问题	违反规则
src/app/(dashboard)/admin/files/page.tsx	整页同步 await，无 Suspense 包裹	"异步数据使用 React Suspense + 骨架屏"
components/admin-files-view.tsx	上传/批量删除错误仅 toast，无 Error Boundary 隔离失败区块	"每个独立的数据区块必须用 React Error Boundary 包裹"
components/file-preview.tsx L188-198	TextPreview 的 fetch 错误仅展示文本，无重试按钮	"明确处理空数据、无权限、网络异常等边界状态"

原因：未引入 React 19 的 Error Boundary 与 Suspense 流式渲染模式。

后果：

1. 上传失败仅 toast，用户无法定位失败任务重试；
2. 整页 await 阻塞流式渲染；
3. 网络异常时整页空白。

2.12 数据级别权限过滤缺失（P1）

位置	问题	违反规则
src/modules/files/data-access.ts L128-143	getAllFileAttachments 不带 scope/uploaderId 过滤，返回全局数据	"所有敏感数据查询必须在 data-access 层结合当前用户权限过滤"
src/modules/files/data-access.ts L83-103	getFileAttachmentsByTarget 不校验调用者是否有权访问该 target 资源	同上
src/modules/files/data-access.ts L196-234	getFileAttachmentsWithFilters 不带任何权限维度	同上
src/app/(dashboard)/admin/files/page.tsx L25-28	仅校验 FILE_READ 权限，未结合 scope（如教师只能看自己班级的文件）	同上

原因：模块未引入 DataScope 概念（grades/classes 模块已实现）。

后果：FILE_READ 持有者可读全部文件元数据，与 K12 多角色数据隔离要求不符。

2.13 架构图遗漏：getFileByUrl 未记录（P2）

位置	问题	违反规则
docs/architecture/005_architecture_data.json modules.files.exports.dataAccess	列出 10 个函数，但代码中实际有 11 个（缺 getFileByUrl）	"如果架构图未覆盖该模块的任何部分，必须优先补全架构图"

原因：getFileByUrl 在 P2-13 修复时新增，未同步到 JSON。

后果：AI 友好数据不准确，自动化审计会遗漏该函数的依赖分析。

2.14 架构图遗漏：settings 模块依赖未记录（P2）

位置	问题
docs/architecture/004_architecture_impact_map.md §2.17 被依赖	仅列 app/api/upload / app/api/files/[id] / app/api/files/batch-delete / homework，遗漏 settings/actions-avatar.ts 调用 getFileByUrl + deleteFileAttachment

原因：avatar 清理功能上线时未同步架构图。

2.15 avatar-upload.tsx 使用 "user_avatar" 非枚举 targetType（P1）

位置	问题	违反规则
src/modules/settings/components/avatar-upload.tsx L78	formData.append("targetType", "user_avatar")	"TypeScript 严格模式：禁止 any"（类型不一致）
src/modules/files/types.ts L2	FileTargetType = "exam" | "textbook" | "question" | "announcement" | "homework" 不含 "user_avatar"	类型契约违反
src/app/api/upload/route.ts L100-102	isTargetType(...) 返回 false 后 fallback 到 null，导致头像文件 targetType=null	数据完整性受损

原因：头像上传复用 /api/upload，但用了未注册的 targetType 字符串。

后果：

1. 头像文件在 DB 中 targetType 字段为 null，无法按类型筛选头像；
2. 清理孤立头像文件时无法用 getFileAttachmentsByTarget("user_avatar", ...)；
3. 类型系统未保护跨模块字符串。

2.16 客户端二次筛选与硬编码 limit 200（P2）

位置	问题
src/app/(dashboard)/admin/files/page.tsx L26	getFileAttachmentsWithFilters({ limit: 200 }) 硬编码 200，无分页
components/admin-files-view.tsx L54-75	客户端 useMemo 重复执行筛选逻辑（与 data-access 的 getFileAttachmentsWithFilters 重复）

原因：早期为简化实现，未做服务端分页 + URL 查询参数。

后果：

1. 文件数超过 200 时静默丢失；
2. 服务端筛选与客户端筛选逻辑双写、易不一致；
3. 无法被搜索引擎或分享链接复用筛选状态。

2.17 监控埋点缺失（P2）

位置	问题	违反规则
src/app/api/upload/route.ts、src/app/api/files/[id]/route.ts、src/app/api/files/batch-delete/route.ts	无 trackEvent 调用	"方案中预留关键操作埋点接口"
src/modules/files/data-access.ts 各写函数	无审计日志（其他模块如 audit、announcements 已接入 audit-logger）	同上

原因：模块创建时未规划可观测性。

后果：无法追踪上传/删除异常、容量增长、恶意批量删除等运营事件。

2.18 可访问性不足（P2）

位置	问题
components/file-list.tsx L70-78	<a> 链接无 aria-label，仅靠 title 提供上下文
components/file-preview.tsx L96-101	PDF iframe 缺 aria-label，仅 title
components/admin-files-view.tsx L226-229	全选 Checkbox indeterminate 状态无 ARIA 描述
components/file-upload.tsx L161-204	拖拽区 role="button" 但缺 aria-describedby 关联限制说明

---

三、行业差距对比

3.1 文件预览能力薄弱

• 行业实践（如 PowerSchool、Canvas、阿里云教育）：Office 文档通过 Office Online Viewer / WPS 在线预览服务打开；视频支持原生 <video> 流式播放；音频支持波形 + 播放器。
• 当前实现：仅支持 image / pdf / text 三类，Office 与视频、音频统一回退到下载。
• 影响：教师上传 PPT 课件时无法快速浏览；学生作业扫描图（PNG）预览体验勉强可用，但 Office 资料无法即时查阅。

3.2 缺少文件分类与文件夹概念

• 行业实践：按课程/班级/学科组织文件树；支持文件夹嵌套；提供"我的文件"/"共享文件"/"班级文件"分区。
• 当前实现：仅靠 targetType + targetId 多态关联，无独立文件夹实体；admin/files 是单一平铺列表。
• 影响：教师上传大量课件后无法分类组织；学生查找特定学科资料困难。

3.3 缺少文件版本管理

• 行业实践：同名文件覆盖时保留历史版本；支持版本对比、回滚；显示修改人/修改时间。
• 当前实现：每次上传生成新 cuid 文件名，无版本关联；同名文件多次上传产生多个独立记录。
• 影响：教师更新课件后旧链接失效；无法回滚误删/误改。

3.4 缺少配额与存储管理

• 行业实践：按用户/角色/班级分配存储配额；接近上限时提醒；超限拒绝上传；管理员可查看配额使用排行。
• 当前实现：仅全局 getFileStats 统计总量，无 per-user 配额、无超限拦截。
• 影响：单个用户可耗尽服务器磁盘；K12 学校存储成本不可控。

3.5 缺少文件分享与权限管理

• 行业实践：生成分享链接（含过期时间、密码、查看/下载权限）；可按用户/班级精细授权；分享操作有审计日志。
• 当前实现：所有文件 url 直接 /uploads/... 公开访问，无签名、无过期、无权限校验。
• 影响：严重安全风险：任何知道 URL 的人（含未登录用户）均可下载；学生隐私材料（成绩单扫描件、家长联系信息）可能泄露。

3.6 缺少病毒扫描与内容安全

• 行业实践：上传时通过 ClamAV / 云安全服务扫描；图片通过 NSFW 检测；扫描结果记录到 DB。
• 当前实现：仅校验 MIME 与大小，无内容安全检测。
• 影响：恶意文件可上传到服务器并被其他用户下载；K12 场景下未成年人保护要求更高。

3.7 缺少图片缩略图与 CDN 加速

• 行业实践：上传图片后异步生成多档缩略图（48/128/512）；通过 CDN 分发；列表用小图、预览用大图。
• 当前实现：原图直出。
• 影响：列表页加载慢；带宽浪费；移动端体验差。

3.8 缺少文件使用追踪

• 行业实践：DB 记录文件被哪些资源（exam/textbook/homework）引用；删除文件前校验引用计数；提供"孤立文件清理"任务。
• 当前实现：仅 targetType + targetId 字段记录关联，无引用计数；删除 exam 时其附件不会自动清理。
• 影响：磁盘孤儿文件累积；删除资源后附件残留。

3.9 多角色体验差距

• 教师：无"我上传的"快捷筛选；无按班级/学科筛选；批量上传后无"批量设置 target"操作。
• 学生：完全无入口查看自己上传的作业扫描图（仅 homework 模块内部使用）；无法预览已上传的作业附件。
• 家长：无入口查看学校下发的通知附件；仅靠 announcement 模块内嵌预览。
• 管理员：无"按上传者筛选"快捷入口；无"近期 7 天"快捷时间筛选；无配额管理面板。

3.10 缺少批量操作与企业级功能

• 行业实践：批量移动到 target、批量设置权限、批量下载（ZIP 打包）、批量重命名、Excel 导出文件清单。
• 当前实现：仅批量删除。
• 影响：管理员整理文件效率低。

---

四、改进优先级建议

P0（必须立即修复 — 安全与架构合规）

#	项	改进方向
P0-1	创建 src/modules/files/actions.ts 编排层	将 upload / delete / batchDelete / query 包装为 Server Actions（带 requirePermission + Zod + 审计日志），路由层改为转发到 actions
P0-2	补全 i18n 翻译键（en + zh-CN files.json）	提取约 40 个翻译键，组件全部接入 useTranslations("files")
P0-3	修复 /api/upload 权限校验	将 requireAuth() 替换为 requirePermission(Permissions.FILE_UPLOAD)
P0-4	修复横向越权	GET /api/files/[id] 加 FILE_READ；DELETE /api/files/[id] 校验调用者 ownership 或拥有 FILE_DELETE；data-access 新增 assertFileOwnedBy 辅助
P0-5	文件 URL 签名保护（中长期）	改为非 public 路径 + 通过 API 路由签名分发，含过期时间与权限校验

P1（本轮实施 — 质量与一致性）

#	项	改进方向
P1-1	新增 loading.tsx + error.tsx	骨架屏 + Error Boundary 隔离
P1-2	新增 src/modules/files/schema.ts	Zod 校验 upload/batchDelete/filter 输入，移除 as 断言
P1-3	抽取 hooks	useFileUpload / useFileBatchOperations / useFilePreview，组件瘦身
P1-4	统一 storageProvider 调用	upload / single delete / avatar cleanup 全部改用 storageProvider
P1-5	修复 user_avatar targetType	将 "user_avatar" 加入 FileTargetType 枚举；upload route VALID_TARGET_TYPES 同步；avatar-upload.tsx 类型对齐
P1-6	引入 DataScope 过滤	data-access 的查询函数新增 scope: DataScope 与 currentUserId?: string 参数，参照 grades 模块实现
P1-7	分区 Error Boundary + Suspense	AdminFilesView 拆为 StatsSection / UploadSection / ListSection，每区独立 Suspense + Boundary
P1-8	接入 audit-logger	upload / delete / batchDelete 记录审计日志（参照 announcements 模块）
P1-9	接入 trackEvent 埋点	关键操作埋点：upload_success / upload_failed / delete / batch_delete

P2（中长期 — 体验与企业级）

#	项	改进方向
P2-1	删除 FileList 死代码	确认无消费者后删除 125 行
P2-2	同步架构图	补全 getFileByUrl 节点、FilePreviewDialog 组件、settings 依赖关系
P2-3	服务端分页 + URL 查询参数	替换硬编码 limit=200，支持 ?page=&size=&type=&search=&uploader=
P2-4	a11y 增强	给所有链接/iframe/Checkbox 加 ARIA 标签；拖拽区 aria-describedby
P2-5	文件预览扩展（中长期）	接入 Office Online Viewer / 视频原生 <video> / 音频播放器
P2-6	文件版本管理（中长期）	新增 file_versions 表，同名覆盖时保留历史
P2-7	文件配额（中长期）	新增 user_storage_quota 配置；data-access 校验超限；admin 配额面板
P2-8	文件分享与签名 URL（中长期）	文件改为非 public 存储 + 签名分发；分享链接生成/吊销
P2-9	病毒扫描（中长期）	接入 ClamAV 或云扫描服务；扫描结果记录到 DB
P2-10	图片缩略图 + CDN（中长期）	异步生成多档缩略图；CDN 分发
P2-11	引用计数与孤立文件清理（中长期）	删除资源时级联清理附件；定期清理孤儿文件任务
P2-12	文件夹/分类实体（中长期）	新增 folders 表；支持嵌套与按班级/学科组织
P2-13	批量操作扩展（中长期）	批量下载 ZIP、批量移动 target、Excel 导出清单

重构设计原则遵循说明

原则	落地方式
完全解耦	data-access 仅暴露纯函数；actions 注入权限/审计；组件通过 props 接收数据（无直接 data-access import）
组合优先	AdminFilesView 拆为 <StatsSection /> + <UploadSection /> + <ListSection /> 组合；逻辑全入 hooks
国际化就绪	所有可见文本走 useTranslations("files.*")；提供翻译文件结构示例
最大化复用	useFileUpload hook 同时被 FileUpload 与 AvatarUpload 复用；FileIcon 已是复用单元
错误与边界处理	每区独立 Error Boundary；Suspense + 骨架屏；上传任务列表保留失败项供重试
可测试性	hooks 独立可测；data-access 纯函数；schema 可独立测试
可扩展性	通过 FILES_ROLE_CONFIG 决定各角色可见 Widget；新增角色仅改配置
企业级补充	a11y ARIA 标签、流式 RSC、storageProvider 二次校验、audit-logger + trackEvent

---

五、架构图同步说明

5.1 004_architecture_impact_map.md §2.17 同步项

1. 导出函数章节：
   • 补充 getFileByUrl 函数（用于头像 URL 反查文件记录）
   • 修正 getFileAttachmentsByOwner → 实际函数名为 getFileAttachmentsByUploader
   • 补充 FilePreviewDialog 组件到组件清单
2. 依赖关系章节：
   • 被依赖方新增 settings（actions-avatar.ts 调用 getFileByUrl + deleteFileAttachment）
3. 已知问题章节：
   • 移除 "⚠️ P2：无 actions.ts" 标记（本轮 P0-1 实施后失效）
   • 新增 "i18n 缺失"、"权限校验缺失"、"横向越权"标记（实施后转为 ✅）

5.2 005_architecture_data.json 同步项

1. modules.files.exports.dataAccess 数组补充：

   {
     "name": "getFileByUrl",
     "signature": "(url: string) => Promise<FileAttachment | null>",
     "file": "data-access.ts",
     "purpose": "按 URL 反查文件附件记录（用于头像等场景的旧文件清理）",
     "deps": ["shared.db", "shared.db.schema.fileAttachments"],
     "usedBy": ["settings/actions-avatar.ts"]
   }
   

2. modules.files.exports.actions 节点新增（P0-1 实施后）：
   • uploadFileAction / deleteFileAction / batchDeleteFilesAction / getFileListAction / getFileStatsAction
3. modules.files.exports.components 数组补充 FilePreviewDialog
4. modules.files.dependencies.usedBy 数组新增 "settings"
5. modules.files.types 中 FileTargetType 定义更新为 "exam" | "textbook" | "question" | "announcement" | "homework" | "user_avatar"（P1-5 实施后）

---

六、翻译文件结构示例（i18n 就绪）

messages/en/files.json 与 messages/zh-CN/files.json 建议结构：

{
  "title": "File Management",
  "description": "View and manage all uploaded files in the system.",
  "nav": { "files": "Files" },
  "upload": {
    "title": "Click to upload or drag and drop",
    "hint": "Images, PDF, Word, Excel, PPT, Text, ZIP / RAR · up to {size}",
    "success": "{name} uploaded",
    "error": "{name}: {message}",
    "empty": "File is empty",
    "tooLarge": "File size exceeds {limit} limit",
    "invalidType": "File type {type} is not allowed",
    "uploaded": "Uploaded",
    "remove": "Remove",
    "networkError": "Network error",
    "invalidResponse": "Invalid response"
  },
  "list": {
    "empty": "No files",
    "emptyDescription": "There are no files yet.",
    "download": "Download",
    "delete": "Delete",
    "deleted": "File deleted",
    "deleteFailed": "Failed to delete file"
  },
  "preview": {
    "trigger": "Preview",
    "title": "File preview",
    "download": "Download",
    "zoomIn": "Zoom in",
    "zoomOut": "Zoom out",
    "office": {
      "title": "Office file preview not available",
      "hint": "Download the file to view its contents in your Office application."
    },
    "other": {
      "title": "Preview not available",
      "hint": "Download the file to view its contents."
    },
    "text": {
      "title": "Text file",
      "hint": "Click below to load the content.",
      "load": "Load preview",
      "loading": "Loading...",
      "error": "Failed to load text: {message}"
    }
  },
  "admin": {
    "title": "Files",
    "subtitle": "Upload and manage all files in the system.",
    "stats": {
      "totalFiles": "Total Files",
      "totalSize": "Total Size"
    },
    "filter": {
      "byType": "Filter by type",
      "search": "Search by file name...",
      "allTypes": "All Types",
      "images": "Images",
      "pdf": "PDF",
      "word": "Word",
      "wordDocx": "Word (docx)",
      "excel": "Excel",
      "excelXlsx": "Excel (xlsx)",
      "powerpoint": "PowerPoint",
      "powerpointPptx": "PowerPoint (pptx)",
      "text": "Text",
      "zip": "ZIP"
    },
    "selection": {
      "selected": "{count} selected",
      "deleteSelected": "Delete Selected",
      "deleting": "Deleting...",
      "deleted": "Deleted {count} file(s)",
      "deleteFailed": "Failed to delete files"
    },
    "empty": {
      "title": "No files found",
      "description": "Try adjusting your filters or upload a new file."
    },
    "columns": {
      "file": "File",
      "size": "Size",
      "type": "Type",
      "uploaded": "Uploaded",
      "actions": "Actions"
    }
  }
}

---

本报告由资深全栈架构师基于 2026-06-25 代码状态生成，所有 P0/P1 项将在本会话内完成实施，P2 中长期项按优先级逐步推进。