HARNESS 架构 架构设计模板 可复制骨架

一个业务域,
七个视图
讲清楚

每个业务域都用同一组视图回答:它是什么、怎么一步步用、界面长什么样、后端有哪些服务、数据怎么连、谁在测它哪里测不到、改过什么。点开一个域,就是这七个页签。

一个域一个入口
不再在模块页之间跳
先流程图再操作
每个场景点哪里、弹出什么
界面照抄真实代码
按钮与弹窗文案不编
机器守形态
缺一页、少一节当场报红
从一个业务域到七个页签
DOMAIN业务域
01

架构设计

参数 · 结构 · 规则
  • 业务参数与结构图
  • 泳道图与判定图
  • 边界与验到什么程度
02

流程设计

场景 · 流程图 · 操作
  • 每个场景先画流程图
  • 再逐步演示点哪里
  • 弹出什么、填什么
03

前端设计

高保真 · 讲解
  • 页面地图
  • 逐屏高保真与编号讲解
  • 代码结构
04

服务设计

服务 · 接口 · 问题
  • 服务全景图
  • 逐个服务收什么做什么
  • 已知问题
05

数据设计

网状图 · 字段 · 约束
  • 表和表怎么连
  • 字段与线上实况
  • 每条约束实际靠谁
06

测试设计

谁在测 · 哪里测不到
  • 测试面与测试床
  • 逐个服务有没有测试
  • 测不到的地方与异常
07

变更历史

版本 · 回看 · 指纹
  • 每一版改了什么
  • 回看结论
  • 在什么代码上回看的
EVIDENCE可信证据
01

七个视图,不多不少地讲清一个业务域

顺序固定,内容随业务事实变化。读者有两种:看不懂代码的决策者要一眼看懂「这是什么、怎么用」,要动手的开发者要看到「改哪里、牵动谁」—— 七个视图同时服务这两种人。

页签#视图名称回答什么必备图形固定的节事实从哪来
第 1 个01

架构设计

这个域是什么、有多大、处在谁和谁之间、规则怎么连带、谁在什么时候做什么、边界在哪、验到什么程度。一页看懂全局。

  • 业务参数条
  • 结构图
  • 泳道图
  • 判定图(按需)
params · structure · rules(按需)· swimlane · decision(按需)· boundary四端代码通读、线上只读查询
第 2 个02

流程设计

每个业务场景怎么走:在哪一端、哪个页面、点哪里、弹出什么框、要填什么、做完会怎样。

  • 每个场景一张流程图
  • 逐步高保真屏
  • 点击位置编号
index · scene-…(至少一个;每个先流程图、后分步操作)真实页面代码与语言包
第 3 个03

前端设计

界面长什么样、每一屏为什么这样设计、哪里只靠界面在保障、代码怎么组织。

  • 页面地图
  • 逐屏高保真 + 编号讲解
map · screen-…(至少一屏)· code前端源码、语言包
第 4 个04

服务设计

后端有哪些服务、谁调它、收什么做什么、关键逻辑在哪一端算、对外与免登录接口、域外依赖、已知问题。

  • 服务全景图
  • 逐个服务表
overview · functions · logic / open / outside(按需)· issues云函数参数校验与服务代码
第 5 个05

数据设计

有哪些表、表和表怎么连、字段、线上数据长什么样、每条约束实际靠数据库、服务端还是界面。

  • 网状图
  • 字段表
  • 约束表
network · fields · shape(按需)· constraints表文档、数据源定义、线上只读查询
第 6 个06

测试设计

谁在测这个域的代码、每个服务有没有自己的测试、哪里测不到只能靠检测与人工验收;本视图自己的问题登在页底。

  • 测试全景表
  • 逐个服务的测试表
  • 测不到的地方
overview · functions · invariants / acceptance(按需)· gaps · issues文档头 describes、测试面判定、部署门注册表
第 7 个07

变更历史

每一版改了什么、回看的结论、这一版是在什么代码上回看的。

  • 版本条目
  • 封版命令写的四行记录(设计、内容、测试指纹与改动)
就是域的 CHANGELOG.md,不另写页开发流收尾回看
02

流程设计:先画流程图,再演示怎么操作

