csctalon/docs

docs 目录组织与命名规范

性质：元需求（META）—— 约束"文档放哪、叫什么名" 生效日期：2026-09-03 版本：v2.2（2026-10-07 #215：§六计数全部按实盘校正——META 15 约束源 / arch 50 锁定 / API 449 路径·547 操作，补登《仓库入库规范》并挂入 AGENTS 铁律 14；v2.1 为 2026-09-11 加入「文档性质索引」） 适用范围：docs/ 下所有文档的命名与放置位置（新增强制，存量按本规范归位） 关联：standards/文档性质标记规范.md（管"文档是什么性质"，与本规范正交）

背景：docs 根目录历史文档中英文混杂、报告/规范/设计/说明混放、无日期前缀，检索与维护困难。v2.0 起统一为「目录按类型 + 文件按类型前缀 + 带日期时间戳」。v2.1 起增加性质标记（元需求/需求/参考），见 §六。

---

一、目录职责（按类型分目录）

目录	类型	命名格式	示例
docs/arch/	已锁定架构设计	A-YYYYMMDD-序号-简述.md	A-20260903-001-issue-automation-gates.md
docs/arch/_pending/	待审核设计草案	同 arch 编号	A-20260903-002-xxx.md（PENDING）
docs/standards/	规范/清单/模板	英文 kebab-case	error-code.md、issue-workflow.md
docs/reports/	审计/审查/审核报告	YYYYMMDD-主题-类型.md	20260831-看板缓存优化-审计报告.md
docs/debug/	调试会话/故障归档	debug-<主题>-<YYYYMMDD>.md	debug-cs-record-gap-20260902.md
docs/security/	安全事件/凭证整改	kebab-case	credential-incident-remediation.md
docs/ops/	运维手册/SOP	<主题>-运维手册.md	数据采集-运维手册.md
docs/design/	未锁定设计/方案（评审中）	<主题>-<YYYYMMDD>.md	投诉数据接入设计.md（若未锁定）
docs/ 根目录	全局总纲/索引	中文名或 README	README.md、规划设计.md

规则：报告进 reports，规范进 standards，手册进 ops，设计进 design（锁定后进 arch），调试进 debug。

⚠️ 目录名 ≠ 性质：docs/standards/ 里混着 REF（参考）与 REQ（需求）类文档。 目录只表示"它是规范性材料"；真正约束力看 §六 的性质索引。

---

二、命名规则（统一格式：类型前缀 + 主题 + 日期时间戳）

2.1 通用规则

1. 带时间戳的文档（报告/审计/调试/设计）→ 文件名末尾含 YYYYMMDD 日期。
2. 不带时间戳的文档（规范/清单/手册）→ 用英文 kebab-case 或中文主题名，靠目录体现类型。
3. 禁用：空格、全角字符、无意义序号（新建文档.md、文档1.md、最终版.md）。
4. 中文与英文混排：主题用中文（可读性好），类型/日期用标准格式。

2.2 按类型细表

类型	格式	示例
审计报告	YYYYMMDD-<主题>-审计报告.md	20260831-看板缓存优化-审计报告.md
审查/审核报告	YYYYMMDD-<主题>-审查报告.md	20260820-全栈审查报告.md
调试归档	debug-<主题>-<YYYYMMDD>.md	debug-cs-record-gap-20260902.md
设计（未锁定）	<主题>-<YYYYMMDD>.md	投诉数据接入设计.md
规范	<主题>规范.md 或 kebab-case	数据时间字段使用规范.md
运维手册	<主题>-运维手册.md	数据采集-运维手册.md
说明文档	<主题>说明.md	数据库表结构说明.md

---

三、存量归位映射（本次执行）

