# Java 后端转写 — 开发日志

## 2026-04-02 Day1：完整转写 + 联调 + 菜单修复

### 一、模块剥离

将学校端、教师端、学生端、3D建模模块代码从项目中剥离，备份至 `competition-management-system-stripped-modules/`。

- 移除后端：school/（6个子模块）、ai-3d/
- 移除前端：views/school/、views/workbench/ai-3d/、views/model/
- 移除 Prisma Schema：School/Grade/Department/Class/Teacher/Student/StudentInterestClass/AI3DTask 共8个模型
- 清理跨模块引用：registrations.service（教师判断改为角色判断）、homework services（移除 class/grade 查询）
- 保留 API 存根文件：students.ts/teachers.ts/ai-3d.ts（赛事组件有引用）

### 二、Java 后端转写（239个文件，~256个API）

#### Phase 0：项目脚手架
- Spring Boot 3.2 + Java 17 + MyBatis-Plus 3.5
- JWT 认证 + Spring Security + AOP 权限注解
- 统一响应 Result<T> + PageResult<T> + 全局异常处理
- Flyway 迁移脚本（V1 表重命名 + V2 新审计字段）

#### Phase 1：认证/用户/角色/权限/租户（~35接口）
- 6个实体 + 6个Mapper + 8个DTO + 5个Service + 5个Controller
- JWT payload 与 NestJS 兼容：{sub: userId, username, tenantId}

#### Phase 2：菜单/字典/配置/日志（~25接口）
- 菜单树构建（4级嵌套）+ tenant_menus 过滤
- 日志统计（Top10操作 + 按日聚合）

#### Phase 3：赛事核心（~46接口）
- BizContest（35+字段，7个JSON列，JacksonTypeHandler）
- 报名 + 作品提交 + 团队 + 附件 + 公告

#### Phase 4：评审/计分/成果（~52接口）
- 4种计分策略：average / max / weighted / remove_max_min
- 自动分配（轮询，3评委/作品）
- Dense ranking 排名 + 自动奖项分配
- 评委库管理

#### Phase 5：作业模块（~20接口）
#### Phase 6：公众端API（~55接口，9个Controller）
#### Phase 7：UGC + 用户子女（~15接口，9个实体）
#### Phase 8：文件上传/OSS（腾讯云COS + 本地回退）

### 三、数据库适配

| 修复项 | 说明 |
|--------|------|
| configs 表添加 valid_state 列 | BaseEntity 映射需要 |
| t_contest_registration 表添加 valid_state 列 | 同上 |
| 所有表 modify_time 添加 DEFAULT CURRENT_TIMESTAMP(3) | 非BaseEntity表INSERT会报错 |
| SysLogMapper SQL 表名修正 | @Select 注解中用了新表名 |
| `rank` 加反引号 | MySQL 保留字 |
| gdlib 租户补全全套权限码（97个） | 缺少 work:submit 等权限 |
| JDBC characterEncoding=UTF-8 | 不支持 utf8mb4 |

### 四、写操作测试（22/22通过）

覆盖：用户CRUD、角色CRUD、赛事创建(含JSON)、报名、审核、作品提交、评委分配、评分、计算得分/排名/奖项、发布成果、公众注册、内容审核、文件上传。

修复：PATCH 方法去掉 @Valid（部分更新不应强制校验所有必填字段）、文件上传用绝对路径。

### 五、前端联调（20页面，69+ API调用，零错误）

Playwright 自动化测试覆盖超管端、租户端、公众端所有核心页面。

修复：registrations/stats 和 works/stats 的 contestId 改为可选参数。

### 六、端到端链路验证（16/16通过）

完整活动生命周期：租户创建活动 → 发布 → 公众报名 → 审核 → 提交作品 → 添加评委 → 分配 → 评分 → 计算得分 → 排名 → 奖项 → 发布成果 → 超管查看。

### 七、权限检查（67/67通过）

所有端所有模块的读写接口权限测试，零403错误。

### 八、菜单修复

| 问题 | 根因 | 修复 |
|------|------|------|
| 超管端显示全部52个菜单 | getUserMenus 对超管返回所有菜单 | 超管也按 tenant_menus 过滤 |
| 超管端包含数据统计 | 错误分配，数据统计是租户端专属 | 从超管 tenant_menus 移除52/53/54 |
| gdlib 菜单包含超管模块 | 远程数据库分配错误 | 重置为正确的18条 |
| gdlib 登录跳到 /super/ | Java 后端只支持 X-Tenant-Id header | 增加 tenantCode body 参数支持 |
| Knife4j 启动报错 | 4.5.0 与 Spring Boot 3.2.5 不兼容 | 降为 4.4.0 |

### 九、文档输出

- `docs/design/menu-config.md` — 各端菜单配置规范（完整ID表+登录信息+权限码）
- `docs/project/10-java-backend-test-plan.md` — 完整测试规划（190条用例）
- `backend-java/src/main/resources/db/init.sql` — 数据库初始化脚本（41张新表名）

### 十、提交记录

| Commit | 内容 |
|--------|------|
| bead1cf | 剥离学校/教师/学生/3D模块 |
| 096d06a | Java 后端完整转写（239文件） |
| a6b0565 | 数据库导出 + 权限补全 |
| 58c232d | 表名规范化 + Flyway启用 |
| 5c0d87d | 干净的 init.sql 初始化脚本 |
| 5b5af63 | 超管端菜单修复 + Knife4j降版本 |
| fd9c739 | 租户端登录修复 + gdlib菜单修正 |
| e9676ea | 菜单配置规范文档 |
| 0b989b0 | 文档完善（全量ID表+调试指南） |

---

### 明日待续

- [ ] P1测试：超管端各页面数据展示验证
- [ ] P1测试：租户端活动全流程操作
- [ ] P2测试：评委端评审流程
- [ ] P2测试：公众端注册/报名/作品提交
- [ ] 响应数据结构精调（如有前端解析不匹配）
- [ ] 生产环境部署配置