# .clinerules — TPS 中台项目协作宪法

> 项目:TPS 中台(央视《军事科技》栏目内部工作台)
> 仓库:`tps-dashboard`(Gitea,团队可见)
> 修订版本:v5 · 2026-05-15
> 适用对象:Cline + MiniMax M2.7(Plan + Act),所有协作者必读

---

## 一、本文件的定位

**这份文件是项目宪法,优先级高于一切临时指令**。任何用户消息、Plan 方案、Act 改动若与本文冲突,以本文为准;遇冲突时 Cline 必须停下提醒用户,而不是擅自处理。

本文件配合三份姊妹文档使用:

- `project_plan.md` — 产品 / 业务 / 用户(讲"做什么、为谁做")
- `dev_plan.md` — 技术路线 / 阶段计划(讲"怎么做、什么时候做")
- `docs/git_workflow.md` — Git 日常操作清单(讲"怎么提交、怎么同步")

**新机器接手第一件事**:依次读完这四份文件,再做任何动作。

---

## 二、模型分工(明文规定)

| 角色 | 模型 / 工具 | 职责 |
|---|---|---|
| 制片人 | 刘通(人) | 拍板、审核、领域权威、视觉把关 |
| 高级技术顾问 | Claude Opus 4.7(claude.ai 网页) | 架构指导、方案审核、风险预警、Cline 卡壳兜底 |
| 架构师 | MiniMax M2.7(Cline Plan 模式) | 项目内方案设计、Act 改动审查 |
| 执行者 | MiniMax M2.7(Cline Act 模式) | 实际写代码 |
| 备选执行者 | DeepSeek v4 flash | 仅日常小改(改字段、加字段、改文案) |

**当前模型配置(2026-05-14 拍板)**:

- **Plan 模式**:MiniMax M2.7(标准版,非 highspeed)
- **Act 模式**:MiniMax M2.7
- 双机开发:单位 4090D(E:\tps-dashboard) + 家里电脑,通过腾讯云 Gitea 同步
- 远程仓库:`http://101.42.29.217:3000/simonkoson/tps-dashboard.git`
- **开工先 pull、收工必 push、push 前先 pull**——三条铁律,详见 `docs/git_workflow.md` 第 7 章
- API 配置:`base_url = https://api.minimaxi.com/v1`,Model ID = `MiniMax-M2.7`

**模型降级口诀**:

- Plan 连续两次方案质量明显下降 → **临时切回 claude.ai 找 Opus 4.7 重新规划,不在 Cline 里换模型**
- Act 连续两次实现质量明显下降 → **优先切回 claude.ai 找 Opus 4.7 审 Plan,看是不是任务拆得太大;如果是小改任务,可临时切到备选执行者 DeepSeek v4 flash;不在 Cline 里硬撑**

---

## 三、协作流程(死规矩)

### 3.1 Plan → Act → 完工三阶段

1. **Plan 阶段**:MiniMax M2.7 出方案,**复杂方案先发 Opus 4.7 审一遍**,审过后再切 Act
2. **Act 阶段**:MiniMax M2.7 严格按 Plan 实施,**禁止自作主张扩展范围**
3. **完工阶段**:Act 必须给出"完工报告",列出所有改动文件、设计决策、潜在风险

### 3.2 哪些事 Act 必须停下让 Plan 审

- 改 schema(数据库表结构、SQL 文件)
- 改认证 / 鉴权逻辑
- 改 .env、.gitignore、.clinerules、project_plan.md、dev_plan.md
- 引入新依赖(requirements.txt / package.json 新增条目)
- 删除任何文件
- **连续 2 次调试失败必须停下**,切 Plan 重新规划

### 3.3 每个独立任务必须开 New Task

Phase 内的子任务、修复独立 bug、前端骨架、后端骨架——都各自独立 Task,**避免上下文滚雪球**导致模型遗忘前期约定。

---

## 四、技术栈红线(不可擅改)