现状（根目录）	目标位置	新文件名
审计报告-看板缓存优化-2026-08-31.md	docs/reports/	20260831-看板缓存优化-审计报告.md
审计报告-部署日志分析-2026-08-30.md	docs/reports/	20260830-部署日志分析-审计报告.md
审计报告-全栈审计-v0.7.md	docs/reports/	20260902-全栈审计-审计报告.md
审核报告-全栈审查-v0.6.md	docs/reports/	20260820-全栈审查-审查报告.md
审核报告-界面工作流管理效果.md	docs/reports/	界面工作流管理效果-审查报告.md
审查报告-规划设计审查-v0.6.md	docs/reports/	规划设计审查-审查报告.md
数据时间审核报告.md	docs/reports/	20260801-数据时间审核-审计报告.md
数据采集运维手册.md	docs/ops/	数据采集-运维手册.md
数据时间字段使用规范.md	docs/standards/	保持原名
数据同步与加工说明.md	docs/standards/	保持原名
数据源接入与缓存加速规范.md	docs/standards/	保持原名
workbuddy数据同步接入规范.md	docs/standards/	保持原名
workbuddy手动退款数据同步接入规范.md	docs/standards/	保持原名
外部只读数据接入规范.md	docs/standards/	保持原名
投诉数据接入说明.md	docs/standards/	保持原名
数据库表结构说明.md	docs/standards/	保持原名
人均效率算法说明.md	docs/standards/	保持原名
界面设计说明规范.md	docs/standards/	新增 v1.0（2026-09-11）· 强制
Group-Specialty双体系设计.md	docs/design/	保持原名
腾讯云部署迁移方案.md	docs/design/	保持原名
共享文档投诉数据接入设计.md	docs/design/	保持原名
需求派工单-外部工具只读开放平台-草稿.md	docs/design/	保持原名
审查行动项登记.md	docs/（总纲）	保持原名
alembic-migration管理规范.md	docs/standards/	保持原名
API接口文档.md	docs/（总纲）	保持原名
规划设计.md / 规划设计-v0.5.md	docs/（总纲）	保持原名

注意：audit-report-20260820.html、csctalon.xmind 为附件，保持原位不移动。

---

四、运维手册的分发（不在生产目录）

docs/ 不随发布包进生产（package.sh 排除 docs，upgrade.sh 清理 docs），因此运维手册在生产服务器上不可见。运维人员获取方式二选一：

1. 首选：从代码仓库（Gitea）在线查看——运维手册与代码同仓库，永远是最新版本。
2. 兜底：将手册同步到团队共享文档/知识库，供无仓库访问权限的现场人员查阅。

原则：手册跟随代码仓库，不单独部署到运行环境；如确需服务器现场可查，可在 .env 指向的 logs/ 同级放一份拷贝，但不要改发布打包清单。

---

五、存量迁移 SOP（未来再次归位时复用）

本次（2026-09-03）已完成首轮归位。若未来再次新增分类或调整命名，按此 SOP 执行，避免断链。

5.1 步骤

1. 先建工单（governance 类），明确迁移映射表（旧路径 → 新路径）。
2. 盘点交叉引用：grep -rn '旧文件名' --include='*.md' 找全引用方。
3. 先改引用，再移动（或移动后立即同步改，顺序必须闭环）：
   • docs/xxx.md 绝对路径引用 → 直接替换为新路径；
   • ](xxx.md) 相对路径引用 → 按「当前文件目录到目标文件目录」重算相对路径。
4. 用 git mv 移动（保留历史，git 识别 rename）。
5. 验证断链：遍历所有 .md 的相对链接，逐一检查目标文件是否存在。
6. 提交并关联工单号，gitleaks 通过后推送。

5.2 断链验证脚本（可直接复用）

cd <repo_root>
python3 - <<'PY'
import os, re
broken = []
for root, dirs, fs in os.walk("."):
    if ".git" in root or "node_modules" in root or ".venv" in root:
        continue
    for f in fs:
        if not f.endswith(".md"):
            continue
        path = os.path.join(root, f)
        content = open(path, encoding="utf-8").read()
        for m in re.finditer(r'\]\(([^)]+)\)', content):
            t = m.group(1)
            if t.startswith(("http://", "https://", "file://", "#")):
                continue
            tc = t.split("#")[0]
            if not tc.endswith(".md"):
                continue
            tp = os.path.normpath(os.path.join(root, tc))
            if not os.path.exists(tp):
                broken.append((path, t))
if broken:
    print("BROKEN:")
    for p, t in broken:
        print("  ", p, "->", t)
else:
    print("NO BROKEN LINKS")
PY

5.3 易错点（本次踩坑）

• 相对路径 vs 绝对路径：docs/xxx.md 开头的引用不受文件位置影响，可直接 sed 全局替换；](xxx.md) 相对引用必须按新位置重算 ../ 层级。
• 跨目录 ../ 数量：文件从根目录移入 docs/design/ 后，引用仓库根文件需从 ../AGENTS.md 改为 ../../AGENTS.md。
• 历史遗留链接：指向已迁移目录（如 .trae/documents/）的链接，应改指向 arch 里对应的锁定文档。
• README 目录树与索引：移动后必须同步更新 README 的目录树代码块和文档索引表。

---

六、文档性质索引（v2.1 新增）

