立项配置页初步优化

docs/setup-config-code-audit.md

@@ -0,0 +1,74 @@
+# 立项配置代码审计报告（2026-02）
+
+## 范围
+- 前端：`frontend/src/views/admin/ProjectDetail.vue`、`frontend/src/api/studies.ts`、`frontend/src/types/setupConfig.ts`、`frontend/src/utils/setupFieldLocator.ts`
+- 后端：`backend/app/api/v1/studies.py`、`backend/app/crud/study_setup_config.py`、`backend/app/schemas/study_setup_config.py`、`backend/app/services/setup_config_excel.py`
+- 文档：`docs/setup-config-api.md`、`docs/setup-config-curl-smoke.sh`、`docs/postman/setup-config.postman_collection.json`、`backend/scripts/smoke_setup_config.py`
+
+## 发现清单
+
+### 严重（会导致错误或明显行为偏差）
+- 无新增严重问题。
+
+### 中等（会导致交互不一致或维护风险）
+1. `ProjectDetail.vue` 中存在大量 `v-if="false"` 历史分支（Step4-7），增加阅读成本并容易引发误改。
+2. 步骤表格从“输入态表格”转“展示态 + 抽屉编辑”后，存在未清理的旧方法与旧样式残留，导致逻辑路径复杂。
+3. “发布预览”语义已切换为“当前草稿只读预览”，但文档未明确，容易与后端 `published_data` 概念混淆。
+
+### 低（代码异味/重复/可读性）
+1. `ProjectDetail.vue` 文件过长（约 3800+ 行），后续改动冲突概率高。
+2. 多个步骤编辑抽屉逻辑重复，适合后续抽象为通用 `RowEditorDrawer`。
+3. 表格列模板重复，适合后续改为列配置驱动。
+
+## 本轮已处理
+1. 删除 Step4-7 全部 `v-if="false"` 模板分支。
+2. 删除上述分支遗留的无用方法：
+   - `handleSiteMilestoneSiteChange`
+   - `handleSiteEnrollmentSiteChange`
+   - `handleCenterConfirmSiteChange`
+   - `touchStrategy`
+   - `applyStrategy`
+3. 清理无用样式：
+   - `.section-toolbar`
+   - `.setup-content.is-published-preview .section-toolbar` 相关规则
+4. 保持现有交互行为不变并完成构建验证。
+5. 修复步骤标题行按钮保护不一致问题：
+   - 第2/4/5/6/7步标题行功能键增加 `:disabled="!canEditSetup"`，避免锁定项目或无权限时误触发。
+   - 对应新增/删除/抽屉打开与保存方法统一加守卫，防止外部调用绕过前端可见状态。
+6. 收敛重复的草稿可编辑判定，新增 `canMutateDraft()` 供步骤行编辑方法复用（不改变界面行为）。
+7. 抽取步骤行编辑通用控制器（`IndexedEditorController`）与通用函数：
+   - `openIndexedEditor`
+   - `getEditingIndex`
+   - `closeIndexedEditor`
+   复用到 Step2/4/5/6/7 的单行抽屉编辑逻辑，减少重复代码。
+8. 合并重复 `onMounted` 注册逻辑，统一在单一入口完成 `loadProject` 与 `beforeunload` 监听初始化。
+9. 新增 `frontend/src/composables/useSetupConfig.ts`：
+   - 将 setup-config 相关 API 编排从页面中收口到 composable（获取/保存/发布/版本列表/回滚/版本删除/Excel 导入导出）。
+   - `ProjectDetail.vue` 改为依赖 composable 暴露的方法，降低页面对 API 层的直接耦合。
+10. 新增 `frontend/src/utils/setupDiffRows.ts`：
+   - 将“步骤差异明细”计算与字段路径可读化逻辑从 `ProjectDetail.vue` 抽离为工具函数。
+   - 页面保留项目主字段差异拼装，步骤差异统一由工具输出，降低页面认知负担。
+11. 将步骤标题行按钮显隐规则收敛为 `stepActionMode` 计算属性：
+   - 去除模板中多段 `activeStep === n && !isPublishedView` 分支。
+   - 保持按钮行为与权限控制不变，降低后续步骤扩展的修改面。
+
+## 验证结果
+1. `frontend npm run build` 通过。
+2. 后端 setup-config 核心文件通过 AST 语法解析检查。
+3. 当前环境 `npx tsc --noEmit` 失败主要来自项目既有依赖类型版本不匹配（`vue`/`element-plus`/`csstype`），非本轮立项配置改动引入。
+
+## 一致性核对结果
+1. 前后端 setup-config 路由一致：
+   - `GET/PUT /setup-config`
+   - `POST /setup-config/publish`
+   - `GET /setup-config/versions`
+   - `POST /setup-config/rollback`
+   - `DELETE /setup-config/versions/{target_version}`
+   - `GET /setup-config/export-excel`
+   - `POST /setup-config/import-excel`
+2. 前端 `setupConfig` 类型与后端 schema 字段一致（`published_data` 仍保留用于发布快照与差异比较）。
+
+## 下一步建议（不改行为）
+1. 拆分 `ProjectDetail.vue` 为步骤子组件（先拆 Step4-7）。
+2. 抽象通用行编辑抽屉组件，统一校验和保存流程。
+3. 使用列配置对象复用 `el-table-column` 渲染，降低重复模板。