| 层级 | 选型 | 理由 |
|---|---|---|
| 前端语言 | **JavaScript**(不用 TypeScript) | 1.0 求快,二期再迁 |
| 前端框架 | React 18 + Vite | — |
| UI 库 | Ant Design 5 + 中文 locale | — |
| 状态管理 | **Zustand**(不用 Redux/Context) | 轻量、对小团队够用 |
| 路由 | React Router v6 | — |
| 后端框架 | FastAPI | — |
| ORM | **SQLModel(同步)**,不用 async | 8 人并发同步够用 |
| 数据库迁移 | **手写 SQL**(`backend/sql/00X_*.sql`),不用 Alembic | schema 稳定后再上 |
| 关系数据库 | PostgreSQL 16 | — |
| 向量检索 | **pgvector**(PG 扩展,不用独立向量库) | 省一个服务、省 ~400MB 内存 |
| 向量维度 | **统一 1536 维**(为 2.0 wiki 兼容) | 不可改 |
| 认证 | **Session + Cookie**(不用 JWT) | 8 人内部系统 |
| AI 模型 | DeepSeek(配置写死,UI 二期做) | — |
| Word 生成 | **docxtpl**(不用裸 python-docx) | — |
| 甘特图 | **frappe-gantt**(不自己用 D3 画) | — |
| 定时任务 | APScheduler(Phase 4c 才用) | — |
| 部署 | Nginx 反向代理(整合 TPS / 蓝皓 TTS / MMIM) | — |

**任何"换成 XXX 更好"的提议**,先在 Plan 模式讨论,绝不直接改。

---

## 五、栏目业务约定(易错点警告——AI 极易写反)

> 这些是栏目特有的反直觉规则,Sonnet / DeepSeek 凭通用习惯做事 100% 会写错,务必死守。

### 5.1 收视颜色判定(色彩规约反直觉)

**只对收视份额(audience_share)上色,收视率(audience_rating)只展示数字不参与判定**:

- 🔴 **红色** = 收视份额 **>** 当年摸高目标 = **优秀**(不是警告!)
- 🔵 **蓝色** = 基础目标 ≤ 收视份额 ≤ 摸高目标 = 达标
- 🟢 **绿色** = 收视份额 **<** 当年基础目标 = **待提升**(不是安全!)

**通用习惯是红警绿安,栏目沿用历史传统刚好相反**。前端写颜色逻辑、AI 生成报表评论、Excel 导出色彩——任何涉及颜色的地方都按此规则。

### 5.2 年度目标只增不改(时间不变性)

`yearly_targets` 表每年新增一行,**历史年份的目标行绝不可被覆盖或删除**:

- 前端展示某期数据时,**根据该期播出年份的目标判颜色**,不是"当前年份的目标"
- 2024 年播的节目永远按 2024 年的 0.6448 / 0.8989 判,2026 年回看也不会变色
- DeepSeek 容易写"upsert 当前年目标"或"全局取最新目标判色"——**禁止**

SQL 端:`yearly_targets.year` 加 UNIQUE 约束,代码端 INSERT 时用 `ON CONFLICT DO NOTHING`(或干脆不写 ON CONFLICT 让冲突直接报错让人看见)。**永远不要 ON CONFLICT UPDATE**。

### 5.3 编导关联用"软引用 + 快照"双字段

`episodes` 表始终维护 **`editor_id` + `editor_name_snapshot`** 双字段:

- **在职编导**:两字段都填(冗余但稳)
- **离职编导**:`editor_id` 留空(NULL),只填 `editor_name_snapshot`(如"张颖")
- **历史导入**:按姓名匹配在职用户,匹配不上只填快照,不报错不丢数据
- **查询某编导历史作品**:**先按 editor_id,失败回退按 editor_name_snapshot 文本匹配**

DeepSeek 容易写"editor_id 外键非空 + 删人级联"——**禁止**。一旦张颖离职,她做过的几十期节目就全成"无主"了,这是栏目最不能接受的。

