crm-backend-matt/.scratch/api-docs-reorg/tmp_write_readmes.py

# -*- coding: utf-8 -*-
# 票 04 / t10：11 个分区索引 README 程序化落盘（文档仓在 workspace 外，Bash+python 写入）
# 自校验：写后回读逐字比对，任何丢载荷当场报错
import os, sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
DOCS = r'E:\code\crm-api-docs'

FOOTER = (
    "\n---\n\n"
    "> 维护纪律：本 README 为人工维护的分区索引；`.bru` 接口文件由 bruno-sync 依据后端 "
    "Controller tag 自动同步（只动带 `generated` 标记的文件，结构听源码、表述听人），请勿手改。"
    "新接口按页面全路径挂 tag 即自动归位对应目录；一级目录与蓝湖原型 A 区分区一一对应，"
    "二级及更深目录不做重排。\n"
)

READMES = {}

READMES['A0 登录界面'] = """# A0 登录界面

> 对应蓝湖原型「A0 登录界面」分区（A0-1 登录、A0-3 个人信息）。

## 已落地接口（5 个，均在分区根目录）

- 钉钉登录 —— 钉钉扫码登录
- 确认顶号登录 —— 单设备登录顶号后的确认
- 注销 —— 退出登录
- 获取当前用户信息 —— 登录态下取当前用户
- 菜单树 —— 登录后拉取前端菜单树（随原「登录」分组整体并入本分区）

## 空缺标注

- A0-1 登录页：接口已齐。
- A0-3 个人信息页：暂无独立接口目录，当前用户信息经「获取当前用户信息」获取。

## 对接工程师示位

负责登录页与全局壳（菜单 / 当前用户）的前端工程师只对接本分区 5 个接口；其余全部业务接口均需登录后携带 token 调用。
"""

READMES['A1 销售工作台（首页）'] = """# A1 销售工作台（首页）

> 对应蓝湖原型「A1 销售工作台（首页）」分区（A1-1 工作台、A1-2 消息中心）。

**占位分区：暂无接口落地。** 原型两页对应的后端接口尚未开发；接口落地后由 bruno-sync 按源码 tag 自动同步至本分区，并同步更新本 README。
"""

READMES['A1X 工作计划'] = """# A1X 工作计划

> 对应蓝湖原型「A1X 工作计划」分区（v29 新增：A1X-1 工作日历、A1X-2 计划管理、A1X-3 出差与拜访）。

**占位分区：暂无接口落地。** 原型页面为 v29 新增，后端接口尚未开发。

注意：现有「工作计划」类接口（新增 / 编辑 / 删除 / 列表）当前归属商机详情页，见 `A3 商机管理/商机详情/工作计划/`；A1X 页面联调如需独立的工作计划接口，另行裁决挂载。
"""

READMES['A2 线索管理'] = """# A2 线索管理

> 对应蓝湖原型「A2 线索管理」分区（A2-1 线索：公海 / 我的线索 / 我的关注 / 线索管理 / 线索设置）。

## 已落地接口（56 个 / 5 个页面目录）

- **我的线索/**（14）：新建线索、编辑线索、删除线索、转商机、释放线索、批量释放、提交反馈、保存反馈草稿、线索分页、线索详情、历史记录、视图统计卡片、读取列偏好、保存列偏好
- **线索公海/**（12）：领取线索、批量领取、关注线索、批量关注、取消关注、释放线索、线索分页、线索详情、历史记录、视图统计卡片、读取列偏好、保存列偏好
- **我的关注/**（10）：领取线索、批量领取、取消关注、批量取关、线索分页、线索详情、历史记录、视图统计卡片、读取列偏好、保存列偏好
- **线索管理/**（15）：新建线索、激活线索、批量激活、分配线索到池、批量分配到池、分配线索到销售、批量分配到销售、删除线索、批量删除、线索分页、线索详情、历史记录、视图统计卡片、读取列偏好、保存列偏好
- **线索设置/**（5）：公海池分页列表、公海池详情、新建编辑公海池、删除公海池、批量删除公海池

## 空缺标注

无 —— 原型 A2-1 下五个功能页均有接口落地。

## 对接工程师示位

线索模块前端按页面目录联调：列表页四选一（我的线索 / 线索公海 / 我的关注 / 线索管理），每个目录内含该页全集（分页、详情、历史、统计卡片与列偏好）；公海池配置页用「线索设置」。同一接口出现在多个目录是按页面归属的多副本（内容一致），取所在页面那份联调即可。「线索设置」在 `A7 后台管理/线索规则/` 另有后台入口副本（双归属，同源自动同步）。
"""

