kaoshi-development

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 或构建命令；最终收口必须说明已经运行的真实命令和结果。