这是整套模板里唯一一条关于「内容怎么组织」的硬要求,机器也判它:每个场景先有流程图,后有分步操作,顺序颠倒即红。

  1. 1场景头

    四格说清前提与出口:谁来做 · 在哪一端(PC 管理端还是移动端,另一端没有入口也要写明)· 从哪进(顶栏、侧栏、页面的完整路径)· 做完的结果。

  2. 2流程图

    一张原生 SVG:人在界面上做的事(金框)、系统做的事(青框)、判断(蓝色菱形)、要特别注意的结果(橙框)、起点与终点(白底墨框)、取消与异常分支也画进去。节点上的蓝色圆圈是下面第几步。

  3. 3分步操作

    每一步先写要点,再放那一屏的真实高保真;要点的地方用橙色圆圈编号,屏里同一个位置标同一个号 —— 读者对着号就知道点哪里、弹出什么、填什么。

  4. 4结果与提醒

    每一步末尾写做完会看到什么;只靠界面在保障、绕过界面就不成立的地方,用橙条直接点破,不藏。

文案照抄,不编

按钮、弹窗、提示、菜单路径全部取自真实代码与语言包;为了演示做的假设(例如「假设这一项还不存在」)写明是假设。

两端分开讲

同一件事 PC 端与移动端都能做,就是两个场景;移动端的屏用手机外壳画,不拿 PC 的屏凑。

一个场景一件事

场景以用户要完成的事命名(新增一个菜单、把页面设为公开),不以按钮或接口命名。

机器只判形态

判得了「有没有流程图、有没有分步、谁在前」,判不了画得对不对 —— 那要人打开看。

03

测试设计:谁在测、哪里测不到,写实不写愿望

宪法的测试闭环要求:测试守不到的地方,必须写进设计。这一页只写结构性事实 —— 谁测什么、哪里测不到;「此刻测过没有」按内容记账,写进页面就会过期,由收尾与封版当场判。

  1. 1测试全景

    按本域文档头 describes 认领的代码,列出哪些测试面、哪些测试床在测它;四端逐端写清测的方式 —— 有行为测试的写床,只有规范检测的写检测。

  2. 2逐个服务的测试

    本域每个云函数一行:读还是写、有没有自己的测试;登记在部署门的写明「发布前当场真跑」并点出床的路径,其余写明发布前只跑内核级测试。

  3. 3测不到的地方

    写数据却没有测试的云函数、后台页面、移动端业务页、表里的数据 —— 如实列出,写明它们靠检测与人工验收。这是覆盖缺口,不是异常。

  4. 4异常

    本视图自己的问题登在页底,与其它视图同一套字段:编号、会出什么事、动不动钱、依据、状态、由什么测试守着。只登记,不在这里修。

事实派生,不凭印象

测试面与床取自测试面判定,部署门登记取自 x-test/deploy-gate.json,云函数取自 describes 认领的目录;代码或测试变了就重新派生。

只写结构,不写结果

跑过没有、对哪份内容跑过由测试记账按内容判;页面上写「全绿」的那一刻起就在过期。

两节按需

资金与状态不变量(绝对不许错的事逐条对到哪张测试)、人工验收(真机、真浏览器验到哪一步),有就写,没有就不建。

问题留在本页底部

不另建全局问题清单:每个视图的问题登在它自己那一页的底部,复盘哪个域就看哪个域。

04

文件与真相源:一份文档头,六页视图,一份历史

机器读的事实只住一处;视图页是给人读的展开,冲突时以真相源为准。

TRUTH SOURCE

ARCH.md

文档头给机器读:版本与四端描述面 —— 版本锁步与代码锁步都锚在它上面(代码逐个文件记在域的锁清单里,不写进文档头)。正文只写域级事实:定位、四端边界、谁在读、诚实边界、七个视图的索引。

谁来写
开发流收尾回看(x-architect)
冲突时
以它为准
不应该出现
界面、流程的逐步细节
七个视图展开讲
READING VIEWS

parts/ 六页 + CHANGELOG.md

六页住 parts/,文件名就是视图 id:architecture · flow · frontend · service · data · test;第七个页签是 CHANGELOG.md。站点构建时按名册与这六页自动给这个域出七个页签。

表达层
先引共用底座 business-module.css,再引视图画法 business-views.css
不应该出现
与 ARCH.md 矛盾的事实

旧形态退场旧模板的 modules/(模块页)、ARCH.html(域总览)、CHANGELOG.html(历史视图)与这些视图讲的是同一件事 —— 一个域铺完全部视图,它们同批删掉,留着就是两套账。assets/(图素材)与 adr/(架构决策)按需保留。

05

业务结构:每张表先定在哪一层

