docs(orders): T11.2 展示脱敏文档 + 字段分类表更新

- data/orders/README.md 新增 T11.2 段:展示脱敏三态策略示例代码
- 文件结构表新增 masking.py / test_masking.py
- 字段分类表:强/弱敏感 PII 增加'展示遮罩'列
- DoD 勾选'展示脱敏'项
- 版本号 v1.0 → v1.1

代码改动见下个 feat commit(分离便于回滚/review)。
This commit is contained in:
Hermes Agent
2026-06-12 16:26:32 +08:00
parent 00e596ab10
commit bdd361e50f

View File

@@ -9,25 +9,30 @@ data/orders/
├── __init__.py
├── README.md
├── crypto.py # Fernet 加密/解密/哈希派生
├── masking.py # 展示脱敏工具 (T11.2)
├── state_machine.py # 6 态转换验证
├── models.py # Order dataclass + 序列化
├── models.py # Order dataclass + 序列化(to_dict 支持 mask 策略)
├── schema.py # DDL + apply_schema()
└── tests/
├── __init__.py
├── test_crypto.py
├── test_masking.py
├── test_state_machine.py
└── test_schema.py
```
## 字段分类
| 类别 | 处理方式 | 字段 |
| ---------- | ------------ | ------------------------------------- |
| 强敏感 PII | AES-256 加密 | `customer_phone`, `candidate_id_card` |
| 弱敏感 PII | 脱敏存储 | `customer_name`, `candidate_name` |
| 索引用哈希 | SHA-256 hex | `customer_phone_hash` |
| 业务字段 | 明文 | `amount_cents`, `source`, `status` |
| 元数据 | 明文 | `created_at`, `tags` |
| 类别 | 处理方式 | 字段 |
| ---------- | ----------------------- | ------------------------------------- |
| 强敏感 PII | AES-256 加密 + 展示遮罩 | `customer_phone`, `candidate_id_card` |
| 弱敏感 PII | 脱敏存储 + 展示遮罩 | `customer_name`, `candidate_name` |
| 索引用哈希 | SHA-256 hex | `customer_phone_hash` |
| 业务字段 | 明文 | `amount_cents`, `source`, `status` |
| 元数据 | 明文 | `created_at`, `tags` |
> T11.2 起,`Order.to_dict()` 默认走"展示遮罩"(如 `138****1234`
> API 响应 / 前端列表无需再做额外处理。
## 6 态状态机
@@ -93,6 +98,42 @@ assert_valid_transition(order.status, "paid")
- [x] 外键约束启用
- [x] SHA-256 hash 字段支持手机号去重
- [x] CHECK 约束拒绝非法 status
- [x] 展示脱敏T11.2Order.to_dict 默认走 mask 策略(手机/身份证/姓名)
## 展示脱敏 (T11.2)
为防止 API 响应 / 前端 / 日志 / 截图泄露完整 PII订单数据模型支持"展示遮罩"
```python
from data.orders.models import Order
order = Order(
id="GKO-20260612-AAAA",
source="web",
service_version="basic",
customer_name="张三",
customer_phone="13800001234",
candidate_id_card="430102200501011234",
)
# 默认:mask 模式 — 适合 API 响应 / 前端
order.to_dict()
# {
# "customer_phone": "138****1234",
# "candidate_id_card": "430102********1234",
# "customer_name": "张*",
# ...
# }
# 显式明文(后台人工核对场景)
order.to_dict(decrypt_sensitive=True)
# 完全移除(对外公开统计/审计日志)
order.to_dict(decrypt_sensitive=False)
```
`masking` 模块是纯字符串工具,与 `crypto` 正交可在任意层API 序列化、Jinja2
模板过滤器、日志格式化、CSV 导出器)独立复用。
## 下游衔接
@@ -102,4 +143,5 @@ assert_valid_transition(order.status, "paid")
## 版本
v1.1 — 2026-06-12 — T11.2 展示脱敏(mask 策略 + masking.py)
v1.0 — 2026-06-12 — T4.1 实施