文档：Docker 启动问题修复报告

添加完整的 Docker 启动问题修复报告，包括：
- 4 个问题的详细说明
- 每个问题的原因分析
- 具体的修复方案
- 验证结果和访问方式

所有问题已解决，应用现在可以正常启动。

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

DOCKER_FIX_REPORT.md

@@ -0,0 +1,159 @@
+# Docker 启动问题修复报告
+
+**修复日期**: 2026-05-14  
+**修复状态**: ✅ **完成**
+
+---
+
+## 问题概述
+
+Docker Compose 启动失败，前端编译错误和后端导入错误导致服务无法启动。
+
+---
+
+## 修复内容
+
+### 1. 前端 SCSS 编译依赖问题
+
+**问题**: `npm run build` 失败，提示缺少 `sass-embedded` 依赖
+
+**原因**: 新增的 Vue 组件（ApiPermissions.vue、PermissionMonitoring.vue 等）使用了 SCSS 样式，但 package.json 中没有安装 sass-embedded
+
+**修复**:
+```json
+// frontend/package.json
+{
+  "devDependencies": {
+    "sass-embedded": "^1.77.0"  // 新增
+  }
+}
+```
+
+**文件**: `frontend/package.json`
+
+---
+
+### 2. Vite 路径别名配置问题
+
+**问题**: Vite 构建时无法解析 `@/` 路径别名，导致导入失败
+
+**原因**: `vite.config.ts` 缺少 `resolve.alias` 配置
+
+**修复**:
+```typescript
+// frontend/vite.config.ts
+import { fileURLToPath } from "node:url";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+});
+```
+
+**文件**: `frontend/vite.config.ts`
+
+---
+
+### 3. 后端循环导入问题
+
+**问题**: 后端启动时出现循环导入错误
+
+```
+ImportError: cannot import name 'get_project_role_permissions' from partially initialized module 'app.core.project_permissions'
+```
+
+**原因**: 
+- `permission_cache.py` 在模块级别导入 `project_permissions.py` 中的函数
+- `project_permissions.py` 也导入 `permission_cache.py` 中的函数
+- 形成了循环导入
+
+**修复**: 使用延迟导入，在方法内部导入所需的函数
+
+```python
+# backend/app/core/permission_cache.py
+async def get_project_role_permissions(self, db, study_id, ttl=None):
+    # 延迟导入，避免循环导入
+    from app.core.project_permissions import get_project_role_permissions as _get_project_role_permissions
+    
+    # ... 使用 _get_project_role_permissions
+```
+
+**文件**: `backend/app/core/permission_cache.py`
+
+---
+
+### 4. 后端缺失常量问题
+
+**问题**: 导入错误，缺少 `PROJECT_PERMISSION_ROLES` 常量
+
+```
+ImportError: cannot import name 'PROJECT_PERMISSION_ROLES' from 'app.core.api_permissions'
+```
+
+**原因**: `api_permissions.py` 中定义了 `API_ENDPOINT_PERMISSIONS` 但没有定义 `PROJECT_PERMISSION_ROLES`，而 `api_permissions.py` 路由文件需要导入这个常量
+
+**修复**: 在 `api_permissions.py` 末尾添加常量定义
+
+```python
+# backend/app/core/api_permissions.py
+PROJECT_PERMISSION_ROLES = ["PM", "CRA", "PV", "MEDICAL_REVIEW", "IMP", "QA"]
+```
+
+**文件**: `backend/app/core/api_permissions.py`
+
+---
+
+## 修复提交
+
+| 提交 | 文件 | 说明 |
+|------|------|------|
+| 77b16ffa | frontend/package.json | 添加 sass-embedded 依赖 |
+| 7b397640 | frontend/vite.config.ts | 添加 Vite 路径别名配置 |
+| fdf64069 | backend/app/core/permission_cache.py | 解决循环导入问题 |
+| 50106452 | backend/app/core/api_permissions.py | 添加缺失的常量 |
+
+---
+
+## 验证结果
+
+### 服务状态
+
+```
+NAME           IMAGE                STATUS
+ctms_backend   ctms_dev-backend     Up (健康)
+ctms_db        postgres:15-alpine   Up (健康)
+ctms_nginx     ctms_dev-nginx       Up (健康)
+```
+
+### 功能验证
+
+✅ 前端编译成功  
+✅ 后端启动成功  
+✅ Nginx 代理正常  
+✅ 数据库连接正常  
+✅ 应用可访问
+
+### 访问方式
+
+- **前端应用**: http://localhost:8888
+- **后端 API**: http://localhost:8000
+- **数据库**: localhost:5432
+
+---
+
+## 总结
+
+所有 Docker 启动问题都已修复，应用现在可以正常启动和运行。修复涉及：
+
+1. **前端依赖**: 添加 SCSS 编译器依赖
+2. **前端配置**: 配置路径别名解析
+3. **后端代码**: 解决循环导入和缺失常量问题
+
+所有修复都是最小化的，不影响现有功能，只是补充了缺失的配置和依赖。
+
+---
+
+**修复完成**: ✅ 2026-05-14