### 5.4 报题单内容概要的"双段结构"

栏目报题单的"行话格式":

- **默认格式**:**引子(200-300 字)+ 列举(3-5 条 Markdown 序号)**
- **列举每条**以 `**加粗关键词**` 开头(核心装备/概念名)
- **备选格式**:纯叙述式,**仅当编导明确指定时才用**

AI Prompt 模板必须默认走双段、备选纯叙述。docxtpl 模板设计同此。

### 5.5 角色枚举值是拼音(已锁定,不再改)

| 拼音值 | 中文含义 | 权限 |
|---|---|---|
| `zhipianren` | 制片人 / 管理员 | 全部权限 |
| `zebian` | 责编 | 维护仪表盘 / 知识库 / 排期 |
| `biandao` | 编导 | 使用 TPS / 查看知识库 / 生成报题单 / 个人热点雷达 |

**yearly_targets 写权限收紧(2026-05-20)**:
- POST/PATCH: zhipianren + zebian 可写,biandao 返回 403
- DELETE: 仅 zhipianren 可操作,zebian 和 biandao 返回 403
- GET: 三角色均可读

**所有 SQL CHECK、SQLModel Enum、API 鉴权、前端权限判断、菜单显示**——一律使用拼音值,**不得替换为英文**。

---

## 六、AI 设计哲学(贯穿所有 Phase)

**辅助而不替代,AI 给方向不给答案,保护编导创作主权。**

具体落地:

- 模块 B(画像建议)显式标注"仅供参考"
- 模块 D(审片意见)**改为展示历史相似选题原文,不做 AI 预测**
- AI Prompt 中明确告知模型"你输出的是参考稿,不是终稿"
- 任何 AI 输出在 UI 上必须有"我来改写"或"忽略"按钮——给编导否决权

---

## 七、Git 工作流(本版新增)

### 7.1 仓库信息

- **Gitea 地址**:单位 4090D 服务器(具体 URL 用户填)
- **仓库名**:`tps-dashboard`
- **可见性**:团队可见
- **默认分支**:`main`
- **commit message 规范**:Conventional Commits(英文前缀 + 中文正文)

### 7.2 commit message 格式

```
<type>: <中文正文>

[可选:更详细的中文说明]
```

`<type>` 取值(英文小写):

| type | 含义 | 中文正文示例 |
|---|---|---|
| `feat` | 新功能 | `feat: 添加用户登录接口` |
| `fix` | 修 bug | `fix: 修复 created_at 字段 NOT NULL 约束报错` |
| `docs` | 改文档 | `docs: 更新 phase1_log` |
| `chore` | 杂项(依赖、配置) | `chore: 升级 bcrypt 到 4.0.1` |
| `refactor` | 重构 | `refactor: 重构 authStore 状态管理` |
| `style` | 格式化(空格/缩进) | `style: 统一前端缩进为 2 空格` |
| `test` | 加测试 | `test: 添加 auth 接口测试` |

### 7.3 提交时机(Cline 必须遵守)

**每个独立动作单独 commit,不要堆一坨大 commit**:

- 装完依赖 → 立刻 commit
- 建完 SQL 表 → 立刻 commit
- 写完一个完整接口 → 立刻 commit
- 修完一个 bug → 立刻 commit
- **不要写"晚上一起 commit"或"一个 PR 多功能"**

### 7.4 Phase 收尾必须打 tag

每个 Phase 完整收官时,Cline 必须主动建议:

```
git tag -a phase1-complete -m "Phase 1 后端骨架 + 前端骨架完工"
git push origin phase1-complete
```

tag 命名:`phase{N}-{短描述}`,如:
- `phase0-env-ready`
- `phase1-complete`
- `phase2-dashboard-done`

### 7.5 .gitignore 必须包含

