anyone-can-architect 0.2.0 → 0.4.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/CONTEXT.md +2 -2
- package/README.md +6 -4
- package/README.zh-CN.md +4 -2
- package/SSOT.md +5 -0
- package/VERSION +1 -1
- package/axioms/README.md +1 -1
- package/axioms/writing.md +3 -1
- package/dist/antigravity/aca/SKILL.md +3 -2
- package/dist/antigravity/aca-design/SKILL.md +12 -6
- package/dist/antigravity/aca-implement/SKILL.md +102 -114
- package/dist/antigravity/aca-release/SKILL.md +13 -20
- package/dist/antigravity/aca-repo-audit/SKILL.md +13 -9
- package/dist/antigravity/aca-review/SKILL.md +146 -182
- package/dist/antigravity/aca-test/SKILL.md +112 -0
- package/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
- package/dist/antigravity-cli/aca/SKILL.md +3 -2
- package/dist/antigravity-cli/aca-design/SKILL.md +12 -6
- package/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
- package/dist/antigravity-cli/aca-release/SKILL.md +13 -20
- package/dist/antigravity-cli/aca-repo-audit/SKILL.md +13 -9
- package/dist/antigravity-cli/aca-review/SKILL.md +146 -182
- package/dist/antigravity-cli/aca-test/SKILL.md +112 -0
- package/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
- package/dist/codex/aca/SKILL.md +3 -2
- package/dist/codex/aca-design/SKILL.md +12 -6
- package/dist/codex/aca-implement/SKILL.md +102 -114
- package/dist/codex/aca-release/SKILL.md +13 -20
- package/dist/codex/aca-repo-audit/SKILL.md +13 -9
- package/dist/codex/aca-review/SKILL.md +146 -182
- package/dist/codex/aca-test/SKILL.md +112 -0
- package/dist/codex/aca-walkthrough/SKILL.md +18 -14
- package/dist/cursor/aca/SKILL.md +3 -2
- package/dist/cursor/aca-design/SKILL.md +12 -6
- package/dist/cursor/aca-implement/SKILL.md +102 -114
- package/dist/cursor/aca-release/SKILL.md +13 -20
- package/dist/cursor/aca-repo-audit/SKILL.md +13 -9
- package/dist/cursor/aca-review/SKILL.md +146 -182
- package/dist/cursor/aca-test/SKILL.md +113 -0
- package/dist/cursor/aca-walkthrough/SKILL.md +18 -14
- package/dist/grok/aca/SKILL.md +3 -2
- package/dist/grok/aca-design/SKILL.md +12 -6
- package/dist/grok/aca-implement/SKILL.md +102 -114
- package/dist/grok/aca-release/SKILL.md +13 -20
- package/dist/grok/aca-repo-audit/SKILL.md +13 -9
- package/dist/grok/aca-review/SKILL.md +146 -182
- package/dist/grok/aca-test/SKILL.md +112 -0
- package/dist/grok/aca-walkthrough/SKILL.md +18 -14
- package/doc-design/document-sets/module.md +6 -2
- package/doc-design/document-sets/ops-guide.md +25 -27
- package/doc-design/documents/class-design.md +7 -4
- package/doc-design/documents/instrumentation.md +3 -2
- package/doc-design/documents/integration-guide.md +7 -5
- package/doc-design/documents/interaction.md +516 -143
- package/doc-design/documents/interface.md +12 -7
- package/doc-design/documents/release.md +137 -105
- package/doc-design/patterns/interface.md +135 -14
- package/doc-design/repo-types/client-sdk.md +3 -3
- package/doc-design/repo-types/web-app.md +11 -5
- package/meta-skills/aca/SKILL.md +3 -2
- package/meta-skills/aca/SKILL.md.tmpl +3 -2
- package/package.json +1 -1
- package/skills/aca-design/SKILL.md +12 -6
- package/skills/aca-design/SKILL.md.tmpl +9 -5
- package/skills/aca-implement/SKILL.md +102 -114
- package/skills/aca-implement/SKILL.md.tmpl +103 -115
- package/skills/aca-release/SKILL.md +13 -20
- package/skills/aca-release/SKILL.md.tmpl +13 -20
- package/skills/aca-repo-audit/SKILL.md +13 -9
- package/skills/aca-repo-audit/SKILL.md.tmpl +10 -8
- package/skills/aca-review/SKILL.md +146 -182
- package/skills/aca-review/SKILL.md.tmpl +143 -181
- package/skills/aca-test/SKILL.md +112 -0
- package/skills/aca-test/SKILL.md.tmpl +110 -0
- package/skills/aca-walkthrough/SKILL.md +18 -14
- package/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
- package/zh-CN/CONTEXT.md +2 -2
- package/zh-CN/SSOT.md +5 -0
- package/zh-CN/axioms/README.md +1 -1
- package/zh-CN/axioms/writing.md +3 -1
- package/zh-CN/dist/antigravity/aca/SKILL.md +3 -2
- package/zh-CN/dist/antigravity/aca-design/SKILL.md +12 -6
- package/zh-CN/dist/antigravity/aca-implement/SKILL.md +102 -114
- package/zh-CN/dist/antigravity/aca-release/SKILL.md +71 -69
- package/zh-CN/dist/antigravity/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/dist/antigravity/aca-review/SKILL.md +143 -179
- package/zh-CN/dist/antigravity/aca-test/SKILL.md +112 -0
- package/zh-CN/dist/antigravity/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/dist/antigravity-cli/aca/SKILL.md +3 -2
- package/zh-CN/dist/antigravity-cli/aca-design/SKILL.md +12 -6
- package/zh-CN/dist/antigravity-cli/aca-implement/SKILL.md +102 -114
- package/zh-CN/dist/antigravity-cli/aca-release/SKILL.md +71 -69
- package/zh-CN/dist/antigravity-cli/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/dist/antigravity-cli/aca-review/SKILL.md +143 -179
- package/zh-CN/dist/antigravity-cli/aca-test/SKILL.md +112 -0
- package/zh-CN/dist/antigravity-cli/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/dist/codex/aca/SKILL.md +3 -2
- package/zh-CN/dist/codex/aca-design/SKILL.md +12 -6
- package/zh-CN/dist/codex/aca-implement/SKILL.md +102 -114
- package/zh-CN/dist/codex/aca-release/SKILL.md +71 -69
- package/zh-CN/dist/codex/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/dist/codex/aca-review/SKILL.md +143 -179
- package/zh-CN/dist/codex/aca-test/SKILL.md +112 -0
- package/zh-CN/dist/codex/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/dist/cursor/aca/SKILL.md +3 -2
- package/zh-CN/dist/cursor/aca-design/SKILL.md +12 -6
- package/zh-CN/dist/cursor/aca-implement/SKILL.md +102 -114
- package/zh-CN/dist/cursor/aca-release/SKILL.md +71 -69
- package/zh-CN/dist/cursor/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/dist/cursor/aca-review/SKILL.md +143 -179
- package/zh-CN/dist/cursor/aca-test/SKILL.md +113 -0
- package/zh-CN/dist/cursor/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/dist/grok/aca/SKILL.md +3 -2
- package/zh-CN/dist/grok/aca-design/SKILL.md +12 -6
- package/zh-CN/dist/grok/aca-implement/SKILL.md +102 -114
- package/zh-CN/dist/grok/aca-release/SKILL.md +71 -69
- package/zh-CN/dist/grok/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/dist/grok/aca-review/SKILL.md +143 -179
- package/zh-CN/dist/grok/aca-test/SKILL.md +112 -0
- package/zh-CN/dist/grok/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/doc-design/document-sets/module.md +6 -2
- package/zh-CN/doc-design/document-sets/ops-guide.md +25 -27
- package/zh-CN/doc-design/documents/class-design.md +7 -4
- package/zh-CN/doc-design/documents/instrumentation.md +3 -2
- package/zh-CN/doc-design/documents/integration-guide.md +7 -5
- package/zh-CN/doc-design/documents/interaction.md +516 -143
- package/zh-CN/doc-design/documents/interface.md +12 -7
- package/zh-CN/doc-design/documents/release.md +138 -106
- package/zh-CN/doc-design/patterns/interface.md +135 -14
- package/zh-CN/doc-design/repo-types/client-sdk.md +3 -3
- package/zh-CN/doc-design/repo-types/web-app.md +11 -5
- package/zh-CN/meta-skills/aca/SKILL.md +3 -2
- package/zh-CN/meta-skills/aca/SKILL.md.tmpl +3 -2
- package/zh-CN/skills/aca-design/SKILL.md +12 -6
- package/zh-CN/skills/aca-design/SKILL.md.tmpl +9 -5
- package/zh-CN/skills/aca-implement/SKILL.md +102 -114
- package/zh-CN/skills/aca-implement/SKILL.md.tmpl +102 -114
- package/zh-CN/skills/aca-release/SKILL.md +71 -69
- package/zh-CN/skills/aca-release/SKILL.md.tmpl +71 -69
- package/zh-CN/skills/aca-repo-audit/SKILL.md +39 -29
- package/zh-CN/skills/aca-repo-audit/SKILL.md.tmpl +36 -28
- package/zh-CN/skills/aca-review/SKILL.md +143 -179
- package/zh-CN/skills/aca-review/SKILL.md.tmpl +140 -178
- package/zh-CN/skills/aca-test/SKILL.md +112 -0
- package/zh-CN/skills/aca-test/SKILL.md.tmpl +110 -0
- package/zh-CN/skills/aca-walkthrough/SKILL.md +18 -14
- package/zh-CN/skills/aca-walkthrough/SKILL.md.tmpl +15 -13
|
@@ -18,9 +18,9 @@
|
|
|
18
18
|
结构示意:
|
|
19
19
|
|
|
20
20
|
```text
|
|
21
|
-
## 1 公共契约 按需 ·
|
|
21
|
+
## 1 公共契约 按需 · 数据契约及共用连接与认证约定
|
|
22
22
|
## 2 <一类业务>
|
|
23
|
-
### 2.1 共用契约 按需 ·
|
|
23
|
+
### 2.1 共用契约 按需 · 数据契约及共用连接与认证约定
|
|
24
24
|
### 2.2 <接口> 模块接口
|
|
25
25
|
### 2.3 <接口> 模块接口
|
|
26
26
|
## 3 <接口> 业务只有一个接口时 chapter 本身就是接口 · 模块接口
|
|
@@ -30,20 +30,23 @@
|
|
|
30
30
|
- 一类业务的 [chapter](../../CONTEXT.md#chapter):每个接口一个 [section](../../CONTEXT.md#section)
|
|
31
31
|
- 共用契约 [section](../../CONTEXT.md#section):这类业务共用的契约
|
|
32
32
|
|
|
33
|
+
数据结构与校验契约按[数据契约](../patterns/schema.md)表达
|
|
34
|
+
共用连接与认证约定说明协议入口及认证方式,各接口引用对应内容
|
|
35
|
+
|
|
33
36
|
## 3 行文步骤
|
|
34
37
|
|
|
35
38
|
1. 理解并列出全部内容,先不动笔
|
|
36
39
|
- 理解业务:每个接口服务什么业务
|
|
37
|
-
-
|
|
40
|
+
- 理解契约:每个接口用到的数据结构、连接与认证约定
|
|
38
41
|
2. 决定公共契约
|
|
39
|
-
-
|
|
42
|
+
- 有被不同业务的接口共用的数据结构、校验契约或连接与认证约定:作为第一个 [chapter](../../CONTEXT.md#chapter)
|
|
40
43
|
- 没有:跳过
|
|
41
44
|
3. 划分 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section)
|
|
42
45
|
- 按业务把接口归成几个 [chapter](../../CONTEXT.md#chapter),名字用业务语言,不用协议动词、路径或方法名
|
|
43
46
|
- 只含一个接口的 [chapter](../../CONTEXT.md#chapter) 就是这个接口,不设 [section](../../CONTEXT.md#section)
|
|
44
|
-
- 含多个接口的 [chapter](../../CONTEXT.md#chapter)
|
|
47
|
+
- 含多个接口的 [chapter](../../CONTEXT.md#chapter) 内有共用契约:作为它的第一个 [section](../../CONTEXT.md#section)
|
|
45
48
|
- 含多个接口的 [chapter](../../CONTEXT.md#chapter) 一个接口一个 [section](../../CONTEXT.md#section),名字用业务语言
|
|
46
|
-
4.
|
|
49
|
+
4. 逐个写接口:按[模块接口](../patterns/interface.md)选择语言或协议对应的表达方式,引用共用契约,不列举调用方
|
|
47
50
|
|
|
48
51
|
## 4 示例
|
|
49
52
|
|
|
@@ -54,6 +57,7 @@
|
|
|
54
57
|
| `## 1 公共契约` | 只有标题 |
|
|
55
58
|
| `### 1.1 错误体与错误码` | [数据契约](../patterns/schema.md) |
|
|
56
59
|
| `### 1.2 公共类型` | [数据契约](../patterns/schema.md) |
|
|
60
|
+
| `### 1.3 连接与认证` | 共用协议约定,表达参考[连接与认证示例](../patterns/interface.md#51-连接与认证) |
|
|
57
61
|
| `## 2 订单受理` | 只有标题 |
|
|
58
62
|
| `### 2.1 订单共用类型` | [数据契约](../patterns/schema.md) |
|
|
59
63
|
| `### 2.2 创建订单` | [模块接口](../patterns/interface.md) |
|
|
@@ -79,6 +83,7 @@
|
|
|
79
83
|
|
|
80
84
|
- [ ] 只有 [chapter](../../CONTEXT.md#chapter) 与 [section](../../CONTEXT.md#section) 两层,没有一个 [chapter](../../CONTEXT.md#chapter) 只有一个 [section](../../CONTEXT.md#section)
|
|
81
85
|
- [ ] [chapter](../../CONTEXT.md#chapter) 名与 [section](../../CONTEXT.md#section) 名是业务语言,没有协议动词、路径或方法名
|
|
82
|
-
- [ ]
|
|
86
|
+
- [ ] 共用契约按使用范围归属,公共契约 [chapter](../../CONTEXT.md#chapter) 里没有只被一个 [chapter](../../CONTEXT.md#chapter) 使用的约定,共用契约 [section](../../CONTEXT.md#section) 里没有只被一个接口使用的约定
|
|
87
|
+
- [ ] 共用连接与认证约定可定位,各接口按调用方使用的语言或协议表达
|
|
83
88
|
- [ ] 没有列举调用方
|
|
84
89
|
- [ ] architecture 工况中调用到的接口都在本文档中,本文档列出的接口都有工况触发
|
|
@@ -3,162 +3,194 @@
|
|
|
3
3
|
## 1 文档定位
|
|
4
4
|
|
|
5
5
|
定义本仓库从发布前验证到合入 main、锁定 Tag 的完整流程,包括每一步的执行方式、通过条件、失败处理与恢复位置
|
|
6
|
+
同仓交付的各部分使用同一个仓库版本,统一定义发布流程
|
|
6
7
|
|
|
7
8
|
## 2 文档结构
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
10
|
+
第一个 [chapter](../../CONTEXT.md#chapter) 用 [flowchart](../patterns/flowchart.md#21-流程图) 展示发布流程,节点引用对应阶段
|
|
11
|
+
后续按阶段展开,可以各用一个 [chapter](../../CONTEXT.md#chapter)
|
|
12
|
+
阶段较少时,可以合并在一个 [chapter](../../CONTEXT.md#chapter) 内,用 [section](../../CONTEXT.md#section) 分开
|
|
13
|
+
每个阶段说明执行方式、通过条件、失败处理与恢复位置
|
|
12
14
|
复杂阶段按实际内容[层层深入](../../skills/references/drill-down.md)
|
|
13
15
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
16
|
+
发布前提作为需要核对的阶段,说明版本来源、版本记录、合并链及执行条件
|
|
17
|
+
验证步骤按仓库需要安排,包括测试、构建、真实平台验证及其他必要操作,可统一执行全量验证,或按改动突破的设计边界与依赖范围分级定义
|
|
18
|
+
发布摘要归入锁定 Tag 的阶段
|
|
19
|
+
分支清理按仓库策略安排,范围为本次已合并且不再承担后续工作的分支
|
|
20
|
+
发布通告按需安排
|
|
17
21
|
|
|
18
|
-
|
|
22
|
+
以下[层级树](../patterns/hierarchy-tree.md#21-树)展示阶段分别成章的组织示例,具体阶段按仓库流程确定
|
|
19
23
|
|
|
20
24
|
```text
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
25
|
+
<发布文档>
|
|
26
|
+
├─ 1 发布流程 chapter
|
|
27
|
+
├─ 2 确认发布前提 chapter
|
|
28
|
+
├─ 3 收口版本记录 chapter
|
|
29
|
+
├─ 4 验证候选版本 chapter
|
|
30
|
+
├─ 5 合入 main chapter
|
|
31
|
+
├─ 6 核对最终提交 chapter
|
|
32
|
+
├─ 7 锁定版本 chapter
|
|
33
|
+
├─ 8 清理版本分支 chapter
|
|
34
|
+
└─ 9 发布通告 chapter,按需
|
|
27
35
|
```
|
|
28
36
|
|
|
29
37
|
## 3 行文步骤
|
|
30
38
|
|
|
31
|
-
1.
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
2.
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
- Tag
|
|
43
|
-
-
|
|
44
|
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
5. 按 [§2](#2-文档结构)组织各章,核对完整流程
|
|
51
|
-
- 前一步的结果满足后一步的前提,恢复执行不会重复不可重入的操作
|
|
52
|
-
- 版本号、Tag、main 最终提交与验证结果能够相互追溯
|
|
39
|
+
1. **确定发布输入**
|
|
40
|
+
- 确定版本来源、版本记录、合并链与目标 Tag
|
|
41
|
+
- 定位执行所需的环境、权限、工具与外部依赖
|
|
42
|
+
2. **编排阶段与验证**
|
|
43
|
+
- 按依赖关系安排前提核对、版本记录收口、验证与合并,绘制流程总图
|
|
44
|
+
- 定义各阶段的操作、通过条件与失败后的恢复位置
|
|
45
|
+
- 按改动影响分级验证时,定义对应测试集、升级为全量验证的条件及定期兜底
|
|
46
|
+
- 验证涉及真实平台或模型评测时,定义所需环境、数据与结果判定
|
|
47
|
+
- 最终核验按已有结果的复用条件判断是否重验,验证结果关联最终提交
|
|
48
|
+
3. **定义版本固化与后续处理**
|
|
49
|
+
- 定义最终版本记录核对、发布摘要的来源、格式与校验方式
|
|
50
|
+
- 在已验证的 main 提交上创建 annotated Tag,推送后核对远端指向与注解
|
|
51
|
+
- Tag 创建后不移动、不重建,推送失败只重推,同名 Tag 冲突时停止
|
|
52
|
+
- 按仓库策略安排本次已合并分支的清理
|
|
53
|
+
- 需要通告时,定义从 Tag 注解提取内容的方式、渠道、发送结果核对与失败重发
|
|
54
|
+
使用飞书卡片时按[卡片示意](../patterns/lark-card-mockup.md)绘制
|
|
55
|
+
4. **组织正文并核对**
|
|
56
|
+
- 按[文档结构](#2-文档结构)展开各阶段,核对前后步骤与失败恢复路径
|
|
57
|
+
- 按[检查条件](#5-检查条件)核对版本、Tag、最终提交与验证结果
|
|
53
58
|
|
|
54
59
|
## 4 示例
|
|
55
60
|
|
|
56
61
|
````markdown
|
|
57
62
|
# 报告服务发布
|
|
58
63
|
|
|
59
|
-
## 1
|
|
64
|
+
## 1 发布流程
|
|
65
|
+
|
|
66
|
+
```mermaid
|
|
67
|
+
flowchart TD
|
|
68
|
+
Prepare["确认发布前提 · §2"] --> Close["收口版本记录 · §3"]
|
|
69
|
+
Close --> Verify["验证候选版本 · §4"]
|
|
70
|
+
Verify -->|通过| Merge["合入 main · §5"]
|
|
71
|
+
Verify -->|失败,修正后重验| Close
|
|
72
|
+
Merge --> Final["核对最终提交 · §6"]
|
|
73
|
+
Final -->|通过或验证结果可复用| Tag["锁定版本 · §7"]
|
|
74
|
+
Final -->|需要修正,经修复分支重新验证| Close
|
|
75
|
+
Tag --> Cleanup["清理版本分支 · §8"]
|
|
76
|
+
Cleanup -->|已配置通告| Notice["发布通告 · §9"]
|
|
77
|
+
Cleanup -->|未配置通告| Done([完成])
|
|
78
|
+
Notice --> Done
|
|
79
|
+
click Prepare "#2-确认发布前提"
|
|
80
|
+
click Close "#3-收口版本记录"
|
|
81
|
+
click Verify "#4-验证候选版本"
|
|
82
|
+
click Merge "#5-合入-main"
|
|
83
|
+
click Final "#6-核对最终提交"
|
|
84
|
+
click Tag "#7-锁定版本"
|
|
85
|
+
click Cleanup "#8-清理版本分支"
|
|
86
|
+
click Notice "#9-发布通告"
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## 2 确认发布前提
|
|
60
90
|
|
|
61
|
-
|
|
91
|
+
核对以下条件,未满足的条件补齐后继续
|
|
92
|
+
|
|
93
|
+
| 内容 | 本版要求 |
|
|
62
94
|
| --- | --- |
|
|
63
95
|
| 版本来源 | VERSION,本次为 2.0.0 |
|
|
64
96
|
| 版本记录 | CHANGELOG 本版定版段 |
|
|
65
|
-
| 一致性要求 | VERSION、pyproject.toml
|
|
66
|
-
| 合并链 | feature/report-export-v2.0.0 → main
|
|
97
|
+
| 一致性要求 | VERSION、pyproject.toml 与目标 Tag 版本一致 |
|
|
98
|
+
| 合并链 | feature/report-export-v2.0.0 → main,通过 Pull Request 合并 |
|
|
67
99
|
| Tag | v2.0.0,annotated Tag |
|
|
68
100
|
| 执行环境 | Bash、Git、项目 Python 环境与容器构建工具 |
|
|
69
101
|
| 仓库权限 | 提交版本记录、合并 Pull Request 与推送 Tag |
|
|
70
|
-
| 验证环境 |
|
|
71
|
-
|
|
72
|
-
`scripts/release-verify.sh` 依次执行单元测试、数据库迁移测试、镜像构建及真实对象存储上传与下载验证
|
|
73
|
-
脚本记录源码提交、各项结果与镜像摘要,任一检查失败时返回非零退出码
|
|
74
|
-
验证产生的记录与镜像留在仓库外,验证后清理本次测试数据
|
|
75
|
-
|
|
76
|
-
## 2 发布流程
|
|
77
|
-
|
|
78
|
-
### 2.1 收口版本记录
|
|
79
|
-
|
|
80
|
-
**执行**:将 VERSION 与 pyproject.toml 的项目版本更新为 2.0.0,收口 CHANGELOG 本版定版段并提交
|
|
102
|
+
| 验证环境 | 独立测试数据库与对象存储,使用[测试夹具](testcase.md#1-夹具)中定义的隔离资源 |
|
|
81
103
|
|
|
82
|
-
|
|
104
|
+
`scripts/release-verify.sh` 执行单元测试、数据库迁移测试、镜像构建及对象存储上传与下载验证
|
|
105
|
+
验证结果关联源码提交、验证输入、各项结果与镜像摘要,任一检查失败时返回非零退出码
|
|
106
|
+
验证后清理本次测试数据
|
|
83
107
|
|
|
84
|
-
|
|
108
|
+
## 3 收口版本记录
|
|
85
109
|
|
|
86
|
-
|
|
110
|
+
1. 将 VERSION 与 pyproject.toml 的项目版本更新为 2.0.0,收口 CHANGELOG 本版定版段并提交
|
|
111
|
+
2. 运行 `bash scripts/check-version.sh 2.0.0`
|
|
112
|
+
- 返回 0 且工作区干净:进入[候选验证](#4-验证候选版本)
|
|
113
|
+
- 校验失败:修正版本记录并提交后重新校验
|
|
87
114
|
|
|
88
|
-
|
|
115
|
+
## 4 验证候选版本
|
|
89
116
|
|
|
90
|
-
|
|
117
|
+
1. 运行 `bash scripts/release-verify.sh`
|
|
118
|
+
2. 核对执行结果
|
|
119
|
+
- 全部通过,结果关联当前候选提交:进入[合入 main](#5-合入-main)
|
|
120
|
+
- 验证失败:修正后重新执行本阶段
|
|
121
|
+
- 测试数据清理失败:先清理本次数据,再重新验证
|
|
91
122
|
|
|
92
|
-
|
|
93
|
-
测试数据清理失败时,先清理本次运行的数据,再重新验证
|
|
123
|
+
## 5 合入 main
|
|
94
124
|
|
|
95
|
-
|
|
125
|
+
1. 创建或更新 Pull Request,完成分支保护要求的审查与检查,再合入 main
|
|
126
|
+
- 需要解决冲突或修改内容:经[候选验证](#4-验证候选版本)后更新 Pull Request
|
|
127
|
+
- Pull Request 尚未合并:停在本阶段
|
|
128
|
+
- Pull Request 已合并:继续[最终核验](#6-核对最终提交)
|
|
129
|
+
2. 恢复执行时先核对合并状态,已合并的 Pull Request 沿用其合并结果
|
|
96
130
|
|
|
97
|
-
|
|
131
|
+
## 6 核对最终提交
|
|
98
132
|
|
|
99
|
-
|
|
133
|
+
1. 执行 `git fetch origin`,切换 main 并通过 `git pull --ff-only origin main` 同步
|
|
134
|
+
2. 核对本地与远端 main 一致,工作区干净,运行 `bash scripts/check-version.sh 2.0.0` 通过
|
|
135
|
+
3. 核对[候选验证](#4-验证候选版本)的结果是否适用于当前 main
|
|
136
|
+
- 被测内容、测试、夹具、配置、工具链与依赖环境一致,且验证不依赖变化的提交元数据:复用已有结果,并关联当前 main 提交
|
|
137
|
+
- 复用条件不满足:在当前 main 上运行 `bash scripts/release-verify.sh`
|
|
138
|
+
4. 必需核对与验证均通过后,进入[锁定版本](#7-锁定版本)
|
|
139
|
+
核对或验证未通过时,停在本阶段处理失败原因并重验
|
|
140
|
+
需要修正内容时,经修复分支验证并合入 main 后,重新执行本阶段
|
|
100
141
|
|
|
101
|
-
|
|
102
|
-
解决冲突或修改代码后回到 §2.2 验证,再更新 Pull Request
|
|
103
|
-
恢复执行前核对合并状态,已经合并的 Pull Request 不重复合并
|
|
142
|
+
仅提交号变化时仍需核对上述验证条件,源码内容可用 `git diff --exit-code <候选提交> HEAD` 比较
|
|
104
143
|
|
|
105
|
-
|
|
144
|
+
## 7 锁定版本
|
|
106
145
|
|
|
107
|
-
|
|
108
|
-
|
|
146
|
+
1. 从 CHANGELOG 本版定版段生成仓库外的摘要文件,按[摘要校验工具](../../bin/aca-tag-notify-check)校验格式
|
|
147
|
+
摘要末条采用[最终核验](#6-核对最终提交)的验证结果
|
|
148
|
+
校验失败时,修正摘要并重新校验后继续
|
|
109
149
|
|
|
110
|
-
|
|
111
|
-
|
|
150
|
+
```text
|
|
151
|
+
v2.0.0:报告导出
|
|
112
152
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
**执行**:从 CHANGELOG 本版定版段生成仓库外的摘要文件,按[摘要校验工具](../../bin/aca-tag-notify-check)校验格式
|
|
120
|
-
摘要末条记录 §2.4 的验证结果
|
|
121
|
-
|
|
122
|
-
摘要示例:
|
|
123
|
-
|
|
124
|
-
```text
|
|
125
|
-
v2.0.0:报告导出
|
|
126
|
-
|
|
127
|
-
---NOTIFY-BEGIN---
|
|
128
|
-
📄 报告 · 支持导出并下载业务报告
|
|
129
|
-
✅ 验证 · 单元测试、迁移测试、镜像构建与对象存储验证通过
|
|
130
|
-
---NOTIFY-END---
|
|
131
|
-
```
|
|
153
|
+
---NOTIFY-BEGIN---
|
|
154
|
+
📄 报告 · 支持导出并下载业务报告
|
|
155
|
+
✅ 验证 · 单元测试、迁移测试、镜像构建与对象存储验证通过
|
|
156
|
+
---NOTIFY-END---
|
|
157
|
+
```
|
|
132
158
|
|
|
133
|
-
|
|
134
|
-
|
|
159
|
+
2. 再次同步远端,确认 main 仍指向已验证提交,核对本地与远端目标 Tag
|
|
160
|
+
- 本地与远端均无目标 Tag:使用 `git tag -a v2.0.0 <已验证的main提交> -F /tmp/report-service-v2.0.0.md` 创建 Tag,再执行 `git push origin v2.0.0`
|
|
161
|
+
- main 已变化:回到[最终核验](#6-核对最终提交)
|
|
162
|
+
- Tag 已存在且指向与注解匹配:沿用已有 Tag,远端尚无该 Tag 时补推送
|
|
163
|
+
- 同名 Tag 的指向或注解不匹配:停止并报告冲突
|
|
164
|
+
3. 核对远端为 annotated Tag,指向已验证的 main 提交,注解包含本版摘要
|
|
135
165
|
|
|
136
|
-
|
|
166
|
+
## 8 清理版本分支
|
|
137
167
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
168
|
+
1. 核对远端 Tag 已通过验证,确认本次版本分支已经合入 main,且不再承担后续工作
|
|
169
|
+
2. 按本仓库策略清理该版本分支
|
|
170
|
+
- 满足清理条件:删除本次已合并的本地与远端版本分支
|
|
171
|
+
- 仍承担后续工作或无法确认合并情况:保留该分支
|
|
172
|
+
- 清理失败:保留已固化的 Tag,修复清理问题后继续本阶段
|
|
142
173
|
|
|
143
|
-
##
|
|
174
|
+
## 9 发布通告
|
|
144
175
|
|
|
145
|
-
远端 v* Tag
|
|
146
|
-
|
|
147
|
-
机器人凭据来源与泄露处置见[发布机器人 §3](security.md#3-发布机器人)
|
|
176
|
+
远端 v* Tag 推送触发通告流水线,使用[通告提取工具](../../bin/aca-tag-notify-extract)从 Tag 注解提取内容,发送到研发发布群
|
|
177
|
+
机器人凭据来源与泄露处置见[发布机器人](security.md#3-发布机器人)
|
|
148
178
|
|
|
149
|
-
|
|
150
|
-
|
|
179
|
+
核对通告任务的实际发送结果
|
|
180
|
+
凭据缺失或发送失败时,补齐凭据或修复故障后,使用同一 Tag 重跑通告任务
|
|
151
181
|
````
|
|
152
182
|
|
|
153
183
|
## 5 检查条件
|
|
154
184
|
|
|
155
|
-
- [ ]
|
|
185
|
+
- [ ] 总图与对应阶段一致,发布前提包含版本来源、版本记录、合并链、目标 Tag 与执行条件
|
|
156
186
|
- [ ] 流程覆盖本仓库从发布前验证到合入 main、锁定 Tag 的全部必要操作
|
|
157
|
-
- [ ]
|
|
158
|
-
- [ ]
|
|
159
|
-
- [ ]
|
|
187
|
+
- [ ] 每个阶段有执行方式、通过条件、失败处理与恢复位置
|
|
188
|
+
- [ ] 验证环境、命令与结果判定已定义,已有结果按复用条件核对并关联最终提交
|
|
189
|
+
- [ ] 如采用分级验证,不同影响范围对应的测试集、升级为全量验证的条件及全量验证的兜底方式已定义
|
|
190
|
+
- [ ] 各阶段的前提与结果能够衔接,恢复执行有明确位置
|
|
160
191
|
- [ ] 版本记录一致,摘要来源、格式与校验方式已定义
|
|
161
192
|
- [ ] 远端 annotated Tag 指向已验证的 main 最终提交,版本、提交与验证结果可追溯
|
|
162
193
|
- [ ] Tag 不移动、不重建,推送失败只重推,同名 Tag 的指向或注解冲突时停止
|
|
163
|
-
- [ ]
|
|
164
|
-
- [ ]
|
|
194
|
+
- [ ] 如配置分支清理,范围限定为本次已合并且不再承担后续工作的分支
|
|
195
|
+
- [ ] 如配置通告,触发、内容提取、渠道、凭据来源、发送结果核对与失败重发方式明确
|
|
196
|
+
- [ ] 清理或通告失败时,继续对应阶段并沿用已固化版本
|
|
@@ -14,11 +14,19 @@
|
|
|
14
14
|
| --- | --- | --- |
|
|
15
15
|
| 接口定义 | 始终必需 | [§2.1](#21-接口定义) |
|
|
16
16
|
| 数据结构说明 | 始终必需 | [§2.2](#22-数据结构说明) |
|
|
17
|
-
| 业务解释 |
|
|
17
|
+
| 业务解释 | 声明及关联说明无法承载时必需 | [§2.3](#23-业务解释) |
|
|
18
18
|
|
|
19
19
|
### 2.1 接口定义
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
按调用方使用的语言或协议选择表达方式,常见接口如下
|
|
22
|
+
|
|
23
|
+
| 接口对象 | 表达方式 | 契约内容 |
|
|
24
|
+
| --- | --- | --- |
|
|
25
|
+
| 语言方法 | 对应语言的原始声明与文档机制 | 方法签名、参数、返回与异常 |
|
|
26
|
+
| HTTP 接口 | 所选接口描述规范,如 OpenAPI | HTTP 方法、路径、鉴权、请求与响应 |
|
|
27
|
+
| 事件接口 | 所选协议的事件契约 | 连接入口、事件名、发送方向、消息结构与确认方式 |
|
|
28
|
+
|
|
29
|
+
其他协议按所选协议的接口描述方式定义
|
|
22
30
|
在声明关联的文档说明中写清调用目的、业务能力、结果交付方式、异常及触发条件
|
|
23
31
|
按需说明顺序、范围、空结果、失败、超时及业务副作用
|
|
24
32
|
接口具有幂等性时,说明重复调用的业务含义
|
|
@@ -28,7 +36,8 @@
|
|
|
28
36
|
|
|
29
37
|
### 2.2 数据结构说明
|
|
30
38
|
|
|
31
|
-
|
|
39
|
+
使用对应语言的类型声明或所选数据描述规范,说明写在文档注释、文档字符串或描述字段中
|
|
40
|
+
已有定义直接引用
|
|
32
41
|
被依赖的类型在前,引用它的类型在后
|
|
33
42
|
在参数、返回类型与字段声明处说明业务含义、取值约束与适用的默认值
|
|
34
43
|
类型、必填性、枚举等可声明的约束直接写入声明,各类结果的业务含义写入对应的文档说明
|
|
@@ -38,7 +47,7 @@
|
|
|
38
47
|
|
|
39
48
|
### 2.3 业务解释
|
|
40
49
|
|
|
41
|
-
|
|
50
|
+
使用代码块外的文字或表格,仅补充声明及关联说明未表达的业务含义与约束
|
|
42
51
|
每条业务解释标明对应的接口、字段或结果
|
|
43
52
|
|
|
44
53
|
## 3 模块方法示例:取消订单(TypeScript)
|
|
@@ -178,9 +187,119 @@ export declare function cancelOrder(
|
|
|
178
187
|
}
|
|
179
188
|
```
|
|
180
189
|
|
|
181
|
-
## 5
|
|
190
|
+
## 5 Socket.IO 事件示例:取消订单与状态通知
|
|
191
|
+
|
|
192
|
+
采用 Socket.IO 4.x,事件映射按[官方类型声明](../../SSOT.md#6-api-设计)表达
|
|
193
|
+
载荷使用 zod [数据契约](schema.md#21-契约声明),从校验声明派生事件参数类型
|
|
194
|
+
|
|
195
|
+
### 5.1 连接与认证
|
|
196
|
+
|
|
197
|
+
以下约定由本节两个事件共用
|
|
198
|
+
|
|
199
|
+
| 项目 | 约定 |
|
|
200
|
+
| --- | --- |
|
|
201
|
+
| 服务地址 | `https://api.example.com` |
|
|
202
|
+
| 连接 path | `/socket.io/` |
|
|
203
|
+
| namespace | `/orders` |
|
|
204
|
+
| 连接认证 | `auth.token` 携带订单访问令牌,结构见 `OrderAuthSchema` |
|
|
205
|
+
| 认证失败 | 拒绝连接,客户端收到 `connect_error`,`message` 为 `UNAUTHORIZED` |
|
|
206
|
+
|
|
207
|
+
### 5.2 消息数据
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
import { z } from "zod";
|
|
211
|
+
|
|
212
|
+
/** 订单唯一标识,不能为空或仅含空白字符 */
|
|
213
|
+
const OrderIdSchema = z.string().regex(/\S/);
|
|
214
|
+
|
|
215
|
+
export const OrderAuthSchema = z.object({
|
|
216
|
+
/** 已取得的订单访问令牌 */
|
|
217
|
+
token: z.string().min(1),
|
|
218
|
+
}).strict();
|
|
219
|
+
|
|
220
|
+
export const OrderSchema = z.object({
|
|
221
|
+
id: OrderIdSchema,
|
|
222
|
+
/** 订单当前业务状态 */
|
|
223
|
+
status: z.enum([
|
|
224
|
+
"pending_payment", // 待付款
|
|
225
|
+
"paid", // 已付款
|
|
226
|
+
"cancelled", // 已取消
|
|
227
|
+
]),
|
|
228
|
+
}).strict();
|
|
229
|
+
|
|
230
|
+
export const CancelRequestSchema = z.object({
|
|
231
|
+
/** 要申请取消的订单 */
|
|
232
|
+
orderId: OrderIdSchema,
|
|
233
|
+
}).strict();
|
|
234
|
+
|
|
235
|
+
const CancelledOrderSchema = OrderSchema.extend({ status: z.literal("cancelled") });
|
|
236
|
+
const PaidOrderSchema = OrderSchema.extend({ status: z.literal("paid") });
|
|
237
|
+
|
|
238
|
+
export const CancelAckSchema = z.discriminatedUnion("outcome", [
|
|
239
|
+
// 本次取消已完成,返回取消后的订单
|
|
240
|
+
z.object({ outcome: z.literal("cancelled"), order: CancelledOrderSchema }).strict(),
|
|
241
|
+
// 此前已取消,返回当前订单
|
|
242
|
+
z.object({ outcome: z.literal("already_cancelled"), order: CancelledOrderSchema }).strict(),
|
|
243
|
+
// 订单已付款,返回当前订单
|
|
244
|
+
z.object({ outcome: z.literal("not_allowed"), order: PaidOrderSchema }).strict(),
|
|
245
|
+
// 指定订单不存在
|
|
246
|
+
z.object({ outcome: z.literal("not_found") }).strict(),
|
|
247
|
+
// 请求不符合 CancelRequestSchema
|
|
248
|
+
z.object({ outcome: z.literal("invalid_request") }).strict(),
|
|
249
|
+
// 当前身份没有操作该订单的权限
|
|
250
|
+
z.object({ outcome: z.literal("forbidden") }).strict(),
|
|
251
|
+
// 本次处理未能确认取消结果
|
|
252
|
+
z.object({ outcome: z.literal("failed") }).strict(),
|
|
253
|
+
]);
|
|
254
|
+
|
|
255
|
+
/** 客户端已收到本次订单状态通知 */
|
|
256
|
+
export const StatusAckSchema = z.object({
|
|
257
|
+
outcome: z.literal("received"),
|
|
258
|
+
}).strict();
|
|
259
|
+
|
|
260
|
+
export type Order = z.infer<typeof OrderSchema>;
|
|
261
|
+
export type CancelRequest = z.infer<typeof CancelRequestSchema>;
|
|
262
|
+
export type CancelAck = z.infer<typeof CancelAckSchema>;
|
|
263
|
+
export type StatusAck = z.infer<typeof StatusAckSchema>;
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### 5.3 分方向事件声明
|
|
267
|
+
|
|
268
|
+
以下声明与[消息数据](#52-消息数据)合并为同一个 TypeScript 文件
|
|
269
|
+
|
|
270
|
+
```typescript
|
|
271
|
+
import type { Socket } from "socket.io-client";
|
|
272
|
+
|
|
273
|
+
export interface ClientToServerEvents {
|
|
274
|
+
/**
|
|
275
|
+
* 客户端向服务端申请取消订单
|
|
276
|
+
* 订单须属于当前身份的可操作范围
|
|
277
|
+
* @param request 取消请求,按 CancelRequestSchema 校验
|
|
278
|
+
* @param ack 交付本次取消的业务结果,按 CancelAckSchema 校验
|
|
279
|
+
* @remarks 5 秒未收到确认或连接中断时,可重发同一 orderId;
|
|
280
|
+
* 已取消的订单返回 already_cancelled,不重复产生取消效果
|
|
281
|
+
*/
|
|
282
|
+
"order.cancel": (request: CancelRequest, ack: (result: CancelAck) => void) => void;
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
export interface ServerToClientEvents {
|
|
286
|
+
/**
|
|
287
|
+
* 服务端向客户端推送当前身份可访问订单的最新状态
|
|
288
|
+
* @param order 订单状态,按 OrderSchema 校验
|
|
289
|
+
* @param ack 客户端确认收到本次通知,按 StatusAckSchema 校验
|
|
290
|
+
* @remarks 服务端等待确认 5 秒,本例超时后不重发该通知;
|
|
291
|
+
* 重连后服务端推送当前可访问订单的最新状态
|
|
292
|
+
*/
|
|
293
|
+
"order.status": (order: Order, ack: (result: StatusAck) => void) => void;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** 客户端接收 ServerToClientEvents,发送 ClientToServerEvents */
|
|
297
|
+
export type OrderSocket = Socket<ServerToClientEvents, ClientToServerEvents>;
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
## 6 检查条件
|
|
182
301
|
|
|
183
|
-
###
|
|
302
|
+
### 6.1 接口契约混入实现机制
|
|
184
303
|
|
|
185
304
|
- [ ] 能力行为不变、内部实现更换后,接口描述仍成立
|
|
186
305
|
- [ ] 实现机制未替代调用方可验证的行为约束
|
|
@@ -193,10 +312,10 @@ export declare function cancelOrder(
|
|
|
193
312
|
| 并行查询库存与物流,超时取消在途请求 | 超时时返回已查到的信息,未查到的部分标记为超时 |
|
|
194
313
|
| 查询走只读副本,不参与事务 | 查询不会修改订单 |
|
|
195
314
|
|
|
196
|
-
###
|
|
315
|
+
### 6.2 说明与声明分离
|
|
197
316
|
|
|
198
|
-
- [ ]
|
|
199
|
-
- [ ]
|
|
317
|
+
- [ ] 接口与数据结构按调用方使用的语言或协议声明,说明写在对应文档机制或描述字段中
|
|
318
|
+
- [ ] 独立业务解释仅补充声明及关联说明无法承载的内容,且能定位对应声明
|
|
200
319
|
|
|
201
320
|
**反例**
|
|
202
321
|
|
|
@@ -204,9 +323,11 @@ export declare function cancelOrder(
|
|
|
204
323
|
|
|
205
324
|
调用方必须在声明与表格之间对照,接口契约未在声明处完整表达
|
|
206
325
|
|
|
207
|
-
###
|
|
326
|
+
### 6.3 接口定义不规范或类型顺序不符
|
|
208
327
|
|
|
209
328
|
- [ ] 模块方法使用对应语言的原始声明,网络接口按所选接口描述规范定义
|
|
329
|
+
- [ ] 网络接口的连接入口可定位,事件契约明确事件名与发送方向
|
|
330
|
+
- [ ] 采用确认机制时,确认结果的业务含义明确
|
|
210
331
|
- [ ] 数据结构使用对应语言的类型声明或所选接口描述规范定义
|
|
211
332
|
- [ ] 数据结构声明中,被依赖的类型在前,引用它的类型在后
|
|
212
333
|
|
|
@@ -232,7 +353,7 @@ export declare function cancelOrder(
|
|
|
232
353
|
|
|
233
354
|
该样例未定义字段是否必填,也未定义 `outcome` 的完整允许取值
|
|
234
355
|
|
|
235
|
-
###
|
|
356
|
+
### 6.4 数据结构说明不完整
|
|
236
357
|
|
|
237
358
|
- [ ] 每个输入、输出及其数据字段均有业务含义、取值约束与适用的默认值说明
|
|
238
359
|
- [ ] 沿类型依赖递归说明,直至所用语言或描述规范的基本数据类型
|
|
@@ -250,7 +371,7 @@ export interface OrderSummary {
|
|
|
250
371
|
|
|
251
372
|
既没有给出 `OrderStatus` 的定义与取值含义,也没有提供具体引用位置,无法继续查到完整说明
|
|
252
373
|
|
|
253
|
-
###
|
|
374
|
+
### 6.5 接口能力或输出含义不清
|
|
254
375
|
|
|
255
376
|
- [ ] 说明调用目的、接口提供的业务能力,以及已约定的各类输出结果的业务含义与交付方式
|
|
256
377
|
- [ ] 适用的顺序、范围、空结果、失败、超时及业务副作用均有明确约定
|
|
@@ -265,9 +386,9 @@ export declare function cancelOrder(orderId: string): Promise<CancelOrderResult>
|
|
|
265
386
|
|
|
266
387
|
没有说明重复调用、订单不存在、订单已付款时各自得到什么结果,调用方无法据此处理任何一种非正常情况
|
|
267
388
|
|
|
268
|
-
###
|
|
389
|
+
### 6.6 文字复述了声明已表达的内容
|
|
269
390
|
|
|
270
|
-
- [ ]
|
|
391
|
+
- [ ] 声明关联的说明补充业务含义与约束,不重复声明已经明确的类型、只读性等信息
|
|
271
392
|
|
|
272
393
|
**反例**
|
|
273
394
|
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
```
|
|
47
47
|
|
|
48
48
|
`user-guide/` 面向产品使用者,指导接入或使用产品
|
|
49
|
-
`ops-guide/`
|
|
49
|
+
`ops-guide/` 面向运营或数据平台使用者,按本工程需要提供数据收集、分析判断或运营动作指导
|
|
50
50
|
`user-guide/` 内的指南根据使用方式选用 [integration-guide](../documents/integration-guide.md) 或 [user-manual](../documents/user-manual.md) 的写法
|
|
51
51
|
`ops-guide/` 按 [ops-guide](../document-sets/ops-guide.md) 文档组组织
|
|
52
52
|
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
| `instrumentation.md` | 始终必需 | [instrumentation](../documents/instrumentation.md) |
|
|
65
65
|
| `interface.md` | 始终必需 | [interface](../documents/interface.md) |
|
|
66
66
|
| `module-<标识>/` 文档组 | SDK 包含多个业务模块 | [module](../document-sets/module.md) |
|
|
67
|
-
| `ops-guide/` 文档组 |
|
|
67
|
+
| `ops-guide/` 文档组 | 本工程需要向运营或数据平台使用者提供数据收集、分析判断或运营操作指导 | [ops-guide](../document-sets/ops-guide.md) |
|
|
68
68
|
| `release.md` | 需要发布版本 | [release](../documents/release.md) |
|
|
69
69
|
| `security.md` | 涉及凭据、用户数据、网络传输或权限 | [security](../documents/security.md) |
|
|
70
70
|
| `testcase.md` | 始终必需 | [testcase](../documents/testcase.md) |
|
|
@@ -143,7 +143,7 @@ SDK 分发与后台部署分别由 `sdk/design/distribution.md` 和 `backend/des
|
|
|
143
143
|
必要条件沿用各自类型规则
|
|
144
144
|
运营指南按采集、分析与动作职责分篇
|
|
145
145
|
各篇的内容组织沿用 [ops-guide](../document-sets/ops-guide.md) 文档组与对应文档设计
|
|
146
|
-
|
|
146
|
+
一个运营目标涉及两端时,已选用的指南引用对应端的契约、数据与安全设计
|
|
147
147
|
通过跨文档引用串联数据采集、分析判断、运营动作与效果验证
|
|
148
148
|
共用方法与操作在一处定义,其他指南引用
|
|
149
149
|
|