add readme

2026-04-28 11:36:41 +08:00
parent 23470ebda3
commit 2d4a7e2cdd
5 changed files with 431 additions and 19 deletions
@@ -0,0 +1,3 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Verify README architecture, modules, and backend descriptions against project guidelines."}
+{"file": ".trellis/spec/frontend/index.md", "reason": "Verify README frontend/JSP descriptions against project guidelines."}
+{"file": ".trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Verify README content against developer-provided project facts."}
@@ -0,0 +1,3 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Project architecture, core modules, and backend stack facts needed for accurate README content."}
+{"file": ".trellis/spec/frontend/index.md", "reason": "JSP/CSS presentation-layer context and frontend conventions relevant to README descriptions."}
+{"file": ".trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Developer-provided stack, layered architecture, data model, and module requirements to summarize in README."}
@@ -0,0 +1,74 @@
+# 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`.
@@ -0,0 +1,26 @@
+{
+  "id": "chinese-detailed-readme",
+  "name": "chinese-detailed-readme",
+  "title": "brainstorm: 中文详细 README",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "Zzzz",
+  "assignee": "Zzzz",
+  "createdAt": "2026-04-28",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}