三种业务只看一件事 —— 它有几个上级。放在哪一层由一条规则决定,依据是表文档里写明的上级,不是从外键里猜的;x-arch 的业务结构放置闸逐张表核对。数据设计视图的网状图就按这个结构画。

主业务 · 没有上级

表名以 _base 或 _dict 结尾,独立存在、有自己的编号,是一棵树的根,不写上级。例:客户、订单、商品、供应商、菜单。

子业务 · 一个上级

表名以 _node、_leaf、_log 结尾,在「上游/下游关系」段写「- 上级:」加反引号包住的上级表,挂在上级下面、与上级同域。例:收货地址、订单商品行。

关系业务 · 两端

表名以 _relation 结尾,写「- 两端:」加反引号包住的两张以上的表;挂在两端的最近共同上级下面。两端跨域就自成关系域(kind: relation 与 relates)。例:购物车、供货、角色分配。

唯一的人工判断

哪几个主业务编进同一个域,三类数据推不出来,按业务定。除此之外,每张表放在哪一层都由规则决定,一张表只能归一个域。

三条补充关系下面也可以挂子业务 —— 供货下面挂着 SKU 维护与 SOP,它们的上级写供货这张关系表。两端完全相同的几个关系合成一个关系域 —— 购物车、收藏、浏览足迹的两端都是「客户 × 商品定价」。名字叫关系、但只有一端是表的(另一端是代码里定义的东西),写「上级」按子业务算。子业务和关系业务的判别只看一条:有没有自己的生命周期。

06

交付门槛:七个视图互相对得上,才算讲清了

架构设计里画的结构,要在流程、界面、服务、数据四页里找得到对应,测试设计说得出每一处由谁测、哪里测不到;每一处判断都要指得到真实的页面、接口、表、查询或测试床。

01

架构设计

结构、规则、边界

02

流程设计

每个场景
怎么走、点哪里

03

前端设计

每一屏
长什么样

04

服务设计

每个服务
收什么做什么

05

数据设计

表怎么连
约束靠谁

06

测试设计

谁在测
哪里测不到

四道交付门槛

  1. A边界完整

    架构设计说清范围内外、四端各有没有、谁在读这个域、哪些事明确不归它。

  2. B流程闭合

    每个业务场景都有流程图与逐步操作;取消、异常、回退也画进流程图,连带改动说出连带了谁。

  3. C实现可证

    界面、服务、数据都指得到真实代码、接口与表;文案照抄,线上数据标明查询日期。

  4. D演进可控

    诚实边界、验到什么程度、变更历史分开记;缺的写缺,不用漂亮图代替没做完的事。

07

机器守的那一面:缺一页、少一节,当场报红

本模板可机判的部分固化在名册 x-arch-design-template.json,由 x-arch 的 NS-COMMON-0012 逐域、逐页核对;两者的关系与条款书和判据相同 —— 本页讲为什么,名册讲机器怎么判。

① 域

名册里的视图页(现在六页)齐全;旧模板的 modules/、ARCH.html、CHANGELOG.html 已删;parts/ 里只放这些视图页。视图的数目从名册读,增减视图不改判据代码。

② 视图页骨架

节只取自这个视图的名册、顺序一致、必填齐全;场景与逐屏至少一节;流程设计每个场景先流程图、后分步操作。

③ 表达层

前两份样式表依次落在共用底座与视图画法(按落点判,不按字面);不许把共用层复制进自己的域。

④ 名册只减不增

立闸当日另外 14 个域还没铺成视图,登记在名册里等迁移,2026-09-23 已清零;此后模板新增视图(如测试设计)不进名册,所有域同批补齐。

机器判不了的那一节写得对不对、图画得像不像真实页面、流程图有没有漏掉一个分支 —— 这些只能人打开看。报绿只说明形态对了。

08

架构设计与变更历史,必须分开治理

稳定知识解释「为什么这样设计」;高频记录说明「何时改了什么」。二者相关,但不能在同一正文里混成流水账。

SIX VIEWS

六个视图

稳定 · 面向当前与未来

维护结构、流程、界面、服务、数据、测试与边界判断;每一处都指得到真实代码或查询。

何时更新
业务边界、流程、界面、接口、表或约束发生实质变化
不记录
版本流水、谁在哪天改了什么
独立制品相互引用
CHANGE HISTORY

变更历史

高频 · 面向审计与追溯

每一版的改动与回看结论,标题下四行记录只由封版命令写;代码或设计变了必须在最上面加新的一版并封版,一次只升一步。

