团队协作与架构治理

1.1 工程师 vs 架构师：衡量标准变了

1.2 架构师的四种常见错误定位

• 「图纸管理员」：只画架构图不碰代码，脱离现实。对策：每周至少半天深入代码，保持对真实系统的触觉。
• 「超级工程师」：所有难活自己上，团队没成长。对策：把「教会别人」当成任务的验收标准。
• 「独裁者」：决策不解释、不听取反对意见。对策：决策要写 ADR、要能被人挑战。
• 「老好人」：怕冲突，一切让业务节奏推着走，架构慢性腐烂。对策：对关键红线敢说「不」，并给出替代方案。

2.1 什么需要设计评审（轻量即可）

2.2 设计评审文档模板（一页纸）

# 设计评审：商家中心权限系统重构

## 1. 背景与目标（为什么现在做）
现有权限散落在各页面 if 判断里，新增角色要改十几处；本季度要
接入集团统一 SSO，借此机会收敛权限模型。
目标：新增一个角色类型时，改动点 <= 2 个文件。

## 2. 方案概述（高层）
统一 RBAC 模型（角色→权限点），前端按「权限点」而非「角色名」判断；
权限点列表由后端接口下发，前端缓存 5 分钟。

## 3. 关键设计决策（附备选与理由）
- 前端存「权限点集合」而非「角色名」：角色是后端概念，直接判断角色
  会在前端复制后端逻辑（ADR-0021）
- 权限检查用 HOC 还是 Hook？→ 用自定义 Hook，避免包装层带来的调试困难
- 失败降级：接口失败时默认「全部拒绝」+ 错误提示，避免误放行（安全优先）

## 4. 影响面与兼容性
- 涉及页面：商家中心全部 23 个页面
- 存量判断需迁移清单：附录 A（逐页列出）
- 灰度策略：按商家 ID 灰度 10% → 50% → 100%

## 5. 风险与对策
- 接口下发权限点延迟 → 首屏加 loading 态，超时走缓存
- 角色名判断散落各处遗漏 → 上线前用 grep 全仓扫描残余判断

## 6. 验证方案
- 单元测试：权限判断纯函数全分支覆盖
- E2E：低权限账号访问高权限页面，断言跳转与提示

3.1 什么是技术债（技术债务 Technical Debt）

为了「短期快」而牺牲「长期质量」的决定，就是欠债。负债本身不是问题——创业期用技术债换上线速度是合理的；问题是：无意识负债（不知道欠了）、不付利息（每次改动都更慢）、从不还本（债越滚越大直到系统烂尾）。

3.2 技术债治理机制（可执行版本）

1. 记账：每个技术债在「技术债清单」里一条记录：现象、影响、预估偿还成本、发现日期、负责人。清单放仓库里（docs/tech-debt.md），和代码一起维护。
2. 量化优先级：用「利息/本金」比排序——利息 = 每周因它多花的分钟数，本金 = 一次性修复成本。利息高本金低的先还。
3. 定期还款：每个迭代固定 10%～20% 容量用于还债（「投资时间」，不是「救火」）。
4. 禁止新债「隐形」：新欠的债必须当场记账，不允许「先这样，以后再说」——以后永远不会来。

# docs/tech-debt.md 示例
| 编号 | 现象 | 利息(每周) | 本金(修复) | 发现 | 负责人 | 状态 |
|------|------|-----------|-----------|------|--------|------|
| TD-12 | 订单页复用 3 份相似表格逻辑 | 2 小时(改表头要改 3 处) | 4 小时 | 2026-08 | 小李 | 待还 |
| TD-15 | lodash 版本过旧(CVE-2024-xxxx) | 0(但安全风险高) | 30 分钟 | 2026-08 | 小李 | 本周还 |

4.1 规范的三种形态（按强制力排序）

4.2 规范演进：规范是「活的」，要定期更新

• 触发更新：当规则被频繁违反（可能规则不合理）或频繁「特殊豁免」（可能规则过时）时，就该开评审更新规范，而不是继续强调。
• 变更流程：规范变更也要走评审（RFC 或轻量讨论），并写明「为什么改、兼容性如何、迁移步骤」。
• 沉淀位置：ADL（Architecture Decision Log）放「决策」，CONVENTIONS.md 放「约定」，README 放「怎么跑」。三者职责分开，避免一个巨型文档没人看。

5.1 前后端契约管理

• 契约先行：先定义接口（OpenAPI 规范），前后端按契约并行开发，mock 先行。禁止「后端先写，前端等联调才知道字段」。
• 契约变更要通知：后端改字段/删字段，必须走契约变更流程（MR + 通知），不能悄悄改——前端线上直接崩。
• 版本与兼容：破坏性变更用版本化（/v2）或兼容过渡（新增字段先加，旧字段过渡期后删）。

// 实践：前端 mock 与真实请求同构 —— 契约变了 mock 会先失败
// 用 MSW 或 json-server 维护一份与 OpenAPI 同步的 mock 数据
// 契约变更 → 生成脚本重新生成 types → mock 同步更新 → 前后端 MR 一起合
import { paths } from '@company/api-spec'   // 由 OpenAPI 自动生成的类型
type GetUserResp = paths['/api/user']['get']['responses']['200']

5.2 依赖团队/公共包治理

• 公共包有负责人：每个 shared 包（ui / request / utils）有明确 owner，变更走评审，发布有 changelog。
• semver 纪律：minor 加功能、patch 修 bug、major 破坏性变更。消费者锁版本范围，升级前看 changelog。
• 变更影响面评估：改公共包前用依赖图工具（如 nx 的 affected、pnpm --filter）算出影响哪些应用，逐个验证。
• 通知机制：破坏性变更提前一周公告（周会 / 群公告），给消费方排期升级，而不是「今天改明天崩」。

