Cheng Zhou
75 lines
4.4 KiB
Markdown
75 lines
4.4 KiB
Markdown
# 立项配置代码审计报告（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` 渲染，降低重复模板。
|