| name | kaoshi-development |
| description | 维护 kaoshi 考试平台时使用。适用于修改 Java、Spring Boot、MySQL、Redis、Vue、TypeScript、接口契约、数据模型、权限、考试作答、评分、成绩、测试、README、spec、AGENTS、skills 或运行配置；要求先确认事实、维护 plan，再按生产级验收闭环交付。 |
kaoshi Development
每次接手都先确认当前仓库事实，再执行任务。事实来自 spec.md、AGENTS.md、README.md、后端代码、前端代码、数据库脚本、测试、配置、git 状态、命令结果和 owner 明确输入；如果当前任务存在 plan.md，事实也来自 plan.md。
核心规则
- 先确认事实，再按任务需要写或更新
plan.md，然后实现。
- 不把未实现能力写成当前事实。
- 不交半成品。
- 架构、类型、测试、文档和验证必须作为同一次交付的一部分。
- kaoshi 是快速演进项目，当前生产级目标高于历史形态。
- 数据结构、接口、页面、测试和文档需要重建时，直接建立当前主干。
- 数据库脚本承载当前初始化事实；结构变化后以清空数据库、重新初始化和重新验收为准。
- 历史数据保留、旧接口保留和旧页面保留只在 owner 明确要求并写入当次
plan.md 后执行。
- Excel、文件上传、富媒体展示、表格、分页、表单校验、权限勾选、树形组织、路由和状态管理使用项目已有框架、组件和工具链承载。
文件职责
- 单一职责看变化原因，不看行数。
- 超过 300 行必须触发职责审查，但不是自动拆分理由。
- 能一句话说清职责、变化原因一致、内部耦合合理，可以保留。
- 状态管理、规则计算、数据读写、渲染展示、外部接线、错误兼容、业务判断混在一起时，必须拆清边界。
- 不为了拆而拆，不为了省事硬塞。
当前产品主干
kaoshi 是现代化考试与考试管理平台。
核心领域：用户、角色、权限、部门、题库、试题、考试、发布快照、作答快照、评分、成绩、文件附件。
默认技术方向：Java 21、Spring Boot 3、MySQL 8、MyBatis-Plus、Spring Security、JWT、Redis、Vue 3、TypeScript、Vite、Element Plus、Docker Compose。
后端纪律
- Controller 只做参数接入、鉴权上下文接入和响应转换。
- Service 承载业务流程。
- Domain/Entity 承载领域结构。
- Mapper 承载数据访问。
- Excel、附件、文件模板和导入解析使用专门工具或服务承载。
- Security 承载认证、授权和上下文解析。
- 接口必须有请求、响应、错误码和权限边界。
- 考试保存必须能读回当前详情。
- 考试发布必须生成发布快照。
- 作答必须创建 attempt 快照。
- 考试提交必须幂等并锁定。
- 评分必须基于快照可复现。
- 成绩必须可追溯。
前端纪律
- Vue 页面只做页面状态和用户交互。
- API client 统一封装请求。
- 表单校验和业务校验分层。
- 管理端和考试端路径分离。
- 权限配置使用用户可理解的中文名称、分组和复选控件。
- 考试端倒计时、提交、锁定和异常恢复必须有明确状态。
- 保存动作必须有 loading、防重复提交和保存后读回。
测试纪律
- 后端测试保护接口契约、业务规则、生命周期、Excel 导入导出和权限边界。
- 前端单元测试保护 API client、状态流和独立前端规则。
- Playwright 测试保护真实用户路径和真实前后端联通。
- 测试名称表达当前能力。
- 单元测试可以隔离依赖；真实浏览器验收必须运行真实后端、真实前端和真实数据库。
验证
生产级收口优先运行：
python .\start_test.py
python .\start_browser_test.py
如任务范围更小，可先运行相关 mvn test、npm.cmd run typecheck、npm.cmd run test:unit 或构建命令；最终收口必须说明已经运行的真实命令和结果。
