# HKU ICB ClassHub Agent Guide 本文件用于约束后续 agent 与开发者在本项目中的工作方式。目标是让每次改动都符合项目定位、权限模型、技术栈和现有设计语言，避免临时拼接式开发。 ## 1. 项目定义 本项目是 HKU ICB Graduate Class Resource Platform，面向班级、教师、学生和班委的班级资源与协作系统。核心价值是围绕“班级”组织信息，提供可信、清晰、轻量的日常管理能力。 主要模块包括： - 登录、激活、账号审核与个人资料 - 班级与成员管理 - 通讯录、时间线、公告、课程日程、资源、作业、投票、班费 - 通知、上传与外部存储 开发时必须优先保护以下产品原则： - 班级数据隔离优先，任何列表、详情、写入都要明确 class scope。 - 权限优先于界面便利，不允许只靠前端隐藏按钮来保证安全。 - 管理功能要清晰可审计，避免隐式批量修改。 - 面向真实班级使用场景，界面应安静、稳定、易扫描，不做营销页式表达。 ## 2. 技术栈与目录 仓库结构： - `backend/`：FastAPI 后端，SQLAlchemy async ORM，Alembic 迁移，SQLite 默认部署数据源。 - `frontend/`：Next.js App Router 前端，React 19，TypeScript，Tailwind CSS 4，shadcn/base-ui 风格组件，lucide-react 图标。 - `nginx/`：反向代理配置。 - `docker-compose.yml`：本地或服务器编排，前端端口映射为 `3008:3000`，后端为 `8000`。 关键命令： - 前端开发：`cd frontend && npm run dev` - 前端构建：`cd frontend && npm run build` - 前端检查：`cd frontend && npm run lint` - 后端运行：`cd backend && uvicorn app.main:app --reload` - 后端迁移：`cd backend && alembic upgrade head` - 整体容器：`docker compose up --build` 注意：`frontend/AGENTS.md` 已明确提示 Next.js 版本存在重要变化。修改 Next.js 相关 API、路由、缓存、服务端/客户端组件边界前，应以本仓库安装版本与本地文档为准，不要凭旧版本记忆实现。 ## 3. 架构约束 ### 后端分层 后端代码按以下边界组织： - `app/api/`：HTTP 路由层，只处理请求参数、依赖注入、状态码与响应。 - `app/services/`：业务逻辑层，承载跨模型操作、校验、查询组合和副作用。 - `app/schemas/`：Pydantic 输入输出模型。 - `app/db/models.py`：SQLAlchemy 数据模型。 - `app/core/`：鉴权、依赖、权限与通用基础能力。 - `app/config.py`：环境配置，统一使用 `CH_` 前缀。 开发规则： - 新业务优先放入 service，不要把复杂逻辑堆在 route handler。 - 数据库访问使用 async SQLAlchemy，不引入同步 session。 - 查询关系时优先使用 `selectinload` 等显式加载策略，避免隐式懒加载导致异步上下文问题。 - 新增或修改表结构必须提供 Alembic migration，不允许只改 model。 - 错误信息面向用户时要清晰，面向系统时要保留日志；不要把密钥、token、内部堆栈暴露给前端。 ### 前端分层 前端代码按以下边界组织： - `src/app/`：页面与布局，App Router 路由入口。 - `src/components/`：跨页面业务组件。 - `src/components/ui/`：基础 UI 组件，尽量保持通用和低业务耦合。 - `src/hooks/`：认证、通知、当前班级、侧边栏等状态逻辑。 - `src/lib/`：API 客户端、类型、权限、常量、工具函数。 开发规则： - 复用 `src/lib/api.ts` 中的 `fetchAPI`、`postAPI`、`putAPI`、`deleteAPI`、`uploadAPI`，不要在页面中散落裸 `fetch`。 - 复用 `src/lib/permissions.ts` 判断前端可见性，但后端仍必须做真实权限校验。 - 能用已有 UI 组件就不要新写一套样式系统。 - 表单提交、加载、空状态、错误状态、成功反馈都要完整处理。 - 客户端组件只在需要浏览器状态、事件、localStorage、交互状态时使用。 ## 4. 权限与数据边界 系统存在两层权限： - 全局角色：`super_admin`、`teacher`、`student` - 班级内角色与权限：由 `ClassMembership` 的 `membership_role`、`committee_role`、`class_permissions` 控制 后端权限入口主要在 `app/core/deps.py`： - `get_current_user` - `require_role` - `resolve_class_id_for_user` - `ensure_class_access` - `ensure_class_permission` 权限开发必须遵守： - 任何班级资源 API 都必须解析并校验 `class_id`。 - student 只能访问自己所属班级的数据。 - teacher 与 super_admin 的跨班级访问能力必须通过后端依赖或 service 显式表达。 - 新增班级模块时，要同步更新后端 `CLASS_PERMISSIONS`、`TEACHER_DEFAULT_PERMISSIONS`，前端权限类型、常量、导航与模块启用逻辑。 - 前端隐藏按钮只是体验优化，不是安全边界。 ## 5. 设计规范 本项目不是营销网站，而是班级运营工具。界面应更像可靠的工作台：信息密度适中、层级清楚、操作明确。 视觉方向： - 采用现有 Tailwind 4 token 与 `globals.css` 中的主题变量。 - 保持温暖、克制、学术感的视觉语气，不要突然引入高饱和大渐变或强装饰背景。 - 图标优先使用 `lucide-react`。 - 卡片、弹窗、表格、表单、按钮优先复用 `src/components/ui/`。 - 中文界面文案要简洁、具体，避免“智能化”“一站式”等空泛营销词。 布局规则： - 后台页面优先服务浏览、筛选、创建、编辑、审核等真实任务。 - 列表页必须考虑空状态、加载态、错误态和分页或数据量增长。 - 管理页的危险操作必须有确认弹窗。 - 移动端至少保证主要阅读、筛选和提交流程可用。 - 不在工具型页面中加入大 hero、宣传区、装饰性卡片堆叠。 交互规则： - 成功、失败、权限不足、登录过期要给出明确反馈。 - 上传、提交、删除、批量操作要有 pending 状态，避免重复提交。 - 需要选择班级的页面，应与 `use-active-class` 等现有机制保持一致。 ## 6. API 与数据契约 后端响应模型应由 `app/schemas/` 定义，前端类型应在 `src/lib/types.ts` 中保持同步。 约定： - API 路径统一放在 `/api/...` 下。 - 新增字段时同时检查 model、schema、service、API、前端 type、表单、列表展示。 - 日期时间字段使用明确语义，例如 `created_at`、`updated_at`、`start_time`、`end_time`。 - JSON 字符串字段已有历史用法时，可沿用模型中的 helper 方法；新增复杂结构时优先评估是否需要独立表。 - 不把数据库内部字段、密码 hash、验证码 hash、密钥配置返回给前端。 ## 7. 数据库与迁移 数据库相关改动必须遵守： - 修改 `app/db/models.py` 后必须新增 Alembic migration。 - migration 文件命名要包含日期或清晰语义。 - migration 要能从旧库升级，不假设空库。 - 对生产已有数据的字段变更要考虑 backfill、默认值和 nullable 策略。 - 不直接删除历史字段或表，除非确认没有线上依赖，并在 migration 中清楚表达。 SQLite 是当前部署默认数据库，避免使用 SQLite 不支持或行为差异明显的 SQL 特性，除非同时处理兼容方案。 ## 8. 安全规范 - 密钥、SMTP、COS、JWT 等配置只通过 `.env` 和环境变量提供，不提交真实值。 - JWT secret 生产环境必须覆盖默认值。 - 上传能力必须限制文件类型、大小与访问路径，避免任意文件执行或路径穿越。 - 邮箱验证码、密码、token 等敏感值只存 hash 或安全派生值。 - 日志中不得打印密码、验证码、完整 token、COS secret。 - CORS 配置应随部署域名收敛，不为方便调试长期开放任意来源。 ## 9. 开发工作流 开始修改前： - 先读相关 route、service、schema、model、前端 page/component/type。 - 确认是否已有相同模式，优先复用。 - 用 `rg` 搜索模块名、权限名、API 路径和类型定义，避免漏改。 实现时： - 小步提交代码，保持每次改动有明确目的。 - 不做与需求无关的大重构。 - 不删除用户已有改动。 - 不引入新依赖，除非能明显降低复杂度，并更新安装与构建说明。 - Python 代码遵循当前项目风格和类型标注；TypeScript 避免 `any`，优先定义明确类型。 交付前至少检查： - 前端：`npm run lint`，重要 UI 改动再跑 `npm run build`。 - 后端：能启动应用；涉及数据库时跑迁移；核心 service 改动要用脚本或测试验证主路径。 - API 契约：前后端字段、错误处理、权限处理一致。 - 浏览器体验：关键页面没有明显布局破损、重复提交、空白状态。 ## 10. 新功能 Checklist 新增一个业务模块时，按顺序检查： - 数据模型是否需要新增表或字段。 - Alembic migration 是否完整。 - Pydantic schema 是否覆盖创建、更新、读取。 - service 是否包含权限、班级边界、业务校验。 - API router 是否挂载到 `app/main.py`。 - 前端 type 是否同步。 - API client 调用是否使用 `src/lib/api.ts`。 - 页面是否接入侧边栏、权限可见性、模块启用状态。 - 是否有加载、空、错、成功状态。 - 是否需要通知、上传、分页或搜索。 - 是否更新常量、权限集合和文案。 ## 11. Agent 行为准则 后续 agent 在本仓库工作时，应遵守： - 用中文与项目维护者沟通，技术名词可保留英文。 - 先理解项目边界，再动手改代码。 - 发现需求与权限、安全、数据隔离冲突时，主动指出并给出更安全的实现。 - 能直接完成的任务直接实现，不只给建议。 - 修改前说明将改哪些区域；修改后说明改了什么、如何验证、还剩什么风险。 - 遇到 Next.js、React、FastAPI、SQLAlchemy 等版本敏感问题时，以本仓库依赖版本和官方文档为准。 - 保持代码和文档简洁，避免过度抽象。