1060 lines
61 KiB
Markdown
1060 lines
61 KiB
Markdown
# Phase 1：凭据槽位数据层 — 研究
|
||
|
||
**调研日期**：2026-05-07
|
||
**领域**：Django 4.2 单例模型 + Django Admin（SimpleUI 主题）+ 中文 i18n + 字段脱敏
|
||
**整体置信度**：HIGH（绝大多数答案在本仓库现有代码内可直接核对）
|
||
|
||
## 摘要
|
||
|
||
本调研回答 6 个 plan 启动前必须先弄清的问题。最重要的发现：
|
||
|
||
1. **本仓库已存在一个生产可用的单例模型范本** —— `userapp.models.AffinitySetting`（约 247-314 行）。它就是 CONTEXT.md 锁定的 `pk=1 + get_or_create` 模式的现成实现，连 `save()` 钩子和 `get_solo()` 类方法都已落地。**Phase 1 应直接 1:1 复刻它**，不要重新发明。
|
||
2. **`common/` 不是 Django app**（没有 `apps.py`，未在 `INSTALLED_APPS` 注册），只能放工具函数，不能放 Django 模型。
|
||
3. **本仓库的 i18n 现状是"宣称双语，实际中文硬编码"** —— `LANGUAGES` 与 `LOCALE_PATHS` 在 `settings.py` 第 207-218 行被注释掉，全仓库只有 7 处 `verbose_name=_('...')`，却有 159 处 `verbose_name='...'`（中文字面量）。CONTEXT.md 提到的"`_()` 标记翻译"是约定俗成的"愿景"，实操按现有模型一致性写中文字面量即可，不要为本 phase 单独引入 `gettext_lazy`，会和 14 个其它模型不一致。
|
||
4. **`mask_token` / `mask_secret` 工具在仓库里完全不存在**，需新建；放 `common/utils.py`（新文件），后续 Phase 3 阿里云日志脱敏可复用。
|
||
5. **单例 Admin 没有现成范本** —— `AffinitySetting` 没有 admin 注册条目；`card/admin.py:262`（`CardUsageLogAdmin`）有 `has_add_permission` 返回 `False` 的写法可以参考；但本 phase 需要"已存在 1 条时禁新增 / 不存在时允许 1 次新增"的条件式权限，需自己写。
|
||
|
||
**主要建议**：把 `CredentialSlot` 放进 `aiapp/models.py`（凭据语义偏 AI 服务商接入，aiapp 现仅 51 行非常瘦），admin 注册在 `aiapp/admin.py`，脱敏工具放新建的 `common/utils.py`，所有 verbose_name 用中文字面量与既有 14 个模型保持一致。
|
||
|
||
---
|
||
|
||
## User Constraints (from CONTEXT.md)
|
||
|
||
### Locked Decisions（不要质疑、不要给替代方案）
|
||
|
||
- **单例语义**：`pk=1` 固定主键 + `get_or_create(pk=1)` 模式；`save()` 钩子强制 `self.pk = 1`。**不**用单字段唯一约束方案。
|
||
- **字段集合**（最小集，沿用 ParadiseUser / 其它现有模型命名习惯）：
|
||
- `app_id`：`CharField(max_length=128, blank=True, default='')`
|
||
- `access_token`：`CharField(max_length=512, blank=True, default='')`
|
||
- `updated_at`：`DateTimeField(auto_now=True)`
|
||
- **数据迁移**：`python manage.py makemigrations <app>` 自动生成，不手写；命名沿用 Django 默认 `0001_initial.py` / `000X_*.py`。
|
||
- **不引入新依赖**：不使用 `django-encrypted-model-fields` 等加密库；at-rest 加密推迟。
|
||
- **Access Token 仅 Admin 展示态脱敏**：list 列 / 查看态末 4 位掩码（如 `****abcd`）；编辑表单明文供运营录入。DB 始终明文。
|
||
- **Admin 隐藏"新增"按钮**：重写 `has_add_permission`，记录已存在时返回 `False`、不存在时返回 `True`。
|
||
- **Admin 禁止删除**：重写 `has_delete_permission` 永远返回 `False`。
|
||
- **i18n**：模型 `Meta.verbose_name` / `verbose_name_plural` 以及 admin 列表方法的 `short_description` 用 `_()` 标记翻译。⚠ 见下方"研究问题 5"补充说明：本仓库实际 i18n 落地情况与此条约束有冲突，已在 Open Questions 标注。
|
||
- **兼容性**：Django 4.2.13、Python 3.8；沿用 `StandardResponseMiddleware`（本 phase 不直接产生 REST 响应，无关）。
|
||
|
||
### Claude's Discretion（planner / executor 自行决定的细节）
|
||
|
||
- 模型放在 `aiapp/models.py` 还是 `aiapp/models/credential_slot.py` 子文件 —— 取决于 `aiapp/models.py` 现有大小。**已核实：`aiapp/models.py` 仅 51 行，2 个模型（Bot、ChatMessage），直接追加在尾部即可，不必拆子文件。**
|
||
- 是否把 `access_token_masked` 工具函数抽到 `common/utils.py` 复用（Phase 3 阿里云日志脱敏可能也用得上）—— **强烈推荐抽**，避免 Phase 3 再写一份。
|
||
- Admin 列表页的字段顺序、过滤器等 UX 细节。
|
||
- `verbose_name` 中文字面量（如"凭据槽位"还是"通用凭据"）—— 推荐"凭据槽位"，与 ROADMAP / REQUIREMENTS 全文措辞一致。
|
||
|
||
### Deferred Ideas（OUT OF SCOPE — 不要碰）
|
||
|
||
- at-rest 加密 `access_token` 字段（依赖 PostgreSQL 访问控制即可，未来开新 phase 评估）
|
||
- 谁在何时改了 `access_token` 的审计日志（Django Admin 自带 `LogEntry` 已经记录基本信息）
|
||
- 管理端 / 客户端 REST 接口（分别在 Phase 2 / Phase 3）
|
||
- 阿里云日志脱敏过滤器（Phase 3 处理）
|
||
- 任何前端工作（在 `qy-lty-admin/` 独立项目）
|
||
|
||
---
|
||
|
||
## Phase 需求
|
||
|
||
| ID | 描述 | 研究支撑 |
|
||
|----|------|----------|
|
||
| **CRED-01** | 单例 `CredentialSlot` Django 模型 + 迁移；DB 层强制最多一条记录（`pk=1`）；含 `app_id`、`access_token`、`updated_at` 字段 | 研究问题 #1（app 归属决策）+ #2（`AffinitySetting` 单例范本）+ #5（字段命名约定） |
|
||
| **CRED-02** | Django Admin 注册：列表/查看态对 `access_token` 脱敏；编辑态明文；隐藏"新增"按钮（强制单例语义）；禁止删除 | 研究问题 #3（Admin 注册模板）+ #4（脱敏工具实现） |
|
||
|
||
---
|
||
|
||
## Project Constraints (from CLAUDE.md)
|
||
|
||
| 约束 | 内容 | 对本 phase 的影响 |
|
||
|------|------|--------------------|
|
||
| 沟通语言 | 所有面向用户回复用中文 | 不影响代码；影响 plan / verify-work agent 的对话措辞 |
|
||
| 修改记录强制 | 每次代码 / 配置 / 迁移 / Docker / 文档结构性改动**必须**追加到 `qy_lty/docs/修改记录.md` 顶部 | **本 phase 至少需要 2 条修改记录条目**（详见研究问题 #6） |
|
||
| 跨项目互不混合 | `qy_lty/docs/修改记录.md` 仅记录服务端，`qy-lty-admin/docs/修改记录.md` 仅记录前端；跨项目联动各写一条相互引用 | 本 phase 是**纯服务端**改动，只在 `qy_lty/docs/修改记录.md` 写；不需要联动 qy-lty-admin（前端联动属于 Phase 2/3） |
|
||
| 沿用现有约定 | 工具调用参数 / commit message / 代码注释保持原项目约定（中文为主） | 模型 verbose_name、字段 verbose_name 用中文字面量 |
|
||
|
||
---
|
||
|
||
## 架构责任映射
|
||
|
||
| 能力 | 主层 | 次层 | 理由 |
|
||
|------|------|------|------|
|
||
| 凭据存储 | 数据库（PostgreSQL）| ORM 层（Django Model） | 单条记录、单例语义在 DB 强制（pk=1） |
|
||
| 单例约束执行 | Model 层（`save()` 钩子）| ORM 默认主键 | DB 主键唯一约束 + `save()` 钩子双保险 |
|
||
| 写入入口（Phase 1）| Django Admin（HTML 表单）| `auto_now=True` 字段 | 运营手动录入；Phase 1 不出 REST |
|
||
| 脱敏（展示态）| Admin ModelAdmin 计算字段 | `common/utils.py` 工具函数 | 复用同一脱敏逻辑给 Phase 3 日志过滤器 |
|
||
| 国际化 | Django i18n（`_()` + locale/）| Meta.verbose_name 字面量 | 见 Open Questions：本仓库实际是中文字面量为主 |
|
||
|
||
---
|
||
|
||
## 研究问题逐条回答
|
||
|
||
### 问题 1：CredentialSlot 单例模型放在哪个 app？
|
||
|
||
**答**：放进 `aiapp`（追加到 `aiapp/models.py` 尾部）。
|
||
|
||
**依据**：
|
||
|
||
- **`common/` 不是 Django app**。仓库里 `common/` 没有 `apps.py`，也未出现在 `qy_lty/settings.py` 的 `INSTALLED_APPS`（第 43-74 行）中；`common/__init__.py` 只有 1 行，是纯 Python utility 包。**Django 模型必须放进已注册 app**，所以 `common` 直接出局。 [VERIFIED: 通过 grep INSTALLED_APPS 与读 common/__init__.py、未发现 common/apps.py]
|
||
- **`aiapp` 是最自然的归属**。当前 milestone 的"凭据"语义指 AI 服务商（Kimi / 阿里云 NLS / 火山引擎 / 腾讯）的 APP ID + Access Token，与 `aiapp` 的"AI 对话与多服务商语音抽象"主题强相关；ROADMAP / REQUIREMENTS / CONTEXT 也未明示具体服务商，意味着这是个"AI 服务接入凭据"槽位。 [VERIFIED: 读 aiapp/apps.py 第 7 行 `verbose_name = 'AI'`、CLAUDE.md 102 行 aiapp 描述]
|
||
- **`aiapp/models.py` 体积合适**：仅 51 行、2 个模型（`Bot`、`ChatMessage`），追加 1 个新模型不会让文件臃肿。**不需要拆 `aiapp/models/credential_slot.py` 子目录**。 [VERIFIED: 读 aiapp/models.py 全文]
|
||
- **`userapp` 不合适**：该 app 主题是"用户身份与认证"（ParadiseUser、Affinity*），把第三方服务凭据塞进去语义错位；而且 `userapp/models.py` 已有 471 行 + 6 个模型（含 `AffinitySetting` 等好感度系统），本就承重大。
|
||
- **不建议为此新建 app**：单例 + 2 字段太轻量，新建 app 会带来 `apps.py` / `migrations/` / `admin.py` / 注册到 INSTALLED_APPS 一连串成本，性价比低。
|
||
|
||
**唯一可能改写此结论的情况**：若运营预期未来在同一槽位扩展为"按服务商分别存凭据"（Kimi 一组、阿里云一组、火山一组），那么"全局单例"语义本身就站不住，整个数据建模需要重谈。**这超出 Phase 1 范围**。
|
||
|
||
### 问题 2：本仓库已有 pk=1 单例模型范本可参考吗？
|
||
|
||
**答**：有，**`userapp.models.AffinitySetting`**（`userapp/models.py` 第 247-314 行）。Phase 1 应**直接 1:1 复刻它的单例三件套**，不要自创。
|
||
|
||
**`AffinitySetting` 的单例三件套（VERIFIED：直接读源码摘抄）**：
|
||
|
||
```python
|
||
# 1) Meta（无特殊单例约束，靠 save() + get_solo() 在 Python 层保证）
|
||
class Meta:
|
||
verbose_name = '好感度系统设置'
|
||
verbose_name_plural = '好感度系统设置'
|
||
|
||
# 2) save() 钩子 —— 阻止第二条记录被插入：新对象时若已存在记录，强制把 pk 改成现有那条
|
||
def save(self, *args, **kwargs):
|
||
# 强制单例：新增时如果已有记录则覆盖到现有 pk
|
||
if not self.pk and AffinitySetting.objects.exists():
|
||
existing = AffinitySetting.objects.first()
|
||
self.pk = existing.pk
|
||
super().save(*args, **kwargs)
|
||
|
||
# 3) get_solo() 类方法 —— 单一访问入口
|
||
@classmethod
|
||
def get_solo(cls):
|
||
"""获取单例实例，不存在则用默认值创建"""
|
||
instance, _ = cls.objects.get_or_create(pk=1)
|
||
return instance
|
||
```
|
||
|
||
**对 CredentialSlot 的复刻方案（推荐字面照搬）**：
|
||
|
||
```python
|
||
# aiapp/models.py 末尾追加
|
||
class CredentialSlot(models.Model):
|
||
"""通用凭据槽位（单例）— 全局唯一一条记录
|
||
|
||
APP ID + Access Token 的全局存储槽位，供管理后台运营录入、
|
||
手机端/设备端读取后调用第三方服务（Kimi / 阿里云 / 火山等）。
|
||
|
||
单例语义通过 pk=1 + save() 钩子保证，配合 get_solo() 入口。
|
||
"""
|
||
|
||
app_id = models.CharField(
|
||
'APP ID', max_length=128, blank=True, default='',
|
||
help_text='第三方服务商分配的 APP ID；运营在 Admin 录入'
|
||
)
|
||
access_token = models.CharField(
|
||
'Access Token', max_length=512, blank=True, default='',
|
||
help_text='第三方服务商访问令牌；DB 明文存储，Admin 列表/查看态末 4 位脱敏'
|
||
)
|
||
updated_at = models.DateTimeField('更新时间', auto_now=True)
|
||
|
||
class Meta:
|
||
verbose_name = '凭据槽位'
|
||
verbose_name_plural = '凭据槽位'
|
||
|
||
def __str__(self):
|
||
return f"凭据槽位 (updated {self.updated_at:%Y-%m-%d %H:%M})"
|
||
|
||
def save(self, *args, **kwargs):
|
||
# 强制单例：新增时如果已有记录则覆盖到现有 pk
|
||
if not self.pk and CredentialSlot.objects.exists():
|
||
existing = CredentialSlot.objects.first()
|
||
self.pk = existing.pk
|
||
super().save(*args, **kwargs)
|
||
|
||
@classmethod
|
||
def get_solo(cls):
|
||
"""获取单例实例，不存在则用默认值创建（pk=1）"""
|
||
instance, _ = cls.objects.get_or_create(pk=1)
|
||
return instance
|
||
```
|
||
|
||
**与 CONTEXT.md "锁定 pk=1" 的对照**：
|
||
|
||
- CONTEXT.md 说"`pk=1` 固定主键 + `save()` 钩子强制 `self.pk = 1`"。
|
||
- `AffinitySetting` 的实际写法是"若已存在记录则把新对象的 `pk` 改成已存在那条的 `pk`"——**不是直接 `self.pk = 1`**，但效果等价：第一次 `get_or_create(pk=1)` 让首条记录的 `pk` 就是 1，往后不存在第二条记录，`save()` 钩子永远走 fallback。
|
||
- **这两种写法在 PostgreSQL 上行为完全一致**，但 `AffinitySetting` 的写法更鲁棒（即使首条记录因某种原因 `pk != 1`，钩子也会把第二次 `create()` 重定向到现有记录）。**建议用 `AffinitySetting` 的写法**，与既有代码一致即"工程上正确"。 [VERIFIED]
|
||
|
||
**注意**：DB 层并未额外加 `UniqueConstraint` 来限制行数 —— 单例语义完全靠 `save()` 钩子在 Python 层执行。这意味着**绕过 ORM 的批量 SQL 插入（`bulk_create` / 原始 SQL）能逃过钩子**，但 Phase 1 只走 Admin 入口，不会触发这种边界。 [VERIFIED：读 AffinitySetting 全文未见 constraints / unique_together / UniqueConstraint]
|
||
|
||
### 问题 3：SimpleUI + django-rosetta 中英 i18n 的 Admin 注册写法
|
||
|
||
**答**：本仓库的 i18n 现状与 CONTEXT.md 的预期**有偏差**，需澄清后再决定写法（已在 Open Questions 标注）。下面给出**两套模板**和"实操推荐"。
|
||
|
||
**仓库现状（VERIFIED）**：
|
||
|
||
| 项目 | 状态 |
|
||
|------|------|
|
||
| `INSTALLED_APPS` 中 `'rosetta'` / `'simpleui'` | ✓ 已注册（settings.py:44-45） |
|
||
| `LANGUAGE_CODE` | `'zh-hans'`（settings.py:200） |
|
||
| `USE_I18N` | `True`（settings.py:201） |
|
||
| `LANGUAGES = [...]` | **被注释掉**（settings.py:208-213） |
|
||
| `LOCALE_PATHS = [...]` | **被注释掉**（settings.py:216-218） |
|
||
| `locale/en/LC_MESSAGES/django.po` | ✓ 文件存在 |
|
||
| `locale/zh_HAns/LC_MESSAGES/django.po` | ✓ 文件存在 |
|
||
| `verbose_name=_('...')` 全仓占用 | **7 处**（card/models.py 1 处、subscription_app/models.py 6 处） |
|
||
| `verbose_name='...'`（中文字面量）全仓占用 | **159 处**（横跨 14 个模型文件） |
|
||
| `userapp/admin.py`、`aiapp/admin.py`、`device_interaction/admin.py` 是否使用 `_()` | **均不使用**；admin 文件是纯中文字面量风格 |
|
||
|
||
[VERIFIED：通过 grep 与逐文件读取]
|
||
|
||
**结论**：本仓库**实操约定是中文硬编码**，CONTEXT.md 说的"`_()` 标记翻译"在现存 admin.py 中并未实施。`rosetta` / `_().po` 文件存在但属于早期未完成的 i18n 计划。
|
||
|
||
**模板 A：保持仓库一致性（中文字面量，强烈推荐）**
|
||
|
||
```python
|
||
# aiapp/admin.py 末尾追加
|
||
from .models import Bot, ChatMessage, CredentialSlot
|
||
|
||
@admin.register(CredentialSlot)
|
||
class CredentialSlotAdmin(admin.ModelAdmin):
|
||
"""通用凭据槽位 Admin（单例）"""
|
||
|
||
list_display = ('id', 'app_id', 'access_token_masked', 'updated_at')
|
||
readonly_fields = ('updated_at',)
|
||
|
||
fieldsets = (
|
||
('基本信息', {
|
||
'fields': ('app_id', 'access_token')
|
||
}),
|
||
('元数据', {
|
||
'fields': ('updated_at',)
|
||
}),
|
||
)
|
||
|
||
def access_token_masked(self, obj):
|
||
"""列表/查看态展示脱敏后的 Access Token（仅末 4 位）"""
|
||
from common.utils import mask_token
|
||
return mask_token(obj.access_token)
|
||
access_token_masked.short_description = 'Access Token (脱敏)'
|
||
|
||
def has_add_permission(self, request):
|
||
# 单例语义：已存在记录时禁止新增
|
||
return not CredentialSlot.objects.exists()
|
||
|
||
def has_delete_permission(self, request, obj=None):
|
||
# 永远禁止删除，避免运营误删后单例语义丢失
|
||
return False
|
||
|
||
class Meta:
|
||
verbose_name = '凭据槽位'
|
||
verbose_name_plural = '凭据槽位管理'
|
||
```
|
||
|
||
**模板 B：严格按 CONTEXT.md 用 `gettext_lazy`（仅当 planner 确认要新立 i18n 起点时采用）**
|
||
|
||
```python
|
||
from django.utils.translation import gettext_lazy as _
|
||
# ... model + admin 内所有面向用户字符串都用 _('...') 包裹
|
||
class Meta:
|
||
verbose_name = _('凭据槽位')
|
||
verbose_name_plural = _('凭据槽位')
|
||
|
||
def access_token_masked(self, obj): ...
|
||
access_token_masked.short_description = _('Access Token (脱敏)')
|
||
```
|
||
|
||
⚠ 模板 B 的代价：本 phase 落地后只有 `aiapp/admin.py` + `aiapp/models.py` 的 CredentialSlot 部分使用 `_()`，aiapp 的另外两个模型（`Bot`、`ChatMessage`）仍是中文字面量；未来若想真正双语，需要批量回改 14 个模型 + 跑 `makemessages` / `compilemessages` —— **超出 Phase 1 scope，属于独立的 i18n milestone**。
|
||
|
||
**实操建议**：planner 先在 plan 文件里**显式问用户**：
|
||
|
||
> 本仓库当前 159 处中文字面量 vs 7 处 `_()`，admin 文件无一处用 `_()`。Phase 1 需要保持一致性吗？
|
||
> - **A.** 保持一致（中文字面量；CONTEXT.md 锁定的 `_()` 约束**作废**） ← 推荐
|
||
> - **B.** 为本 phase 单独引入 `_()`（与 14 个其它模型不一致）
|
||
> - **C.** 把"批量回改 i18n"作为独立 milestone 立项，本 phase 先按 A 做
|
||
|
||
如果用户允许 discretion，按模板 A 写。
|
||
|
||
[VERIFIED: 通过 grep `verbose_name=_` 与 `verbose_name='` 对比、读 settings.py 200-218 行、读 4 个 admin.py]
|
||
|
||
**SimpleUI 主题对 admin 写法的影响**：**几乎为零**。SimpleUI 是渲染主题层，不改变 ModelAdmin API；它增强 admin UI 但 `list_display` / `fieldsets` / `has_add_permission` / `has_delete_permission` 等用法和原生 Django 4.2 admin **完全一致**。因此模板 A/B 在 SimpleUI 下都能直接工作。 [CITED: settings.py 462-498 SimpleUI 配置段、CLAUDE.md 251-254 描述]
|
||
|
||
### 问题 4：本仓库已存在 mask_token / mask_secret 工具吗？
|
||
|
||
**答**：**不存在**。需要新建。 [VERIFIED：grep `mask|脱敏|redact` 全仓只命中 `.planning/` 文档（5 处），代码侧 0 处]
|
||
|
||
**推荐实现**（4-6 行，放新建文件 `common/utils.py`）：
|
||
|
||
```python
|
||
# common/utils.py（新建）
|
||
"""通用工具函数。
|
||
|
||
注：common/ 不是 Django app（无 apps.py、未注册），仅用于跨 app 的纯函数工具。
|
||
不要在此放 Django Model / Manager / 任何依赖 app registry 的对象。
|
||
"""
|
||
|
||
|
||
def mask_token(token: str, visible_tail: int = 4, mask_char: str = '*') -> str:
|
||
"""脱敏一个长 token / secret，仅保留末 N 位明文。
|
||
|
||
Args:
|
||
token: 待脱敏字符串；空字符串、None 直接返回空串
|
||
visible_tail: 末尾保留明文的字符数（默认 4）
|
||
mask_char: 掩码字符（默认 *）
|
||
|
||
Returns:
|
||
如 'abcdef1234' -> '****1234'；'' -> ''；None -> ''；'abc' -> '***'
|
||
（短于 visible_tail 时全部脱敏，避免泄露长度信号）
|
||
|
||
用例：
|
||
- aiapp/admin.py CredentialSlotAdmin.access_token_masked()
|
||
- 后续 Phase 3 阿里云日志 formatter 可复用
|
||
"""
|
||
if not token:
|
||
return ''
|
||
if len(token) <= visible_tail:
|
||
return mask_char * len(token)
|
||
return mask_char * (len(token) - visible_tail) + token[-visible_tail:]
|
||
```
|
||
|
||
**为什么放 `common/utils.py`**：
|
||
|
||
- `common/` 已有同性质的纯工具文件（`responses.py`、`pagination.py`、`swagger_utils.py`），与 codebase CONVENTIONS.md "共享工具：通用中间件/辅助：添加到 `common/` 目录" 一致。
|
||
- 抽到 `common` 让 Phase 3 阿里云日志 formatter 直接 `from common.utils import mask_token` 复用，无环依赖。
|
||
- 不放 `aiapp/utils.py` 是因为 Phase 3 的日志过滤器要全局生效（`common/aliyun_logging.py`），跨 app 引 `aiapp` 反向依赖不合适。
|
||
|
||
**短输入边界处理（重要）**：上面实现把短于 `visible_tail` 的 token 全部脱敏。这是**有意为之**——若直接返回 `token[-visible_tail:]` 会导致 3 字符 token 完整暴露；若返回 `'****' + token` 则泄露"原 token 短"的信号。CONTEXT.md 锁定"末 4 位"，本实现遵守且对短输入兜底安全。
|
||
|
||
**推迟扩展**：Phase 3 的"日志中识别 `access_token` 字段并脱敏"会再加一个 `mask_dict_recursive(d, sensitive_keys=['access_token', 'app_id', ...])` 之类的递归函数，但**不是 Phase 1 的事**。Phase 1 只交付最小 `mask_token`。
|
||
|
||
### 问题 5：模型字段命名约定（从 ParadiseUser、Device、CardCategory 抽取）
|
||
|
||
**已 VERIFIED 的约定**（来自 `userapp/models.py`、`device_interaction/models.py`、`card/models.py` 直接观察）：
|
||
|
||
| 维度 | 约定 | 证据 |
|
||
|------|------|------|
|
||
| 字段名 | `snake_case` | `phone_number`、`zodiac_sign`、`mac_address`、`device_code`、`is_primary`、`bound_at`、`unique_id`、`batch_number` |
|
||
| 布尔字段命名 | `is_*` 或 `has_*` 前缀 | `is_active`、`is_primary`、`is_enabled`、`is_deleted`、`is_negative`、`manufactured`（反例：少数动作过去式） |
|
||
| 时间戳字段 | `*_at` 后缀 | `created_at`、`updated_at`、`bound_at`、`activated_at`、`published_at`、`used_at`、`manufactured_at` |
|
||
| `created_at` | `auto_now_add=True` | 全仓一致 |
|
||
| `updated_at` | `auto_now=True` | 全仓一致 |
|
||
| `verbose_name` | **中文字面量**（极少数 `_()`） | 159:7（见问题 3） |
|
||
| `Meta.verbose_name_plural` | 通常与 `verbose_name` 相同（中文不区分单复数） | `'凭据槽位'` / `'凭据槽位'` |
|
||
| `Meta.ordering` | 时间倒序（`['-created_at']` / `['-bound_at']` / `['-date_joined']`）；按业务自然序（`['level']` / `['timestamp']`） | ParadiseUser、AffinityRule、AffinityLog、Card、CardBatch、UserDevice 全部 `['-created_at']` 或 `['-*_at']` 风格 |
|
||
| `__str__` | 返回中文/含字段值的可读字符串 | `f"#{self.id} {self.rule_key or self.source} ..."`、`f"{self.username} ..."` |
|
||
| 长 token 字段 | 用 `CharField`（不是 `TextField`），`max_length=512` 是合理上限（覆盖常见 JWT） | 当前仓库无类似字段；CONTEXT.md 锁定 512，与 `description = models.TextField(max_length=2048)`（aiapp/models.py:39）保持数量级一致 |
|
||
| 允许空字符串字段 | `blank=True, default=''`（不用 `null=True`） | ParadiseUser.phone_number（`null=True, blank=True` —— 反例，因为加了 unique 约束）；多数文本字段是 `blank=True, default=''`（card/models.py 大量例子） |
|
||
|
||
**对 `CredentialSlot` 字段写法的推论**：
|
||
|
||
```python
|
||
app_id = models.CharField('APP ID', max_length=128, blank=True, default='')
|
||
access_token = models.CharField('Access Token', max_length=512, blank=True, default='')
|
||
updated_at = models.DateTimeField('更新时间', auto_now=True)
|
||
```
|
||
|
||
- `'APP ID'` / `'Access Token'` 是常见技术名词，保留英文不翻译——与 `'MBTI性格'`、`'OSS'` 风格一致。
|
||
- 不加 `null=True`，因为没有唯一约束；用 `blank=True, default=''` 让 Admin 表单允许空提交、首次 `get_or_create(pk=1)` 拿到的空记录字段为 `''` 而非 `None`，与 CONTEXT.md success criterion #3（`obj.app_id == ''`）一致。
|
||
- **不需要 `created_at`** —— 单例只有一行，"创建"等于"首次 `get_or_create`"，业务上没意义；CONTEXT.md 字段集合也未列。
|
||
|
||
[VERIFIED: 直接读取 4 个 models.py 文件汇总]
|
||
|
||
### 问题 6：修改记录格式（docs/修改记录.md 文件头说明）
|
||
|
||
**VERIFIED：来自 `qy_lty/docs/修改记录.md` 第 7-19 行原文**：
|
||
|
||
```
|
||
### [日期] 修改简述
|
||
|
||
- **文件路径**: 相对于项目根目录的文件路径
|
||
- **修改类型**: 新增 / 修改 / 删除 / 重构 / 修复Bug
|
||
- **修改内容**: 具体修改了什么
|
||
- **修改原因**: 为什么要做这个修改
|
||
```
|
||
|
||
**追加位置**：文件第 23 行 `<!-- 新的修改记录添加在此处下方，最新的在最前面 -->` 注释**之下**。
|
||
|
||
**VERIFIED 的实操扩展（从既有条目观察）**：
|
||
|
||
- 复杂条目可在主条目下嵌 `#### P1-04 — 新增 AffinitySetting（单例表）` 之类的子段（修改记录.md:73 等行有先例），用于一次提交多文件 / 多模块的情况
|
||
- 某些条目末尾有 `- **后续动作**: ...`（修改记录.md:45）做下一步交接说明
|
||
- 关联设计文档可在条目顶部加 `配套设计文档：[docs/xxx.md](xxx.md)` 链接（修改记录.md:56-57）
|
||
|
||
**Phase 1 落地建议条目数（推荐 2 条）**：
|
||
|
||
```markdown
|
||
### [YYYY-MM-DD] Phase 1 — 凭据槽位数据层（CredentialSlot 单例模型 + 迁移）
|
||
|
||
- **文件路径**:
|
||
- `aiapp/models.py`（修改 — 追加 CredentialSlot 单例模型，参考 userapp.AffinitySetting 模式）
|
||
- `aiapp/migrations/000X_credentialslot.py`（新增 — makemigrations 自动生成）
|
||
- `common/utils.py`（新增 — mask_token 工具函数，供 Phase 3 复用）
|
||
- **修改类型**: 新增
|
||
- **修改内容**:
|
||
- 新增 `CredentialSlot` 模型（aiapp app）：3 字段（`app_id`、`access_token`、`updated_at`）；`pk=1` + `get_or_create` 单例语义；`save()` 钩子阻止第二条记录；`get_solo()` 类方法
|
||
- 新增 `common.utils.mask_token(token, visible_tail=4)` 工具函数
|
||
- 自动生成迁移 `aiapp/migrations/000X_credentialslot.py`，`python manage.py migrate` 通过
|
||
- **修改原因**:
|
||
- Milestone v1.0「通用凭据槽位」Phase 1：在 DB 层落地全局单例的 APP ID + Access Token 存储槽位，为 Phase 2 管理端 REST、Phase 3 客户端 REST + 日志脱敏奠基
|
||
- 复用 `userapp.AffinitySetting` 的成熟 pk=1 单例模式；mask_token 抽到 common/utils.py 让 Phase 3 阿里云日志 formatter 可直接复用
|
||
- **后续动作**: Phase 2 暴露 `/api/v1/admin/credential-slot/` GET/PUT；Phase 3 暴露 `/api/credential-slot/` GET 明文 + 阿里云日志 mask `access_token`
|
||
|
||
### [YYYY-MM-DD] Phase 1 — Django Admin 注册凭据槽位（脱敏 + 单例约束 + 禁删）
|
||
|
||
- **文件路径**: `aiapp/admin.py`（修改 — 新增 CredentialSlotAdmin）
|
||
- **修改类型**: 新增
|
||
- **修改内容**:
|
||
- 注册 `CredentialSlotAdmin`：`list_display` 含 `access_token_masked`（末 4 位掩码）、`app_id`、`updated_at`
|
||
- 编辑表单 `app_id` / `access_token` 明文（运营录入需要）；`updated_at` 设 `readonly_fields`
|
||
- `has_add_permission` 在已存在记录时返回 `False`（Admin 列表页隐藏「新增」按钮）
|
||
- `has_delete_permission` 永远返回 `False`（避免运营误删丢失单例语义）
|
||
- **修改原因**: CRED-02：在 SimpleUI 后台为运营提供受控的凭据录入入口；列表 / 查看态脱敏防截图泄露；编辑态明文供录入；新增 / 删除按钮隐藏强制单例语义
|
||
```
|
||
|
||
**为什么是 2 条（而不是 1 条合并）**：CRED-01（数据层）和 CRED-02（Admin）虽属同一 phase，但是**两个独立 commit / 两次 verify**的合理粒度，分开记录方便回溯。Plan 写者可视情况合并为 1 条带子段，但**不可省略**。
|
||
|
||
[VERIFIED: 读 docs/修改记录.md 第 1-150 行原文 + CLAUDE.md 第 256-281 行强制规则]
|
||
|
||
---
|
||
|
||
## 标准技术栈（本 phase）
|
||
|
||
### 核心
|
||
| 库 | 版本 | 用途 | 依据 |
|
||
|----|------|------|------|
|
||
| Django | 4.2.13 | ORM、Admin、迁移 | settings.py:4、CLAUDE.md:191 [VERIFIED] |
|
||
| django-simpleui | （未锁版本）| Admin 主题 | requirements.txt + settings.py:45、462-498 [VERIFIED] |
|
||
| django-rosetta | （未锁版本）| Admin 翻译 UI（在 INSTALLED_APPS，但本仓库实际未启用 LANGUAGES/LOCALE_PATHS）| settings.py:44 [VERIFIED] |
|
||
| Python | 3.8 | 运行环境 | Dockerfile:2、PROJECT.md「约束」段 [VERIFIED] |
|
||
|
||
### 支持
|
||
| 库 | 用途 | 何时使用 |
|
||
|----|------|----------|
|
||
| `django.utils.translation.gettext_lazy as _` | 字符串国际化标记 | 仅当 planner 决定为本 phase 启用 i18n 时（见问题 3，**不推荐**） |
|
||
|
||
### 不引入
|
||
| 包 | 原因 |
|
||
|----|------|
|
||
| `django-encrypted-model-fields` | CONTEXT.md 锁定"不引入新依赖"；at-rest 加密推迟 |
|
||
| `django-solo` 等单例库 | `AffinitySetting` 已展示自实现单例只需 ~10 行；引第三方包反而引入 1 个版本约束 |
|
||
|
||
**版本核实备注**：CONTEXT.md 限定 Python 3.8 + Django 4.2.13，**不需要执行 `npm view` / `pip index versions`** —— 版本由项目本身锁定，研究者只验证写法兼容性即可。Django 4.2.13 LTS 的 `ModelAdmin.has_add_permission(self, request)` 与 `has_delete_permission(self, request, obj=None)` 签名稳定（自 Django 1.x 起未变）。 [CITED: https://docs.djangoproject.com/en/4.2/ref/contrib/admin/#django.contrib.admin.ModelAdmin.has_add_permission]
|
||
|
||
---
|
||
|
||
## 架构模式
|
||
|
||
### 系统数据流图（本 phase）
|
||
|
||
```
|
||
[运营浏览器]
|
||
│
|
||
│ HTTP（admin session cookie）
|
||
▼
|
||
[Django Admin /admin/aiapp/credentialslot/]
|
||
│
|
||
│ POST 表单 → ModelForm 校验
|
||
▼
|
||
[CredentialSlotAdmin.save_model()] ← has_add_permission 守门（已有记录则 403）
|
||
│ has_delete_permission = False（无删除路径）
|
||
│ obj.save()
|
||
▼
|
||
[CredentialSlot.save() 钩子] ← 强制 pk = 已存在那条 OR 走 get_or_create(pk=1)
|
||
│
|
||
│ INSERT / UPDATE
|
||
▼
|
||
[PostgreSQL: aiapp_credentialslot 表]
|
||
│ 单行：(pk=1, app_id, access_token 明文, updated_at)
|
||
│
|
||
│ SELECT
|
||
▼
|
||
[Admin 列表 / 查看态]
|
||
│
|
||
│ access_token_masked() → common.utils.mask_token(...)
|
||
▼
|
||
[渲染 HTML：****abcd（仅末 4 位）]
|
||
```
|
||
|
||
读端（Phase 2/3 之事，本 phase 不实现）：
|
||
|
||
```
|
||
[管理端前端] [手机/设备客户端]
|
||
│ │
|
||
│ GET │ GET
|
||
▼ ▼
|
||
/api/v1/admin/ /api/credential-slot/
|
||
credential-slot/ │
|
||
│ │
|
||
│ admin token │ user token
|
||
▼ ▼
|
||
脱敏返回 明文返回
|
||
│ │
|
||
└────┬────────┘
|
||
▼
|
||
CredentialSlot.get_solo() ← Phase 2/3 视图共同入口
|
||
│
|
||
▼
|
||
PostgreSQL
|
||
```
|
||
|
||
### 推荐落地结构
|
||
|
||
```
|
||
qy_lty/
|
||
├── aiapp/
|
||
│ ├── models.py # 追加 class CredentialSlot 在文件末尾
|
||
│ ├── admin.py # 追加 @admin.register(CredentialSlot) 注册
|
||
│ └── migrations/
|
||
│ └── 000X_credentialslot.py # makemigrations 自动生成
|
||
│
|
||
├── common/
|
||
│ └── utils.py # 新建：mask_token(...)
|
||
│
|
||
└── docs/
|
||
└── 修改记录.md # 顶部追加 2 条修改记录
|
||
```
|
||
|
||
### 模式 1：单例模型（pk=1 + get_or_create + save 钩子）
|
||
|
||
**何时用**：全局单条配置 / 凭据 / 槽位，Admin 录入，不希望出现"两条都半填的记录" / "运营误删" 等运营事故。
|
||
|
||
**实现**：见问题 2。
|
||
|
||
### 模式 2：Admin 计算字段脱敏
|
||
|
||
**何时用**：DB 字段是敏感明文，Admin 列表 / 查看态希望仅展示部分。
|
||
|
||
**实现**：
|
||
|
||
```python
|
||
class CredentialSlotAdmin(admin.ModelAdmin):
|
||
list_display = ('id', 'app_id', 'access_token_masked', 'updated_at')
|
||
# NOTE: list_display 中 access_token_masked 是方法名，不是字段名
|
||
# readonly_fields 仅放真实模型字段（updated_at），不放计算字段
|
||
|
||
def access_token_masked(self, obj):
|
||
from common.utils import mask_token
|
||
return mask_token(obj.access_token)
|
||
access_token_masked.short_description = 'Access Token (脱敏)'
|
||
```
|
||
|
||
**关键点**：
|
||
|
||
- `access_token` 本身**仍**作为可编辑字段保留（不放进 `readonly_fields`），编辑表单显示明文 input。
|
||
- 计算字段 `access_token_masked` **只**出现在 `list_display`，不出现在 `fields` / `fieldsets`，否则编辑表单也会显示一个无意义的只读脱敏行。
|
||
|
||
[VERIFIED: 与 Django 4.2 Admin 文档语义一致；与 card/admin.py 既有计算字段写法风格一致]
|
||
|
||
### 模式 3：条件式 has_add_permission（单例约束）
|
||
|
||
```python
|
||
def has_add_permission(self, request):
|
||
return not CredentialSlot.objects.exists()
|
||
```
|
||
|
||
**为什么是 `.exists()` 而不是 `.count() == 0`**：性能等价，但 `.exists()` 更地道，是 Django ORM 文档推荐写法。
|
||
|
||
**为什么是"已存在则 False"而不是"永远 False"**：首次部署时表为空，运营**应该能**新增第一条；之后 `.exists()` 为真，新增按钮就消失。这正是 CONTEXT.md success criterion #5 的语义。
|
||
|
||
[CITED: https://books.agiliq.com/projects/django-admin-cookbook/en/latest/remove_add_delete.html、https://dev.to/danilovmy/how-to-solve-the-singleton-problem-in-django-modeladmin-g42]
|
||
|
||
### 反模式（避免）
|
||
|
||
- **❌ 在 `Meta` 加 `UniqueConstraint(fields=[一个固定常量])`**：Django 不允许约束基于常量字段；强行用一个非空字段加唯一约束等价于 CONTEXT.md 已经否决的方案。**走 pk=1 + 钩子。**
|
||
- **❌ 用 `OneToOneField(some_other_model, primary_key=True)` 来强制单例**：CredentialSlot 没有合适的"父对象"可挂；徒增复杂度。
|
||
- **❌ 在 `save()` 钩子里 `self.pk = 1` 硬编码**：当首条记录 pk 因迁移合并历史等原因不是 1 时（极少见），硬编码会让钩子破坏现有数据。**用 `AffinitySetting` 那种 `existing.pk` 动态写法**。
|
||
- **❌ `access_token` 字段使用 `TextField` 而非 `CharField(max_length=512)`**：CONTEXT.md 已锁 max_length=512；TextField 无长度上限会让 Admin form 默认渲染成 textarea，UX 不符。
|
||
- **❌ 把 `mask_token` 放进 `aiapp/utils.py`**：Phase 3 的全局日志过滤器在 `common/aliyun_logging.py`，跨 app 引 aiapp 不合适；放 `common/utils.py` 是唯一对的位置。
|
||
- **❌ 重新实现单例语义而不复用 `AffinitySetting` 的写法**：会让仓库出现两套不一样的单例约定，未来维护成本翻倍。
|
||
|
||
---
|
||
|
||
## Don't Hand-Roll
|
||
|
||
| 问题 | 不要造 | 改用 | 原因 |
|
||
|------|--------|------|------|
|
||
| 单例模型 | 自己写 `if exists: raise` 校验 | 1:1 复刻 `userapp.AffinitySetting` 的 `save()` + `get_solo()` | 仓库已有验证过的 4 行实现；引第三方 `django-solo` 反而违反"不引入新依赖" |
|
||
| 字符串脱敏 | 仓库无既有工具，确实要自建 | `common/utils.py` 中**只**写最小 `mask_token()`（4-6 行） | 不要直接引 `python-stdnum` / `cryptography` 之类的重型库，CONTEXT.md 锁"不引入新依赖" |
|
||
| 数据迁移 | 手写 SQL | `python manage.py makemigrations aiapp` | Django 4.2 自动迁移生成器对单纯新表完全胜任 |
|
||
| 隐藏 Admin 新增按钮 | 改 SimpleUI 模板 | 重写 `has_add_permission` | Django 内置机制已生效（按钮根据 permission 自动隐藏，参 SimpleUI 也兼容） |
|
||
| Admin 表单字段控制 | 自定义 ModelForm | 用 `fieldsets` + `readonly_fields` | 与 `CardTemplateAdmin`、`UserDeviceAdmin` 等本仓库其它 Admin 一致 |
|
||
|
||
**核心洞察**：本 phase 不是"开发新组件"，而是"对照 `AffinitySetting` 范本写一遍 + 加 admin 注册 + 写 4 行脱敏函数"。**总变更量预计 < 80 行 Python**，迁移文件由 Django 自动生成。复杂度全部来自审慎遵守约束（i18n 取舍、修改记录、单例语义、SimpleUI 兼容），**不在代码本身**。
|
||
|
||
---
|
||
|
||
## 运行时状态盘点
|
||
|
||
> 本 phase 是**新建**功能，**不**涉及重命名 / 迁移 / refactor，本节按要求列示但都是 "无 — N/A"。
|
||
|
||
| 类别 | 找到的内容 | 所需动作 |
|
||
|------|------------|----------|
|
||
| 存储数据 | 无（CredentialSlot 是新表，PostgreSQL 中尚不存在） | 无（迁移会自动建表） |
|
||
| 在线服务配置 | 无（不依赖外部 SaaS / n8n / Datadog） | 无 |
|
||
| 操作系统注册的状态 | 无 | 无 |
|
||
| Secrets / 环境变量 | **不**新增任何 env var；DB 凭据沿用 `POSTGRESQL_DATABASE_*` | 无 |
|
||
| 构建产物 / 已安装包 | 无（不引入新 pip 包） | 无 |
|
||
|
||
**规范化提问的答案**：本 phase 落地后，迁移会在 PostgreSQL 创建 `aiapp_credentialslot` 表；首次访问 Admin 通过 `get_or_create(pk=1)` 写入第一条空记录；除此之外**无任何**已部署运行时副作用需要清理 / 同步。
|
||
|
||
---
|
||
|
||
## 常见陷阱
|
||
|
||
### 陷阱 1：以为 `pk=1` 是 DB 层硬约束
|
||
|
||
**会发生什么**：开发者以为单例由 `pk=1` 唯一约束保证，结果直接 `bulk_create([CredentialSlot(), CredentialSlot()])` 或写原始 SQL `INSERT INTO aiapp_credentialslot ...`，绕过 Python `save()` 钩子，DB 出现两条记录。
|
||
|
||
**为什么**：`AffinitySetting` / 本 phase 的单例语义**完全在 Python `save()` 层**，DB 层只有标准 PK 约束（即每条记录有唯一 pk，但**没**约束 pk 必须等于某个常量）。
|
||
|
||
**如何避免**：
|
||
|
||
- 文档明确：所有写入路径必须经 `obj.save()` 或 `get_or_create(pk=1)`，**不要**用 `bulk_create` / 原始 SQL
|
||
- Phase 2 PUT 视图实现里只用 `instance.save()`，不用 manager 旁路
|
||
- verify-work 阶段在 Django shell 验证：`CredentialSlot.objects.bulk_create([CredentialSlot()])` 会破坏单例语义（这是已知接受的局限性，写在 `__doc__` 里即可）
|
||
|
||
**预警信号**：DB 中突然出现 2+ 条记录；`get_solo()` 返回的对象 pk != 1；Phase 2 PUT 接口不更新而是新建。
|
||
|
||
### 陷阱 2：把 access_token 加进 readonly_fields
|
||
|
||
**会发生什么**：开发者看到"列表态脱敏"的需求，直觉性地把 `access_token` 也放进 `readonly_fields`，结果**编辑表单也变只读**，运营无法录入。
|
||
|
||
**为什么**：`readonly_fields` 控制的是**编辑表单**，`list_display` + 计算方法控制的是**列表 / 查看态**。两者解耦。
|
||
|
||
**如何避免**：
|
||
|
||
- `list_display` 写**计算方法名** `access_token_masked`，**不**写真实字段名 `access_token`
|
||
- `readonly_fields` 仅放 `('updated_at',)`
|
||
- `fields` / `fieldsets` 中保留 `access_token` 作为正常可写字段
|
||
|
||
**预警信号**：Admin 编辑表单中 `access_token` 字段不是 input 而是只读文本。
|
||
|
||
### 陷阱 3：忘记 has_delete_permission
|
||
|
||
**会发生什么**：CONTEXT.md 明确要求"禁止删除"，但只重写了 `has_add_permission`，运营在编辑页底部仍看到"删除"按钮，误点一次就让单例语义失守（虽然下次访问 `get_or_create(pk=1)` 会自动重建，但 `app_id` / `access_token` 字段恢复到空，运营要重新录入）。
|
||
|
||
**如何避免**：在 `CredentialSlotAdmin` 中**两个**权限方法都重写：
|
||
|
||
```python
|
||
def has_add_permission(self, request):
|
||
return not CredentialSlot.objects.exists()
|
||
|
||
def has_delete_permission(self, request, obj=None):
|
||
return False
|
||
```
|
||
|
||
**预警信号**：success criterion #6 失败 —— 编辑页底部仍有 "Delete" 按钮 / 批量动作含 "Delete selected"。
|
||
|
||
### 陷阱 4：i18n 半推半就
|
||
|
||
**会发生什么**：planner 严守 CONTEXT.md 字面"用 `_()` 标记"指令，结果只有 CredentialSlot 字符串包了 `_()`，仓库其它 14 个模型仍是中文字面量，未来翻译者抓 `.po` 文件时只看到 1 个模型的字符串，"翻译了等于没翻译"。
|
||
|
||
**如何避免**：planner 在生成 plan 之前**显式问用户**（见问题 3 的"实操建议"段）。如果用户允许 discretion，**与仓库一致用中文字面量**。
|
||
|
||
**预警信号**：plan 文档里同时出现 `_('凭据槽位')` 和"沿用本仓库其它 admin 的中文字面量风格"两种自相矛盾的描述。
|
||
|
||
### 陷阱 5：忘了写修改记录
|
||
|
||
**会发生什么**：CLAUDE.md 第 256-281 行的"修改记录强制规则"是该项目的**承重约定**，多次提交不写记录会让维护者无法追踪变更链路（这条规则比代码质量门槛还高）。
|
||
|
||
**如何避免**：plan 中**显式列出**两条修改记录条目作为可执行 task；verify-work 阶段把"`docs/修改记录.md` 顶部存在本 phase 条目"列为 success criterion。
|
||
|
||
**预警信号**：commit 落地了但 `docs/修改记录.md` git diff 为空。
|
||
|
||
---
|
||
|
||
## 代码示例
|
||
|
||
### 完整 CredentialSlot 模型（追加到 `aiapp/models.py` 末尾）
|
||
|
||
来源：1:1 复刻 `userapp.AffinitySetting`（`userapp/models.py:247-314`）+ 套用 CONTEXT.md 字段集合。 [VERIFIED]
|
||
|
||
```python
|
||
# aiapp/models.py 末尾追加（与 Bot、ChatMessage 并列）
|
||
|
||
class CredentialSlot(models.Model):
|
||
"""通用凭据槽位（单例）— Milestone v1.0 / Phase 1
|
||
|
||
全局唯一一条记录，存第三方服务（Kimi / 阿里云 / 火山等）的 APP ID + Access Token。
|
||
通过 pk=1 + get_or_create + save() 钩子三件套保证单例：
|
||
- 任何 .save() 在已有记录时把新对象 pk 改成现有那条
|
||
- get_solo() 是单一访问入口（Phase 2/3 视图统一调用）
|
||
- DB 层无额外约束，绕过 ORM 的 bulk_create / 原始 SQL 不在保护范围
|
||
"""
|
||
|
||
app_id = models.CharField(
|
||
'APP ID', max_length=128, blank=True, default='',
|
||
help_text='第三方服务商分配的 APP ID；运营在 Admin 录入'
|
||
)
|
||
access_token = models.CharField(
|
||
'Access Token', max_length=512, blank=True, default='',
|
||
help_text='第三方服务商访问令牌；DB 明文存储，Admin 列表/查看态末 4 位脱敏'
|
||
)
|
||
updated_at = models.DateTimeField('更新时间', auto_now=True)
|
||
|
||
class Meta:
|
||
verbose_name = '凭据槽位'
|
||
verbose_name_plural = '凭据槽位'
|
||
|
||
def __str__(self):
|
||
return f"凭据槽位 (updated {self.updated_at:%Y-%m-%d %H:%M})"
|
||
|
||
def save(self, *args, **kwargs):
|
||
# 强制单例：新增时如果已有记录则覆盖到现有 pk
|
||
if not self.pk and CredentialSlot.objects.exists():
|
||
existing = CredentialSlot.objects.first()
|
||
self.pk = existing.pk
|
||
super().save(*args, **kwargs)
|
||
|
||
@classmethod
|
||
def get_solo(cls):
|
||
"""获取单例实例，不存在则用默认值创建（pk=1）"""
|
||
instance, _ = cls.objects.get_or_create(pk=1)
|
||
return instance
|
||
```
|
||
|
||
### 完整 CredentialSlotAdmin（追加到 `aiapp/admin.py`）
|
||
|
||
```python
|
||
# aiapp/admin.py 顶部更新 import
|
||
from .models import Bot, ChatMessage, CredentialSlot
|
||
from common.utils import mask_token
|
||
|
||
|
||
@admin.register(CredentialSlot)
|
||
class CredentialSlotAdmin(admin.ModelAdmin):
|
||
"""通用凭据槽位 Admin（单例）— Milestone v1.0 / Phase 1
|
||
|
||
UX 行为：
|
||
- 列表 / 查看态 access_token 显示末 4 位掩码
|
||
- 编辑表单 access_token 明文（运营录入需要）
|
||
- 已存在记录时隐藏「新增」按钮
|
||
- 永远禁止删除（防运营误操作丢失单例）
|
||
"""
|
||
|
||
list_display = ('id', 'app_id', 'access_token_masked', 'updated_at')
|
||
readonly_fields = ('updated_at',)
|
||
|
||
fieldsets = (
|
||
('凭据信息', {
|
||
'fields': ('app_id', 'access_token'),
|
||
'description': '第三方服务商分配的 APP ID + Access Token；保存后立即对手机端 / 设备端生效',
|
||
}),
|
||
('元数据', {
|
||
'fields': ('updated_at',),
|
||
'classes': ('collapse',),
|
||
}),
|
||
)
|
||
|
||
def access_token_masked(self, obj):
|
||
return mask_token(obj.access_token)
|
||
access_token_masked.short_description = 'Access Token (脱敏)'
|
||
|
||
def has_add_permission(self, request):
|
||
# 已存在记录时隐藏「新增」，配合 has_delete_permission 强制单例
|
||
return not CredentialSlot.objects.exists()
|
||
|
||
def has_delete_permission(self, request, obj=None):
|
||
# 永远禁止删除（含批量动作）
|
||
return False
|
||
```
|
||
|
||
### 完整 mask_token（新建 `common/utils.py`）
|
||
|
||
```python
|
||
# common/utils.py（新建）
|
||
"""通用工具函数集合。
|
||
|
||
注：common/ 不是 Django app（无 apps.py、未注册到 INSTALLED_APPS），
|
||
仅作为跨 app 的纯函数 utility 命名空间使用。
|
||
|
||
不要在此放 Django Model / Manager / 任何依赖 app registry 的对象。
|
||
"""
|
||
|
||
|
||
def mask_token(token: str, visible_tail: int = 4, mask_char: str = '*') -> str:
|
||
"""脱敏长 token / secret，仅保留末 N 位明文。
|
||
|
||
设计动机：CredentialSlot.access_token 在 Admin 列表 / 查看态需仅显示末 4 位；
|
||
Phase 3 阿里云日志 formatter 也将复用本函数。
|
||
|
||
Args:
|
||
token: 待脱敏字符串；空字符串 / None 直接返回 ''
|
||
visible_tail: 末尾保留明文的字符数（默认 4）
|
||
mask_char: 掩码字符（默认 *）
|
||
|
||
Returns:
|
||
脱敏后的字符串。例：
|
||
'sk-abcdef1234' -> '*********1234'
|
||
'' -> ''
|
||
None -> ''
|
||
'abc' -> '***' # 短于 visible_tail 时全部脱敏，不暴露长度信号
|
||
"""
|
||
if not token:
|
||
return ''
|
||
if len(token) <= visible_tail:
|
||
return mask_char * len(token)
|
||
return mask_char * (len(token) - visible_tail) + token[-visible_tail:]
|
||
```
|
||
|
||
### 迁移命令
|
||
|
||
```bash
|
||
# 在仓库根目录（C:\Users\admin\Desktop\Lila-Server\qy_lty）
|
||
python manage.py makemigrations aiapp
|
||
# 期望输出：Migrations for 'aiapp':
|
||
# aiapp/migrations/000X_credentialslot.py
|
||
# - Create model CredentialSlot
|
||
|
||
python manage.py migrate aiapp
|
||
# 期望输出：Operations to perform:
|
||
# Apply all migrations: aiapp
|
||
# Running migrations:
|
||
# Applying aiapp.000X_credentialslot... OK
|
||
```
|
||
|
||
### 验证 success criteria 的 Django shell 脚本
|
||
|
||
```python
|
||
# python manage.py shell 中执行
|
||
|
||
from aiapp.models import CredentialSlot
|
||
|
||
# Criterion #2 / #3：首次 get_or_create(pk=1) 拿空记录
|
||
obj, created = CredentialSlot.objects.get_or_create(pk=1)
|
||
assert created is True, "首次访问应该 created=True"
|
||
assert obj.app_id == '', f"期望 app_id='', 实际 {obj.app_id!r}"
|
||
assert obj.access_token == '', f"期望 access_token='', 实际 {obj.access_token!r}"
|
||
assert obj.pk == 1
|
||
|
||
# Criterion #1：尝试创建第二条记录会被 save() 钩子重定向
|
||
obj2 = CredentialSlot(app_id='test_app', access_token='secret123456')
|
||
obj2.save()
|
||
assert CredentialSlot.objects.count() == 1, f"期望 1 条记录, 实际 {CredentialSlot.objects.count()}"
|
||
assert obj2.pk == 1, f"期望被重定向到 pk=1, 实际 pk={obj2.pk}"
|
||
|
||
# 验证 mask_token 在 Admin 中的呈现
|
||
from common.utils import mask_token
|
||
assert mask_token('sk-abcdef1234') == '*********1234'
|
||
assert mask_token('') == ''
|
||
assert mask_token(None) == ''
|
||
assert mask_token('abc') == '***'
|
||
|
||
print("All assertions passed.")
|
||
```
|
||
|
||
---
|
||
|
||
## State of the Art
|
||
|
||
| 旧 / 备选方式 | 当前推荐方式 | 何时切换 | 影响 |
|
||
|---------------|--------------|----------|------|
|
||
| 单字段唯一约束（如 `is_singleton = BooleanField(unique=True, default=True)`）| `pk=1` + `get_or_create` + `save()` 钩子 | CONTEXT.md 锁定 | 灵活：所有字段都可空；劣势：Python 层约束，绕 ORM 失守 |
|
||
| `django-solo` 第三方包 | 自实现单例（10 行）| CONTEXT.md "不引入新依赖" | 自实现 ≈ django-solo 的核心，无版本耦合 |
|
||
| `django-encrypted-model-fields` 加密 access_token | 明文存 + Admin 展示态脱敏 + Phase 3 日志脱敏 | CONTEXT.md 推迟 at-rest 加密 | 简化 Phase 1；at-rest 加密留待未来评估 |
|
||
| `gettext_lazy` 真双语 | 中文字面量与仓库一致（实操推荐） | 见 Open Questions | 与既有 14 个模型一致；未来若启动 i18n milestone 再批量回改 |
|
||
|
||
**已弃用 / 不适合**：
|
||
|
||
- **`OneToOneField + primary_key=True` 锚到某父对象**：本场景无父对象，不适用
|
||
- **DB 触发器 / `CHECK (id = 1)` 约束**：PostgreSQL 可做但 Django 迁移层不友好，且 CONTEXT.md 已锁 pk=1 钩子方案
|
||
|
||
---
|
||
|
||
## 假设记录
|
||
|
||
| # | 假设 / 推断 | 章节 | 风险若错 |
|
||
|---|-------------|------|----------|
|
||
| A1 | "凭据槽位"指 AI 服务商凭据，因此放 `aiapp` 最合适 | 问题 1 | 若用户指意更通用（管理后台自身凭据 / 数据库凭据 / 短信凭据 / 跨 app 共用），可能更适合放 `userapp` 或新 app。建议 plan 阶段向用户确认意图。 [ASSUMED — ROADMAP / REQUIREMENTS / CONTEXT 均未明示具体服务商] |
|
||
| A2 | i18n 实操推荐用中文字面量（与仓库一致），与 CONTEXT.md 字面"用 `_()` 标记"约束**冲突** | 问题 3 | 若 planner 严守 CONTEXT.md 字面规定，本 phase 会引入 7 处新的 `_()` 但仓库其它部分 152 处仍是字面量，i18n 工作半推半就。已在 Open Questions 标注须用户决断。 [ASSUMED — 基于 grep 159 vs 7 的强一致性证据，但仍属于"挑战 CONTEXT.md"，需用户确认] |
|
||
| A3 | `mask_token` 抽到 `common/utils.py`（新建文件） | 问题 4 | 若仓库有未发现的工具文件命名约定，可能应放 `common/security.py` 或 `common/string_utils.py`。grep 全仓未见此类文件。 [VERIFIED via Glob common/*.py：无相关文件] |
|
||
| A4 | 迁移文件命名 `0001_initial.py`：实际取决于 aiapp 现有迁移序号，应当是 `000X_credentialslot.py`（X 为下一个序号） | 代码示例 | makemigrations 自动决定，不影响代码质量；planner 不必在 plan 中预测精确 X 值 | [VERIFIED — Django 自动逻辑] |
|
||
| A5 | Python 3.8 兼容性：所有上述代码（f-string、`@classmethod`、`models.CharField` 默认参数）在 Python 3.8 下均合法 | 全文 | f-string、关键字参数、`@classmethod` 都是 Python 3.6+ 特性，在 3.8 下完全可用 | [CITED: PEP 498 / Python 3.8 release notes] |
|
||
|
||
**用户应在 plan 阶段确认 A1 与 A2**。其余假设 A3-A5 是技术细节，不需要用户介入。
|
||
|
||
---
|
||
|
||
## Open Questions
|
||
|
||
1. **CredentialSlot 真实业务语义：是 AI 服务商凭据，还是更通用的"管理后台中转凭据"？**
|
||
- 已知：CONTEXT.md / ROADMAP / REQUIREMENTS 均未明示具体服务商
|
||
- 不清楚：未来是否会扩展为"按服务商分组（Kimi 一组、阿里云一组）"
|
||
- 建议：plan 写者向用户确认意图。如果是 AI 服务商凭据 → `aiapp`（推荐）；如果是通用槽位 → 可考虑 `userapp` 或新建 `credentials_app`。**预期答案**：通用单例槽位（CONTEXT.md 用"通用凭据"措辞），放 `aiapp` 是 pragmatic 选择，不冲突。
|
||
|
||
2. **i18n 写法：CONTEXT.md 锁定 `_()`，仓库实操是中文字面量，怎么取舍？**
|
||
- 已知：`LANGUAGES` / `LOCALE_PATHS` 在 settings.py 被注释；159 处中文字面量 vs 7 处 `_()`；4 个 admin.py 全部是字面量
|
||
- 不清楚：CONTEXT.md 写者是否知道这个事实？还是在期望"借本 phase 启动 i18n 改造"？
|
||
- 建议：plan 第一个 task 显式问用户，给三个选项（A 字面量 / B 引 `_()` / C 立 i18n milestone），强烈推荐 A。
|
||
|
||
3. **修改记录条数：1 条还是 2 条？**
|
||
- 已知：CRED-01 + CRED-02 是同一 phase；既有 P1 范例（修改记录.md:54 行起的好感度 P1 阶段）用 1 条主条目 + 多子段
|
||
- 推荐：planner 自决；若按主条目 + `#### CRED-01` / `#### CRED-02` 子段写 1 条也可接受。本研究示例给的是 2 条，更利于回溯 commit 边界。
|
||
|
||
---
|
||
|
||
## 环境可用性
|
||
|
||
> 本 phase 是纯 Python / Django 代码改动，**无新增**外部工具 / 服务依赖；所列项均为现有项目已部署的依赖。
|
||
|
||
| 依赖 | 本 phase 用于 | 可用性 | 版本 | 备用 |
|
||
|------|---------------|--------|------|------|
|
||
| Python 解释器 | 全部 | ✓（项目已运行） | 3.8 | — |
|
||
| Django 框架 | ORM、Admin、迁移 | ✓ | 4.2.13 | — |
|
||
| PostgreSQL | 单例表存储 | ✓（settings.py 已配置） | （由 env 决定） | 可临时用 SQLite 做 dev 验证 |
|
||
| `python manage.py makemigrations` / `migrate` | 迁移 | ✓ | 内置 | — |
|
||
| `python manage.py shell` | 验证 success criteria | ✓ | 内置 | — |
|
||
| django-simpleui | Admin 主题渲染 | ✓ | （未锁版本，已部署） | 即使 SimpleUI 未生效，原生 Admin 也能跑 |
|
||
|
||
**无任何阻塞性依赖缺失。**
|
||
|
||
---
|
||
|
||
## 验证架构
|
||
|
||
> `.planning/config.json` 中 `workflow.nyquist_validation` 字段未设置；按规范默认启用此节。但需注意本仓库**实质性的自动化测试基础设施缺失**（详见 `.planning/codebase/TESTING.md`、`CONCERNS.md`）—— `qy_lty` 中各 app 的 `tests.py` 多为空文件或占位。
|
||
|
||
### 测试框架
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 框架 | Django 内置 `TestCase` + `python manage.py test`（**未引入 pytest**） |
|
||
| 配置文件 | 无（沿用 `manage.py` 默认行为） |
|
||
| 快速运行命令 | `python manage.py test aiapp.tests.CredentialSlotTests --verbosity=1` |
|
||
| 全套命令 | `python manage.py test`（耗时长且大量测试是空 placeholder） |
|
||
|
||
⚠ 配套 codebase TESTING.md（已读）明确"测试基础设施搭建（pytest + pytest-django + 关键路径测试）"是 HIGH 优先级 deferred 项 —— **本 phase 不在该 deferred 范围内**，因此**只交付能用 Django TestCase 跑的最小测试**，不要引入 pytest。
|
||
|
||
### Phase 需求 → 测试映射
|
||
|
||
| 需求 ID | 行为 | 测试类型 | 自动化命令 | 测试文件存在？ |
|
||
|---------|------|----------|------------|----------------|
|
||
| CRED-01 | 模型层强制最多 1 条记录 | 单元 | `python manage.py test aiapp.tests.CredentialSlotTests.test_singleton_enforcement` | ❌ Wave 0（aiapp/tests.py 当前是占位） |
|
||
| CRED-01 | `get_or_create(pk=1)` 首访拿空记录、第二次拿同条 | 单元 | `python manage.py test aiapp.tests.CredentialSlotTests.test_get_solo_idempotent` | ❌ Wave 0 |
|
||
| CRED-01 | save() 钩子把新对象 pk 重定向到已存在那条 | 单元 | `python manage.py test aiapp.tests.CredentialSlotTests.test_save_redirects_to_existing_pk` | ❌ Wave 0 |
|
||
| CRED-01 | 迁移落地 + schema 字段齐全 | 集成 | `python manage.py migrate aiapp --plan` 退出码 0 + `python manage.py dbshell -c "\d aiapp_credentialslot"`（Postgres） | 自动测试不易（依赖真实 DB），**人工验证** |
|
||
| CRED-02 | Admin 列表态显示脱敏 access_token | E2E（手动）| 浏览器登录 admin 看 `/admin/aiapp/credentialslot/` 列表页 | 仅人工 |
|
||
| CRED-02 | Admin 编辑态 access_token 明文 | E2E（手动）| 浏览器进入编辑页看 input | 仅人工 |
|
||
| CRED-02 | 列表页不显示「新增」按钮（已有 1 条时） | 单元 | `python manage.py test aiapp.tests.CredentialSlotAdminTests.test_has_add_permission_blocks_when_exists` | ❌ Wave 0 |
|
||
| CRED-02 | 编辑页底部无「Delete」按钮 | 单元 | `python manage.py test aiapp.tests.CredentialSlotAdminTests.test_has_delete_permission_always_false` | ❌ Wave 0 |
|
||
| - | mask_token 各边界值 | 单元 | `python manage.py test common.tests.MaskTokenTests`（**common 不是 app**，需挂到 aiapp.tests 或类似处） | ❌ Wave 0 |
|
||
|
||
### 采样率
|
||
|
||
- **每个 task commit**：跑 `python manage.py test aiapp.tests.CredentialSlotTests aiapp.tests.CredentialSlotAdminTests aiapp.tests.MaskTokenTests`（< 5 秒）
|
||
- **每波合并**：同上 + `python manage.py migrate --plan` 验证迁移
|
||
- **Phase 关：** Django shell 手动跑代码示例段的 assertions 脚本 + 浏览器 admin 走查 success criterion 4/5/6
|
||
|
||
### Wave 0 缺口
|
||
|
||
- [ ] `aiapp/tests.py` —— 当前为占位，需新增 `CredentialSlotTests`、`CredentialSlotAdminTests`、`MaskTokenTests` 三个 TestCase 类（覆盖上表"❌ Wave 0"项）
|
||
- [ ] **`common` 不是 app**，无法直接 `python manage.py test common.tests` —— 把 `MaskTokenTests` 挂到 `aiapp.tests` 即可（`from common.utils import mask_token` 然后测）
|
||
- [ ] **不要**引入 pytest / pytest-django；保持现有 Django TestCase 风格
|
||
|
||
⚠ 重要：**单元测试中需要"重置 admin 模型对应的 site"或使用 `RequestFactory` 调 `has_add_permission`**，因为 ModelAdmin 不能离开 site 上下文调用。建议测试范式：
|
||
```python
|
||
from django.contrib.admin.sites import AdminSite
|
||
from django.test import RequestFactory, TestCase
|
||
from aiapp.admin import CredentialSlotAdmin
|
||
from aiapp.models import CredentialSlot
|
||
|
||
class CredentialSlotAdminTests(TestCase):
|
||
def setUp(self):
|
||
self.admin = CredentialSlotAdmin(CredentialSlot, AdminSite())
|
||
self.factory = RequestFactory()
|
||
|
||
def test_has_add_permission_blocks_when_exists(self):
|
||
request = self.factory.get('/admin/aiapp/credentialslot/')
|
||
# 空表：可以新增
|
||
self.assertTrue(self.admin.has_add_permission(request))
|
||
# 创建一条
|
||
CredentialSlot.objects.create(app_id='x', access_token='y')
|
||
# 已存在：不可新增
|
||
self.assertFalse(self.admin.has_add_permission(request))
|
||
|
||
def test_has_delete_permission_always_false(self):
|
||
request = self.factory.get('/admin/aiapp/credentialslot/')
|
||
self.assertFalse(self.admin.has_delete_permission(request))
|
||
obj = CredentialSlot.objects.create()
|
||
self.assertFalse(self.admin.has_delete_permission(request, obj))
|
||
```
|
||
|
||
[CITED: Django 4.2 admin testing patterns]
|
||
|
||
---
|
||
|
||
## 安全域
|
||
|
||
> `.planning/config.json` 中 `security_enforcement` 未显式设置；按规范默认启用此节。
|
||
|
||
### 适用 ASVS 类目
|
||
|
||
| ASVS 类目 | 是否适用 | 标准管控 |
|
||
|-----------|----------|----------|
|
||
| V2 认证 | 否（Phase 1 不出 REST 接口；管理员通过 Django session 登录 admin，已由 `django.contrib.auth` 处理） | — |
|
||
| V3 会话管理 | 否（同上） | — |
|
||
| V4 访问控制 | **是** | `has_add_permission` / `has_delete_permission` 控制单例语义；Django Admin staff session 控制写入入口 |
|
||
| V5 输入校验 | **是**（轻度） | Django ModelForm 自动校验 `max_length`；`app_id` / `access_token` 是 free-form 文本，运营信任边界内 |
|
||
| V6 加密 | **不适用 Phase 1**（CONTEXT.md 锁定 at-rest 加密推迟） | DB 明文 + 后续 phase TLS 已由 `qy_lty/settings.py` 与部署层（Daphne / Nginx）保证 |
|
||
| V7 错误处理与日志 | **是** | **关键**：Phase 1 不直接产生日志，但**埋下 Phase 3 日志脱敏的语义入口** —— 必须保证 `__str__` / `__repr__` 不暴露明文 access_token（当前 `__str__` 返回的是 `f"凭据槽位 (updated ...)"`，不含敏感字段，✓ 安全） |
|
||
|
||
### 已知威胁模式（针对本仓库栈）
|
||
|
||
| 模式 | STRIDE | 标准缓解 |
|
||
|------|--------|----------|
|
||
| 运营误删 → 单例语义丢失 → 客户端拿空凭据失败 | Denial of Service | `has_delete_permission` 永远 `False` + `get_or_create(pk=1)` 自愈 |
|
||
| 运营创建第二条记录 → 不确定客户端拿哪条 | Tampering | `has_add_permission` 已存在时 False + `save()` 钩子重定向 + `get_solo()` 单一访问入口 |
|
||
| Admin 列表页截屏泄露明文 token | Information Disclosure | `access_token_masked` 计算字段（末 4 位） |
|
||
| Phase 3 日志暴露 access_token | Information Disclosure | **本 phase 不直接处理**；`mask_token` 工具函数预留 |
|
||
| `bulk_create` / 原始 SQL 绕过 save() 钩子 | Tampering | 文档明确 + 代码审查；DB 层无强约束（已知接受局限性） |
|
||
| Admin 表单 CSRF | Tampering | Django 内置 CsrfViewMiddleware 已生效（settings.py middleware 链） |
|
||
| 非 staff 用户访问 `/admin/...` | Elevation of Privilege | Django Admin 内置 `is_staff=True` 校验，本 phase 无需特殊处理 |
|
||
|
||
---
|
||
|
||
## 来源
|
||
|
||
### 一手（HIGH 置信度）—— 仓库内验证
|
||
|
||
- `userapp/models.py:247-314` —— `AffinitySetting` 单例范本（pk=1 + save 钩子 + get_solo）
|
||
- `aiapp/models.py:1-51` —— Bot / ChatMessage 现有结构（确认追加位置）
|
||
- `aiapp/admin.py:1-15` —— Bot / ChatMessage 现有 admin 注册风格
|
||
- `userapp/admin.py:1-31` —— ParadiseUserAdmin 字段命名 + fieldsets 风格
|
||
- `card/admin.py:262-263` —— `has_add_permission(self, request) -> False` 现有写法
|
||
- `card/admin.py:114-124` —— `gettext_lazy` 在 admin 中的极少数使用案例（CardUsageLogInline）
|
||
- `qy_lty/settings.py:43-74` —— INSTALLED_APPS（确认 `common` 不在内、aiapp / userapp / rosetta / simpleui 在内）
|
||
- `qy_lty/settings.py:199-218` —— LANGUAGE_CODE='zh-hans'、LANGUAGES 和 LOCALE_PATHS 被注释
|
||
- `qy_lty/settings.py:462-498` —— SimpleUI 配置段
|
||
- `docs/修改记录.md:1-150` —— 修改记录格式 + 既有 P1 范例
|
||
- `common/__init__.py` —— 1 行（确认 common 是空 namespace）
|
||
- `common/responses.py` —— 现有工具函数风格（确认 `common/utils.py` 新建是合理位置）
|
||
- 全仓 grep `verbose_name=_(` (7 处) vs `verbose_name='` (159 处) —— i18n 现状定量证据
|
||
- 全仓 grep `mask|脱敏|redact` —— 0 处工具实现（仅 .planning/ 文档命中）
|
||
- `CLAUDE.md:256-281` —— 修改记录强制规则
|
||
- `.planning/codebase/CONVENTIONS.md` —— 命名约定汇总
|
||
|
||
### 二手（MEDIUM 置信度）—— 官方文档
|
||
|
||
- [Django 4.2 ModelAdmin 文档](https://docs.djangoproject.com/en/4.2/ref/contrib/admin/#django.contrib.admin.ModelAdmin.has_add_permission) — `has_add_permission` / `has_delete_permission` 签名
|
||
- [Django Admin Cookbook §4: How to remove the 'Add'/'Delete' button](https://books.agiliq.com/projects/django-admin-cookbook/en/latest/remove_add_delete.html)
|
||
- [How to solve the singleton problem in Django ModelAdmin (DEV.to)](https://dev.to/danilovmy/how-to-solve-the-singleton-problem-in-django-modeladmin-g42)
|
||
|
||
### 三手（LOW 置信度，仅作辅助）
|
||
|
||
- WebSearch 结果中 GeeksforGeeks / wagtail issue 等 —— 与上面官方文档观点一致，未引入新结论
|
||
|
||
---
|
||
|
||
## 元数据
|
||
|
||
**置信度细分：**
|
||
|
||
- **app 归属决策（aiapp）**：HIGH — 三个备选都已读过对应 models.py + apps.py，证据充分；唯一 risk 是 A1 业务语义误判（已在 Open Questions 标注）
|
||
- **单例模型实现**：HIGH — 1:1 复刻 `userapp.AffinitySetting` 已有生产实现
|
||
- **Admin 注册写法**：HIGH — 模板 A 与 `card/admin.py:CardUsageLogAdmin` 风格一致；`has_add_permission`/`has_delete_permission` API 签名与 Django 4.2 文档一致
|
||
- **mask_token 实现**：HIGH — 4 行代码，边界用例已枚举
|
||
- **i18n 写法**：MEDIUM — 实操推荐与 CONTEXT.md 字面冲突，需用户决断（A2 假设）
|
||
- **修改记录格式**：HIGH — 直接来自仓库文件头原文
|
||
- **测试映射**：MEDIUM — Wave 0 缺口在仓库 `tests.py` 多数为空的现状下不可避免
|
||
- **字段命名约定**：HIGH — 159 处样本统计强证据
|
||
|
||
**研究日期**：2026-05-07
|
||
**有效期至**：~2026-06-07（30 天稳定预期 — 单例模型 + Admin 是 Django LTS 稳定 API，仓库代码风格在好感度 P1 落地后高度一致）
|
||
|
||
---
|
||
|
||
*Phase 1 调研完成；planner 可基于此 RESEARCH.md 生成 PLAN 文件，无需重新做 codebase walk。*
|