tps-dashboard/logs/phase0_log.md

# Phase 0 开发日志 — 单位机环境就绪

> 《军事科技》栏目内部工作台 · Phase 0
> 撰写日期:2026-05-09
> 状态:**完成**

---

## 一、本 Phase 完成时间

- **开始日期**:2026-05-09(单位 4090D 机器接续家用机进度)
- **完成日期**:2026-05-09 当天

---

## 二、本 Phase 做了什么

1. **勘察 4090D 现有开发环境**:发现 Python 3.12 / Python 3.14 / Node 24 / Git 2.53 / npm 已存在,PostgreSQL 未装。基于勘察结果定下"补缺不重装"的策略,避免破坏 4090D 上其他项目的依赖。

2. **PowerShell 执行策略调整**:`Restricted` → `RemoteSigned`(用户级),解决 npm 调用 ps1 脚本被拦截的问题。

3. **Node 24 → Node 22 LTS 替换**:发现项目原定的 Node 20 已 EOL(官方 2026-04-30 停止维护),选 Node 22 LTS(Active LTS 至 2027-04)替代。dev_plan 文档同步更新。

4. **PostgreSQL 16.13 + pgvector 0.8.2 安装**:
   - PG 16 用 EnterpriseDB 官方安装包,Locale 选 `C`(非中文 Locale,避免排序行为副作用)
   - pgvector 用第三方预编译 Windows 二进制(`andreiramani/pgvector_pgsql_windows` v0.8.2-pg16),手动复制 lib/share/include 到 PG 安装目录
   - `CREATE EXTENSION vector` 在 `postgres` 库验证通过,`extversion = 0.8.2`

5. **创建项目数据库 `milsci_dev`**:UTF8 编码,Locale 跟随实例为 `C`,等 Phase 1 跑 `001_init.sql` 时再启用 vector 扩展。