6.1 文档的最小可行体系

6.2 技术分享：教是最好的学

• 节奏：双周一次，每人轮流（分享者是收获最大的人，让新人也有机会讲）。
• 内容来源：近期踩的坑、完成的复杂功能复盘、读到的好文章 + 自己的验证、工具效率技巧。
• 格式：30 分钟以内，一个主题，必须包含「能带走的结论」而不是「炫技」。好的分享标准：听完的人立刻能用在工作中。
• 沉淀：分享材料进团队文档库，避免「讲完就忘」。

7.1 如何「说服」而不是「压服」

1. 用数据说话：「这样改能省 30% 的联调时间」比「这样更规范」有力量——先把现状量化（每次联调平均 3 天 → 契约先行后 1 天）。
2. 讲业务收益：把技术方案翻译成业务语言（上线速度、故障率、成本），决策者听不懂技术名词，但听得懂损失和收益。
3. 先小后大：别一上来推全量重构。先选一个模块试点，拿试点数据说话，再推广——「实证」比「论证」有效十倍。
4. 尊重既有投入：批评方案前先肯定它解决的问题，再指出「随着规模变化，出现了新问题」——没有人愿意承认自己过去的决策是错的。

7.2 向上管理与期望对齐

• 明确你的权责：和 leader 对齐「哪些决策你可以拍板、哪些必须上报」——架构师的边界感来自清晰的授权。
• 主动汇报节奏：技术方案关键节点（选型完成、试点结果、上线计划）主动同步，别等被问。
• 风险提前暴露：发现「业务目标和技术现实冲突」（如：2 个月上线 + 全部重写）时，尽早说「做不到 / 怎么做不到 / 什么方案能达成目标」，而不是硬扛到最后一刻。
• 管理期望：架构改进的效果是长期的，主动设定里程碑和可度量指标（如：重构后部署时长从 40 分钟降到 8 分钟），让投入看得见。

7.3 辅导与培养：复制你的能力

• 结对指导：每周一次结对，让 junior 主导、你提问引导，而不是你动手他围观。
• 把决策过程讲出来：评审时不要只说「这里要改」，要说「我看到的风险是什么、我是怎么判断的」——教思维，不教结论。
• 给成长路径：帮 junior 定义「下一级的验收标准」，让他们清楚自己的差距和路径。
• 授权与容错：让团队成员独立负责模块级设计，错了帮忙复盘而不是代劳——「他们成长了，你才自由」。

8.1 全手册知识地图（一页总结）

8.2 学习节奏建议与自测方式

• 节奏：每个阶段 1～3 周，总时长约 6～9 个月（每天 2～3 小时）。先通读 → 每个实战项目做透 → 自检题能口头讲清 → 进入下一章。
• 自测：每章自检题找人讲一遍（或录下来自己听）；定期（每月）回看上一章的坑清单，检查自己是否踩过。
• 输出倒逼输入：每章写一篇「教别人」的文章/分享，能讲清楚 = 真学会。

• 评审变成「过流程」：文档没人看，会议走形式，结论永远「通过」。解法：评审必须产出一条具体修改项或明确拒绝，零输出 = 无效评审。
• 技术债不记账：「先这样吧」成为口头禅，债越积越多直到系统瘫痪。解法：新债当场入清单，迭代固定 10% 容量还债。
• 规范靠「人肉执法」：靠评审者反复提醒而不是工具强制，效率低还伤感情。解法：能自动化的规则全部进 CI。
• 规范文档「写而不用」：100 页规范没人看。解法：砍到 10 页以内，其余用工具表达；规范变更走评审，不搞「一把手拍板」。
• 公共包被业务私有化：公共包长出业务专属逻辑，消费方被迫升级。解法：公共包 API 变更必须多消费方评审。
• 契约变更不通知：后端悄悄删字段，前端线上崩。解法：契约变更 MR + 强制通知 + 破坏性变更版本化。
• 文档过期不标：旧文档误导新人比没有更糟。解法：标注最后更新时间，超期标记「可能过期」。
• 架构师陷入「自己写」：所有难活自己做，团队没成长，自己成瓶颈。解法：把「教会别人」写进任务验收标准。
• 不敢说「不」：对明显不合理的需求和技术路线全盘接受，用加班掩盖问题。解法：对红线说不，并给出替代方案和数据。
• 只向上对齐不向下沟通：架构决策只和 leader 汇报，团队不理解就执行走样。解法：决策后开 10 分钟「为什么这么定」的说明会。

项目 A：在团队里落地一套「轻量治理机制」（强烈推荐）

1. 选一个真实痛点（如：联调经常返工 / 测试覆盖率低 / 公共代码没人维护），先量化现状（收集 2 周数据）。
2. 设计一套最小机制：一条规范 + 一个工具 + 一次评审流程（如：契约先行 + 自动生成 types + 变更通知群）。
3. 用「试点 → 数据 → 推广」的方式推动落地，写一页纸的收益报告。
4. 把这次推动过程写成复盘：什么有效、什么被抵触、下次怎么改进。

项目 B：技术债盘点与还债计划（适合已有项目）

1. 盘点你负责系统的技术债：代码债、测试债、依赖债、文档债、基建债各找 2～3 个具体例子。
2. 为每个债计算「利息」（每周多花的时间）和「本金」（修复成本），排出优先级。
3. 挑利息最高的一条，在两周内实际偿还，记录修复前后的对比数据。
4. 建立技术债清单（docs/tech-debt.md），并定下还款节奏。