架构设计
参数 · 结构 · 规则- 业务参数与结构图
- 泳道图与判定图
- 边界与验到什么程度
每个业务域都用同一组视图回答:它是什么、怎么一步步用、界面长什么样、后端有哪些服务、数据怎么连、谁在测它哪里测不到、改过什么。点开一个域,就是这七个页签。
顺序固定,内容随业务事实变化。读者有两种:看不懂代码的决策者要一眼看懂「这是什么、怎么用」,要动手的开发者要看到「改哪里、牵动谁」—— 七个视图同时服务这两种人。
这个域是什么、有多大、处在谁和谁之间、规则怎么连带、谁在什么时候做什么、边界在哪、验到什么程度。一页看懂全局。
每个业务场景怎么走:在哪一端、哪个页面、点哪里、弹出什么框、要填什么、做完会怎样。
界面长什么样、每一屏为什么这样设计、哪里只靠界面在保障、代码怎么组织。
后端有哪些服务、谁调它、收什么做什么、关键逻辑在哪一端算、对外与免登录接口、域外依赖、已知问题。
有哪些表、表和表怎么连、字段、线上数据长什么样、每条约束实际靠数据库、服务端还是界面。
谁在测这个域的代码、每个服务有没有自己的测试、哪里测不到只能靠检测与人工验收;本视图自己的问题登在页底。
每一版改了什么、回看的结论、这一版是在什么代码上回看的。
这是整套模板里唯一一条关于「内容怎么组织」的硬要求,机器也判它:每个场景先有流程图,后有分步操作,顺序颠倒即红。
四格说清前提与出口:谁来做 · 在哪一端(PC 管理端还是移动端,另一端没有入口也要写明)· 从哪进(顶栏、侧栏、页面的完整路径)· 做完的结果。
一张原生 SVG:人在界面上做的事(金框)、系统做的事(青框)、判断(蓝色菱形)、要特别注意的结果(橙框)、起点与终点(白底墨框)、取消与异常分支也画进去。节点上的蓝色圆圈是下面第几步。
每一步先写要点,再放那一屏的真实高保真;要点的地方用橙色圆圈编号,屏里同一个位置标同一个号 —— 读者对着号就知道点哪里、弹出什么、填什么。
每一步末尾写做完会看到什么;只靠界面在保障、绕过界面就不成立的地方,用橙条直接点破,不藏。
按钮、弹窗、提示、菜单路径全部取自真实代码与语言包;为了演示做的假设(例如「假设这一项还不存在」)写明是假设。
同一件事 PC 端与移动端都能做,就是两个场景;移动端的屏用手机外壳画,不拿 PC 的屏凑。
场景以用户要完成的事命名(新增一个菜单、把页面设为公开),不以按钮或接口命名。
判得了「有没有流程图、有没有分步、谁在前」,判不了画得对不对 —— 那要人打开看。
宪法的测试闭环要求:测试守不到的地方,必须写进设计。这一页只写结构性事实 —— 谁测什么、哪里测不到;「此刻测过没有」按内容记账,写进页面就会过期,由收尾与封版当场判。
按本域文档头 describes 认领的代码,列出哪些测试面、哪些测试床在测它;四端逐端写清测的方式 —— 有行为测试的写床,只有规范检测的写检测。
本域每个云函数一行:读还是写、有没有自己的测试;登记在部署门的写明「发布前当场真跑」并点出床的路径,其余写明发布前只跑内核级测试。
写数据却没有测试的云函数、后台页面、移动端业务页、表里的数据 —— 如实列出,写明它们靠检测与人工验收。这是覆盖缺口,不是异常。
本视图自己的问题登在页底,与其它视图同一套字段:编号、会出什么事、动不动钱、依据、状态、由什么测试守着。只登记,不在这里修。
测试面与床取自测试面判定,部署门登记取自 x-test/deploy-gate.json,云函数取自 describes 认领的目录;代码或测试变了就重新派生。
跑过没有、对哪份内容跑过由测试记账按内容判;页面上写「全绿」的那一刻起就在过期。
资金与状态不变量(绝对不许错的事逐条对到哪张测试)、人工验收(真机、真浏览器验到哪一步),有就写,没有就不建。
不另建全局问题清单:每个视图的问题登在它自己那一页的底部,复盘哪个域就看哪个域。
机器读的事实只住一处;视图页是给人读的展开,冲突时以真相源为准。
文档头给机器读:版本与四端描述面 —— 版本锁步与代码锁步都锚在它上面(代码逐个文件记在域的锁清单里,不写进文档头)。正文只写域级事实:定位、四端边界、谁在读、诚实边界、七个视图的索引。
六页住 parts/,文件名就是视图 id:architecture · flow · frontend · service · data · test;第七个页签是 CHANGELOG.md。站点构建时按名册与这六页自动给这个域出七个页签。
旧形态退场旧模板的 modules/(模块页)、ARCH.html(域总览)、CHANGELOG.html(历史视图)与这些视图讲的是同一件事 —— 一个域铺完全部视图,它们同批删掉,留着就是两套账。assets/(图素材)与 adr/(架构决策)按需保留。
三种业务只看一件事 —— 它有几个上级。放在哪一层由一条规则决定,依据是表文档里写明的上级,不是从外键里猜的;x-arch 的业务结构放置闸逐张表核对。数据设计视图的网状图就按这个结构画。
表名以 _base 或 _dict 结尾,独立存在、有自己的编号,是一棵树的根,不写上级。例:客户、订单、商品、供应商、菜单。
表名以 _node、_leaf、_log 结尾,在「上游/下游关系」段写「- 上级:」加反引号包住的上级表,挂在上级下面、与上级同域。例:收货地址、订单商品行。
表名以 _relation 结尾,写「- 两端:」加反引号包住的两张以上的表;挂在两端的最近共同上级下面。两端跨域就自成关系域(kind: relation 与 relates)。例:购物车、供货、角色分配。
哪几个主业务编进同一个域,三类数据推不出来,按业务定。除此之外,每张表放在哪一层都由规则决定,一张表只能归一个域。
三条补充关系下面也可以挂子业务 —— 供货下面挂着 SKU 维护与 SOP,它们的上级写供货这张关系表。两端完全相同的几个关系合成一个关系域 —— 购物车、收藏、浏览足迹的两端都是「客户 × 商品定价」。名字叫关系、但只有一端是表的(另一端是代码里定义的东西),写「上级」按子业务算。子业务和关系业务的判别只看一条:有没有自己的生命周期。
架构设计里画的结构,要在流程、界面、服务、数据四页里找得到对应,测试设计说得出每一处由谁测、哪里测不到;每一处判断都要指得到真实的页面、接口、表、查询或测试床。
结构、规则、边界
每个场景
怎么走、点哪里
每一屏
长什么样
每个服务
收什么做什么
表怎么连
约束靠谁
谁在测
哪里测不到
架构设计说清范围内外、四端各有没有、谁在读这个域、哪些事明确不归它。
每个业务场景都有流程图与逐步操作;取消、异常、回退也画进流程图,连带改动说出连带了谁。
界面、服务、数据都指得到真实代码、接口与表;文案照抄,线上数据标明查询日期。
诚实边界、验到什么程度、变更历史分开记;缺的写缺,不用漂亮图代替没做完的事。
本模板可机判的部分固化在名册 x-arch-design-template.json,由 x-arch 的 NS-COMMON-0012 逐域、逐页核对;两者的关系与条款书和判据相同 —— 本页讲为什么,名册讲机器怎么判。
名册里的视图页(现在六页)齐全;旧模板的 modules/、ARCH.html、CHANGELOG.html 已删;parts/ 里只放这些视图页。视图的数目从名册读,增减视图不改判据代码。
节只取自这个视图的名册、顺序一致、必填齐全;场景与逐屏至少一节;流程设计每个场景先流程图、后分步操作。
前两份样式表依次落在共用底座与视图画法(按落点判,不按字面);不许把共用层复制进自己的域。
立闸当日另外 14 个域还没铺成视图,登记在名册里等迁移,2026-09-23 已清零;此后模板新增视图(如测试设计)不进名册,所有域同批补齐。
机器判不了的那一节写得对不对、图画得像不像真实页面、流程图有没有漏掉一个分支 —— 这些只能人打开看。报绿只说明形态对了。
稳定知识解释「为什么这样设计」;高频记录说明「何时改了什么」。二者相关,但不能在同一正文里混成流水账。
维护结构、流程、界面、服务、数据、测试与边界判断;每一处都指得到真实代码或查询。
每一版的改动与回看结论,标题下四行记录只由封版命令写;代码或设计变了必须在最上面加新的一版并封版,一次只升一步。
节的 id 以名册为准,不以记忆为准;照着菜单域六页的结构抄,换成自己域的事实。
architecture.html · params 业务参数 → structure 结构图 → rules 状态与规则(按需)→ swimlane 泳道图 → decision 判定图(按需)→ boundary 边界与弱点
flow.html · index 场景总览 → scene-… 业务场景(至少一个,每个含场景头、流程图、分步操作)
frontend.html · map 页面地图 → screen-… 逐屏高保真(至少一屏)→ code 代码结构
service.html · overview 服务全景 → functions 逐个服务 → logic 关键逻辑在哪算(按需)→ open 对外与免登录接口(按需)→ outside 域外依赖(按需)→ issues 已知问题
data.html · network 网状图 → fields 字段 → shape 数据实况(按需)→ constraints 约束在哪里
test.html · overview 测试全景 → functions 逐个服务的测试 → invariants 资金与状态不变量(按需)→ acceptance 人工验收(按需)→ gaps 测不到的地方 → issues 异常
金框 = 人在界面上做的事;青框 = 系统做的事;蓝色菱形 = 判断;橙框 = 要特别注意的结果;白底墨框 = 起点、终点与本域的核心;紫色虚框 = 不在本域;灰框 = 数据表与文件。
实线 = 有约束的调用或引用;橙色虚线 = 按字符串对接、没有任何约束 —— 这是最该让人看见的风险线。
蓝色圆圈 = 流程设计里的第几步;橙色圆圈 = 这一屏要点的地方;绿条 = 做完会看到什么;橙条 = 只靠界面在保障。
后台用顶栏 + 侧栏 + 面包屑的真实外壳,移动端用手机外壳;列名、按钮、弹窗、提示文案照抄代码与语言包。
页面上的配色:真白背景、深海军蓝文字;蓝=操作与调用,红 / 橙=约束与缺口,青绿=验证与证据。图里方块的颜色按角色走,见上面「节点」那一条。
细线、轨道、表格与画布;禁止大面积黑底、渐变、玻璃态与通用卡片墙。
流程图、泳道、结构图、网状图一律 SVG 画,可搜索、可缩放、可维护 —— 不贴位图。
共用底座 .claude/arch/assets/business-module.css 与视图画法 business-views.css;某个域独有的构图才放进本域 assets/,接在两者之后引。
旧模板按业务模块切页、每页十节;新模板按业务域组织、七个视图。内容不丢,只是换了归处。
旧第 1–2 节 → 架构设计:业务参数、结构图(谁写、谁读、和谁对接)、边界里的「不归本域」。
旧第 3、5 节(渠道体验、前端架构)→ 前端设计(每一屏长什么样)与流程设计(每个场景怎么操作)。
旧第 4 节 → 流程设计的场景,以及架构设计的状态与规则、泳道图。
旧第 6 节 → 服务设计。
旧第 7、8 节(数据架构、规则治理)→ 数据设计(网状图、字段、约束在哪里);不变量里讲「连带」的进架构设计的状态与规则。
旧第 9–10 节(质量运行、证据演进)→ 架构设计的边界与弱点、验到什么程度;版本流水进变更历史。
旧模板没有这一节 → 测试设计按本域 describes、测试面判定与部署门注册表新写;原先散在服务设计备注里讲测试的异常,挪到测试设计底部。
写六页 → 删掉 modules/、ARCH.html、CHANGELOG.html → ARCH.md 换成七个视图的索引、升版记账 → 这个域的 ARCH.md 报「同批划掉」时从名册划掉。客户域与企业信息是下一批。