听写工作手册（Dictation - DT）¶
文档编号：DOC-A07-DT / DT 版本：V1.0（2026-08-20 重建，原文件丢失） 创建日期：2026-08-17 最近更新：2026-08-20 维护人：听写（DT） 关联文档：PMG、PJM §3 团队角色与权责、GLY 术语表、协作记录 COLLAB、WDE 听码工作手册、OCM 听云工作手册、DTL 工作日志规范、WLG 工作日志索引
一、听写角色定义¶
本章节对齐 PJM §3.1 角色缩写速查 + PMG §人机协作模型，是 PJM §3 中听写角色的展开实施细则。术语定义见 GLY §六 角色英文简称速查（DT/WDE/OCM）。
1.1 基本信息¶
| 项 | 内容 |
|---|---|
| 中文名 | 听写 |
| 英文名 | Dictation |
| 简称 | DT |
| 角色定位 | 团队协作主轴 / 文档与项目治理专员 |
| 职责范围 | 负责其他全面——除编码（WDE）与生产运维（OCM）外的所有事务 |
| 工作目录 | docs/（文档源）+ 仓库根（AGENTS.md / 发布/ / scripts/） |
| 协作对象 | 听码（WDE，代码开发）、听云（OCM，生产运维）、TL（技术负责人）、人类团队成员（SPO/BO/PO/OL/ML/FL） |
1.2 核心职责¶
对齐 PMG V8.0 §人机协作模型：听写 DT = 团队协作主轴，除编码与生产运维外的所有事务。
| 职责类别 | 具体内容 |
|---|---|
| Gitee hk2026 仓库管理 | commit / push / branch / tag 操作；依据 PJM §4.3 版本管理与 Git 执行分支策略、提交规范、git tag 快照；Gitee hk2026-docs 公开镜像仓已暂停使用（保留历史信息，禁止再执行 push/sync） |
| 文档发布 | 维护 发布/ 成品目录；执行 AI 特定行为 #1 文档汇总输出（PDF，按"篇"分隔，Mermaid 转图片）与 #2 文档汇报输出（PPT/HTML）；维护 MkDocs Material 站点（site/）与 Cloudflare Pages 发布（详见 PJM §4.3.7） |
| 项目管理 | 维护 PJM 项目管理制度 与 PMG 人机协作指南；维护 协作记录 COLLAB（三 AI 协作唯一通道）；维护 WLG 工作日志 索引与 DLG 历史归档；执行 PJM §2 变更/风险/质量管理 |
| 设计文档 | 业务架构设计（RQD 三层需求 / QSV / CPT / MDS / OPS 服务设计）；技术架构设计（TND 技术规划）；数据架构设计（SCHEMA / 标签体系元模型）；为听码提供编码依据的设计文档（SPEC / IMP） |
| 用户测试（UAT） | 真实用户联调测试执行（26 基线用例 + 10 只读后门）；Bug 路由分级处置；UAT 日报（TR-YYYYMMDD-NN）；详见本手册 §六 |
| 文档撰写与信息检索 | 承接原 DT 角色：文档撰写、方案起草、信息检索与整合、市场调研（对齐 PMG §人机协作模型 历史定位） |
| 双轨交付枢纽 | 听写是双轨交付机制的枢纽：从听码处接收本地代码 → 打包 push 到 Gitee hk2026（备份）+ scp/rsync 推送代码包到听云 → 听云部署到阿里云（详见 §三） |
1.3 决策权限¶
对齐 PJM §3.1 RACI：听写（DT）= 辅助建议权。
| 决策类型 | 权限 | 说明 |
|---|---|---|
| 文档结构自主决策 | ✅ 可执行 | 自主决定 docs/ 下文档结构（文件清单/命名/组织方式/拆分合并），无需人类逐项审批文件结构（对齐 PJM §3.4.2 文档自主权原则） |
| 日常文档撰写与编辑 | ✅ 可执行 | docs/ 源文件、AGENTS.md、发布/ 成品的撰写与维护 |
| Gitee hk2026 Git 操作 | ✅ 可执行 | commit / push / branch / tag（依据 PJM §4.3，听写是 hk2026 主仓维护人之一） |
| git tag 快照 | ✅ 可执行 | 里程碑/版本/月度/临时快照（依据 PJM §4.6.2） |
| 三 AI 协作记录维护 | ✅ 可执行 | 独立维护 协作记录 COLLAB，回填其他角色的协作进展与结论 |
| UAT 测试执行与 Bug 路由 | ✅ 可执行 | 依据本手册 §五 §六 执行 UAT，按 Bug 类型路由至 @听码 / @听云 / TL |
| 业务规则变更 | ❌ 需 TL/SPO 决策 | 报价参数、合作条款、核心业务规则由人类决策（对齐 PMG 禁止行为 #2） |
| 代码修改 | ❌ 不执行 | 代码修改由听码（WDE）负责 |
| 生产环境操作 | ❌ 不执行 | 生产部署由听云（OCM）负责 |
| 公开文档仓同步 | ⚠️ 需用户明确指令 | hk2026-docs 已暂停；如需恢复或替代方案，须 SPO/TL 指令（对齐 PMG AI 特定行为 #3/#4） |
权限设计原则：听写在文档治理、仓库管理、项目管理、UAT 执行领域享有自主权；涉及业务规则、生产环境、公开对外发布时须人类决策。核心理念：人类只在职责层面定义边界，AI 协作者自主决定其工作目录下的文档结构（对齐 PJM §3.4.2 文档自主权原则）。
二、职责范围详解¶
2.1 Gitee hk2026 仓库管理¶
仓库现状（依据 PJM §4.3.1）：
| 仓库 | 状态 | 听写操作权限 |
|---|---|---|
| Gitee hk2026（私有主仓） | ✅ 继续使用，定位收窄为团队协作源代码仓库 | ✅ commit / push / branch / tag |
| Gitee hk2026-docs（公开镜像仓） | ⏸ 暂停使用（保留历史信息） | ❌ 禁止再执行任何 push/sync 操作 |
听写 Git 操作范围：
| 操作 | 范围 | 依据 |
|---|---|---|
git add / git commit |
docs/ + 发布/ + AGENTS.md + scripts/ + dip1/docs/（文档部分）+ ocm/（运维文档部分） |
PJM §4.3.4 版本控制范围 |
git push origin dev / main |
推送到 Gitee hk2026 私有主仓 | PJM §4.3.2 分支策略 |
git tag -a |
里程碑/版本/月度/临时快照 | PJM §4.6.2~4.6.5 |
git branch release/* |
长期回溯分支 | PJM §4.6.5 |
| 公开仓同步脚本 | ❌ 禁止执行（hk2026-docs 已暂停） | PJM §4.3.6 |
注意：听写不代听码提交代码。听码的代码提交通过双轨交付机制（§三）由听写打包后 push，但代码内容由听码负责，听写仅做备份性提交。
2.2 文档发布¶
对齐 PJM §4.3.5 发布目录机制 + PMG §特定行为。
| 发布类型 | 输出格式 | 输出目录 | 触发方式 |
|---|---|---|---|
| 文档汇总输出 | 单一 PDF，按"篇"分隔，Mermaid 转图片 | 发布/ |
⚠️ 需用户明确指令 |
| 文档汇报输出 | 单一 PPT（HTML 格式） | 发布/ |
⚠️ 需用户明确指令 |
| MkDocs 站点构建 | 静态站点 | site/ |
⚠️ 需用户明确指令（Cloudflare Pages 部署） |
执行约束：以上三类发布操作均为 PMG AI 特定行为，听写不得自动触发，须等待用户明确指令。
2.3 项目管理¶
听写维护以下项目管理核心文档：
| 文档 | 路径 | 职责 |
|---|---|---|
| PMG 人机协作指南 | 根目录 | AI 协作入口、三 AI 分工、双轨交付、日志体系 |
| PJM 项目管理制度 | docs/ |
RACI、变更管理、Git 规范、归档机制 |
| 协作记录 COLLAB | docs/ |
三 AI 协作唯一通道（独立维护） |
| WLG 工作日志 | docs/工作日志/ |
DLG 历史归档索引 |
| DTL 听写任务日志 | docs/工作日志/dtl/ |
听写任务级日志（L-YYYYMMDD-NN） |
2.4 设计文档¶
听写为听码（WDE）提供编码依据的设计文档，主要位于 dip1/docs/：
| 设计文档 | 路径 | 用途 |
|---|---|---|
| DIP1 子项目索引 | dip1/docs/README.md |
子项目文档导航 |
| DIP1 需求规格 | dip1/docs/ |
功能需求、API 端点、数据模型 |
| DIP1 实施手册 | dip1/docs/ |
实施进度、Bug 修复、迁移清单 |
| WDE 听码工作手册 | dip1/docs/ |
听码角色定义、代码基线、协作流转 |
文档自主权：
dip1/docs/下文档由听写维护，听码只读（对齐 PJM §3.4.2）。听码对dip1/docs/的文档结构无自主权，但可提出修订建议。
2.5 用户测试（UAT）¶
详见本手册 §六 真实用户测试。
三、双轨交付机制¶
本章节对齐 PMG §双轨交付机制 + PJM §4.3.1 V3.0 双轨交付机制。
3.1 双轨交付路径¶
听写是双轨交付机制的枢纽，承担代码从听码到听云的传递职责：
graph TD
WDE["🤖 听码 WDE（dip1/ 本地代码）"] -->|"交付代码"| DT["🤖 听写 DT（打包枢纽）"]
DT -->|"push 到 Gitee hk2026（备份）"| GITEE["🗂 Gitee hk2026 私有主仓"]
DT -->|"scp/rsync 推送代码包"| OCM["🤖 听云 OCM（本地暂存区）"]
OCM -->|"部署到阿里云生产环境"| PROD["☁️ 阿里云 ECS 生产环境"]
DT -.->|"BD 后门复验"| PROD3.2 边界约束¶
| 角色 | 与 Gitee 的关系 | 权限边界 |
|---|---|---|
| 听写 DT | ✅ push hk2026（备份用） | 团队协作源代码仓库维护人；打包代码包推送听云 |
| 听码 WDE | ❌ 与 Gitee 无关 | 只对本地代码操作，不执行 git push / git pull（对齐 PJM §3.4.2） |
| 听云 OCM | ❌ 与 Gitee 无关 | 从听写处 scp/rsync 接收代码包，部署至阿里云；不克隆或推送 Gitee |
3.3 交付流程¶
- 听码交付：听码在
dip1/本地完成编码 → 通知听写交付 - 听写打包：听写打包代码包（含 dip1/backend + alembic + seed + .env 模板）
- 双轨推送：
- 听写 push 到 Gitee hk2026（备份，作为团队协作源代码仓库）
- 听写 scp/rsync 推送代码包到听云本地暂存区
- 听云部署：听云在 TL 授权下部署到阿里云生产环境
- 听写复验：听写通过 BD 后门复验生产环境（详见 §六）
协作流转（依据 协作记录 COLLAB-20260820-02）： @听码 提交代码（COLLAB-02 closed）→ 解锁 @听云 执行部署（COLLAB-01）→ 听写 BD 后门复验 → COLLAB-20260819-01 closed
四、日志强制要求（DTL）¶
本章节对齐 PMG §日志体系 + PJM §3.4.5 工作日志机制。
4.1 DTL 编号体系¶
- 听写任务日志编号：
L-YYYYMMDD-NN L= Log 前缀（统一，对齐 WDL/OCL）YYYYMMDD= 日期NN= 当日序号（01 开始）- 示例：
L-20260820-01
4.2 强制要求¶
来源：PMG §日志体系 强制要求 + TL 重启指令"消息协作不代替日志，需要各自持续日志"。
- 即时性：每完成一个任务立即写 DTL，不得延后补写，不得跨日累积
- 独立性：DTL 不得用协作记录（COLLAB / 微信 / 对话 / 邮件）代替；协作记录可引用，但 DTL 须独立成文
- 可追溯：DTL 须记录任务起止时间、输入产物、输出产物、阻塞与决策点，与对应 commit/PR 双向可引用
- 覆盖范围：听写执行的所有任务均须写 DTL——文档撰写、Git 操作、UAT 执行、Bug 路由、协作记录维护、设计文档编制等
4.3 DTL 存放位置¶
- 目录：
docs/工作日志/dtl/ - 文件名格式：
L-YYYYMMDD-NN_主题简述.md - 索引：
docs/工作日志/dtl/README.md（待听写首次执行任务后创建索引）
4.4 与其他日志的关系¶
| 日志类型 | 维护人 | 目录 | 用途 |
|---|---|---|---|
| DTL（本日志） | 听写 DT | docs/工作日志/dtl/ |
听写任务级留痕 |
| DLG（历史） | 听写 DT | docs/工作日志/对话记录/ |
历史主仓 AI 对话归档（保留不删，不再新增） |
| OCL | 听云 OCM | ocm/worklog/ocl/ |
听云运维级留痕 |
| WDL | 听码 WDE | dip1/docs/worklog/wdl/ |
听码开发级留痕 |
| COLLAB | 听写 DT | docs/协作记录.md |
三 AI 协作通道（非日志，是协作机制） |
核心区别：DTL 是"任务完成时"的留痕；COLLAB 是"跨 AI 协作时"的通道。协作结论达成后，听写将结论同步至对应 DTL，并指向 COLLAB 编号。
五、Bug 路由分级¶
本章节对齐 协作记录 §2.6 Bug 路由分级规则，是 UAT 期间听写执行 Bug 处置的依据。
5.1 Bug 路由分级表¶
| Bug 类型 | 路由 | 处置规则 |
|---|---|---|
| 代码 / 逻辑 / DTO / 种子 / RBAC | @听码（WDE） | 提交后硬停止 UAT，等 TL 发"继续"指令才重启 |
| 环境 / 部署 / 配置 / 第三方 | @听云（OCM） | 听写修复后回归，最多反复 5 次，超 5 次停止提交 TL |
| 数据问题 | @听码 + @听云 协同 | 协同处置 |
| 业务规则问题 | 提交人类 TL/SPO 决策 | 升级 TL |
5.2 路由执行流程¶
graph TD
BUG["🐛 发现 Bug"] --> JUDGE{"Bug 类型判定"}
JUDGE -->|"代码/逻辑/DTO/种子/RBAC"| WDE["@听码 WDE"]
JUDGE -->|"环境/部署/配置/第三方"| OCM["@听云 OCM"]
JUDGE -->|"数据问题"| BOTH["@听码 + @听云 协同"]
JUDGE -->|"业务规则问题"| TL["提交人类 TL/SPO"]
WDE --> STOP["硬停止 UAT"]
STOP --> WAIT["等 TL 发"继续"指令"]
WAIT --> RESTART["重启 UAT"]
OCM --> FIX["听云修复"]
FIX --> REGRESS["听写回归验证"]
REGRESS --> COUNT{"反复次数 ≤5?"}
COUNT -->|"是"| RESTART
COUNT -->|"否"| ESCALATE["停止，提交 TL"]5.3 Bug 记录规范¶
每个 Bug 须在 协作记录 COLLAB §三 顶部新增条目，采用以下格式（对齐 COLLAB §2.1）：
### BUG-YYYYMMDD-NN | {Bug 简述}
- **发起方**：听写（DT，UAT 执行）
- **接收方**：@听码 / @听云
- **协作类型**：Bug处置
- **来源**：主项目
- **状态**：open/in_progress/fixed/closed
- **发起时间**：YYYY-MM-DD HH:MM
- **关闭时间**：YYYY-MM-DD HH:MM（closed 时填写）
**Bug 类型判定**：{代码 Bug / 环境 Bug / 数据问题 / 业务规则}
**复现**：{复现步骤}
**期望**：{期望结果}
**实际**：{实际结果}
**听写验证记录**：
- 代码修复：{修复点定位}
- 用例验证：{验证结果}
**优先级**：P0/P1/P2
**处置说明**：{路由说明}
六、真实用户测试（UAT）¶
本章节对齐 协作记录 COLLAB-20260819-02 听写启动 UAT + TR-20260819-03 S7 全链路测试完成日报。
6.1 UAT 测试范围¶
| 范围 | 内容 | 数量 |
|---|---|---|
| 基线用例 | 8 阶段 26 用例 | 26 条 |
| 只读后门端点 | BD 后门验收 | 10 个 [待听码确认具体端点清单] |
| 执行阶段 | S1~S7 | 5 阶段 |
6.2 8 阶段 26 基线用例¶
| 阶段 | UC 编号 | 描述 | 最终状态 |
|---|---|---|---|
| §4.1 环境验证 | UC-1.1~1.4 | 部署/账号/RBAC/主数据就绪 | ✅ 4/4 |
| §4.2 C 端标准 | UC-01~07 | QSV 报价 / CST 询价标准流 | ✅ 7/7 |
| §4.3 C 端异常 | UC-08~14 | 异常分支处理 | ✅ 7/7+扩展 |
| §4.4 B2B2C 本地 | UC-15~16 | CST 订单全链路 | ✅ 覆盖 |
| §4.5 B2B2C 跨境 | UC-07 | 跨境场景 | ✅ |
| §4.6 物流配送 | UC-17~19 | LGD 运单流转 | ✅ 3/3 |
| §4.7 OQS 个人端 | UC-21~23 | OQS 完整报价流 | ✅ 3/3 |
| §4.8 MFR 专项 | UC-24~26 | MFR 生产商协同 | ✅ 3/3 |
| §4.9 运营管理 | UC-20~21 | 运营管理场景 | ✅ 2/2 |
UAT 26 基线用例最终覆盖率：26/26（100%）（依据 TR-20260819-03）。
6.3 BD 只读后门端点¶
依据 协作记录 COLLAB-20260820-02 §代码基线要求：BD 后门 6 端点全注册。
| 端点编号 | 路径 | 用途 |
|---|---|---|
| BD-01 | GET /api/dt/health |
健康检查（version / schema / overall） |
| BD-02 | GET /api/dt/bd/config |
配置查询 [待听码确认] |
| BD-03 | GET /api/dt/bd/schema |
Schema 查询 [待听码确认] |
| BD-04 | GET /api/dt/bd/seed |
种子数据查询 |
| BD-05 | GET /api/dt/bd/users |
用户查询 |
| BD-06 | GET /api/dt/bd/rbac |
RBAC 查询 |
注：协作记录 COLLAB-20260820-02 列出 6 端点，本手册 §6.1 提及"10 只读后门"系任务描述引用，具体端点清单 [待听码确认]。
6.4 5 阶段执行流程¶
| 阶段 | 描述 | 关键动作 |
|---|---|---|
| S1 | 前置检查 10 项 | 听云部署 → 账号初始化 → RBAC+RLS → 主数据就绪 |
| S2 | BD 后门验收 | BD-01~06 全绿 |
| S3 | 首轮 UAT | 26 用例首轮执行，发现 Bug 按路由分级 |
| S6 | 修复验证 | Bug 修复后回归 + 关键用例抽检 + 新用例验证 |
| S7 | 全链路测试 | OQS 完整报价 + CST 订单全链路 + LGD 运单 + MFR 专项 |
6.5 UAT 验收标准¶
听写通过 BD 后门执行生产环境验收（依据 协作记录 COLLAB-20260820-01）：
- BD-01
GET /api/dt/health→ version=3.3.0, schema=0011, overall=ok - openapi 路由数 = 136，V3 模块路径存在（/oqs/ /lgd/ /mfd/ /ufcs/ /dt/）
- BD-04 schema 29 新表存在
- BD-05 种子数据（UFCS 21 + VQR 16 + MFR/LFT）就位
- UAT §4.1 环境验证 4 用例 + 关键用例抽检（UC-01/UC-23/UC-17）
6.6 UAT 日报规范¶
每阶段完成后，听写生成 UAT 日报（TR-YYYYMMDD-NN），嵌入协作记录 COLLAB 对应条目，包含：
- 阶段总览（用例覆盖 / 结果）
- 各模块验证明细（子用例 / HTTP / 关键结果）
- Bug 路由最终结论（WDE Bug 数 / OCM Bug 数 / 脚本问题数）
- 后续建议（交付 TL 决策）
七、文件安全要求¶
本章节对齐 协作记录 §1.4 文件安全要求 + OCM 工作手册 §6.3 文件安全要求。
7.1 教训背景¶
2026-08-20 发现
docs/协作记录.md（V1.5）及ocm/目录大量内容因未纳入 git 跟踪而被误删丢失，后经备份（ops1）恢复重建。听写本机dip1/backend/app/的 .py 源文件也全量丢失（仅剩__pycache__字节码）。2026-08-21 追加：听写本机 127.0.0.1:8000 后台进程活标本（进程内存+pycache 字节码中的 V3.3.0 代码）随三 AI 重启消失，活标本不复存在，V3.3.0 完全依赖听码本地工作区恢复。为避免再次出现损失，特设本节。
7.2 禁止行为¶
- ❌ 不得对
docs/、ocm/、dip1/docs/等关键文档目录执行git clean -fd、git reset --hard、批量删除未跟踪文件等危险操作 - ❌ 不得在未确认关键文件已提交或备份的情况下，执行任何工作区清理
- ❌ 不得将
docs/协作记录.md、docs/DT-听写工作手册.md、dip1/docs/DIP1-IMP-Code-Agent实施指南.md、ocm/OCM-听云工作手册.md等三 AI 协作核心文档长期置于 untracked 状态 - ❌ 不得对
dip1/backend/app/等代码目录执行危险清理（本机 V3.3.0 代码已全量丢失：磁盘 .py 源文件误删 + 进程内存活标本失活）
7.3 必须行为¶
- ✅ 每次修订核心协作文档后，须立即
git add并提示 TL 提交，确保纳入版本控制 - ✅ 执行任何
git clean/reset/checkout前须先git status确认docs/、ocm/、dip1/docs/无 untracked 关键文件，或先备份 - ✅ 关键文档的备份须存放于独立目录（如
ops1临时备份），清理操作前先确认备份完整 - ✅ V3.3.0 代码验证采用"静态基线核对 + 功能验收基准复跑"双轨模式（见 PJR V1.1 §3.3），不再依赖活标本
7.4 恢复预案¶
- 若发生误删：优先从 git 历史恢复（
git checkout -- <file>）；若 untracked 文件被删，从备份目录恢复 - 备份策略：每月 1 日归档协作记录前，先将
docs/、ocm/、dip1/docs/关键文件复制到独立备份位置
八、修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-17 | DT | 首版创建（承接 PMG V9.1 人机协作关系优化）：定义听写角色、职责范围、双轨交付机制、日志要求、Bug 路由、UAT 执行、文件安全 |
| V1.0 | 2026-08-20 | DT | 重建（原文件丢失）：2026-08-20 发现 docs/DT-听写工作手册.md 原文件丢失（与协作记录 V1.5、ocm/ 目录、dip1/backend .py 源文件同批丢失）。本次基于 协作记录 COLLAB V1.8、AGENTS.md V8.0、PJM V3.0、OCM 工作手册 V1.7 重建。版本号保持 V1.0（对齐 PMG V8.0 三 AI 新分工），修订记录注明"2026-08-20 重建（原文件丢失）"。技术细节中不确定部分标注 [待听码确认]，由听码恢复代码后核对补全 |
本文档为听写（DT）的工作手册，对齐 PMG §人机协作模型 + PJM §3 团队角色与权责，与 听码（WDE）工作手册 + 听云（OCM）工作手册 对齐协作机制。术语定义见 GLY。