单一事实来源：本表是全部约束性文档的性质登记处。 判定标准与三类差异见 standards/文档性质标记规范.md。

性质：META=元需求（约束所有需求怎么做）· REQ=需求（做一个具体功能）· REF=参考（现状记录，无约束）

强制链：META 中的"强制类"必须挂进 AGENTS.md，否则标记只是标签、不构成约束。

6.1 元需求（META）—— standards/ 15 份 + 根级 AGENTS.md（共 16 个约束源，实盘 2026-10-16）

文档	强制力	AGENTS 引用	一句话职责
AGENTS.md（根级）	🔴 强	自身即约束源	仓库级 AI 铁律（禁止 console.log / 裸 SQL 拼接 / 硬编码密钥）+ 工单纪律 + 界面设计纪律
standards/issue-workflow.md	🔴 强	✅	所有任务先建工单；一单一目标；禁止无凭证关闭
standards/review-checklist.md	🔴 强	✅	代码审查清单（安全/正确性/一致性/性能/界面设计）；CRITICAL 阻塞合并
standards/数据时间字段使用规范.md	🔴 强	✅	时区换算元规则（AT TIME ZONE 'Asia/Shanghai'）+ SYS/system 排除
standards/界面设计说明规范.md	🔴 强	✅	界面五要素 + 三层落地；"说不清替谁解决问题的界面不许开工"
standards/看板卡片数据说明与下钻规范.md	🔴 强	✅	看板卡片双强制：必须有数据说明（来源/口径/时点）+ 必须可下钻（带窗口与筛选）；不可下钻须声明理由。v1.1 新增 §八 看板技术路线主序：新增看板默认配置驱动，手写页须复用 components/dashboard/ 标准封装（#259）
standards/error-code.md	🔴 强	✅ 铁律 8	全后端响应格式元规则（成功 {code:0,data,message}、错误走 HTTPException）
standards/数据采集合并去重机制说明.md	🟠 中	✅ 铁律 9	所有采集通道的去重键口径（投诉指纹 / 手动退款复合键 / 各 data_type 唯一键）
standards/投诉渠道口径与对账说明.md	🟠 中	✅ 铁律 10	投诉三源归类的权威定义（改动影响所有投诉统计）+ 双方缺口对账口径
standards/退款五路数据标准与采纳规则.md	🟠 中	✅ 铁律 15	退款五路（A线上直退/B钱包流水/C闪猫/D手动/E企微记录）采纳口径权威定义：原始表只同步+三态采纳标识、统计一律读 std_* 标准表、E 路企业商户维表与运营标签两维并存（#332）
standards/数据源接入与缓存加速规范.md	🔴 强	✅ 铁律 11	新增数据源/看板接口的缓存铁律（写入后必须失效 pattern、key 逐字符对齐）
standards/数据源命名与分组规范.md	🟠 中	✅ 铁律 13	数据查看树的命名与分组元规则：五分组顺序唯一来源、前缀白名单、⚠️ 强制标注（停用/易误用）、投影机制（同表别名须声明真身）
standards/task-work-order.md	🟠 中	—	AI 派工单模板（强制填输入/输出/约束/禁止事项/测试要求）—— 模板非铁律，不挂禁止项
standards/alembic-migration管理规范.md	🟠 中	✅ 铁律 6	表结构变更元规则（单一 head、downgrade 必须可实现、空库可重放）
standards/仓库入库规范.md	🔴 强	✅ 铁律 14（#215 挂）	文件入库分类纪律（C1~C8）：密钥/PII/任务现场禁入 git、协作配置必入；gitleaks + CI 兜底
standards/文档性质标记规范.md	🟠 中	✅ 文末「文档性质纪律」段	本索引的依据：文档必须标性质；三类的规则差异

✅ 强制链已闭环（#215，2026-10-07）：除模板类 task-work-order.md（非铁律，是派工模板）外， 全部强制类 META 均已挂进 AGENTS.md —— error-code=铁律 8、去重=铁律 9、渠道口径=铁律 10、 缓存=铁律 11、命名分组=铁律 13、仓库入库=铁律 14（本次新挂）、Alembic=铁律 6、 文档性质=文末「文档性质纪律」段。「标记 ≠ 约束」的缺口已消除。

6.2 需求（REQ）—— 具体功能/集成

