You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
30 lines
3.3 KiB
30 lines
3.3 KiB
6 days ago
|
# -*- coding: utf-8 -*-
|
||
|
|
# 票 04 / t11：ADR-0024 文末追加 2026-08-31 修订段（六要点 + 机制联动），回读校验
|
||
|
|
import sys, io
|
||
|
|
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
|
||
|
|
TARGET = r'E:\code\crm-backend-matt\docs\adr\0024-bruno-docs-grouping-by-menu.md'
|
||
|
|
|
||
|
|
SECTION = """## 修订（2026-08-31，api-docs-reorg effort）
|
||
|
|
|
||
|
|
**一级目录对齐蓝湖原型 A 区**：v29 快照（2026-08-31）冻结为权威树（`.scratch/api-docs-reorg/lanhu-tree-v29.md`），文档仓一级目录改为 A0 登录界面 / A1 销售工作台（首页）/ A1X 工作计划 / A2 线索管理 / A3 商机管理 / A4 客户管理 / A5 项目管理 / A6 数据看板 / A7 后台管理 / 公共依赖 / 调试(验证专用)，与原型 A 区分区一一对应；二级及更深目录不做重排。
|
||
|
|
|
||
|
|
1. **深 tag 纪律**：tag = 完整页面路径——一级 = 分区原文，二级 = 页面，更深 = 页面内分组（最深 4 级，如 `A7 后台管理/商机规则/公海规则`）。tag 原文即文档目录路径（bruno-sync 身份映射），swagger/knife4j 分组同构。决策 2 的 `menuBindings`（viewType/scopeKey 绑定）不变，四键前缀随本修订换为 `A2 线索管理/…`。
|
||
|
|
2. **商机规则归 A7**（决策 1 页面归属修正）：v29 将 A3-4 商机管理设置整体迁至 A7-3-2 商机规则，后台为唯一入口，阶段模板 / 方案卡模板 / 公海规则三组接口改挂 `A7 后台管理/商机规则/{阶段模板,方案卡模板,公海规则}`。线索规则接口（LeadPoolController）对称裁决为**双归属**：`A2 线索管理/线索设置`（主本，功能页所在）+ `A7 后台管理/线索规则`（副本，A7-3-1 为 A2-1-5 的引用页）。
|
||
|
|
3. **双归属 = 方法级多值 `@Operation(tags)`**：单接口挂 N 个 tag 即在 N 个页面文件夹各有一份副本，由 bruno-sync「多值全取」幂等输出，无需生成器特判。
|
||
|
|
4. **URL 回退通道关闭**：无 tag 端点不再按 URL 兜底分组——全部端点必须显式挂深 tag（SystemController 10 端点已补挂，`system/` 游离顶级目录消灭）；「进集合的端点必挂 tag」成为一眼可审纪律。
|
||
|
|
5. **新接口挂载纪律**：新 Controller 一律按页面全路径挂 tag——1:1 页面控制器可用类级 `@Tag`，跨页 / 双归属用方法级多值 tags；类级 `@Tag` 与方法级 `@Operation(tags)` 互斥，并存会因「多值全取」产生双份副本；无真实页面入口的接口不挂页签（2026-08-17 修订纪律延续）。
|
||
|
|
6. **机制联动**：bruno-sync 注解驱动通道为唯一权威机制；手工生成器家族（`gen_bruno.py` / `gen_opp_*.py` / `gen_v2_*.py` / `bru_lib.py`）退役留档、不再运行，其 `MENUS` 常量同源义务随之作废；分区索引 README 为人工维护件（bruno-sync 不生成 README）。文档仓现路径 `E:\\code\\crm-api-docs`（2026-08-31 换机记录，前值 `D:\\code\\crm-api-docs` 作废）。
|
||
|
|
"""
|
||
|
|
|
||
|
|
txt = open(TARGET, encoding='utf-8').read()
|
||
|
|
txt = txt.rstrip()
|
||
|
|
new = txt + '\n\n' + SECTION
|
||
|
|
with open(TARGET, 'w', encoding='utf-8', newline='\n') as f:
|
||
|
|
f.write(new)
|
||
|
|
back = open(TARGET, encoding='utf-8').read()
|
||
|
|
assert back == new, 'MISMATCH after append'
|
||
|
|
raw = open(TARGET, 'rb').read()
|
||
|
|
print('OK appended; total chars=', len(back), ' BOM=', raw[:3] == b'\xef\xbb\xbf')
|
||
|
|
print('--- tail ---')
|
||
|
|
print('\n'.join(back.splitlines()[-6:]))
|