Bilingual reading edition
This entry preserves the local document as the technical source of truth. The guide below is localized for English readers; commands, paths, API names, and code stay verbatim so their technical meaning is not changed in transit.
English guide
The complete course index from discovery through deployable milestones.
PZT 技术博客工程化开发课程
本课程以 PZT 双语技术博客为真实项目案例，完整演示如何从需求调研、产品定义、架构设计推进到 M0 基础里程碑落地，并建立可验证、可复盘、可持续迭代的工程流程。
课程不是“照着做一个页面”的教程，而是一套面向真实团队的标准交付方法：每个阶段都有输入、活动、产物、责任人、验收标准和失败处理方式。
1. 项目背景
PZT 是一个中英双语技术博客，目标用户包括：
- 需要快速理解技术文章并进行有效学习的开发者；
- 编写、翻译、审核和发布内容的内容团队；
- 负责账号、权限、数据、安全和部署的运营人员。
产品已确认的方向：
- 品牌名称为 PZT；
- 首批内容支持中文和英文；
- 内容使用自建后台管理；
- 数据库采用 MySQL；
- 搜索需要拼写纠错、同义词和搜索建议；
- Preview 分享链接必须受保护；
- 邮件一期不做；
- 需要内容审核人账号和审计身份；
- UI 设计环节暂时跳过，先完成产品与工程基础；
- Playground 窄屏使用上下布局，触控拖拽不是一期必需能力；
- 日间/夜间主题可切换，蓝色系视觉方向作为后续设计约束。
2. 学习目标
完成课程后，学习者应能够：
- 把模糊想法拆成用户、场景、问题、需求和可验证假设。
- 编写包含范围、用户故事、验收标准、非功能需求和待确认问题的 PRD。
- 设计前后端、数据库、认证授权、发布产物、搜索和部署边界。
- 使用里程碑、任务依赖和 Definition of Done 推进工程交付。
- 为 Java/Spring Boot 后端和 Next.js 前端建立可运行、可测试的 M0 骨架。
- 用自动化测试、契约测试、迁移检查、健康检查和审查记录证明交付结果。
- 在未完成能力存在时明确标记占位边界，而不是把骨架误报为生产能力。
3. 课程结构
| 阶段 | 主题 | 核心产物 | 完成标准 |
|---|---|---|---|
| 0 | 项目启动 | 项目章程、假设清单、角色分工 | 所有人知道为什么做、做什么、不做什么 |
| 1 | 需求调研 | 研究记录、用户分层、问题陈述、机会清单 | 每个主要需求都有证据或明确假设 |
| 2 | PRD | 功能需求、用户故事、验收标准、非功能需求、范围分层 | 开发和测试可以据此拆任务与验收 |
| 3 | 架构设计 | 上下文图、容器图、模块边界、数据库模型、API 规则、ADR | 关键技术决策可解释、可验证、可回滚 |
| 4 | M0 计划 | WBS、依赖关系、风险清单、里程碑门禁 | 能排出可执行的开发顺序 |
| 5 | M0 落地 | Monorepo、Spring Boot 骨架、MySQL 迁移、契约、测试 | 本地可启动，健康接口和测试通过 |
| 6 | M0 验收 | 验收报告、缺陷清单、复盘记录、下一里程碑计划 | 交付证据完整，未完成项透明 |
对应课件：
- 01-需求调研与产品发现
- 02-PRD 与验收标准
- 03-前后端架构与数据库设计
- 04-M0 计划与落地
- 05-M0 验证、评审与交付
- 06-M1 内容后台、Preview 与发布准备
- 07-M2-5 Release Artifact 与发布验收
- 08-M3-1 基础搜索与内容发现
- 09-M3-2 同义词检索与验收
- 10-M3-3 拼写纠错、建议词与验收
- 11-M3-4 搜索分析、质量评估与运营后台
- 12-M3-5 数据保留、删除与隐私护栏
- 13-M4-1 生产级保留清理作业
- 14-M4-2 一次性 Retention Worker 与部署边界
- 15-M5 生产部署基线与验收
4. 推荐学习方式
每个阶段按以下循环执行：
flowchart LR
A[定义问题] --> B[记录假设]
B --> C[设计方案]
C --> D[实现最小切片]
D --> E[自动化验证]
E --> F[人工评审]
F --> G[记录决策与风险]
G --> A
学习者不要跳过“验证”和“记录”步骤。没有验收证据的功能，只能称为实现尝试；没有记录边界的架构，只能称为讨论方案。
5. 统一交付规则
5.1 每项工作必须有四类信息
每个需求、技术任务或缺陷至少记录：
- 目标：解决谁的什么问题。
- 范围：本次包含和不包含什么。
- 证据：用什么测试、截图、日志或文档证明完成。
- 风险：什么情况下会失败，失败后如何回滚或降级。
5.2 Definition of Ready
任务只有满足以下条件才进入开发：
- 目标和用户场景明确；
- 依赖项已列出；
- 接口、数据或页面边界已经确定；
- 验收标准可执行；
- 未决问题不会阻断本任务，或已经指定决策人和截止时间。
5.3 Definition of Done
任务完成必须同时满足：
- 源代码和配置已提交到正确模块；
- 单元测试或集成测试已补齐；
- 失败路径和权限边界已验证；
- 文档与实际行为一致；
- 日志、错误码、关联 ID 或审计要求没有遗漏；
- 本地验证命令可重复执行；
- 已知限制和后续工作已登记。
6. 当前仓库映射
pzt-blog/
├─ apps/
│ ├─ public-web/ # Next.js 公共阅读站点，M1 使用本地发布产物
│ └─ api/ # Spring Boot 模块化单体，M0 后端基础
├─ docs/
│ ├─ api-contract.md # API 边界
│ ├─ release-artifact-v1.md
│ └─ course/ # 本课程
├─ infra/backend/ # MySQL、Redis、OpenSearch 本地依赖
└─ README.md
当前 apps/public-web 属于 M1 公共阅读切片；本课程的主要实施对象是 M0 基础工程。M0 不等于完整产品上线。
7. M0 课程最终产物
完成 M0 后，仓库应具备：
- 可安装和构建的前后端目录；
- Spring Boot 运行入口；
GET /api/v1/health和GET /api/v1/version；- API 版本、错误响应和
X-Correlation-ID规则； - MySQL 8+ 的 Flyway 初始迁移；
- 内容、审核、Preview、发布、审计的 API 占位边界；
- 公共阅读路径不直接访问 MySQL 的架构约束；
- 本地 MySQL/Redis/OpenSearch 基础设施说明；
- 后端集成测试和迁移契约测试；
- M0 验收报告和下一里程碑清单。
M0 明确不交付：
- 完整自建后台页面；
- 真正的 Preview 签发、兑换、撤销和访问审计；
- 真正的 Release Artifact 构建和对象存储发布；
- OpenSearch 搜索、拼写纠错、同义词和建议词；
- 邮件 Provider 和发送策略；
- 生产 OIDC 配置、真实 RBAC 和合规上线认证。
8. 课程总验收
课程完成时，学习者应提交：
- 一份需求调研报告；
- 一份 PRD；
- 一份架构设计文档和至少三条 ADR；
- 一份 M0 WBS 和风险清单；
- 可运行的 M0 代码；
- 自动化测试输出；
- M0 验收报告；
- 下一里程碑的明确目标、依赖和风险。
模板位于 templates：