文档	说明
standards/workbuddy数据同步接入规范.md	投诉推送接口契约（/sync/complaints/push）—— 约束单个集成，非元需求
standards/workbuddy手动退款数据同步接入规范.md	手动退款推送契约（/sync/manual-refunds/push + 复合键幂等）
standards/外部只读数据接入规范.md	对外开放只读 API 契约（/api/v1/external scope / 限频 / 字段 / 单位）
规划设计.md	系统总体设计与需求规划（v0.4）
规划设计-v0.5.md	迭代需求方案（7 项需求 + 5 级角色 + 交互规范 + ADR）
规划设计-v0.7.md	#199 双审查后整体重规划（2026-10-07）：R/S 共 68 项行动项映射 6 批次（B0~B5）双线并行；6 个架构专题概要（客户域四层主数据/统计口径现代化/调度韧性/AI 夜间预警/前端可演化性/质量合规）；冲突时以本版为准
reports/20261009-下一步开发计划-排期规划.md	下一步开发计划 v2（2026-10-09）：剩余 45 项排 5 批次（B1 风险/B1.5 事件时间轴/B2 AI 策略/B3 功能深化/B4 架构）+ 13 择机项；新增经营事件标注、AI 报告策略调整、退款按销售天数、分品类看板、人员重设计；关键路径 today.py→事件时间轴→客户域→夜间预警→架构演进
arch/A-*.md（50 份 LOCKED，实盘 2026-10-07；另有 arch/_pending/ 4 份 PENDING 待审草案）	已锁定架构设计，逐份对应一个需求/改造
arch/A-20260913-001-AI接待口径分层.md	#78 AI 接待来源四分类（真人/AI全自动/系统/客户自助）+ KPI 堆叠配色 + AI 单列；含「不做 AI 转人工细分」的取舍声明
arch/A-20260917-001-ai报告草稿摘取与三级命中.md	#135 AI 报告命中链路三级化（L1 关键词→L2 27b 语义匹配→L3 clarify 兜底）+ 摘取层（split_sections 按 H2 切分 + extract_section 27b 按问句摘取+排版）；含「不用 122b 摘取、不做问句归一化」取舍声明
arch/A-20260919-001-ai回答模式分级框架.md	#152 AI 回答模式分级框架（简报/明细/深度 + 完整性校验 + 同窗口快照补算 + 用户明确要求的深度分析兜底）；维度清单走模板配置（detail_level/required_dimensions JSONB），框架不绑定具体业务分块
arch/A-20260919-002-ai提示词反馈闭环.md	#153 AI 提示词反馈闭环（收集→评审→人工迭代）：standard 校验缺失落库 latest_missing + 周期「提示词健康报告」落 system_events（命中率/live占比/缺失维度TopN/高频问题）+ 模板/提示词/feed 三层建议；含「只出建议不自动改提示词」取舍声明
design/AI数据接入助手设计-20260919.md	已实施（#155/#156/#157/#158） AI 数据接入助手（P1）：样例→AI 起草接入声明（字段语义/命名/分组/去重建议）→纯规则校验器（16 条断言拦截）→人工确认→生成落地包走现有流程；AI 只出配置不出代码，含 data_source_specs 表/接口/提示词/验收标准
design/采集语义增强设计-20260920.md	评审中 采集语义增强（第二期，框架 §七）：三场景（CSV 换行截断 / 明显错误日期 / 语义补全）= 导入期留痕（复用 #40 拒收行，不建新表）+ 事后扫描（D4/D5/D6 探测器）+ 分级执行（改值恒 L2 fix_time）；含「判据同源」取舍与 E1/E2/E3 拆分
design/20260924-#193-AI报告刷新策略-无新事件跳过-实现方案.md	待评审（#193） AI 报告刷新策略："无新事件则跳过"（水位判定 + 五类保底 + off/dry_run/enforce 三档 + 跳过留痕 + 管理端 4 列可观测）；含"v1 用全局开关不加列"与"不做刷新成本看板/不做逐模板频率编辑器"的取舍声明
design/AI数据治理框架-20260919.md	已实施（#162/#163/#164/#165/#167） AI 数据治理框架（探测→研判→分级执行）：确定性探测器算证据（唯一索引重复/行数突变/外键孤儿）→ AI 研判真问题 vs 业务允许 → L0只读/L1可逆自动、L2不可逆必须人工确认（红线）；AI 结论沉淀为 governance_rules 规则（下次短路不调 LLM）；含采集语义增强（CSV 换行截断/错误日期/语义补全）第二期规划
arch/A-20261008-003-统一变更审计与日志保留期.md	#261 统一变更审计（zammad histories 范式：audit_changes 实体+动作+字段级 before/after，persons 更新示范接入）+ 保留期夜批（operation_logs 180d / audit_changes 730d，db_guard 显式放行）+ 分区方案设计先行（原生按月 RANGE，触发条件与迁移步骤已定，本单不执行）；含「不归并 13 张存量日志表、不做审计查询页」取舍声明