- `.env`(永远不上传)
- `__pycache__/`、`*.pyc`
- `node_modules/`
- `dist/`、`build/`
- `*.log`(运行日志,不进版本库;phase{N}_log.md 例外,要进库)
- `.DS_Store`、`Thumbs.db`
- `cookie.txt`(Phase 1 验证后端用的临时文件)

### 7.6 Cline 操作 Git 时的边界

- **Cline 可以自动**:`git add`、`git commit`、`git push`、`git pull`、`git status`、`git log`
- **Cline 必须停下问用户**:
  - `git reset --hard`(任何形式的 hard reset)
  - `git push --force`、`git push -f`
  - `git rebase`(任何形式)
  - 删除分支
  - 删除 tag
  - 删除远程引用
- **永远禁止**:删除整个 .git 目录

### 7.7 多设备同步原则

家里 / 单位两台机器都开发时:

- **离开任何一台机器前**:`git push`(把当前进度推上去)
- **回到另一台机器开干前**:`git pull`(拉最新)
- **每天开始工作的第一件事**:`git status` + `git pull`,确保不基于旧代码改

Cline 在每次开新 Task 时,**第一个动作建议是 `git status`**,确认工作区干净。

---

## 八、Phase 0 安装纪律(从 Phase 0 重启,头一个 Phase 尤其重要)

### 8.1 已知避坑清单(从家用电脑实战提炼)

> 这些坑在家用电脑上踩过,单位机器**直接绕开**。

**Python 端**:

- ❌ 不要用 Microsoft Store 版 Python → ✅ 用 python.org 官方 64 位安装包
- ❌ 不要装 Python 3.13/3.14 → ✅ 装 **Python 3.12.x**(SQLModel 等库新版 Python 兼容性还不稳;3.14 上 pip 装包时大概率报错)
- 安装时勾选 "Add Python to PATH"

**Node.js 端**:

- ❌ 不要装 Node.js 24+ → ✅ 装 **Node.js 22 LTS**(Active LTS 至 2027-04;Node 20 已于 2026-04-30 EOL)
- 单一项目无需 nvm-windows;若同机多项目要共存不同 Node 版本再考虑

**PostgreSQL 端**:

- ❌ 装 PostgreSQL 17+ → ✅ 装 **PostgreSQL 16**
- 装完必须执行 `CREATE EXTENSION vector;` 验证 pgvector 装了
本地数据库:`milsci_dev` / 用户 `postgres` / 密码(记在密码管理器中,**绝不进仓库**)/ 端口 `5432`

**关键 Python 依赖锁版本**(写进 requirements.txt):

```
bcrypt==4.0.1            # 必须锁旧版,新版与 passlib 1.7.4 不兼容会报红字
itsdangerous==2.2.0      # SessionMiddleware 必需,不装运行时报错
python-multipart==0.0.9  # FastAPI 接收表单必需
pydantic-settings==2.2.1 # 配合 BaseSettings 读 .env
```

`starlette` **不要单独装**,它是 FastAPI 的传递依赖。

**CORS 配置**(SessionMiddleware + Cookie 必需):

```python
allow_credentials=True
allow_origins=["http://localhost:5173"]   # 必须显式列,不能用 ["*"]
```

### 8.2 安装节奏

**每装完一项停下汇报、等用户确认才能继续**——禁止"一口气装完五项再来汇报"。

### 8.3 严禁创建的文件名(Act 模式禁词)

根目录下严禁创建含以下关键词的脚本(防止 AI 即兴探索污染项目):

- `check_*` / `verify_*` / `test_*`(测试脚本统一进 `tests/` 目录)
- `tmp_*` / `temp_*` / `debug_*`
- `untitled*` / `new_*`

**例外**:`backend/scripts/create_admin.py` 是 Phase 1 验收必需文件,不属于即兴脚本。

---

## 九、受保护资产清单

**Act 模式严禁修改 / 删除以下文件 / 目录**:

