DIP1 工作日志 — 听写只读后门（F-DT-001~006）实施
DWLG 编号：DWLG-20260817-01
日期：2026-08-17
参与方：听码（WDE / DIP1 Code Agent）
关联文档：DIP1-SPEC V2.1 §3.10、DIP1-IMP V2.2 §一、WDE 工作手册、DT 听写工作手册 §4.4
关联 Issue：无（DIP1-IMP V2.2 新增实施任务，承接 PMG V9.1 听写真实用户测试职责）
一、任务背景
DIP1-SPEC V2.1（2026-08-17）新增 §3.10 听写只读后门功能（F-DT-001006，BD-01BD-06）：仅供听写（DT）在真实用户测试时识别 bug 类型（代码问题 vs 环境/配置问题），普通真实用户无权访问。DIP1-IMP V2.2 明确该功能由听码实施（§B 后端业务阶段 +1 人天）。本日志记录完整实施与验证。
二、实现内容
2.1 产出文件
| 类型 |
文件 |
说明 |
| 配置 |
backend/app/infrastructure/config.py |
新增 3 项：dt_backdoor_token（SecretStr，空=后门关闭）/ dt_backdoor_ip_whitelist（CIDR 逗号分隔，空=不限制）/ dt_backdoor_rate_limit_per_min（默认 60） |
| 脱敏 |
backend/app/infrastructure/masking.py |
新增公共模块：mask_phone（中间 4 位 *）/ mask_email / mask_token（***），对齐 SPEC §3.10.2 |
| 迁移 |
backend/alembic/versions/0005_dt_backdoor_audit.py |
新增 dt_backdoor_audit 表（BIGSERIAL 主键）+ 2 索引 + RLS 2 策略，down_revision=0004 |
| 模型 |
backend/app/infrastructure/db/models/dt.py |
DtBackdoorAudit（裸基类，无 updated_at，同 audit_logs 模式）；注册入 models/init |
| 中间件 |
backend/app/infrastructure/observability.py |
RequestLogMiddleware：全请求摘要写 Redis dt:calls:{METHOD}:{path}（LTRIM 10 + TTL 1h，ULID 归一化 :id）；5xx 写 dt:errors（LTRIM 200）；Redis 异常 fail-open |
| 接口 |
backend/app/interfaces/api/dt.py |
6 端点 + 认证依赖 get_dt_caller + 审计路由类 DtAuditedRoute |
| 装配 |
backend/app/main.py |
注册 RequestLogMiddleware + dt_router（prefix /api/dt，不带 /v1，对齐 SPEC） |
| 环境 |
.env.example |
新增 DT_BACKDOOR_TOKEN / DT_BACKDOOR_IP_WHITELIST / DT_BACKDOOR_RATE_LIMIT_PER_MIN 3 项 |
| 测试 |
backend/tests/interfaces/test_dt_api.py |
41 用例（详见 §三） |
| 文档 |
docs/DIP1-API-OpenAPI规格.yaml → V2.1 |
新增 tag 10 + 6 path + DtBackdoorAuth；顺带修复 V2.0 遗留 YAML 语法错误（ExponentPushToken[xxxxxx] 未加引号导致整文件不可导入，HEAD 版本即存在） |
| 文档 |
docs/DIP1-Schema数据库详细设计.md → V1.2 |
新增 §三补二 dt_backdoor_audit + RLS 5.8/5.9 + 迁移规则，表总数 22→23，RLS 7→9 |
| 文档 |
docs/DIP1-IMP-Code-Agent实施指南.md §7.1 |
新增 C-B9 行（🟢 100%） |
2.2 访问控制落地（SPEC §3.10.2 七维度）
| 维度 |
实现 |
| 认证 |
Authorization: Bearer dt_xxx，与 settings.dt_backdoor_token 做 hmac.compare_digest 常量时间比对；未配置则后门整体关闭 |
| 授权 |
无 Token → 401/1001；非 dt Token（含普通 JWT/TL Token）→ 403/1006 |
| 审计 |
DtAuditedRoute（APIRoute 子类）在 finally 中写审计行：token 哈希（SHA-256[:16]）/端点/脱敏参数/响应摘要/耗时/客户端 IP；独立会话提交，失败仅记日志不阻断 |
| 网络限制 |
IP 白名单支持单 IP 与 CIDR；违规 → 403/3061 |
| 数据脱敏 |
手机号中间 4 位 *、邮箱用户名 *、Token 一律 ***；审计参数按 key 敏感词 + 值形态双重识别打码 |
| 速率限制 |
Redis INCR dt:rl:{token_hash} + EXPIRE 60s；超限 → 429/3060；Redis 异常 fail-open |
| 只读保证 |
仅注册 GET 路由，POST/PUT/DELETE 由 FastAPI 自动 405（NFR-21 24 用例验证） |
2.3 关键设计决策（技术实现细节，听码 100% 决策权范围）
- RLS 风格：SPEC §3.10.4 示例用 PG 角色
dt_backdoor/admin；实现沿用本库统一的 current_setting('app.current_role', true) 上下文变量风格（对齐 0001 §5 / audit_logs 策略），不新建 PG 角色。已在 Schema 文档 V1.2 注明。
- 5xx 采集：代码库无全局异常处理器/错误存储，新增轻量
RequestLogMiddleware（Redis list，fail-open）支撑 F-DT-003 最近调用 + F-DT-005 错误摘要；路径 ULID 归一化防 Redis key 膨胀。
- 审计范围：认证失败（401/403/429）请求不落审计（依赖在路由 handler 之前执行，且防暴力破解刷爆审计表）；成功认证后的所有调用（含 4xx/5xx 业务错误）100% 落审计。
- 外部服务健康：dt/health 仅对 DB/Redis 做真实探测，R2/WhatsApp/Push 报配置就绪状态（configured/not_configured），保证 SPEC ≤500ms 要求、避免外呼副作用。
- sys_users 无 role 列：角色经 sys_user_roles 关联表
string_agg 聚合返回。
三、验证结果
| 验证项 |
结果 |
| 迁移 |
alembic upgrade head（0001→0005）成功；新表 + 2 索引 + 2 RLS 策略落库 |
新增测试 tests/interfaces/test_dt_api.py |
41 passed, 0 failed：NFR-21 24 用例（6 端点 × GET/POST/PUT/DELETE）+ 认证授权 5 + IP 白名单（单 IP/CIDR）+ 限流 3060 + 6 端点功能 + NFR-22 审计落行 + NFR-23 脱敏 9 例（含会话端点响应体无手机号明文） |
| 既有套件回归（domain + application + interfaces） |
全部通过，0 failed |
| ruff（新增/修改文件） |
All checks passed（存量 6 项告警为既有文件，未代改） |
| mypy（新增 3 文件） |
no issues found（存量 36 项为既有基线，未新增） |
| OpenAPI YAML |
PyYAML 解析通过（修复遗留语法错误后），6 个 dt operationId 注册正确 |
| 手动冒烟 |
401/1001、403/1006、405、404/4001、审计 token 哈希落行均实测符合预期 |
四、状态矩阵更新
DIP1-IMP §7.1 矩阵变更：
- 新增 C-B9（听写只读后门 1 人天）：🟢 100%（证据：backend/app/interfaces/api/dt.py + alembic 0005 + 41 用例测试）
五、遗留事项与协作请求
- @听云（CROSS）：生产/预发环境如需启用后门，请配置 3 项环境变量（
DT_BACKDOOR_TOKEN 由 TL 签发、DT_BACKDOOR_IP_WHITELIST 建议配置听写运行环境 IP 段、DT_BACKDOOR_RATE_LIMIT_PER_MIN 默认 60），并对生产库执行 alembic upgrade head（0005）。不配置 Token 则后门保持关闭（安全默认）。
- @听写（INFO）：后门用法：
Authorization: Bearer <TL签发的dt_Token> 调用 /api/dt/health|config|api-meta/{path}|schema/{table}|errors|session/{user_id}；端点语义见 OpenAPI V2.1 tag 10。
- 本地开发注意：当前 5432/6379 端口被 prod-site 容器占用，本次开发使用独立 dev 容器（PG:5433 / Redis:6380），测试需导出
DATABASE_URL/REDIS_URL 指向 5433/6380。
修订记录
| 版本 |
日期 |
修订人 |
修订内容 |
| V1.0 |
2026-08-17 |
听码（WDE） |
创建：听写只读后门 F-DT-001~006 完整实施记录（6 端点 + 审计表 + 中间件 + 41 用例 + 文档 V2.1/V1.2 同步） |