📌 易混点：名为"XX接入规范"的文档是 REQ 而非 META —— 它只约束某一个具体集成，不是"所有需求怎么做"。 判据是约束范围，不是文件名里有没有"规范"二字。

6.3 参考（REF）—— 现状记录，无约束

文档	说明
standards/数据库表结构说明.md	86 张表清单与时间字段现状（以代码为准）
standards/数据同步与加工说明.md	采集链路实现细节（BMS / ai-acc / OCR / 时区加工）
standards/投诉数据接入说明.md	三种接入方式操作步骤（手册性质）
standards/人均效率算法说明.md	人均效率指标算法现状（工作量分 / 6 专项难度系数 / SCD 回退）
standards/多份存储台账.md	同事实多处存储台账（#278 O-7）：宽表投影/新旧双存/跨路回填逐处登记真身/投影、同步机制、收敛计划；新增多份存储须登记于此
standards/跨项目经验迁移指南.md	方法论沉淀（自述"非本项目强制约束"）
ops/数据采集-运维手册.md	BMS/ai-acc/SCRM/共享文档 采集巡检与故障处置手册（含 §七 Xvfb 排查，以代码为准）
API接口文档.md	全量接口清单（OpenAPI 实盘 2026-10-07：449 个路径 / 547 个 method 操作，其中 448 个 /api/v1 业务路径；以代码为准，复算命令见该文档头部）
审查行动项登记.md	历次审查行动项台账（跟踪登记）
reports/20260920-数据治理框架实施经验.md	治理框架 A→E1 实施经验复盘（判据证据驱动/同源、AI 提示词+代码双守、采集热路径纪律、生产实测与迁移做法、留尾纪律）
reports/20261007-全项目设计评审-审查报告.md	全仓库全维度设计评审（6 路并行深审 + 开源对照）：7 项 P0 发现；行动项已登记台账「来源 R」（R-P0 5 / R-P1 19 / R-P2 19，工单待建）
reports/20261007-开源源码深研与架构规划调整-分析报告.md	参考项深研（Gitea 17 仓库 8 路 + 本项目 4 路深审）：许可证红线、机制级可移植清单、业务事实校准（用户补充 8 条）；无整体引入项；行动项已登记台账「来源 S」（S-P0 4 / S-P1 15 / S-P2 6，工单待建）
reports/20261009-阶段性升级总结-总结报告.md	阶段性升级总结（2026-09-01 ～ 10-09，570 提交/195 工单）：功能/性能/合理性三维度盘点；fix(205)>feat(193)，治理优先于堆功能
reports/20261009-数据表合理性专项审计台账.md	逐表审计（#274 O-1）：133 模型表+2 残留表逐行判定；收敛项已立 #285(bak表)/#286(未用索引)/#287(cs_records全扫)/#288(空表域拍板)
reports/20261009-采集统一入口中台化评估报告.md	采集中台评估（#275 O-2）：结论=部分收口；BMS 已实质中台化维持不动，SCRM 收口并入 #283 拍板，Provider 工厂不形式化，去双写归 #223

📌 REF 的"过期"不是"违反规则"，而是"与代码不一致" → 直接重写即可，无需走变更流程。

6.4 待修复项（本次盘点发现）

#	问题	处置
1	standards/ 目录名误导（混着 REF 与 REQ）	已在 §一 加警示；长期可考虑按性质分目录
2	存量文档多数未标 **性质** 字段	不追溯；谁改动、谁补齐（同 界面设计说明规范 策略）
3	人均效率算法说明.md 含业务口径（难度系数）但自述为"说明"	存疑：若系数变更需全仓评估，应升级为 META

✅ 原第 1 项「4 份 META 无强制入口」已于 #215（2026-10-07） 全部挂入 AGENTS.md，见 §6.1。

6.5 新增文档时的登记义务

新增任何约束性文档时，必须：

1. 在文档头部标 **性质**：元需求（META） / 需求（REQ） / 参考（REF）
2. 在本 §六 对应表格中登记一行
3. 若为 META 且含强制条款 → 同步挂进 AGENTS.md 引用链

未登记的文档视为"未生效" —— review-checklist 可据此判 WARNING。