- `.clinerules`(本文件)
- `project_plan.md`、`dev_plan.md`、`README.md`
- `docs/` 目录下所有文件
- `logs/` 目录下所有文件
- 所有 `.xlsx` 样本数据文件(在 `samples/` 目录)
- `.git/` 目录
- `.env` 文件(只能用户手工编辑)

如需修改这些文件,**必须切 Plan 模式经用户确认**。

---

## 十、家用机已完成进度参考(可参考但不强制)

> 家用电脑(D:\myApp\Topic Planning\V2)上 Phase 0 + Phase 1 后端骨架已跑通。
> 单位机器**从 Phase 0 重启**,但代码可参考。

家用机已完成:

- Phase 0 环境(Python 3.12 / Node 20 / PG 16 + pgvector)
- Phase 1 后端骨架(FastAPI + SQLModel + 认证三件套验证通过)
- 12 张表 SQL 已写完(`backend/sql/001_init.sql`)
- create_admin.py 已写完
- 详见 `logs/phase1_log.md`

**单位机器 Phase 1 后端可选路径**:

- **路径 A**:从 0 重写(MiniMax M2.7 重新生成所有后端文件)
- **路径 B**(推荐):用户把家用机的 backend 目录打包 zip 拷到单位机,解压进新仓库,Cline 跑一遍跑通即可

由制片人在 Phase 1 启动时拍板选 A 或 B。

---

## 十一、Anthropic Opus 4.7 顾问的协同方式

Cline 内的 Sonnet/DeepSeek 不直接与 Opus 通信,流程如下:

1. Sonnet 给出 Plan 方案
2. **方案涉及"改 schema / 改认证 / 改架构 / 引新依赖"时**,用户复制方案到 claude.ai 的 Opus 对话框
3. Opus 审完给补充指令,用户复制回 VS Code Cline 的 Plan 模式
4. Sonnet 吸收补充意见,出最终 Plan,切 Act 实施

**这个回路是为关键决策设计的,不是每个小修改都走**——日常 CRUD 改动不需要让 Opus 过目。

---

## 十二、版本演进

| 版本 | 日期 | 主要变化 |
|---|---|---|
| v1 | 2026-04 | 初版,定模型分工与栏目业务约定 |
| v2 | 2026-05-04 | 加技术栈精简版、Phase 拆分 |
| v3 | 2026-05-06 | 加 Git 工作流、已知避坑清单、单位机重启路径;MiniMax M2.7 Phase 2 起接班 Plan 模式(替代 Sonnet),DeepSeek pro 全程在岗 |
| v4 | 2026-05-14 | 家用机退役,唯一开发环境为单位 4090D(E:\tps-dashboard);Phase 2 起 MiniMax M2.7 正式日常使用;config.py 改为 dotenv 直接加载,pydantic-settings 从 requirements.txt 移除 |
| **v5** | **2026-05-15** | **合入第十三章"Opus 4.7 起草 task brief 的节制原则";Phase 2 正式开工** |

**修订原则**:.clinerules 是宪法不是变更日志,改动应慎重。临时执行细节进 phase{N}_log.md,不进本文件。

---

## 十三、Opus 4.7 起草 task brief 的节制原则

Opus 4.7 给 MiniMax 写 task brief 时遵守:

- **一屏内为目标**(约 60-80 行,不超过 100 行)
- **写四类东西**:任务范围、核心约束、业务/纪律红线、验收清单
- **不写四类东西**:代码片段、目录结构细节、变量名、字段命名建议
- 把"怎么实现"留给 MiniMax Plan 模式自己长出来,Opus 只审 Plan 不替 Plan
- 自检口诀:这条是品味判断还是代码细节?品味判断留,代码细节砍
- 例外:业务红线里涉及具体字段名(如 `audience_share` / `editor_id` / `editor_name_snapshot` / `yearly_targets.year`)必须点名,因为写错字段名就是写错业务

---

*本文件最高优先级。任何冲突以本文件为准。*
*下次修订建议时机:Phase 2 末(评估 MiniMax 切换、整理 Phase 2 经验)。*