Document frontend component structure

- Add docs/component-structure.md covering the current React component hierarchy, page routes, public components, API/Auth/Utils boundaries, and data flow.

- Document the internal responsibilities and split risks for large pages including ReportEditor and TemplateManage.

- Link the new component structure guide from README, docs index, AGENTS file tree, and progress notes.

AGENTS.md

@@ -210,6 +210,7 @@ npm run test:e2e
 │   ├── installation.md
 │   ├── requirements.md
 │   ├── design.md
+│   ├── component-structure.md
 │   ├── permissions.md
 │   ├── api-contract.md
 │   ├── features.md

README.md

@@ -182,6 +182,7 @@ cp .env.example .env.local
 - [docs/installation.md](./docs/installation.md)：安装、初始设置和首次验收。
 - [docs/requirements.md](./docs/requirements.md)：需求文档。
 - [docs/design.md](./docs/design.md)：设计文档。
+- [docs/component-structure.md](./docs/component-structure.md)：前端组件结构和拆分边界。
 - [docs/features.md](./docs/features.md)：功能真实性盘点。
 - [docs/testing.md](./docs/testing.md)：测试文档。
 - [docs/data-storage.md](./docs/data-storage.md)：本地数据存储说明。

docs/README.md

@@ -7,6 +7,7 @@
 - [安装与初始设置](./installation.md)：从源码到可登录系统的首次安装、端口、数据库初始化和常见问题。
 - [需求文档](./requirements.md)：业务目标、用户角色、功能需求和非功能约束。
 - [设计文档](./design.md)：前端架构、路由、状态、数据模型和关键设计取舍。
+- [前端组件结构](./component-structure.md)：页面组件、公共组件、API/Auth/Utils 分层和后续拆分边界。
 - [权限设计](./permissions.md)：已确定的角色、部门、报告、模板和 AI 上下文权限规则。
 - [进度文档](./progress.md)：当前完成度、已知风险和下一步建议。
 - [功能盘点](./features.md)：逐项区分真实可用、外部真实集成、前端演示和预留功能。

docs/component-structure.md

