# brainstorm: 中文详细 README

## Goal

将现有简短英文 README 扩展为一份面向开发、部署和验收的简体中文项目说明文档，让读者能快速理解 MZH 图书馆管理系统的用途、技术栈、功能模块、目录结构、本地运行、数据库初始化、构建部署和开发约定。

## What I already know

* 用户要求：“用中文写一个详细的readme”。
* 当前 `README.md` 只有项目标题、技术栈、基础本地部署步骤和一句已实现功能概述。
* 项目是 Java 11 Maven WAR 应用，使用 JSP + Servlet + MySQL + JDBC DAO，目标部署到 Tomcat。
* `pom.xml` 声明依赖：Servlet API 4.0.1、JSTL 1.2、MySQL Connector/J 8.0.33。
* Web 入口和路由集中在 `src/main/webapp/WEB-INF/web.xml`，包含登录、仪表盘、角色首页、图书目录、图书管理、分类管理、读者管理、借还续借、读者借阅历史、报表中心、用户管理和系统日志。
* 数据库脚本位于 `src/main/resources/db/schema.sql`，会创建 `mzh_library`，并包含角色、权限、用户、系统日志、读者、图书分类、图书、借阅记录等表和本地演示数据。
* 本地数据库配置模板位于 `src/main/resources/db.properties.example`，实际配置文件应复制为 `src/main/resources/db.properties` 且不提交真实凭据。
* 项目使用 Servlet -> Service -> DAO 的分层边界，认证会话只保存安全的 `AuthenticatedUser` 快照。
* 当前前端界面和服务端反馈消息已改为简体中文。

## Assumptions

* README 应替换为中文主文档，而不是额外新增第二份中文文档。
* README 可以保留英文项目名、Maven/Tomcat/MySQL/Servlet/JSP 等技术名词。
* 用户显式要求中文，因此本任务的 README 文档语言覆盖现有 spec 中“文档用英文”的默认约定。
* README 不应写入无法从仓库确认的真实生产账号、真实部署域名或私密数据库信息。

## Open Questions

* None for this MVP.

## Requirements

* 用简体中文重写 `README.md`。
* README 至少包含：
  * 项目概述和适用场景。
  * 核心功能模块。
  * 技术栈和运行环境。
  * 项目目录结构。
  * 数据库初始化和本地配置步骤。
  * Maven 构建与 Tomcat 部署步骤。
  * 主要访问入口和角色权限说明。
  * 开发约定、测试/检查说明、常见问题。
* README 内容必须与当前仓库实际文件、脚本、路由、依赖和数据库结构一致。
* 不修改业务代码、数据库脚本或配置模板。
* 不写入真实密码、个人凭据或未经确认的默认登录明文密码。

## Acceptance Criteria

* [ ] `README.md` 是完整中文说明，明显比当前版本更详细。
* [ ] README 覆盖本地初始化、构建、部署和关键功能模块。
* [ ] README 中的路径、命令、技术版本和路由与仓库当前状态一致。
* [ ] README 没有引入不可验证的账号密码或生产配置。
* [ ] 文档更新不要求 Java 业务测试通过，但应至少做 Markdown/内容自查。

## Definition of Done

* README 更新完成。
* 任务上下文已配置给 implement/check agent。
* Quality check agent 已复核文档与 PRD/仓库事实的一致性。
* 最终说明列出修改文件和验证结果。

## Out of Scope

* 新增业务功能或调整页面。
* 修改数据库表结构或种子数据。
* 创建英文版 README。
* 添加截图、架构图或部署脚本。
* 真实生产环境部署配置。

## Technical Notes

* Relevant current README: `README.md`.
* Relevant project metadata: `pom.xml`, `src/main/webapp/WEB-INF/web.xml`.
* Relevant database files: `src/main/resources/db/schema.sql`, `src/main/resources/db.properties.example`.
* Relevant spec files for context: `.trellis/spec/backend/index.md`, `.trellis/spec/frontend/index.md`, `.trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md`.