From 81afc75cc39f7c62b2d873fc75e3f826f1f0db3f Mon Sep 17 00:00:00 2001 From: chenyuan Date: Tue, 23 Jun 2026 14:59:09 +0800 Subject: [PATCH] docs: plan teacher admin implementation --- ...2026-06-23-teacher-admin-implementation.md | 306 ++++++++++++++++++ 1 file changed, 306 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-23-teacher-admin-implementation.md diff --git a/docs/superpowers/plans/2026-06-23-teacher-admin-implementation.md b/docs/superpowers/plans/2026-06-23-teacher-admin-implementation.md new file mode 100644 index 0000000..405e571 --- /dev/null +++ b/docs/superpowers/plans/2026-06-23-teacher-admin-implementation.md @@ -0,0 +1,306 @@ +# 管理型老师权限改造 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the school-admin direction with platform-managed teacher administrator permissions, using teacher accounts plus class creator ownership. + +**Architecture:** Keep the existing teacher role and teacher-end pages. Add `teacher_admin` to `userinfo` for platform-assigned management capability, and add `created_by` to `school_class` for ownership. Backend enforces all ownership rules; frontend only hides unavailable actions for usability. + +**Tech Stack:** Spring Boot 2.7, MyBatis generated entities/mappers, Vue 3 + Vite + Element Plus, JUnit 5. + +--- + +## File Structure + +Backend files: + +- Modify `src/main/java/com/sztzjy/linkCommerce/entity/Userinfo.java`: add `teacherAdmin` Boolean field. +- Modify `src/main/java/com/sztzjy/linkCommerce/entity/UserinfoExample.java`: add criteria for `teacher_admin`. +- Modify `src/main/resources/mappers/UserinfoMapper.xml`: map `teacher_admin` column in base result map, base columns, insert, selective insert, update. +- Modify `src/main/java/com/sztzjy/linkCommerce/entity/SchoolClass.java`: add `createdBy` and `createdByName` fields. +- Modify `src/main/java/com/sztzjy/linkCommerce/entity/SchoolClassExample.java`: add criteria for `created_by`. +- Modify `src/main/resources/mappers/SchoolClassMapper.xml`: map `created_by` column, keep `createdByName` as response-only. +- Add `docs/sql/2026-06-23-teacher-admin-permissions.sql`: schema changes for `userinfo.teacher_admin` and `school_class.created_by`. +- Modify `src/main/java/com/sztzjy/linkCommerce/controller/platformadmin/PlatformAdminController.java`: rename school-admin endpoints behaviorally into teacher management endpoints while preserving old endpoints only if needed for compatibility. +- Modify `src/main/java/com/sztzjy/linkCommerce/service/PlatformAdminService.java` and `src/main/java/com/sztzjy/linkCommerce/service/impl/PlatformAdminServiceImpl.java`: add teacher save preparation for platform admin, force role 3. +- Modify `src/main/java/com/sztzjy/linkCommerce/controller/stu/UserController.java`: enforce non-platform teacher creation defaults `teacherAdmin=false`, set class `createdBy`, enforce class/student ownership rules. +- Modify `src/main/java/com/sztzjy/linkCommerce/controller/stu/TaskAllocationController.java`: require current user and reject task updates for classes not created by current teacher. +- Modify `src/main/java/com/sztzjy/linkCommerce/controller/stu/LoginController.java`: return `teacherAdmin` in login/user info payload. +- Modify or add backend tests under `src/test/java/com/sztzjy/linkCommerce/...`: cover platform teacher admin flag, non-platform default false, class ownership and delete-teacher guard. + +Frontend files: + +- Modify `src/router/index.js`: remove or hide schoolAdmin routes; change platform school-admin menu copy to teacher management. +- Modify `src/api/schoolAdmin.js` or create `src/api/platformTeacher.js`: expose platform teacher management API. +- Modify platform admin teacher-management view currently under `src/views/platformAdmin/...` or school-admin page: show teacher fields and `是否管理型老师`. +- Modify `src/views/teacherEnd/class/index.vue`: show class creator, hide action buttons for classes not owned by current teacher. +- Modify `src/views/teacherEnd/student/index.vue`: restrict add/import class options to owned classes; hide edit/delete/reset/init for non-owned students. +- Modify `src/views/teacherEnd/task/index.vue`: allow all-class viewing, disable save for non-owned class. +- Modify teacher import/upload API usage to avoid hard-coded host and route through current frontend proxy. + +## Task 1: Backend Data Fields + +**Files:** +- Modify: `src/main/java/com/sztzjy/linkCommerce/entity/Userinfo.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/entity/UserinfoExample.java` +- Modify: `src/main/resources/mappers/UserinfoMapper.xml` +- Modify: `src/main/java/com/sztzjy/linkCommerce/entity/SchoolClass.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/entity/SchoolClassExample.java` +- Modify: `src/main/resources/mappers/SchoolClassMapper.xml` +- Create: `docs/sql/2026-06-23-teacher-admin-permissions.sql` +- Test: `src/test/java/com/sztzjy/linkCommerce/entity/TeacherAdminModelTest.java` + +- [ ] **Step 1: Write failing entity test** + +Create `TeacherAdminModelTest` with assertions that `Userinfo` has `teacherAdmin`, `SchoolClass` has `createdBy`, and `SchoolClass` has response-only `createdByName`. + +Run: `mvn -Dtest=TeacherAdminModelTest test` +Expected: compile failure because fields do not exist. + +- [ ] **Step 2: Add entity fields** + +Add `teacherAdmin` Boolean with getter/setter to `Userinfo`. + +Add `createdBy` String with getter/setter and `createdByName` String with getter/setter to `SchoolClass`. + +- [ ] **Step 3: Update MyBatis mappings** + +Map `userinfo.teacher_admin` to `teacherAdmin`. + +Map `school_class.created_by` to `createdBy`. + +Do not map `createdByName` to a physical column. + +- [ ] **Step 4: Add schema SQL** + +Create SQL: + +```sql +ALTER TABLE userinfo + ADD COLUMN teacher_admin TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否管理型老师：0-否 1-是'; + +ALTER TABLE school_class + ADD COLUMN created_by VARCHAR(64) NULL COMMENT '班级创建人教师用户ID'; +``` + +- [ ] **Step 5: Verify** + +Run: `mvn -Dtest=TeacherAdminModelTest test` +Expected: PASS. + +Run: `mvn test` +Expected: PASS. + +- [ ] **Step 6: Commit** + +Commit message: `feat: add teacher admin ownership fields` + +## Task 2: Platform Teacher Management + +**Files:** +- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/platformadmin/PlatformAdminController.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/service/PlatformAdminService.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/service/impl/PlatformAdminServiceImpl.java` +- Test: `src/test/java/com/sztzjy/linkCommerce/service/impl/PlatformAdminServiceImplTest.java` +- Test: `src/test/java/com/sztzjy/linkCommerce/controller/platformadmin/PlatformAdminControllerTest.java` + +- [ ] **Step 1: Write failing tests** + +Add tests proving: + +- Platform-created teacher can have `teacherAdmin=true`. +- Platform-created teacher always has role `3`. +- Platform delete teacher is rejected when any class has `createdBy` equal to that teacher id. + +Run: `mvn -Dtest=PlatformAdminServiceImplTest,PlatformAdminControllerTest test` +Expected: FAIL because teacher-preparation and delete guard do not exist. + +- [ ] **Step 2: Implement platform teacher preparation** + +Add service method `prepareTeacherForSave(Userinfo userinfo, String schoolId)`: + +- set role to `3` +- set school id +- keep platform-provided `teacherAdmin` +- default null `teacherAdmin` to `false` +- default password to `123qwe` + +- [ ] **Step 3: Update platform endpoints** + +Add platform teacher endpoints or repurpose school-admin endpoint names: + +- list teachers by school/name/username/phone +- create teacher +- update teacher +- delete teacher with class-created guard + +- [ ] **Step 4: Verify** + +Run: `mvn -Dtest=PlatformAdminServiceImplTest,PlatformAdminControllerTest test` +Expected: PASS. + +Run: `mvn test` +Expected: PASS. + +- [ ] **Step 5: Commit** + +Commit message: `feat: manage teachers from platform admin` + +## Task 3: Teacher-Side Backend Permission Enforcement + +**Files:** +- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/UserController.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/TaskAllocationController.java` +- Modify: `src/main/java/com/sztzjy/linkCommerce/controller/stu/LoginController.java` +- Test: `src/test/java/com/sztzjy/linkCommerce/controller/stu/UserControllerTeacherAdminTest.java` +- Test: `src/test/java/com/sztzjy/linkCommerce/controller/stu/TaskAllocationControllerTest.java` + +- [ ] **Step 1: Write failing tests** + +Add tests proving: + +- Non-platform teacher creation forces `teacherAdmin=false`. +- Adding a class sets `createdBy` to current teacher id. +- Editing/deleting/initializing a class is rejected when `createdBy` differs from current teacher id. +- Adding/importing/editing/deleting student is rejected when the target student's class was not created by current teacher. +- Task update is rejected when target class was not created by current teacher. +- Login payload includes `teacherAdmin`. + +Run: `mvn -Dtest=UserControllerTeacherAdminTest,TaskAllocationControllerTest test` +Expected: FAIL for missing ownership enforcement. + +- [ ] **Step 2: Require current user for mutating teacher-end operations** + +Use token-derived user where available. Where legacy endpoints currently receive `userId`, validate that the token user matches or reject mismatches. + +- [ ] **Step 3: Implement helper checks** + +Add helpers: + +- `requireTeacherAdminOrPlatform` +- `isClassOwner` +- `requireClassOwner` +- `requireStudentClassOwner` + +Return clear `BAD_REQUEST` messages for unauthorized actions. + +- [ ] **Step 4: Enforce defaults** + +Every non-platform teacher creation and import path sets `teacherAdmin=false` server-side. + +- [ ] **Step 5: Verify** + +Run targeted tests and `mvn test`. + +- [ ] **Step 6: Commit** + +Commit message: `feat: enforce teacher admin ownership rules` + +## Task 4: Platform Frontend Teacher Management + +**Files:** +- Modify: `src/router/index.js` +- Modify/Create: platform teacher API file +- Modify: platform teacher management view + +- [ ] **Step 1: Add failing lightweight check** + +Add or run a route/API search check that confirms no active label says “学校管理员管理” for the platform teacher management route. + +- [ ] **Step 2: Rename platform menu** + +Change menu label to `教师管理`. + +Remove active school-admin role wording from visible UI. + +- [ ] **Step 3: Add teacher-admin switch** + +In platform teacher add/edit forms, add `是否管理型老师` switch. + +In teacher table, show `是/否`. + +- [ ] **Step 4: Wire API** + +Use platform teacher endpoints. + +Do not show this switch in non-platform teacher pages. + +- [ ] **Step 5: Verify** + +Run: `npm run build:prod` +Expected: PASS. + +- [ ] **Step 6: Commit** + +Commit message: `feat: update platform teacher management` + +## Task 5: Teacher-End Ownership UI + +**Files:** +- Modify: `src/views/teacherEnd/class/index.vue` +- Modify: `src/views/teacherEnd/student/index.vue` +- Modify: `src/views/teacherEnd/task/index.vue` +- Modify: `src/api/teacher.js` + +- [ ] **Step 1: Class page** + +Show class creator. Only show edit/delete/init buttons when row `createdBy` equals current user id. + +- [ ] **Step 2: Student page** + +Show all students. Add/import class dropdowns list only classes owned by current user. Row actions only appear when the student's class creator equals current user id. + +- [ ] **Step 3: Task page** + +Show all classes. Show task status for all classes. Disable save/distribution operation when the selected class is not owned by current user. + +- [ ] **Step 4: Remove hard-coded upload hosts** + +Use relative API/proxy paths for teacher and student import. + +- [ ] **Step 5: Verify** + +Run: `npm run build:prod` +Expected: PASS. + +- [ ] **Step 6: Commit** + +Commit message: `feat: apply teacher ownership UI rules` + +## Task 6: Clean Up School Admin Direction + +**Files:** +- Modify: `src/router/index.js` +- Modify: school-admin frontend menu/page references +- Optionally deprecate backend school-admin tests/controllers without deleting until confirmed safe + +- [ ] **Step 1: Hide school-admin routes** + +Remove school-admin routes from active router arrays so users cannot enter that path. + +- [ ] **Step 2: Keep backend compatibility temporarily** + +Leave backend school-admin controllers in place unless product explicitly approves deletion, because deleting endpoints can break existing test data or bookmarks. + +- [ ] **Step 3: Verify** + +Run backend tests and frontend build. + +- [ ] **Step 4: Commit** + +Commit message: `chore: hide obsolete school admin entry` + +## Final Verification + +- [ ] Run `mvn test`. +- [ ] Run `npm run build:prod`. +- [ ] Restart backend from rebuilt jar. +- [ ] Restart frontend dev server. +- [ ] Manual smoke test: + - platform super admin can create teacher admin + - non-platform teacher creation creates ordinary teacher + - teacher admin can view all classes + - teacher admin can only modify owned classes + - teacher admin can only modify students in owned classes + - task save is blocked for non-owned class + - score export still works