6. **文档微调**:`git_workflow.md` 路径从 `D:\tps-dashboard\` 改为 `Z:\AIworks\tps-dashboard\`(NAS 实际路径);`dev_plan.md` 技术栈表 Node 20 → Node 22。

---

## 三、关键决策记录

### 3.1 沿用 4090D 已有 Python 3.12,不为 3.14 折腾

`where.exe python` 显示 3.12 与 3.14 共存,默认调用 3.14。决策:**项目内永远显式 `py -3.12`**,不动 3.14、不卸 3.14。

### 3.2 Node 20 → Node 22:跟着 LTS 走,不锁版本号

Node 20 在 dev_plan v3 拍板时(2026-05-06)还是 Active LTS,但官方维护期已于 2026-04-30 结束。**LTS 是"求稳"目标,不是"必须 20 这个数字"**。换 22 后 dev_plan 第五章技术选型表已同步更新。

### 3.3 pgvector 走第三方预编译包,放弃源码编译

源码编译要装 Visual Studio Build Tools(几个 GB)+ 配 nmake,新人易卡 1-2 小时。第三方预编译包 `andreiramani/pgvector_pgsql_windows` 是 Windows 圈最常用源,解压拷贝即用。**风险评估**:4090D 内网开发机,数据库无敏感数据,风险可接受。装完文件名/版本号/校验都对得上。

### 3.4 PG Locale 选 `C` 不选中文

中文 Locale 影响排序规则但不影响 UTF-8 中文存储,且选中文 Locale 会引入 LIKE 匹配、字符串函数行为差异等隐性 bug。**项目内所有需要排序的字段都按时间/ID/分数排,不依赖 Locale 排序**——Locale `C` 是 PG 圈开发者标准做法。

---

## 四、踩过的坑 + 怎么解决的

### 坑 1:`where` 命令在 PowerShell 里被劫持

**现象**:`where python` 无输出,以为 Python 没装。
**原因**:PowerShell 里 `where` 是 `Where-Object` 别名,行为跟 cmd 的 `where.exe` 不一样。
**解决**:用 `where.exe python`(显式带扩展名)绕过别名。
**经验**:在 PowerShell 里查 PATH 上的可执行文件位置,**永远用 `where.exe`**。

### 坑 2:Node 20 LTS 在 Node.js 官网下载页被标 EOL

**现象**:Node.js 官网下载页 v20.20.2 标 `EOL`,只有 v22.22.2 标 `LTS`。
**原因**:Node 20 LTS 维护期 2026-04-30 已到期,提前一周被标 EOL。
**解决**:升 Node 22 LTS,dev_plan 同步更新。
**经验**:**长期 LTS 选型决策要写"跟着官方 Active LTS 走"而不是"锁某个数字"**——这个项目的下一次 LTS 切换可能在 2027 年(Node 24 转 Active LTS 时)。

### 坑 3:PG 安装包不带 pgvector

**现象**:PG 16.13 装完后 `share\extension\` 下无 `vector.control`。
**原因**:EnterpriseDB Windows 安装包不附带 pgvector,Stack Builder 也没有。
**解决**:手动从 `andreiramani/pgvector_pgsql_windows` 下载 v0.8.2-pg16 zip,解压后用管理员 PowerShell 复制 dll/sql/header 到 PG 安装目录,启动服务后 `CREATE EXTENSION vector` 通过。
**经验**:Windows + PG + pgvector 这条路,**第三方预编译包是目前最不折腾的方案**——官方暂时没有 Windows 端的省心方案。

---

## 五、遗留事项

### 5.1 跨 Phase 遗留(Phase 1 触发时处理)

- [ ] **Phase 1 后端代码迁移**(路径 B):从家用机 zip 后端整目录,Sonnet Plan 审一遍,跑 `pip install + psql + create_admin + uvicorn` 验证
- [ ] **001_init.sql 中启用 pgvector**:Phase 1 跑 `001_init.sql` 时,在 `milsci_dev` 库里执行 `CREATE EXTENSION IF NOT EXISTS vector;`(脚本第一行应已包含此语句)
- [ ] **Microsoft Store 版 Python 占位符**:`where.exe python` 第三行有 `WindowsApps\python.exe`,目前不影响,如未来意外被调用再处理

### 5.2 跨 Phase 遗留(Phase 5 部署时处理)

- [ ] **`.env` 中的 SECRET_KEY**:Phase 5 部署到腾讯云前必须改为真实随机值
- [ ] **session cookie 部署配置**:`same_site="strict"` + `https_only=True`(目前是开发配置)
- [ ] **关闭生产环境的 `/docs`**:或加密保护

---

## 六、本 Phase 用到的工具 / 模型回顾

| 角色 | 工具 / 模型 | 用途 |
|---|---|---|
| 制片人(刘通) | 人脑 + 浏览器 + VS Code 终端 | 执行命令、装软件、卡壳兜底咨询 |
| 高级技术顾问 | Claude Opus 4.7(Claude.ai 网页) | 全程指导,Phase 0 在对话框里完成,未启用 Cline |

**模型策略**:Phase 0 是环境勘察 + 增量补装,GUI 操作多,**不适合 Cline**。Cline 从 Phase 1 起接入。

---

## 七、当前可启动状态(供 Phase 1 参考)

```bash
# Python 3.12 调用方式(项目内永远显式 py -3.12,不用 python):
py -3.12 --version       # → Python 3.12.10
py -3.12 -m pip --version # → pip 25.0.1 (python 3.12)

# Node:
node --version           # → v22.22.2
npm --version            # → 10.9.7

# Git:
git --version            # → git version 2.53.0.windows.2

# PostgreSQL(密码已记录在密码管理器):
psql -U postgres         # → 进入 postgres=#
```

项目目录:`Z:\AIworks\tps-dashboard\`(NAS 映射)

数据库:`milsci_dev`(待 Phase 1 跑 001_init.sql 建表)

---

## 八、下一步(Phase 1 准备)

1. **打开 Cline,新开一个 Task**(Phase 1 起 Cline 接管骨架开发)
2. **决定路径 A(重写)还是路径 B(迁移)**——dev_plan v3 推荐 B,从家用机 zip backend 整目录到 4090D
3. **路径 B 操作**:制片人在家用机打包 backend zip → 拷到 4090D `Z:\AIworks\tps-dashboard\backend\` → Cline 跑 Plan(Sonnet)审一遍代码与新版宪法一致性 → Act(DeepSeek pro)修补不一致 → 跑通三件套(login / me / logout)
4. **完成后写 phase1_log.md**(扩充家用机版本,加 4090D 上发生的事)

---

*本日志由 Claude Opus 4.7 在 Phase 0 当天对话末尾基于全程对话整理生成。*
*下次 Phase 收尾时,沿用本格式扩充 phase1_log.md。*