@@ -0,0 +1,295 @@
+# 前端组件结构
+
+本文档描述当前 React 前端的实际组织方式、页面组件边界、API/Auth/Utils 分层，以及后续拆分建议。它不把未来计划当作已实现事实；当前系统仍以页面级组件为主，只有少量公共组件。
+
+## 总体结构
+
+```text
+src/
+├── App.tsx                  # AuthProvider、Router 和路由守卫
+├── main.tsx                 # React 挂载入口
+├── index.css                # Tailwind 主题、全局样式和组件类
+├── types.ts                 # 核心前端类型和默认配置
+├── api/                     # 前端 API client 和各业务 API 封装
+├── auth/                    # 登录态 Context 和后端用户 DTO 映射
+├── components/              # 跨页面公共组件
+├── config/                  # 运行时开关
+├── pages/                   # 页面级组件，当前主要业务 UI 都在这里
+├── test/                    # Vitest/jsdom 全局测试设置
+└── utils/                   # 存储、权限、默认模板、打印等通用工具
+```
+
+当前组件层级大致为：
+
+```text
+main.tsx
+└── App
+    └── AuthProvider
+        └── BrowserRouter
+            └── RequireAuth
+                ├── Sidebar
+                └── pages/*
+```
+
+`RequireAuth` 在 `src/App.tsx` 中定义，负责前端路由保护和角色入口控制。真正的生产安全边界仍以后端 API 权限校验为准。
+
+## 路由与页面
+
+| 路由 | 页面组件 | 角色入口 | 主要职责 |
+| --- | --- | --- | --- |
+| `/` | `Login` | 未登录 | 默认数据兼容初始化、登录表单、调用 Auth Context。 |
+| `/dashboard` | `Dashboard` | 全部登录用户 | 工作台统计、趋势和快捷入口。 |
+| `/report-editor` | `ReportEditor` | 全部登录用户 | 新建/编辑报告、富文本、字段同步、视频抽帧、AI、语音、保存。 |
+| `/report-manage` | `ReportManage` | 全部登录用户 | 报告列表、搜索筛选、历史恢复、删除、导出。 |
+| `/report-view/:id` | `ReportView` | 全部登录用户 | 报告查看、受控报告读取、浏览器打印。 |
+| `/template-manage` | `TemplateManage` | 超级管理员、管理员 | 模板内容、字段库、图片资源、导入导出。 |
+| `/user-manage` | `UserManage` | 超级管理员、管理员 | 用户、部门、模板授权和签名维护。 |
+| `/audit-logs` | `AuditLogs` | 超级管理员、管理员 | 审计日志列表、筛选和展示。 |
+| `/system-settings` | `SystemSettings` | 全部登录用户 | 全局设置和个人默认模板；超级管理员可维护 AI/语音/抽帧。 |
+
+页面组件普遍直接组合 UI、状态、API 调用和本地兼容缓存逻辑。新增复杂功能时应优先判断是否需要抽到 `api/`、`utils/` 或新的子组件中，避免继续扩大巨型页面。
+
+## 公共组件
+
+### `src/components/Sidebar.tsx`
+
+当前唯一跨页面公共组件。职责包括：
+
+- 根据 Auth Context 中的当前用户展示导航入口。
+- 在 Auth Context 不可用时回退读取 `localStorage.currentUser`。
+- 在 `/report-editor` 和 `/template-manage` 中自动折叠。
+- 调用 `auth.logout()` 退出登录，并清理本地登录态。
+
+测试：`src/components/Sidebar.test.tsx` 覆盖角色菜单过滤。
+
+## 认证层
+
+### `src/auth/AuthContext.tsx`
+
+`AuthProvider` 是前端登录态入口：
+
+- 启动时调用 `/api/auth/me` 恢复后端 Session。
+- `login` 调用 `/api/auth/login`。
+- `logout` 调用 `/api/auth/logout` 并清理本地 `currentUser`。
+- `syncUser` 把后端安全用户 DTO 转为前端 `User`，并同步迁移期本地缓存。
+
+### `src/auth/backendUser.ts`
+
+负责后端用户模型到前端历史类型的兼容映射：
+
+- 后端 `doctor` 映射为前端 `user`。
+- 后端 `departmentName` 映射为前端 `department`。
+- 部门模板授权映射为 `visibleTemplates` 和 `manageableTemplates`。
+
+新增用户字段时，应优先在后端 DTO、`backendUser.ts`、`src/types.ts` 和对应测试中一起更新。
+
+## API 层
+
+`src/api/client.ts` 是唯一底层请求封装：
+
+- 默认请求相对路径 `/api/...`。
+- 请求带 `credentials: 'include'`，用于 HttpOnly Session Cookie。
+- 解包后端 `{ data }` 响应。
+- 统一抛出 `ApiError`。
+
+业务 API 按资源拆分：
+
+| 文件 | 职责 |
+| --- | --- |
+| `ai.ts` | AI 模型列表和聊天代理。 |
+| `audit.ts` | 审计日志查询。 |
+| `dashboard.ts` | 工作台统计。 |
+| `files.ts` | 签名、模板图片、视频、关键帧等文件资源。 |
+| `library.ts` | 字段库和选项库。 |
+| `reports.ts` | 报告列表、详情、保存和删除。 |
+| `settings.ts` | 系统设置读取、保存、重置。 |
+| `speech.ts` | 讯飞语音 WebSocket URL 生成。 |
+| `templates.ts` | 模板列表、详情、创建、更新、删除。 |
+| `users.ts` | 用户、部门和部门模板授权。 |
+
+页面组件不应直接拼接第三方 API 或绕过 `api/client.ts` 调后端。新增后端接口时，优先新增或扩展对应 `src/api/*.ts`，再由页面调用。
+
+## 工具层
+
+| 文件 | 职责 |
+| --- | --- |
+| `storage.ts` | `localStorage/sessionStorage` JSON 封装，`systemSettings` 做兼容混淆读取。 |
+| `permissions.ts` | 前端角色、报告可见性和模板可见性判断。仅用于体验和开发回退。 |
+| `defaultContent.ts` | 默认报告 HTML 模板，包含 `data-bind` 字段、图片占位符和 AI 区域。 |
+| `print.ts` | iframe 打印工具。 |
+
+工具层应保持无 React UI 依赖。业务规则如果已后端化，应以后端策略为准，前端工具只做展示过滤或离线回退。
+
+## 页面内部结构
+
+### `Login`
+
+主要职责：
+
+- 初始化迁移期默认数据：用户、模板、字段、图片资源、系统设置。
+- 提交登录表单到 `AuthContext.login`。
+- 展示默认测试账号。
+
+注意：真实账号认证已由后端处理，本地 `users.password` 只是旧兼容数据，不是安全边界。
+
+### `Dashboard`
+
+主要职责：
+
+- 调用 `getDashboardStats` 读取后端统计。
+- 根据角色展示报告、用户、模板、近期趋势和快捷入口。
+- API 不可用且本地回退开启时，从本地报告、用户、模板构造统计。
+
+### `ReportEditor`
+
+当前最大页面组件，约 3000 行。它同时承担 UI、状态、富文本编辑、媒体处理和 API 调用。
+
+主要内部区域：
+
+- 顶部工具栏：返回、保存草稿、完成报告、打印等操作。
+- 基本信息表单：由字段库和 `reportData` 驱动。
+- 报告正文编辑区：`contentEditable` HTML、智能字段和图片占位符。
+- 视频分析区：视频上传、预览、自动抽帧、手动截帧。
+- 关键帧列表：点击插入、拖拽插入、后端文件上传状态。
+- AI 撰写面板：对话、区域改写、差异确认和 AI 日志导出。
+- 语音输入：浏览器麦克风采集，连接 `/api/speech/iat`。
+- 保存逻辑：优先调用 Reports API，并同步 `ReportMedia` 所需的视频/关键帧引用。
+
+重要状态来源：
+
+- `reportData`：报告结构化字段。
+- `contentRef`：报告正文 DOM。
+- `videos` / `capturedFrames`：视频和关键帧。
+- `settings`：系统设置、抽帧策略、AI/语音开关。
+- `formFields`：字段库。
+- `chatMessages` / AI 相关状态：AI 面板上下文。
+
+后续拆分优先级：
+
+1. 抽出报告基本信息表单。
+2. 抽出富文本工具栏和正文编辑器适配层。
+3. 抽出视频上传/抽帧/关键帧列表。
+4. 抽出 AI 面板和 Diff 确认弹窗。
+5. 抽出报告保存 hook，例如 `useReportPersistence`。
+
+拆分时要保持字段绑定、图片占位符、历史恢复和保存顺序兼容。
+
+### `ReportManage` 与 `ReportView`
+
+`ReportManage` 负责列表型工作流：
+
+- 调用 Reports API 获取权限过滤后的报告。
+- 前端搜索、状态筛选和日期筛选。
+- 删除报告、历史恢复、JSON 导出和批量操作。
+
+`ReportView` 负责只读展示：
+
+- 调用 Reports API 获取详情。
+- 渲染报告 HTML。
+- 调用 `printDocument` 进入浏览器打印。
+
+这两个页面与 `ReportEditor` 通过路由和 `sessionStorage.restore_${reportId}` 协作。
+
+### `TemplateManage`
+
+当前第二大页面组件，约 1800 行。职责包括：
+
+- 模板列表、选择、新增、复制、删除。
+- 模板正文 `contentEditable` 编辑。
+- 富文本命令、表格、字段、图片占位符、AI 区域插入。
+- 字段库维护。
+- 模板图片资源上传和删除。
+- 模板 JSON 导入导出。
+
+后续拆分优先级：
+
+1. 抽出模板列表和模板元信息编辑。
+2. 抽出模板内容编辑器和工具栏。
+3. 抽出字段库管理面板。
+4. 抽出图片资源管理面板。
+5. 抽出导入导出工具。
+
+### `UserManage`
+
+主要职责：
+
+- 调用 Users API 管理用户。
+- 调用 Departments API 读取部门和更新模板授权。
+- 管理角色、状态、密码、签名和部门模板权限。
+- 校验默认超级管理员、当前用户、管理员唯一性等 UI 规则。
+
+后端仍会做最终权限校验；前端限制只用于减少误操作。
+
+### `SystemSettings`
+
+主要职责：
+
+- 调用 Settings API 读取、保存和重置系统设置。
+- 超级管理员维护抽帧、自动插入、AI Provider、讯飞配置。
+- 普通用户主要维护个人默认模板。
+- 本地回退开启时，API 不可用才读取或保存本地 `systemSettings`。
+
+AI Key 和讯飞密钥由后端代理使用，普通用户读取设置时不会拿到真实密钥。
+
+### `AuditLogs`
+
+主要职责：
+
+- 调用 Audit API 获取审计日志。
+- 支持动作、目标类型、关键字和分页筛选。
+- 格式化元数据、动作名称和目标类型。
+
+管理员只能看到后端允许范围内的日志，超级管理员可看全部。
+
+## 数据流
+
+常见后端化数据流：
+
+```text
+Page Component
+  └── src/api/<resource>.ts
+      └── apiRequest()
+          └── /api/<resource>
+              └── NestJS module/service
+                  └── Prisma/PostgreSQL or file storage
+```
+
+登录态数据流：
+
+```text
+Login
+  └── AuthContext.login()
+      └── POST /api/auth/login
+          └── HttpOnly Session Cookie
+              └── AuthContext.refresh()
+                  └── GET /api/auth/me
+```
+
+开发/迁移期兼容数据流：
+
+```text
+Page Component
+  ├── Try backend API first
+  └── If API failed and VITE_ENABLE_LOCAL_FALLBACK=true
+      └── localStorage/sessionStorage compatibility path
+```
+
+生产构建默认不应依赖本地回退作为主要数据来源。
+
+## 新增组件约定
+
+- 复用业务 API 封装，不在组件中重复写 `fetch('/api/...')`。
+- 页面级入口继续放在 `src/pages`；跨页面复用 UI 放在 `src/components`。
+- 只在复杂页面拆分局部子组件时，可以先放在同目录附近；若开始跨页面复用，再移动到 `src/components`。
+- 状态管理优先保持局部化；只有登录态使用 Auth Context。
+- 业务规则优先放后端或 `src/utils`，不要散落在 JSX 条件里。
+- 新增复杂组件应配套测试，至少覆盖权限入口、API 错误分支或关键交互之一。
+- 修改 `ReportEditor`、`TemplateManage` 这类大组件时，避免顺手重构无关区域；优先小步拆分并保留行为测试。
+
+## 当前结构风险
+
+- `ReportEditor.tsx` 过大，媒体、AI、语音、富文本和保存逻辑耦合高。
+- `TemplateManage.tsx` 同时承担编辑器、字段库、资源库和导入导出。
+- 多个页面仍保留本地兼容回退，阅读时要区分主后端路径和回退路径。
+- 前端权限工具仍存在，但不能当作生产安全边界。
+- HTML 编辑和渲染依赖 `contentEditable` 与 `dangerouslySetInnerHTML`，拆分时必须保持清洗、打印和字段绑定一致。

docs/progress.md

@@ -73,3 +73,4 @@
 | 2026-05-02 | 新增 Dashboard API、数据库 Session Store、审计服务、HTML 白名单清洗、本地回退开关和 Docker 上传目录 volume，清理 Gemini 旧依赖。 |
 | 2026-05-02 | 新增审计日志查询 API/页面、Auth Context 路由角色守卫，并把 Playwright E2E 改为真实后端 API seed。 |
 | 2026-05-02 | 新增安装与初始设置文档，补充首次启动、端口规划、数据库初始化、验收步骤和常见问题。 |
+| 2026-05-02 | 新增前端组件结构文档，梳理页面组件、公共组件、API/Auth/Utils 分层、数据流和大组件拆分边界。 |