anyone-can-architect 0.1.2 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -104,5 +104,5 @@ Run `bash tests/run-tests.sh` before opening a pull request
|
|
|
104
104
|
|
|
105
105
|
---
|
|
106
106
|
|
|
107
|
-
> 📦 **Anyone Can Architect v0.
|
|
108
|
-
> 🤝 Powered by [Anyone Can Architect](https://github.com/ruozi/anyone-can-architect) v0.
|
|
107
|
+
> 📦 **Anyone Can Architect v0.2.0**
|
|
108
|
+
> 🤝 Powered by [Anyone Can Architect](https://github.com/ruozi/anyone-can-architect) v0.2.0 · Repo-Type: `guideline`
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.2.0
|
|
@@ -42,7 +42,7 @@ docs/design/module-order/
|
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
Split a capability within a module into a submodule when it meets all the following criteria
|
|
45
|
-
Otherwise,
|
|
45
|
+
Otherwise, keep it in the parent's class-design, which decides by its [shared mechanism criteria](../documents/class-design.md#2-structure) whether it gets its own chapter
|
|
46
46
|
|
|
47
47
|
- Has an independent external contract that callers can use correctly by reading only the child's interface
|
|
48
48
|
- Owns its state or algorithms
|
|
@@ -53,7 +53,7 @@ Do not split data structures or helper classes into separate submodules
|
|
|
53
53
|
**Counterexamples**
|
|
54
54
|
|
|
55
55
|
- ❌ Place submodule directories directly under `docs/design/`, at the same level as their parent module → The parent–child relationship is lost, so place submodule directories inside their direct parent module's directory
|
|
56
|
-
- ❌ Split an internal class without an independent contract into a submodule → It does not meet the split criteria, so
|
|
56
|
+
- ❌ Split an internal class without an independent contract into a submodule → It does not meet the split criteria, so keep it in the parent's class-design
|
|
57
57
|
- ❌ Repeat signatures from the child's interface or the child's internal implementation in the parent's class-design → The parent only references the child's interface
|
|
58
58
|
|
|
59
59
|
### 2.3 Parent and Child Responsibilities
|
|
@@ -14,48 +14,106 @@ When submodules exist, this doc defines internal composition and submodule colla
|
|
|
14
14
|
|
|
15
15
|
## 2 Structure
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
The body consists of "internal mechanisms", "external capabilities", and "internal tests", in that order
|
|
18
|
+
"Internal mechanisms" consist of "internal composition" and shared mechanisms
|
|
19
|
+
|
|
20
|
+
The first [chapter](../../CONTEXT.md#chapter) of "internal mechanisms" is "internal composition"
|
|
21
|
+
- Without submodules, it lists the module's classes or components, the data this module owns, and the downstream modules or external systems it depends on
|
|
22
|
+
- With submodules, it uses a module table listing submodules, capabilities, and responsibility boundaries, and a relationship table listing collaboration between submodules, with each submodule name linking to its README
|
|
23
|
+
|
|
24
|
+
Shared mechanisms follow "internal composition", one [chapter](../../CONTEXT.md#chapter) per shared mechanism, and are omitted when there are none
|
|
25
|
+
A shared mechanism must meet both of the following criteria
|
|
26
|
+
- At least two "external capabilities" use it
|
|
27
|
+
- It defines a rule, state, or guarantee shared by those capabilities
|
|
28
|
+
|
|
29
|
+
A single field, a set of fields, or a notification helper is not a shared mechanism, and is written next to the implementation that uses it
|
|
30
|
+
|
|
18
31
|
The [chapters](../../CONTEXT.md#chapter) and [sections](../../CONTEXT.md#section) for "external capabilities" correspond one-to-one with interface and follow "internal mechanisms", with [drill-down](../../CONTEXT.md#drill-down) applied to each [section](../../CONTEXT.md#section)
|
|
19
|
-
When submodules exist, the first [chapter](../../CONTEXT.md#chapter) of "internal mechanisms" is "internal composition", with a module table listing submodules, capabilities, and responsibility boundaries, and a relationship table listing collaboration between submodules, with each submodule name linking to its README
|
|
20
32
|
The last chapter is "internal tests", with white-box tests designed from the internal structure and processing mechanisms defined in this doc
|
|
21
33
|
Follow the [test cases](../patterns/testcase.md) pattern throughout the chapter, writing fixtures, test scenarios, and test cases in that order
|
|
22
34
|
|
|
23
35
|
Structure outline:
|
|
24
36
|
|
|
25
37
|
```text
|
|
26
|
-
"Internal mechanisms"
|
|
27
|
-
## 1
|
|
28
|
-
## 2 <
|
|
29
|
-
…
|
|
30
|
-
|
|
31
|
-
|
|
38
|
+
"Internal mechanisms"
|
|
39
|
+
## 1 Internal Composition Classes or components, owned data, and dependencies · module and relationship tables when submodules exist
|
|
40
|
+
## 2 <shared mechanism> As needed, only when it meets the shared mechanism criteria
|
|
41
|
+
…
|
|
42
|
+
"External capabilities"
|
|
43
|
+
## N-1 <business category> Corresponds to a chapter in interface
|
|
44
|
+
### N-1.1 <interface> Corresponds to a section in interface · Apply drill-down
|
|
32
45
|
#### N-1.1.1 <subdivision> As needed
|
|
33
|
-
## N <interface>
|
|
34
|
-
## N+1 Internal Tests
|
|
46
|
+
## N <interface> Also applies when a chapter in interface is itself an interface · Apply drill-down
|
|
47
|
+
## N+1 Internal Tests Follow the test cases pattern, with content headings one level lower
|
|
35
48
|
```
|
|
36
49
|
|
|
37
50
|
## 3 Writing Steps
|
|
38
51
|
|
|
52
|
+
The writing order differs from the reading order: finish the implementation of each external capability first, then extract shared mechanisms from it
|
|
53
|
+
|
|
39
54
|
1. Understand all external capabilities defined in interface, what their implementation requires, and which downstream modules or external systems they depend on
|
|
40
|
-
2.
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
3. Apply [drill-down](../../CONTEXT.md#drill-down) to "internal mechanisms": determine the resulting [chapters](../../CONTEXT.md#chapter), [sections](../../CONTEXT.md#section), and [subsections](../../CONTEXT.md#subsection) in this step
|
|
44
|
-
- Specify normal processing mechanisms, their inherent failure branches, guarantees, boundary conditions, and thresholds, with verification scenarios in the testing part
|
|
45
|
-
- When submodules exist, write "internal composition" first, linking submodule capabilities to the child interface without restating signatures or implementation
|
|
55
|
+
2. Draft "internal composition"
|
|
56
|
+
- List the classes or components needed to implement the external capabilities, the data this module owns, and its dependencies
|
|
57
|
+
- When submodules exist, link submodule capabilities to the child interface without restating signatures or implementation
|
|
46
58
|
- Define only data structures owned by this module
|
|
47
|
-
|
|
48
|
-
|
|
59
|
+
3. Apply [drill-down](../../CONTEXT.md#drill-down) to each "external capability" in order: for each [chapter](../../CONTEXT.md#chapter) or [section](../../CONTEXT.md#section) corresponding to interface, describe how to implement that interface
|
|
60
|
+
- Write the complete execution in one place: inputs, conversions, calls, branches, and outputs
|
|
61
|
+
- Write fields, conversions, and branches that serve only this interface next to its implementation
|
|
49
62
|
- Use only results already declared in interface as external results, and clearly describe how internal errors map to them
|
|
50
|
-
- Link to types and
|
|
51
|
-
-
|
|
52
|
-
|
|
63
|
+
- Link to types, results, and error semantics already defined in interface without restating them
|
|
64
|
+
- Implementation code may include method signatures to show how input parameters flow downstream
|
|
65
|
+
- For interactions with dependency modules or external systems, describe only calls sent and results received by this module, without describing the other party's internals
|
|
66
|
+
- Implementation details of a vendor or platform belong in its own Adapter
|
|
67
|
+
- Choose the expression by [expression](#31-expression), and determine branches by [completeness basis](#32-completeness-basis)
|
|
68
|
+
4. Extract shared mechanisms
|
|
69
|
+
- Find rules, state, or guarantees shared by several external capabilities in the finished implementations
|
|
70
|
+
- Move those that meet the [shared mechanism criteria](#2-structure) into their own [chapter](../../CONTEXT.md#chapter)
|
|
71
|
+
- Each usage site keeps its execution order: where it calls the mechanism, the inputs it passes, the result it gets, and the branches that follow
|
|
72
|
+
- Explain the mechanism's internal rules and implementation details only in the mechanism chapter, and reference them from usage sites
|
|
73
|
+
- Specify the mechanism's normal flow, inherent failure branches, guarantees, boundary conditions, and thresholds, with verification scenarios in the testing part
|
|
74
|
+
- Keep anything that does not meet the criteria next to the implementation that uses it
|
|
75
|
+
5. Arrange the reading order
|
|
76
|
+
- "Internal composition" comes first, followed by shared mechanisms, then "external capabilities", and finally "internal tests"
|
|
77
|
+
- The [sections](../../CONTEXT.md#section) for "external capabilities" follow the same order as interface
|
|
78
|
+
- Check that [chapter](../../CONTEXT.md#chapter) numbering is consecutive throughout
|
|
79
|
+
6. Write "internal tests"
|
|
53
80
|
- List branches, state transitions, error mappings, and invariants to verify based on the internal structure and processing mechanisms
|
|
54
81
|
- Define fixtures, list scenarios, and expand test cases following the [test cases](../patterns/testcase.md) pattern, linking the design basis to the corresponding design location in this doc
|
|
55
82
|
- Specify test entry points and observation points, using internal entry points, state, and dependency test doubles as needed
|
|
56
83
|
- Reference testcase for black-box scenarios already defined for the external contract without expanding them again
|
|
57
84
|
- When submodules exist, verify their composition and collaboration, with each submodule's own contract and implementation verified by its child docs
|
|
58
|
-
|
|
85
|
+
|
|
86
|
+
### 3.1 Expression
|
|
87
|
+
|
|
88
|
+
| Content | Expression |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| Simple calls and field conversions | Code |
|
|
91
|
+
| Multi-step processing without loops | Numbered list<br>Each step starts with a bold phrase stating its purpose<br>Specific operations and conditional branches indented under the step |
|
|
92
|
+
| Flows with loops, or whose branch paths need to be shown as a whole | [Flowchart](../patterns/flowchart.md) |
|
|
93
|
+
| Interaction timing across objects | [Sequence diagram](../patterns/sequence-diagram.md) |
|
|
94
|
+
| Allowed state changes | [State machine](../patterns/state-machine.md), which does not replace the execution order of a handler |
|
|
95
|
+
|
|
96
|
+
Do not restate in prose what a diagram or code already expresses
|
|
97
|
+
Do not add an explanatory paragraph to a call that one line of code fully expresses
|
|
98
|
+
|
|
99
|
+
Show code at the following granularity
|
|
100
|
+
- Short handlers show the necessary processing, field conversions, and notifications directly
|
|
101
|
+
- Wiring repeated in several places is written as one piece of representative code
|
|
102
|
+
- Representative code states which locations it represents
|
|
103
|
+
- Constraints shared by those locations are written once
|
|
104
|
+
- Representative code does not omit key decisions
|
|
105
|
+
- Representative code does not pose as the complete implementation
|
|
106
|
+
|
|
107
|
+
### 3.2 Completeness Basis
|
|
108
|
+
|
|
109
|
+
Branches are based on real contracts and confirmed requirements
|
|
110
|
+
- Distinguish parameter validation, call exceptions, vendor business results, and unknown states
|
|
111
|
+
- Do not design retries, state machines, or notifications for results the contract does not provide
|
|
112
|
+
- Mark behavior that has not been verified as to be verified, without assuming whether it holds
|
|
113
|
+
|
|
114
|
+
Example: a vendor setter returns `void`
|
|
115
|
+
- When the contract provides no business result, do not design a set-success or set-failure flow
|
|
116
|
+
- When call exceptions have not been verified, mark them as to be verified
|
|
59
117
|
|
|
60
118
|
## 4 Example
|
|
61
119
|
|
|
@@ -63,27 +121,32 @@ Paired with the order module in the interface example, the three "external capab
|
|
|
63
121
|
|
|
64
122
|
| Chapter or section | pattern |
|
|
65
123
|
| --- | --- |
|
|
66
|
-
| `## 1
|
|
67
|
-
| `## 2 Order State Machine` | [State machine](../patterns/state-machine.md) |
|
|
68
|
-
| `## 3
|
|
69
|
-
|
|
|
70
|
-
| `###
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
| `###
|
|
74
|
-
|
|
|
75
|
-
| `## 6
|
|
76
|
-
| `## 7 Internal Tests` | [Test cases](../patterns/testcase.md) |
|
|
124
|
+
| `## 1 Internal Composition` | Layered module dependency view from [layered view](../patterns/layered-view.md)<br>Inventory reservation records described as a data structure from [module interface](../patterns/interface.md) |
|
|
125
|
+
| `## 2 Order State Machine` | [State machine](../patterns/state-machine.md)<br>Shared by create, cancel, and reservation result callback |
|
|
126
|
+
| `## 3 Order Intake` | Heading only |
|
|
127
|
+
| `### 3.1 Create Order` | [Sequence diagram](../patterns/sequence-diagram.md) |
|
|
128
|
+
| `### 3.2 Cancel Order` | Numbered list |
|
|
129
|
+
| `## 4 Inventory Collaboration` | Heading only |
|
|
130
|
+
| `### 4.1 Reserve Inventory` | [Sequence diagram](../patterns/sequence-diagram.md) |
|
|
131
|
+
| `### 4.2 Reservation Result Callback` | [Flowchart](../patterns/flowchart.md) |
|
|
132
|
+
| `## 5 Query Order Status` | Code |
|
|
133
|
+
| `## 6 Internal Tests` | [Test cases](../patterns/testcase.md) |
|
|
77
134
|
|
|
78
135
|
## 5 Checklist
|
|
79
136
|
|
|
137
|
+
- [ ] The first chapter is "internal composition"; when submodules exist, it matches the submodule directories and only links submodule capabilities to the child interface
|
|
138
|
+
- [ ] Every shared mechanism chapter meets the shared mechanism criteria and can name at least two external capabilities that use it
|
|
80
139
|
- [ ] The [chapters](../../CONTEXT.md#chapter) and [sections](../../CONTEXT.md#section) for "external capabilities" correspond one-to-one with interface, follow "internal mechanisms", and have consecutive numbering
|
|
81
140
|
- [ ] "Internal mechanisms" and each "external capability" use drill-down to reach the leaves, leaving only one possible implementation of the module
|
|
82
|
-
- [ ]
|
|
83
|
-
- [ ]
|
|
141
|
+
- [ ] The execution order of each interface can be read in one place, without piecing chapters together
|
|
142
|
+
- [ ] Inputs, key conversions, and outputs in examples are coherent
|
|
143
|
+
- [ ] Types, results, and error semantics defined in interface are not restated
|
|
144
|
+
- [ ] Prose, diagrams, and code do not repeat each other
|
|
145
|
+
- [ ] Guarantees, boundary conditions, and thresholds of shared mechanisms are clear, with verification scenarios concentrated in the testing part
|
|
84
146
|
- [ ] The last chapter is "internal tests", verifying branches, state transitions, error mappings, and invariants based on the internal design and satisfying the test cases pattern
|
|
85
147
|
- [ ] All external results are already declared in interface, and mappings from internal errors to these results are clear
|
|
86
|
-
- [ ]
|
|
148
|
+
- [ ] Every branch is based on a contract or a confirmed requirement, and unverified behavior is marked as to be verified
|
|
87
149
|
- [ ] Only data structures owned by this module are defined
|
|
88
150
|
- [ ] Interactions with dependency modules or external systems contain only calls sent and results received by this module
|
|
89
|
-
- [ ]
|
|
151
|
+
- [ ] Implementation details of vendors or platforms are not lifted into this module
|
|
152
|
+
- [ ] "External capabilities" does not restate content already explained in shared mechanisms
|
package/package.json
CHANGED
|
@@ -42,7 +42,7 @@ docs/design/module-order/
|
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
模块内部的能力同时满足以下条件时，拆分为子模块
|
|
45
|
-
|
|
45
|
+
不满足时，留在父级 class-design，按其[公共机制条件](../documents/class-design.md#2-文档结构)决定是否单独成章
|
|
46
46
|
|
|
47
47
|
- 有独立的对外契约，调用方只读子级 interface 就能正确使用
|
|
48
48
|
- 持有自己的状态或算法
|
|
@@ -53,7 +53,7 @@ docs/design/module-order/
|
|
|
53
53
|
**反例**
|
|
54
54
|
|
|
55
55
|
- ❌ 子模块目录平铺在 `docs/design/` 下，与父模块同级 → 所属关系丢失，子模块目录放在直接父级模块目录内
|
|
56
|
-
- ❌ 没有独立契约的内部类拆分为子模块 →
|
|
56
|
+
- ❌ 没有独立契约的内部类拆分为子模块 → 不满足拆分条件，留在父级 class-design
|
|
57
57
|
- ❌ 父级 class-design 复述子级 interface 的签名或子级的内部实现 → 父级只引用子级 interface
|
|
58
58
|
|
|
59
59
|
### 2.3 父子职责
|
|
@@ -14,19 +14,32 @@
|
|
|
14
14
|
|
|
15
15
|
## 2 文档结构
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
正文依次为「内部机制」「对外能力」与「内部测试」
|
|
18
|
+
「内部机制」由「内部组成」与公共机制构成
|
|
19
|
+
|
|
20
|
+
「内部机制」的第一个 [chapter](../../CONTEXT.md#chapter) 为「内部组成」
|
|
21
|
+
- 无子模块时，列出本模块的类或组件、本模块拥有的数据与依赖的下游模块或外部系统
|
|
22
|
+
- 有子模块时，以模块表列出子模块、能力与责任边界，以关系表列出子模块之间的协作，子模块名链接对应 README
|
|
23
|
+
|
|
24
|
+
「内部组成」之后为公共机制，每个公共机制一个 [chapter](../../CONTEXT.md#chapter)，没有公共机制时不设
|
|
25
|
+
公共机制须同时满足以下条件
|
|
26
|
+
- 至少被两个「对外能力」使用
|
|
27
|
+
- 定义这些能力共享的规则、状态或保证
|
|
28
|
+
|
|
29
|
+
单个字段、字段集合或通知辅助方法不构成公共机制，写在使用它的实现旁
|
|
30
|
+
|
|
18
31
|
「对外能力」的 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section) 与 interface 一一对应，排在「内部机制」之后，对每个 [section](../../CONTEXT.md#section) [层层深入](../../CONTEXT.md#drill-down)
|
|
19
|
-
有子模块时，「内部机制」的第一个 [chapter](../../CONTEXT.md#chapter) 为「内部组成」，以模块表列出子模块、能力与责任边界，以关系表列出子模块之间的协作，子模块名链接对应 README
|
|
20
32
|
最后一章为「内部测试」，根据本文定义的内部结构与处理机制设计白盒测试
|
|
21
33
|
整章按[测试用例](../patterns/testcase.md) pattern 展开，依次写夹具、测试场景与测试用例
|
|
22
34
|
|
|
23
35
|
结构示意：
|
|
24
36
|
|
|
25
37
|
```text
|
|
26
|
-
「内部机制」
|
|
27
|
-
## 1
|
|
28
|
-
## 2
|
|
29
|
-
…
|
|
38
|
+
「内部机制」
|
|
39
|
+
## 1 内部组成 类或组件、拥有的数据与依赖 · 有子模块时为模块表与关系表
|
|
40
|
+
## 2 <公共机制> 按需，满足公共机制条件才设
|
|
41
|
+
…
|
|
42
|
+
「对外能力」
|
|
30
43
|
## N-1 <一类业务> 对应 interface 的一个 chapter
|
|
31
44
|
### N-1.1 <接口> 对应 interface 的一个 section · 对它层层深入
|
|
32
45
|
#### N-1.1.1 <细分> 按需
|
|
@@ -36,26 +49,71 @@
|
|
|
36
49
|
|
|
37
50
|
## 3 行文步骤
|
|
38
51
|
|
|
52
|
+
行文顺序与阅读顺序不同：先逐个写完对外能力的实现，再从中提炼公共机制
|
|
53
|
+
|
|
39
54
|
1. 理解所有 interface 定义的对外能力，以及实现它们要什么、依赖哪些下游模块或外部系统
|
|
40
|
-
2.
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
3. 对「内部机制」[层层深入](../../CONTEXT.md#drill-down)：分出的 [chapter](../../CONTEXT.md#chapter)、[section](../../CONTEXT.md#section) 与 [subsection](../../CONTEXT.md#subsection) 在这一步定
|
|
44
|
-
- 明确正向机制、机制固有的失败分支、保证、边界条件与阈值，验证场景写在测试部分
|
|
45
|
-
- 有子模块时，先写「内部组成」，子模块的能力链接子级 interface，不复述其签名与实现
|
|
55
|
+
2. 起草「内部组成」
|
|
56
|
+
- 列出实现对外能力所需的类或组件、本模块拥有的数据与依赖
|
|
57
|
+
- 有子模块时，子模块的能力链接子级 interface，不复述其签名与实现
|
|
46
58
|
- 只定义本模块拥有的数据结构
|
|
47
|
-
|
|
48
|
-
|
|
59
|
+
3. 对每个「对外能力」依次[层层深入](../../CONTEXT.md#drill-down)：每个对应 interface 的 [chapter](../../CONTEXT.md#chapter) 或 [section](../../CONTEXT.md#section)，写这个接口怎样实现
|
|
60
|
+
- 在一处写完整的执行过程：输入、转换、调用、分支与输出
|
|
61
|
+
- 只服务于这个接口的字段、转换与分支写在对应实现旁
|
|
49
62
|
- 对外结果只用 interface 已声明的结果，内部错误到它们的映射写清
|
|
50
|
-
- interface
|
|
51
|
-
-
|
|
52
|
-
|
|
63
|
+
- interface 已定义的类型、结果与错误语义只链接不复述
|
|
64
|
+
- 实现代码可以带方法签名，表达输入参数怎样传到下游
|
|
65
|
+
- 与依赖模块或外部系统的交互只写本模块发出的调用和收到的结果，不描述对方内部
|
|
66
|
+
- 厂商或平台的实现细节归其自身的 Adapter
|
|
67
|
+
- 按[表达方式](#31-表达方式)选择表达，按[完整性依据](#32-完整性依据)确定分支
|
|
68
|
+
4. 提炼公共机制
|
|
69
|
+
- 从已写完的实现中找出被多个对外能力共用的规则、状态或保证
|
|
70
|
+
- 满足[公共机制条件](#2-文档结构)的，移入独立的 [chapter](../../CONTEXT.md#chapter)
|
|
71
|
+
- 各使用处保留执行顺序：调用机制的位置、传入的输入、得到的结果与后续分支
|
|
72
|
+
- 机制内部的规则与实现细节只在机制章说明，使用处引用
|
|
73
|
+
- 明确机制的正向流程、固有的失败分支、保证、边界条件与阈值，验证场景写在测试部分
|
|
74
|
+
- 不满足条件的，留在使用它的实现旁
|
|
75
|
+
5. 排定阅读顺序
|
|
76
|
+
- 「内部组成」在前，公共机制随后，「对外能力」再后，最后为「内部测试」
|
|
77
|
+
- 「对外能力」的 [section](../../CONTEXT.md#section) 顺序与 interface 一致
|
|
78
|
+
- 通篇核对 [chapter](../../CONTEXT.md#chapter) 编号连续
|
|
79
|
+
6. 写「内部测试」
|
|
53
80
|
- 从内部结构与处理机制列出待验证的分支、状态转移、错误映射与不变量
|
|
54
81
|
- 按[测试用例](../patterns/testcase.md) pattern 定义夹具、列出场景并展开用例，设计依据链接本文对应设计位置
|
|
55
82
|
- 明确测试的驱动入口与观察点，按需使用内部入口、状态与依赖替身
|
|
56
83
|
- 对外契约已经定义的黑盒场景引用 testcase，不重复展开
|
|
57
84
|
- 有子模块时，验证子模块之间的组合与协作，子模块自身的契约与实现由子级文档验证
|
|
58
|
-
|
|
85
|
+
|
|
86
|
+
### 3.1 表达方式
|
|
87
|
+
|
|
88
|
+
| 内容 | 表达 |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| 简单调用与字段转换 | 代码 |
|
|
91
|
+
| 无循环的多步骤处理 | 编号列表<br>每步以加粗短语开头，表达这一步的目的<br>具体操作与条件分支缩进在该步下 |
|
|
92
|
+
| 有循环，或分支走向需要整体呈现的流程 | [流程图](../patterns/flowchart.md) |
|
|
93
|
+
| 跨对象的交互时序 | [时序图](../patterns/sequence-diagram.md) |
|
|
94
|
+
| 允许的状态变化 | [状态机](../patterns/state-machine.md)，不代替处理方法的执行顺序 |
|
|
95
|
+
|
|
96
|
+
图或代码已经表达的信息，不再用文字复述
|
|
97
|
+
一行代码能完整表达的调用，不追加解释段落
|
|
98
|
+
|
|
99
|
+
代码按以下粒度展示
|
|
100
|
+
- 简短的处理方法直接展示必要的处理、字段转换与通知
|
|
101
|
+
- 多处重复的接线写一段代表性代码
|
|
102
|
+
- 代表性代码标明它代表哪些位置
|
|
103
|
+
- 这些位置的共同约束只写一次
|
|
104
|
+
- 代表性代码不省略关键决定
|
|
105
|
+
- 代表性代码不冒充完整实现
|
|
106
|
+
|
|
107
|
+
### 3.2 完整性依据
|
|
108
|
+
|
|
109
|
+
分支以真实契约与已确认需求为依据
|
|
110
|
+
- 区分参数校验、调用异常、厂商业务结果与未知状态
|
|
111
|
+
- 契约没有提供的结果，不为其设计重试、状态机或通知
|
|
112
|
+
- 尚未核实的行为标为待核实，不假定其成立或不成立
|
|
113
|
+
|
|
114
|
+
示例：厂商 setter 返回 `void`
|
|
115
|
+
- 契约不提供业务结果时，不设计设置成功或失败的流程
|
|
116
|
+
- 调用异常未核实时，标为待核实
|
|
59
117
|
|
|
60
118
|
## 4 示例
|
|
61
119
|
|
|
@@ -63,27 +121,32 @@
|
|
|
63
121
|
|
|
64
122
|
| 章节 | pattern |
|
|
65
123
|
| --- | --- |
|
|
66
|
-
| `## 1
|
|
67
|
-
| `## 2 订单状态机` | [状态机](../patterns/state-machine.md) |
|
|
68
|
-
| `## 3
|
|
69
|
-
|
|
|
70
|
-
| `###
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
| `###
|
|
74
|
-
|
|
|
75
|
-
| `## 6
|
|
76
|
-
| `## 7 内部测试` | [测试用例](../patterns/testcase.md) |
|
|
124
|
+
| `## 1 内部组成` | [分层视图](../patterns/layered-view.md)的分层模块依赖视图<br>库存预占记录按[模块接口](../patterns/interface.md)的数据结构说明 |
|
|
125
|
+
| `## 2 订单状态机` | [状态机](../patterns/state-machine.md)<br>创建、取消与预占结果回调共用 |
|
|
126
|
+
| `## 3 订单受理` | 只有标题 |
|
|
127
|
+
| `### 3.1 创建订单` | [时序图](../patterns/sequence-diagram.md) |
|
|
128
|
+
| `### 3.2 取消订单` | 编号列表 |
|
|
129
|
+
| `## 4 库存协作` | 只有标题 |
|
|
130
|
+
| `### 4.1 预占库存` | [时序图](../patterns/sequence-diagram.md) |
|
|
131
|
+
| `### 4.2 预占结果回调` | [流程图](../patterns/flowchart.md) |
|
|
132
|
+
| `## 5 查询订单状态` | 代码 |
|
|
133
|
+
| `## 6 内部测试` | [测试用例](../patterns/testcase.md) |
|
|
77
134
|
|
|
78
135
|
## 5 检查条件
|
|
79
136
|
|
|
137
|
+
- [ ] 第一章为「内部组成」，有子模块时与子模块目录一致，子模块的能力只链接子级 interface
|
|
138
|
+
- [ ] 每个公共机制章都满足公共机制条件，能列出至少两个使用它的对外能力
|
|
80
139
|
- [ ] 「对外能力」的 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section) 与 interface 一一对应，排在「内部机制」之后，编号连续
|
|
81
140
|
- [ ] 「内部机制」与每个「对外能力」都层层深入到叶子，模块的实现只有一种
|
|
82
|
-
- [ ]
|
|
83
|
-
- [ ]
|
|
141
|
+
- [ ] 每个接口的执行顺序在一处能读懂，不需要跨章节拼接
|
|
142
|
+
- [ ] 示例的输入、关键转换与输出连贯
|
|
143
|
+
- [ ] 没有复述 interface 定义的类型、结果与错误语义
|
|
144
|
+
- [ ] 文字、图与代码之间没有重复表达
|
|
145
|
+
- [ ] 公共机制的保证、边界条件与阈值明确，验证场景集中在测试部分
|
|
84
146
|
- [ ] 最后一章为「内部测试」，根据内部设计验证分支、状态转移、错误映射与不变量，满足测试用例 pattern
|
|
85
147
|
- [ ] 对外结果都是 interface 已声明的，内部错误到它们的映射写清了
|
|
86
|
-
- [ ]
|
|
148
|
+
- [ ] 每个分支都有契约或已确认需求作为依据，尚未核实的行为已标为待核实
|
|
87
149
|
- [ ] 只定义本模块拥有的数据结构
|
|
88
150
|
- [ ] 与依赖模块或外部系统的交互只有本模块发出的调用和收到的结果
|
|
89
|
-
- [ ]
|
|
151
|
+
- [ ] 厂商或平台的实现细节没有上移到本模块
|
|
152
|
+
- [ ] 「对外能力」没有复述公共机制已说明的内容
|