项目入口
一句话说明
这个项目解决什么问题？
基本信息
| 项 | 内容 |
|---|---|
| 项目名 | |
| 项目代号 | |
| 代码仓库 | |
| 生产环境 | |
| Staging / Preview | |
| 主要用户 / 调用方 | |
| Product Owner | |
| Tech Owner | |
| Ops Owner | |
| Doc Driver | |
| 主要沟通群 |
三角色项目责任
| 角色 | 本项目负责人 | 负责范围 |
|---|---|---|
| 产品负责人 | 用户、优先级、验收、反馈 | |
| 技术负责人 | 架构、质量、风险、review | |
| 平台 / 资深工程师 | 本地运行、CI、发布、监控、排障 |
新人从这里开始
本项目本地开发环境：
| 项 | 内容 |
|---|---|
| 语言和版本 | |
| 包管理器 | |
| 本地依赖服务 | |
| 需要的账号 / 权限 | |
.env 准备方式 |
|
| 默认本地端口 |
# 1. 安装依赖
# 2. 启动依赖服务
# 3. 准备环境变量
# 4. 跑 migration / seed
# 5. 启动应用
# 6. 跑最小检查
如果上面的命令跑不通，找谁：
常用链接
| 类型 | 链接 |
|---|---|
| 需求 / 任务看板 | |
| PR / CI | |
| CODEOWNERS / Reviewer 规则 | |
| API 文档 | |
| 监控 dashboard | |
| 日志查询 | |
| 告警规则 | |
| 发布入口 | |
| 事故记录 |
协作方式
| 场景 | 找谁 / 去哪里 | 期望响应 |
|---|---|---|
| 需求或 scope 不清 | Driver / Product Owner | |
| 技术方案不清 | Tech Owner / 模块 Owner | |
| 本地环境跑不通 | Doc Driver / Tech Owner | |
| PR review | Reviewer / CODEOWNERS | |
| 发布和回滚 | Ops Owner | |
| 线上问题 | 事故群 / Ops Owner |
卡住多久需要同步：
提问时带上任务链接、已看过的文件、试过的命令、报错和你倾向的下一步。
本项目工具流
| 流程 | 使用工具 / 链接 | 负责人 | 组员怎么参与 |
|---|---|---|---|
| 需求进入 | 产品负责人 | 补背景、截图、客户反馈 | |
| 技术方案 | 技术负责人 | 补影响范围、参与 RFC/ADR | |
| 本地开发 | 平台 / 资深工程师 | 按文档跑环境，反馈缺口 | |
| PR review | 技术负责人 / Reviewer | 提 PR、响应评论 | |
| 产品验收 | 产品负责人 / Business Approver | 提供截图、preview、验收记录 | |
| 发布 | Ops Owner / 平台 | 跑 checklist、smoke、通知 | |
| 反馈关闭 | Driver | 回写结论和后续 action |
代码地图
新人先看这些目录：
| 路径 | 负责什么 | Owner |
|---|---|---|
常见改动应该从哪里开始：
| 改动类型 | 入口文件 / 目录 | 测试位置 |
|---|---|---|
| 页面 / UI | ||
| API | ||
| 后端业务逻辑 | ||
| 数据库 / migration | ||
| 配置 / feature flag |
核心路径
这个项目最重要的 1-3 条业务或系统路径：
| 路径 | 怎么验证 | 失败影响 |
|---|---|---|
上下游
| 方向 | 名称 | 依赖方式 | Owner | 失败影响 |
|---|---|---|---|---|
| 上游 | HTTP / event / webhook / manual | |||
| 下游 | HTTP / DB / queue / third-party |
详细依赖见项目内的 docs/DEPENDENCIES.md。
数据和状态
核心数据在哪里？
| 数据 / 表 / Topic | 用途 | Owner | 风险 |
|---|---|---|---|
核心状态机：
检查命令
不要只写命令名，要写它验证什么。
| 场景 | 命令 | 验证什么 |
|---|---|---|
| 安装依赖 | ||
| 启动依赖服务 | ||
| 准备环境变量 | ||
| Migration | ||
| Seed / reset | ||
| 启动 Web | ||
| 启动 API | ||
| 启动 worker | ||
| 本地快速检查 | ||
| PR 必跑检查 | ||
| Smoke |
本地环境排障
| 问题 | 怎么检查 | 找谁 |
|---|---|---|
| 依赖安装失败 | ||
| Docker 服务起不来 | ||
| 环境变量缺失 | ||
| Migration 失败 | ||
| 端口冲突 | ||
| 测试失败 |
第一个 PR 建议
适合新人第一个 PR 的任务：
不适合作为第一个 PR 的任务：
发布和回滚
发布入口：
发布前必须确认：
- CI 通过。
- Migration 状态清楚。
- Feature flag 或回滚方式清楚。
- 发布后 smoke 负责人明确。
回滚方式：
| 类型 | 怎么回滚 | 谁执行 |
|---|---|---|
| 代码 | ||
| 配置 | ||
| 数据 | ||
| Feature flag |
不能随便改的地方
| 区域 | 为什么敏感 | 必须找谁 review |
|---|---|---|
| 权限 / 鉴权 | ||
| 支付 / 计费 | ||
| 客户数据 | ||
| 数据库 migration | ||
| 生产配置 / 密钥 |
项目文档
| 文档 | 链接 | 最近确认时间 |
|---|---|---|
| 架构 | docs/ARCHITECTURE.md |
|
| 技术选型 | docs/TECH_STACK.md |
|
| 依赖 | docs/DEPENDENCIES.md |
|
| Runbook | docs/RUNBOOK.md |
下一步阅读
读完或填完这份文档后，通常继续看：
- 40-项目级闭环-project-level-closure.md：项目入口填完后，回到项目级闭环检查是否达标。
- 43-本地开发-local-development.md：然后让新人按本地开发手册试跑项目。