何时更新
每次回看升版
回写视图
仅当改动影响前六个视图里的事实
09

动手之前:骨架、画法、视觉

节的 id 以名册为准,不以记忆为准;照着菜单域六页的结构抄,换成自己域的事实。

六页的固定节 · id 按这个顺序

  1. 01架构设计

    architecture.html · params 业务参数 → structure 结构图 → rules 状态与规则(按需)→ swimlane 泳道图 → decision 判定图(按需)→ boundary 边界与弱点

  2. 02流程设计

    flow.html · index 场景总览 → scene-… 业务场景(至少一个,每个含场景头、流程图、分步操作)

  3. 03前端设计

    frontend.html · map 页面地图 → screen-… 逐屏高保真(至少一屏)→ code 代码结构

  4. 04服务设计

    service.html · overview 服务全景 → functions 逐个服务 → logic 关键逻辑在哪算(按需)→ open 对外与免登录接口(按需)→ outside 域外依赖(按需)→ issues 已知问题

  5. 05数据设计

    data.html · network 网状图 → fields 字段 → shape 数据实况(按需)→ constraints 约束在哪里

  6. 06测试设计

    test.html · overview 测试全景 → functions 逐个服务的测试 → invariants 资金与状态不变量(按需)→ acceptance 人工验收(按需)→ gaps 测不到的地方 → issues 异常

画法 · 颜色与记号都有语义

节点

金框 = 人在界面上做的事;青框 = 系统做的事;蓝色菱形 = 判断;橙框 = 要特别注意的结果;白底墨框 = 起点、终点与本域的核心;紫色虚框 = 不在本域;灰框 = 数据表与文件。

连线

实线 = 有约束的调用或引用;橙色虚线 = 按字符串对接、没有任何约束 —— 这是最该让人看见的风险线。

记号

蓝色圆圈 = 流程设计里的第几步;橙色圆圈 = 这一屏要点的地方;绿条 = 做完会看到什么;橙条 = 只靠界面在保障。

高保真

后台用顶栏 + 侧栏 + 面包屑的真实外壳,移动端用手机外壳;列名、按钮、弹窗、提示文案照抄代码与语言包。

视觉标准 · 与系统架构标准共享一套语言

配色有语义,不是装饰

页面上的配色:真白背景、深海军蓝文字;蓝=操作与调用,红 / 橙=约束与缺口,青绿=验证与证据。图里方块的颜色按角色走,见上面「节点」那一条。

开放式版面

细线、轨道、表格与画布;禁止大面积黑底、渐变、玻璃态与通用卡片墙。

图用原生绘制

流程图、泳道、结构图、网状图一律 SVG 画,可搜索、可缩放、可维护 —— 不贴位图。

表达层只有两份

共用底座 .claude/arch/assets/business-module.css 与视图画法 business-views.css;某个域独有的构图才放进本域 assets/,接在两者之后引。

10

从旧模板迁过来:十节全部有去处

旧模板按业务模块切页、每页十节;新模板按业务域组织、七个视图。内容不丢,只是换了归处。

  1. 1契约 · 语境

    旧第 1–2 节 → 架构设计:业务参数、结构图(谁写、谁读、和谁对接)、边界里的「不归本域」。

  2. 2体验 · 前端

    旧第 3、5 节(渠道体验、前端架构)→ 前端设计(每一屏长什么样)与流程设计(每个场景怎么操作)。

  3. 3流程状态

    旧第 4 节 → 流程设计的场景,以及架构设计的状态与规则、泳道图。

  4. 4服务架构

    旧第 6 节 → 服务设计。

  5. 5数据 · 规则

    旧第 7、8 节(数据架构、规则治理)→ 数据设计(网状图、字段、约束在哪里);不变量里讲「连带」的进架构设计的状态与规则。

  6. 6质量 · 证据

    旧第 9–10 节(质量运行、证据演进)→ 架构设计的边界与弱点、验到什么程度;版本流水进变更历史。

  7. 7测试

    旧模板没有这一节 → 测试设计按本域 describes、测试面判定与部署门注册表新写;原先散在服务设计备注里讲测试的异常,挪到测试设计底部。

迁一个域

写六页 → 删掉 modules/、ARCH.html、CHANGELOG.html → ARCH.md 换成七个视图的索引、升版记账 → 这个域的 ARCH.md 报「同批划掉」时从名册划掉。客户域与企业信息是下一批。