simonkoson/tps-dashboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
phase0-env-ready
tps-dashboard/logs/phase0_log.md
T

6.8 KiB
Raw Permalink Blame History

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 参考)

# 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。

Reference in New Issue View Git Blame Copy Permalink