Zzzz
3.9 KiB
3.9 KiB
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.