119 lines
3.2 KiB
Markdown
119 lines
3.2 KiB
Markdown
|
# CLAUDE.md
|
|||
|
|
|
|||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|||
|
|
|
|||
|
|
## Project Overview
|
|||
|
|
|
|||
|
|
基于 Rockchip RKNN NPU 的文档隐私安全处理 REST API 服务。支持 RK3588 板端和 x86 双平台。
|
|||
|
|
|
|||
|
|
**功能**：两阶段工作流——先分析检测隐私信息，用户决定后再遮罩处理。
|
|||
|
|
|
|||
|
|
## 开发环境
|
|||
|
|
|
|||
|
|
### 初始化
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
bash setup_venv.sh
|
|||
|
|
source venv/bin/activate
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 常用命令
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
make test # 运行所有测试
|
|||
|
|
make test-one FILE=tests/test_api.py # 单文件测试
|
|||
|
|
make lint # 代码检查（ruff）
|
|||
|
|
make server # 启动服务（http://0.0.0.0:8000）
|
|||
|
|
make verify # 端到端验证（需先启动服务）
|
|||
|
|
make clean # 清理缓存和临时文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API 端点
|
|||
|
|
|
|||
|
|
| 端点 | 说明 |
|
|||
|
|
|------|------|
|
|||
|
|
| `POST /api/v1/analyze` | 检测文档中的隐私信息，返回 JSON 报告 |
|
|||
|
|
| `POST /api/v1/redact` | 遮罩指定类型的隐私信息，返回处理后文档 |
|
|||
|
|
| `GET /api/v1/health` | 服务健康检查 |
|
|||
|
|
| `GET /api/v1/types` | 支持的隐私类型列表 |
|
|||
|
|
|
|||
|
|
### analyze 请求
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://localhost:8000/api/v1/analyze \
|
|||
|
|
-F "file=@document.docx"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### redact 请求
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl -X POST http://localhost:8000/api/v1/redact \
|
|||
|
|
-F "file=@document.docx" \
|
|||
|
|
-F 'config={"redact_types":["id_card","phone","face"]}' \
|
|||
|
|
-o redacted.docx
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 项目架构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
两阶段流水线：
|
|||
|
|
analyze: parser_factory → doc_classifier → [regex_detector, ner_detector, face_detector] → DetectionReport
|
|||
|
|
redact: analyze → strategy_selector → [text_redactor | image_redactor] → 处理后文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 文字层策略（字节级安全）
|
|||
|
|
|
|||
|
|
- PDF（含文字层）/ Word / Excel → `TextRedactor`（删除/替换文字节点）
|
|||
|
|
- 图像 / 扫描 PDF → `ImageRedactor`（OpenCV 黑色矩形覆盖）
|
|||
|
|
- PDF 有文字层时禁止仅使用图像遮罩（防止文字层可提取）
|
|||
|
|
|
|||
|
|
### 可检测隐私类型
|
|||
|
|
|
|||
|
|
| 类型 | 检测方式 | 安全等级 |
|
|||
|
|
|------|---------|---------|
|
|||
|
|
| id_card | Regex | high |
|
|||
|
|
| phone | Regex | high |
|
|||
|
|
| bank_card | Regex | high |
|
|||
|
|
| face | mediapipe RKNN | high |
|
|||
|
|
| email | Regex | medium |
|
|||
|
|
| name | 规则词典 NER | medium |
|
|||
|
|
| address | 规则词典 NER | medium |
|
|||
|
|
| license_plate | Regex | medium |
|
|||
|
|
|
|||
|
|
## 支持的文档类型
|
|||
|
|
|
|||
|
|
| 格式 | 解析方式 |
|
|||
|
|
|------|---------|
|
|||
|
|
| PDF（文字层） | pdfminer.six |
|
|||
|
|
| PDF（扫描件） | paddle_ocr RKNN |
|
|||
|
|
| .docx | python-docx |
|
|||
|
|
| .xlsx | openpyxl |
|
|||
|
|
| JPG/PNG | paddle_ocr RKNN |
|
|||
|
|
|
|||
|
|
## 关键路径
|
|||
|
|
|
|||
|
|
| 内容 | 路径 |
|
|||
|
|
|------|------|
|
|||
|
|
| PII 规则配置 | `configs/pii_rules.yaml` |
|
|||
|
|
| 姓氏词典 | `configs/surnames.txt` |
|
|||
|
|
| paddle_ocr RKNN 模型 | `/data/rockchip/paddle_ocr/models/rknn/PP-OCRv4/` |
|
|||
|
|
| mediapipe 人脸模型 | `/data/rockchip/mediapipe/models/rknn/` |
|
|||
|
|
|
|||
|
|
## RK3588 板端部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 同步代码
|
|||
|
|
rsync -av /data/rockchip/info-privacy/ pi@192.168.0.127:/home/pi/Desktop/info-privacy/
|
|||
|
|
|
|||
|
|
# 板端启动
|
|||
|
|
ssh pi@192.168.0.127 "clashon && clashproxy on && \
|
|||
|
|
cd /home/pi/Desktop/info-privacy && \
|
|||
|
|
bash setup_venv.sh && \
|
|||
|
|
source venv/bin/activate && \
|
|||
|
|
uvicorn info_privacy.api.main:app --host 0.0.0.0 --port 8000"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 设计文档
|
|||
|
|
|
|||
|
|
`docs/plans/2026-02-27-info-privacy-design.md`
|