--- title: HARNESS 业务模块架构描述标准 schema: harness.business.module-architecture/v1 kind: architecture-standard status: active version: 1.0.0 pilot: platform/customer/invoice --- # HARNESS 业务模块架构描述标准 本标准用于描述一个可独立交付、独立演进的业务能力。它不替代业务域总览，也不把页面 Tab、表单分组、数据库表或技术包误判为业务模块。 ## 1. 两级架构描述 | 层级 | 回答的问题 | 核心制品 | 禁止混入 | |---|---|---|---| | 业务域总览 | 一个业务域有哪些稳定能力，它们怎样共同完成客户价值？ | 能力地图、价值流、Context Map、领域对象关系 | 逐接口实现、组件清单、函数目录 | | 业务模块详解 | 一个完整能力如何跨角色、页面、服务、数据和运行形成闭环？ | 高保真界面、泳道、状态机、服务图、ER 图、规则矩阵、运行证据 | 把内部小功能再次拆成目录模块 | 目录级模块必须同时满足： 1. 有独立业务目标和明确用户结果； 2. 有可说清的范围内、范围外和上下游边界； 3. 有相对完整的业务生命周期； 4. 能够在不破坏领域边界的前提下独立演进。 ## 2. 五个架构平面 1. **业务与边界**：价值、角色、流程、范围和上下游关系。 2. **体验与前端**：渠道、入口、页面、交互、组件和客户端状态。 3. **服务与后端**：API、BFF、领域服务、集成、幂等和错误契约。 4. **数据与状态**：对象、事实所有权、状态机、引用、快照和一致性。 5. **控制与运行**：规则、权限、安全、质量、观测、恢复和演进。 五个平面必须沿同一条证据链连接： `业务意图 → 页面体验 → 服务契约 → 数据事实 → 运行证据` ## 3. 十项固定视图 ### 01 模块契约 - 必须回答：为什么存在、为谁创造什么价值、核心职责、范围内外、成熟度。 - 必备图形：价值图、模块边界图。 - 必备证据：立项/需求、现有功能与实现清单。 ### 02 业务语境 - 必须回答：参与者、典型用例、触发与结果、上下游模块、同步/异步协作。 - 必备图形：参与者图、Context Map。 - 必备证据：业务流程、上下游系统与契约清单。 ### 03 渠道体验 - 必须回答：移动端、PC 端、管理端分别提供什么入口、页面和反馈。 - 必备图形：关键场景高保真界面、多端功能矩阵。 - 必备证据：真实页面、路由、产品功能清单。 - 禁止：用未来设计稿伪装成已实现页面；未实现界面必须显式标为目标态。 ### 04 流程状态 - 必须回答：主流程、跨角色交接、状态迁移、异常、回退和补偿。 - 必备图形：流程图、泳道图、状态机；CRUD 仅在能够说明真实业务控制链时使用。 - 必备证据：服务编排、状态字段、业务事件和异常定义。 ### 05 前端架构 - 必须回答：页面结构、路由、组件职责、客户端状态、缓存、校验与端侧安全边界。 - 必备图形：页面结构图、路由图、组件/状态图。 - 必备证据：前端源码路径、组件和状态容器清单。 ### 06 服务架构 - 必须回答：API、BFF、领域服务的职责，调用方向、依赖、幂等、错误与集成语义。 - 必备图形：服务构成图、API 契约图、必要的时序图。 - 必备证据：API 文档、服务源码、契约测试和错误码定义。 ### 07 数据架构 - 必须回答：实体/聚合关系、事实所有权、读写路径、状态生命周期、引用与快照、一致性策略。 - 必备图形：领域对象图、ER 图、数据流图、必要的状态机。 - 必备证据：数据字典、表/索引定义、迁移与数据质量记录。 ### 08 规则治理 - 必须回答：业务不变量、校验顺序、最终裁决点、角色权限、安全、隐私和审计要求。 - 必备图形：规则决策树/决策表、权限矩阵。 - 必备证据：规则清单、权限定义、错误码与审计记录。 ### 09 质量运行 - 必须回答：性能、可用性、容量、可观测性、告警、恢复、降级和数据修复要求。 - 必备图形：SLO 图、可观测架构图、恢复/降级路径。 - 必备证据：真实监控、压测、告警与演练记录。 - 禁止：缺少真实基线时虚构百分比、吞吐量或延迟；应明确登记为待补基线。 ### 10 证据演进 - 必须回答：当前态、目标态、已知差距、残余风险、架构决策和演进路线。 - 必备图形：证据地图、当前/目标对照、路线图。 - 必备证据：代码、测试、数据、ADR、路线图与复核日期。 ## 4. 每项视图的交付契约 每一项都必须同时存在： 1. **图形**：说明角色、关系、顺序、状态或所有权； 2. **判断**：说明为什么这样设计、边界为何成立； 3. **证据**：指向页面、接口、服务、数据、测试或已批准目标态； 4. **状态**：区分已实现、部分实现、目标态、已知缺口； 5. **责任**：明确最终裁决者和维护责任； 6. **日期**：记录版本、最近复核时间和证据有效性。 ## 5. 四道交付门槛 | 门槛 | 验收问题 | 不通过示例 | |---|---|---| | A 边界完整 | 能否说清范围内、范围外、用户边界、系统边界与上下游？ | 一个页面被误当成独立业务模块 | | B 链路闭合 | 主流程、异常、回退、状态和用户反馈是否全部可追踪？ | 只有成功流程，没有异常与补偿 | | C 实现可证 | 前端、API、服务、数据和测试是否有真实证据？ | 仅凭架构师推测或未来设计稿 | | D 演进可控 | 当前态、目标态、差距、ADR 与变更历史是否分离？ | 把缺陷修复时间线混入稳定架构正文 | 四道门槛必须全部通过，模块才能被登记为“完整样板”。质量运行缺少真实基线时，只能标为“部分符合”，不得虚构指标补齐页面。 ## 6. 架构描述与变更历史 ### 架构描述 - 稳定知识，回答“为什么这样设计”。 - 当业务边界、流程、状态、模型、规则、契约或质量目标实质变化时更新。 - 不记录普通缺陷修复、无架构影响的文案和样式调整。 ### 变更历史 - 高频审计记录，回答“何时为什么改了什么”。 - 每次可交付变更均记录动因、内容、影响、验证与是否触发架构复核。 - 只有影响十项标准视图的变化，才回写架构描述。 ## 7. 可复制的页面骨架 ```text 00 模块身份与阅读导航 01 模块契约 02 业务语境 03 渠道体验 04 流程状态 05 前端架构 06 服务架构 07 数据架构 08 规则治理 09 质量运行 10 证据演进 -- 独立入口：变更历史 ``` ## 8. 图形选择规则 - “为什么存在、边界在哪里”用价值图与边界图。 - “谁参与、与谁协作”用参与者图与 Context Map。 - “不同端怎样完成任务”用真实高保真界面与功能矩阵。 - “多人多端怎样交接”用泳道图。 - “对象怎样变化”用状态机或生命周期图。 - “调用如何发生”用服务图、时序图或 API 契约图。 - “数据归谁、怎样流动”用领域对象图、ER 图和数据流图。 - “条件怎样裁决”用决策树、决策表和权限矩阵。 - “如何可靠运行”用 SLO、观测、恢复与降级图。 - “当前与未来如何区分”用证据地图与演进路线图。 ## 9. 视觉标准 - 真白背景、深海军蓝文字、电蓝控制/调用线、红色约束/缺口、青绿色验证/证据。 - 开放式分区、细线、轨道、表格和画布；禁止大面积黑底、渐变、玻璃态和通用卡片墙。 - 核心架构图使用 HTML/CSS/SVG 原生绘制，确保可搜索、可缩放、可维护。 - 正文字号、表格、控件和图内注释必须在桌面与移动端保持可读。 - 每张图必须具备标题、图例、架构结论与事实来源。 ## 10. 首个样板：发票中心 发票中心用于验证本标准，而不是定义所有模块的业务内容。其当前复核结论： - 01—08 已有真实业务与实现证据； - 09 已登记运行与一致性风险，但缺少真实 SLO、监控和压测基线，只能部分符合； - 10 已区分已实现、未实现、残余风险和证据路径； - 发票抬头与收票方式属于同一业务能力内部功能，不再拆成目录级模块。 后续模块必须复用结构、验收规则和视觉语言，不能照抄发票中心的税务规则、页面数量或数据对象。