后端

Go 后端(module ocm-backend,Go 1.26)。net/http ServeMux(Go 1.22+ 方法路由)+ MySQL 8。本页只写行为承诺与横切约定——实现细节看代码注释,路由与参数起测试服务器看(开发环境挂 /swagger/,契约生成物在 backend/docs/)。

横切约定(所有端点)

• 鉴权:Authorization: Bearer <JWT>(HS256、24h,无 refresh token)。公开端点仅 login/wx-bind/wx-login;小程序身份经后端 code2Session 解析 openid,X-WX-OPENID 头可伪造、永不信任。
• 权限:RBAC,handler 校验 permission 字符串(如 course:manage)而非角色名;有效权限 = 直接角色授权 ∪ 组角色授权 ∪ 直接授权(可带 expires_at,过期即失效);通配 * 仅系统 admin 角色持有,不在权限目录、API 无法授予。授权/撤销/过期即时生效(权限每请求实时计算)。权限目录在代码(authz.Catalog),GET /api/permissions 可查。
• 分页/搜索:列表接口统一信封 {items, total, page, pageSize},参数 page/page_size(默认 100、上限 500)/q(LIKE contains,已转义);导出与单条 GET 不分页。
• 错误形状:统一 {"error": "<message>"};每个响应带 X-Request-ID 头,与日志行 request_id 同源——反馈问题时引用它可精确定位那一次请求(见可观测性)。

本地运行

方式	命令	说明
最简	cd backend && APP_ENV=development go run .	需 MySQL 可达(默认 localhost:3306,ocm/ocm)
热更	cd backend && air	.air.toml;Dockerfile.dev 即用此
全栈	docker compose up -d(仓库根)	mysql + backend(air) + web(vite)

APP_ENV=development 允许 DB_HOST 缺省回落 localhost;生产模式(默认)拒绝回落。连接池调优:DB_MAX_OPEN_CONNS/DB_MAX_IDLE_CONNS/DB_CONN_MAX_LIFETIME(默认 25/25/5m)。

健康检查

• GET /healthz —— 进程存活(开库前即注册,不查 DB)。
• GET /readyz —— 就绪(开库后注册,ping DB,3s 超时,不可达 503)。

教室报修(状态机参考)

提交即 open(任何登录用户);processing/completed 由持有 repair:assign 者写入并记录处理人;confirmed 仅报修人本人可置、前置须为 completed、为终态。同教室已有 open/processing 工单时新提交返回 409(紧急报修 POST /api/repairs/emergency 例外)。images 字段为预留,暂不接收上传。

数据政策

改表结构无 ALTER 升级路径:删库重建(开发阶段策略)。部署新版本前确认数据可弃,否则先自行导出。详见 AGENTS.md 的迁移模式说明。