夜雨聆风技术方案设计文档
1文档组织与前置约定
目的：定义文档交付结构、明确哪些模块需要详细设计、建立PRD与详细设计的边界约定，确保方案编写和执行标准一致。
1.1文档交付结构 必填
说明本次交付的文档组织方式：1份架构设计文档 + N份模块详细设计附录。架构文档描述系统级决策，附录按模块独立阐述实现细节。
请说明： - 架构设计文档涵盖范围（系统整体架构、技术选型依据、公共组件设计等） - 模块详细设计附录清单（模块名称 / 负责人 / 预计完成日期） - 各附录与架构文档的关联关系（通过功能点名称关联）
1.2模块详细设计判断规则 必填
并非所有模块都需要做详细设计。以下为必须做详细设计的判断标准：
| ✅ 必须 | ||
| ✅ 必须 | ||
| ✅ 必须 | ||
| ✅ 必须 | ||
| ✅ 必须 | ||
| ❌ 不需要 | ||
| ❌ 不需要 |
⚠️ 一票否决提醒 V4：如果功能涉及资金/安全/权限校验但未做详细设计（对应上表中"必须"类型），方案将直接不予通过。
请列出本次涉及的需要做详细设计的模块清单，并说明判断依据。
1.3PRD边界约定 必填
PRD 定义「做什么」，详细设计定义「怎么做」。本文档不得重复PRD中的功能点描述、用户故事、验收标准等内容。 如需引用PRD，通过功能点名称或编号关联即可。
请说明： - 关联的PRD文档名称/链接 - 本方案涉及的功能点清单（名称/编号即可，不重复PRD详细描述） - 如有本方案与PRD不一致处，需在此标注差异项
功能点逐项对应检查清单（A1）：确保PRD中的每个功能点在方案中都有对应设计，避免遗漏。
⚠️ 一票否决提醒 V9：如果功能点与PRD需求严重脱节（逐项对应清单中出现 ❌ 未覆盖 的情况且无合理解释），方案将直接不予通过。
2业务逻辑闭环与边界
目的：明确新功能的业务边界，对齐PRD规则，防范特殊路径遗漏。
2.1前置与后置条件 必填
| 前置条件 | |
| 后置通知 |
2.2状态机模型流转图 涉及多状态时必填
如果涉及多状态流转的功能（如 INIT → PROCESSING → SUCCESS / FAILED），请用 PlantUML 或文字标明每种状态的流转触发点，严防"无法推进的死状态"。
2.3异常路径与业务兜底流程 必填
如果外部依赖服务（如 Dubbo RPC）超时或报错，该新功能采取哪种兜底策略？
2.4降级方案与重试参数配置 必填
当关键外部依赖不可用时，需定义独立的降级逻辑和兜底方案。同时明确重试参数的精确配置，避免盲目重试导致雪崩。本条来自评审检查清单 E3/E4。
降级方案：
重试参数配置表：
⚠️ 防雪崩检查：当重试次数 × 重试间隔 > 上游调用方超时时间时，会形成"上游已超时、下游还在重试"的资源浪费。请确认重试总时长 ≤ 上游超时时间的 80%。
3⭐ 技术实现设计（核心）
目的：这是详细设计的核心交付物。用时序图和伪代码/流程图清晰表达"系统怎么实现"，从用户操作到后端链路全透明。
⚠️ 注意：本章是原"模板：新功能技术方案"缺失的核心内容，来自"12 功能技术设计方案"的详细设计要求。
3.1⭐ 时序图 核心产出物
从用户前端操作开始，逐层画出 前端 → 网关 → Controller → Service → 中间件（Redis/DB/MQ）→ 跨系统调用 → 响应返回的完整链路。 用 alt/opt标注分支，关键步骤标注异常处理策略。时序图应覆盖"正常流程 + 异常流程 + 边界流程"三类场景。
要求：至少包含前端/网关/核心Service/DAO/数据库/外部依赖六层，关键交互标注方法名和传输对象。
3.2核心处理逻辑 必填
对于核心接口/功能，提供伪代码或流程图来描述主处理流程和分支判断逻辑。
3.3数据变更明细 必填
列出本功能涉及的所有数据库表操作。多条表操作必须标注是否在同一事务内。
4接口契约与API设计
目的：规范前后端或服务间的交互契约，严格防范安全漏洞与不兼容变更。
4.1协议与语义选择 必填
明确接口协议类型：□ RESTful □ Dubbo RPC □ gRPC □ 其他：________ 如果是涉及数据导出或对业务状态有副作用的操作，坚决杜绝使用 GET 请求（避免敏感参数暴露在 URL 中或被缓存），必须改用 POST + @RequestBody。
4.2接口定义 必填
4.3入参定义 必填
入参对象必须搭配 @Validated触发校验。数量、长度类参数必须搭配 @Size(max=100)或 @Max设置硬性上限。
4.4出参定义 必填
列表查询必须统一包装为包含分页元数据 (total, pageNo, pageSize)的结构，禁止直接返回裸 List。
错误码定义：
4.5接口异常场景处理 必填
对每种接口级异常，明确对应的错误码、错误信息和处理方式。
4.6幂等设计 必填
描述本接口重复调用时的处理策略：是基于业务唯一键去重、分布式锁、还是数据库唯一索引？
请说明： - 幂等键是什么（如：订单号、交易流水号、业务唯一键组合） - 幂等实现方式（□ 数据库唯一索引 □ Redis setNX □ 分布式锁 □ 其他：________） - 重复调用的返回策略（□ 返回首次结果 □ 返回幂等错误码 □ 返回成功但标记为重复）
4.7性能要求 必填
4.8权限与安全注解 必填
☐
☐
请列出每个接口需要的权限/角色：
4.9版本管理与向前兼容 涉及接口变更时必填
☐
☐
请说明兼容策略：□ 新增路径 /v2/ □ 老接口保留+标记Deprecated □ 字段向后兼容（新增字段不删老字段） □ 其他
功能级兼容性评估（A5）：新功能是否可能破坏已有功能？需逐项确认。
4.10安全防护扩展 必填
覆盖敏感数据加密、防攻击措施、审计日志三个维度。本条来自评审检查清单 F2/F3/F4。
⚠️ 安全维度占评审权重 9%，F2-F4 三项缺失将直接导致安全性评分严重不足，且可能触发一票否决项 V6。
F2 敏感数据加密：
☐
F3 防攻击措施：
☐
☐
☐
☐
☐
F4 审计日志：
☐
☐
☐
5数据模型与存储设计
目的：规划数据存储结构，提前设计好索引，杜绝全表扫描。
5.1数据库变更评估 必填
新建表请附建表DDL语句：
-- 请粘贴 CREATE TABLE 语句
5.2索引设计 必填
针对新功能的高频查询与组合过滤场景，设计单列或复合索引。防错检查：是否存在隐式全表扫描风险（如 MongoDB 多字段查询无复合索引、MySQL 使用前导通配符 LIKE '%xxx%'）？
5.3数据生命周期与冷热分离 建议评估
5.4变更范围标注与数据迁移方案 涉及数据变更时必填
所有涉及数据库变更的项，必须明确标注变更类型（新增/修改/废弃），并对存量数据提供迁移方案。本条来自评审检查清单 D2/A2。
A2 变更范围总览：
D2 数据迁移方案：
⚠️ 不可回滚检查：若 DDL 包含 DROP COLUMN / DROP TABLE / TRUNCATE 等不可逆操作，必须在变更前备份数据，并在方案中附备份恢复流程。
5.5ER图与缓存变更评估 涉及新表或缓存变更时必填
本条来自评审检查清单 D3（ER图）/ D5（缓存变更）。
D3 ER图：涉及新建表或表关系变更时，需附 ER 图（可使用 Mermaid ERD / PlantUML / 专业绘图工具）。
D5 缓存变更评估：
☐
6事务与分布式数据一致性
目的：防范假事务、并发重复插入或数据不一致问题。
6.1本地事务边界 必填
明确哪些操作必须被同一个本地事务覆盖（要么同时成功，要么同时回滚）。检查是否存在不支持本地 ACID 事务的数据源（如单节点 MongoDB 无法直接靠 @Transactional 回滚，需使用 Session API 或业务补偿）。
请说明： - 事务范围（涉及哪些表/操作） - 事务隔离级别 - 是否有非ACID数据源参与（MongoDB/Redis/ES等），若有，如何处理回滚？
6.2分布式一致性与消息队列（MQ） 必填
☐
☐
请说明 MQ 场景的补偿策略和幂等机制。
6.3高并发防重插入 必填
新功能是否存在"先检查数据是否存在，再执行插入"的模式？高并发时这极易导致重复插入脏数据。方案中准备采用何种手段保证原子性？
请说明防重插入策略： □ 数据库物理唯一索引（推荐，最可靠） □ 分布式锁（锁的TTL = ______ 秒，需确保覆盖最长业务执行时间） □ INSERT ... ON DUPLICATE KEY UPDATE □ Redis setNX + 业务唯一键 □ 其他：________
7性能、容量与防重
目的：自证新功能上线后，不会拖垮原有系统的老业务。
7.1资源消耗与批量控制 必填
☐
☐
请列出循环操作清单及批量优化方案。
7.2防重提交机制 必填
对于核心写操作、资金或状态变更接口，前端防重复点击之外，后端如何设计防重机制？建议：Redis setNX + 业务唯一键。
请说明： - 防重键设计（如：userId + 操作类型 + 业务ID 组合） - 防重窗口时长（如：5秒内同一操作不允许重复提交） - 防重实现方式（□ Redis setNX □ Token机制 □ 数据库唯一约束 □ 其他）
7.3迭代性能影响评估 必填
新功能上线后，对比现有基线评估对系统性能的影响。本条来自评审检查清单 G1。
7.4性能优化方案 性能敏感模块必填
针对识别出的性能敏感模块，提供专项优化方案。本条来自评审检查清单 G3。
⚠️ 性能敏感模块标注：若模块判断规则表（1.2）中标注为"性能敏感"，此处必须填写完整的优化方案，不可留空。若无需优化，需说明理由。
8⭐ 后台定时任务设计
目的：对定时任务做专项设计，确保任务可执行、可控制、可恢复、可监控。
⚠️ 注意：本章是原"模板：新功能技术方案"完全缺失的章节，来自"12 功能技术设计方案"的定时任务详细设计要求。
8.1触发方式 必填
请说明任务触发方式： □ 定时触发（Cron 表达式：__________________） □ 事件驱动（触发事件：__________________） □ 手动触发（触发入口：__________________） □ 混合模式（说明：__________________）
8.2执行逻辑 必填
以流程图或伪代码描述任务完整执行逻辑，包含每一步的数据处理逻辑和分支判断。
【定时任务执行逻辑】 请描述任务执行步骤，格式示例： 1. 从数据库中查询待处理数据（状态=待处理，limit=1000） 2. 逐条处理： a. 校验数据完整性和业务规则 b. 调用外部RPC服务 c. 更新本地状态为"处理中" → "已完成" / "失败" 3. 汇总处理结果，记录执行日志 4. 如有失败数据，写入重试队列 流程图请在此处或附录中补充。
8.3数据量与耗时 必填
8.4失败重试 必填
8.5幂等保证 必填
重复执行不会产生脏数据的具体机制。
请说明： - 幂等判断依据（如：基于业务ID + 处理状态的 CAS 更新） - 具体实现方式（□ 数据库状态机约束 □ 分布式锁 □ 唯一索引 □ 其他：________） - 验证方法（如何证明重复执行不会产生脏数据）
8.6并发控制 必填
请说明： - 是否允许多个实例并行执行同一任务？ □ 允许 □ 不允许 - 如果允许，并发数量上限：______ - 并发控制机制：□ XXL-Job 分片广播 □ 分布式锁（Redis/ZK） □ 数据库任务表行锁 □ 其他：________ - 分布式锁 TTL：（如有）______ 秒（需确保覆盖最长执行时间）
8.7监控告警 必填
9可观测性与可运维性
目的：确保新功能上线后不是"黑盒"，出问题能秒级定位。
9.1日志打印规范 必填
☐
☐
请列出关键日志埋点位置和日志级别（INFO/WARN/ERROR）。
9.2全链路追踪 必填
☐
请说明 TraceId 的传递方式和覆盖范围（跨线程、跨MQ、跨RPC）。
9.3监控埋点与监控大盘 必填
针对新功能的核心业务指标，设计埋点并准备配置告警。
9.4功能开关与灰度上线预案 必填
☐
☐
请说明： - 开关配置项名称和位置 - 灰度策略（按比例/按白名单/按区域） - 灰度观察周期和全量发布条件
10代码质量与架构复用
目的：保持代码干净整洁，拒绝"为了新功能，无脑复制老代码"。
10.1DRY原则 必填
新功能的列表查询、数据转换（VO/DTO 映射），与现有的老功能（如导出功能）是否有大量重复逻辑？如果有，公共逻辑必须抽取为公共方法，严禁直接复制粘贴代码块。
请说明： - 是否存在与现有功能的重复逻辑？具体在哪些模块？ - 可抽取的公共方法清单 - 复用的现有组件/Utils
10.2设计模式与合理抽象 建议评估
如果该功能未来预计会拓展出更多的子类型或新规则（如：新增不同的核销策略），方案中是否考虑了使用策略模式、工厂模式进行解耦，以避免后续出现臃肿的 if-else山？
请说明是否应用了设计模式，以及应用的动机和位置。
10.3目录结构合规性自查 必填
☐
☐
11⭐ 迭代计划与验收标准
目的：定义关键里程碑、每个功能点的验收标准、交付物清单和回滚预案，确保项目可执行、可验收、可回退。本章对应评审一票否决项 V10，缺失将导致方案不予通过。
⚠️ 注意：本章来自 Excel 评审检查清单 I1/I2/I3 + 一票否决项 V10，覆盖评分权重 6%。缺失本章节将导致方案不可评审。
11.1关键里程碑 必填
定义从设计评审到上线的关键时间节点。本条来自评审检查清单 I1。
11.2功能点验收标准 必填
每个功能点必须定义可执行的验收标准（输入 → 预期输出 → 通过准则）。本条来自评审检查清单 I2。
☐
☐
11.3交付物清单 必填
列出本次迭代需提交的全部产出物。本条来自评审检查清单 I3。
11.4灰度与回滚预案 必填
定义灰度策略和回滚操作的具体步骤，这是一票否决项 V10的核心组成部分。本条来自评审检查清单 I3。
灰度策略：
回滚预案：
☐
☐
⚠️ 一票否决提醒 V10：如果方案中未提供完整的迭代计划（里程碑 + 验收标准 + 交付物 + 回滚预案），评审将直接不予通过。
12技术选型与合规自检
目的：确保技术选型符合集团规范，避免使用禁止技术或严重偏离选型清单。本章对应评审一票否决项 V1/V2，评分权重 4%。
⚠️ 注意：本章来自 Excel 评审检查清单 J1/J2/J3 + 一票否决项 V1/V2。本章为伊利集团特定规则章节，若为非伊利项目可标记为"不适用"。
12.1集团禁用技术清单 必填
确认本次方案未使用以下集团禁止技术。本条对应一票否决项 V1。
⚠️ 一票否决提醒 V1：使用以下任何禁止技术将导致方案不予通过。
12.2服务端/前端/中间件选型检查 必填
核对本次新增或变更的技术依赖是否符合集团选型清单。本条来自评审检查清单 J1/J2/J3，对应一票否决项 V2。
⚠️ 一票否决提醒 V2：新增依赖若严重偏离集团选型清单，需提供充分的偏离理由并经架构组审批，否则方案不予通过。
J1 服务端依赖：
J2 前端依赖：
J3 中间件/数据库依赖：
12.3新增依赖审批 涉及新增依赖时必填
所有不在集团标准选型清单中的新增依赖，需在此列明并提交架构组审批。