READMES['A3 商机管理'] = """# A3 商机管理

> 对应蓝湖原型「A3 商机管理」分区（A3-0 最近访问 / A3-1 销售机会 / A3-2 商机管理 / A3-3 商机公海 + 说明页）。

## 已落地接口（62 个）

- **新建商机/**（2）：新建商机、可关联线索下拉
- **销售机会/**（1）：商机分页
  - 销售机会/看板列表/（2）：看板阶段卡片、看板阶段汇总
  - 销售机会/自定义视图/（4）：自定义视图列表、保存自定义视图、删除自定义视图、设为默认视图
- **商机管理/**（1）：商机分页
  - 商机管理/看板列表/（2）：看板阶段卡片、看板阶段汇总
- **商机公海/**（1）：商机分页
  - 商机公海/看板列表/（2）：看板阶段卡片、看板阶段汇总
- **状态流转/**（11）：领取商机、批量领取、分配商机、批量分配、移交商机、抛公海、暂缓、取消暂缓、关闭商机、批量关闭、重启商机
- **商机详情/**（根目录无文件，接口全在子目录）
  - 主体/（9）：商机详情、编辑商机、切换阶段、阶段推进历史、阶段推进指引、关注商机、批量关注、取关商机、上报访问
  - 客户/（4）：客户列表、候选客户搜索、添加关联客户、设为主要意向客户
  - 团队/（4）：团队成员列表、批量添加团队成员、移除团队成员、编辑团队成员
  - 方案卡/（5）：方案卡列表、方案卡详情、保存方案卡、提交方案卡、可选模板版本
  - 跟进/（3）：新增跟进、删除跟进、跟进分页
  - 附件/（3）：新增附件、删除附件、附件列表
  - 日志/（1）：操作日志分页
  - 勘察/（3）：新增勘察、删除勘察、勘察分页
  - 工作计划/（4）：新增工作计划、编辑工作计划、删除工作计划、工作计划列表

## 空缺标注

无 —— 原型 A3 各功能页均有接口落地。说明：原型「A3-0 最近访问」复用销售机会分页端点（viewType=RECENT），不设独立接口目录。

## 对接工程师示位

商机模块前端按页面目录联调：三个列表页（销售机会 / 商机管理 / 商机公海）各自含分页与看板子目录；商机详情页接口集中在「商机详情/」下按页签分目录（主体 / 客户 / 团队 / 方案卡 / 跟进 / 附件 / 日志 / 勘察 / 工作计划）；商机全生命周期操作（领取 / 分配 / 移交 / 关闭等）在「状态流转/」。
"""

READMES['A4 客户管理'] = """# A4 客户管理

> 对应蓝湖原型「A4 客户管理」分区（A4-1 客户公海 / A4-2 客户总览 / A4-3 我的客户 / A4-4 客户详情 / A4-5 联系人 / A4-6 客户查重 / A4-7 客户交割）。

**占位分区：暂无接口落地。** 原型七个页面组对应的后端接口尚未开发；接口落地后由 bruno-sync 按源码 tag 自动同步至本分区，并同步更新本 README。
"""

READMES['A5 项目管理'] = """# A5 项目管理

> 对应蓝湖原型「A5 项目管理」分区（A5-1 项目管理：看板 / 分屏 / 列表视图、我的项目、项目统计）。

**占位分区：暂无接口落地。** 原型页面对应的后端接口尚未开发；接口落地后由 bruno-sync 按源码 tag 自动同步至本分区，并同步更新本 README。
"""

READMES['A6 数据看板'] = """# A6 数据看板

> 对应蓝湖原型「A6 数据看板」分区（A6-1 数据看板：运营看板 / 客户看板 / 营销看板）。

**占位分区：暂无接口落地。** 原型三个看板对应的后端接口尚未开发；接口落地后由 bruno-sync 按源码 tag 自动同步至本分区，并同步更新本 README。
"""

READMES['A7 后台管理'] = """# A7 后台管理

> 对应蓝湖原型「A7 后台管理」分区（A7-1 用户管理 / A7-2 权限管理 / A7-3 业务规则 / A7-4 日志管理 / A7-5 系统设置）。

## 已落地接口（61 个）

- **用户管理/**（4）：用户分页、用户统计、分配用户角色、分配用户部门
- **部门管理/**（3）：部门树、保存部门、删除部门
- **权限管理/角色管理/**（6）：角色分页、角色详情、新增编辑角色、删除角色、分配角色权限、可配数据权限模块
- **权限点管理/**（4）：资源树列表、新增编辑资源节点、删除资源节点、上传图标
- **线索规则/**（5）：公海池分页列表、公海池详情、新建编辑公海池、删除公海池、批量删除公海池（`A2 线索管理/线索设置/` 的后台入口副本，双归属同源同步）
- **商机规则/公海规则/**（8）：公海规则分页、公海规则详情、保存公海规则草稿、发布公海规则、停用公海规则、删除公海规则、复制公海规则、公海规则版本列表
- **商机规则/方案卡模板/**（9）：方案卡模板分页、方案卡模板详情、保存方案卡模板草稿、发布方案卡模板、停用方案卡模板、删除方案卡模板、复制方案卡模板、方案卡模板版本列表、系统字段库列表
- **商机规则/阶段模板/**（8）：阶段模板分页、阶段模板详情、保存阶段模板草稿、发布阶段模板、停用阶段模板、删除阶段模板、复制阶段模板、阶段模板版本列表
- **数据字典-分组/**（5）：分组分页、新建编辑分组、分组启停、删除分组、启用分组列表
- **数据字典-字典项/**（7）：字典项分页、新建编辑字典项、字典项启停、设为默认项、删除字典项、强制删除字典项、启用项列表
- **运维/**（2）：管理员角色配置、钉钉组织同步

## 空缺标注

- A7-3 业务规则的「客户规则」「项目规则」两页暂无接口。
- A7-4 日志管理（用户操作日志 / 登录日志 / 批量操作日志）暂无接口。

## 对接工程师示位

后台管理端前端按二级目录联调：用户 / 部门 / 权限（角色 + 权限点）为账号权限体系；商机规则三目录对应原型 A7-3-2（自 v29 起由 A3 迁入，后台为唯一入口）；数据字典两目录对应 A7-5-1；「运维」含管理员角色配置与钉钉组织同步（对应 A7-1-2 同步任务）。部门管理无独立原型页，接口供用户管理「分配部门」与数据权限配置消费。
"""

READMES['公共依赖'] = """# 公共依赖

> 跨业务模块共用的基础资源接口（文件、行政区划），供各分区页面组合调用。

## 已落地接口（11 个）

- **文件/**（9）：直传上传、分片初始化、上传分片、完成分片、删除文件、下载文件、文件详情、预览地址、缩略图
- **行政区划/**（2）：按层级查区划、按上级查子区划

## 空缺标注

无 —— 文件与行政区划即当前全部公共资源。

## 对接工程师示位

不需要单独对接本分区；各业务页面（附件上传 / 下载 / 预览、地址选择等）按需引用。文件接口含直传与分片两条上传通路，在线预览经「预览地址」接口取跳转地址。
"""

READMES['调试(验证专用)'] = """# 调试(验证专用)

> 验证环境专用辅助接口，不对应任何原型页面，生产前端请勿调用。

## 已落地接口（1 个）

- 签发调试token —— 为自动化验证 / 联调签发调试用 token（仅在 verify 运行 profile 下开放）

## 空缺标注

不适用。
"""

count = 0
for d, body in READMES.items():
    path = os.path.join(DOCS, d, 'README.md')
    full = body + FOOTER
    with open(path, 'w', encoding='utf-8', newline='\n') as f:
        f.write(full)
    back = open(path, encoding='utf-8-sig').read()  # -sig 顺带暴露意外 BOM（BOM 会被读掉但不等于存在）
    raw = open(path, 'rb').read()
    bom = raw[:3] == b'\xef\xbb\xbf'
    if back != full:
        raise SystemExit('MISMATCH: ' + path)
    print('OK  ', d, ' chars=', len(full), ' BOM=', bom)
    count += 1
print('total README files written:', count)