diff --git a/.clinerules b/.clinerules index 36d3670..07f0709 100644 --- a/.clinerules +++ b/.clinerules @@ -271,19 +271,19 @@ Cline 在每次开新 Task 时,**第一个动作建议是 `git status`**,确认 **Python 端**: - ❌ 不要用 Microsoft Store 版 Python → ✅ 用 python.org 官方 64 位安装包 -- ❌ 不要装 Python 3.13 → ✅ 装 **Python 3.12.x**(SQLModel 等库 3.13 兼容性还不稳) +- ❌ 不要装 Python 3.13/3.14 → ✅ 装 **Python 3.12.x**(SQLModel 等库新版 Python 兼容性还不稳;3.14 上 pip 装包时大概率报错) - 安装时勾选 "Add Python to PATH" **Node.js 端**: -- ❌ 不要装 Node.js 22+ → ✅ 装 **Node.js 20 LTS** -- 推荐用 **nvm-windows** 装,方便切换版本 +- ❌ 不要装 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` / 密码 `liutong65` / 端口 `5432` +本地数据库:`milsci_dev` / 用户 `postgres` / 密码(记在密码管理器中,**绝不进仓库**)/ 端口 `5432` **关键 Python 依赖锁版本**(写进 requirements.txt): diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..5a30c3b --- /dev/null +++ b/.gitattributes @@ -0,0 +1,3 @@ +* text=auto eol=lf +*.bat text eol=crlf +*.ps1 text eol=crlf \ No newline at end of file diff --git a/dev_plan.md b/dev_plan.md index 7b9865b..f82e26a 100644 --- a/dev_plan.md +++ b/dev_plan.md @@ -29,7 +29,7 @@ > 家用电脑路径:`D:\myApp\Topic Planning\V2` -- ✅ Phase 0 环境(Python 3.12 / Node 20 / PG 16 + pgvector / VS Code + Cline) +- ✅ Phase 0 环境(Python 3.12 / Node 20 / PG 16 + pgvector / VS Code + Cline)*[家用机记录,单位 4090D 已升级为 Node 22 LTS]* - ✅ Phase 1 后端骨架(FastAPI + SQLModel + Session 认证三件套验证通过) - ✅ 12 张表 SQL 已写完(`backend/sql/001_init.sql`) - ✅ create_admin.py 已写完 @@ -298,7 +298,7 @@ git push origin phase0-env-ready ### Phase 5:部署上线 + Buffer(Week 11-12) - **新服务器准备**:腾讯云 4核8G 轻量服务器(待租) - - Ubuntu 22.04 LTS / Nginx / Python 3.12 / PostgreSQL 16 + pgvector / Node 20 + - Ubuntu 22.04 LTS / Nginx / Python 3.12 / PostgreSQL 16 + pgvector / Node 22 LTS - **Nginx 反向代理整合**(`project_plan.md` 第八章规划): ``` 主域名/ → 工作台前端 diff --git a/docs/git_workflow.md b/docs/git_workflow.md index e6c45ba..a4bf752 100644 --- a/docs/git_workflow.md +++ b/docs/git_workflow.md @@ -60,7 +60,7 @@ **成功标志**:页面跳到一个新页面,显示 `tps-dashboard` 是空的,中间有一段灰底的命令提示,大概长这样(具体地址你以你那台 Gitea 的 URL 为准): ``` -git clone http://你的Gitea地址/你的用户名/tps-dashboard.git +git clone http://localhost:3000/simonkoson/tps-dashboard.git ``` **把这一行复制下来,下一步要用**。 @@ -70,11 +70,11 @@ git clone http://你的Gitea地址/你的用户名/tps-dashboard.git **操作位置**:VS Code 打开任何窗口都行,在终端面板里执行(快捷键 `Ctrl + ` `) ```powershell -# 切换到你想放项目的位置(避免中文路径,推荐 D:\) -cd D:\ +# 切换到你想放项目的位置 +cd Z:\AIworks\ # 把刚才复制的 clone 命令粘贴运行 -git clone http://你的Gitea地址/你的用户名/tps-dashboard.git +git clone http://localhost:3000/simonkoson/tps-dashboard.git ``` **期间可能要求输入 Gitea 账号密码**——输入即可,Git 会记住。 @@ -88,12 +88,12 @@ done. `warning: empty repository` 是**正常的**——本来就是空仓库,不是错误。 -完成后 `D:\` 下多了一个 `tps-dashboard` 文件夹。 +完成后 `Z:\AIworks\` 下多了一个 `tps-dashboard` 文件夹。 ### 2.3 进仓库目录 ```powershell -cd D:\tps-dashboard +cd Z:\AIworks\tps-dashboard ``` 之后所有 git 命令都在这个目录里跑。 @@ -104,17 +104,17 @@ cd D:\tps-dashboard **手动操作**(用 Windows 资源管理器): -1. 在 `D:\tps-dashboard\` 下: +1. 在 `Z:\AIworks\tps-dashboard\` 下: - 直接拷入 `.clinerules`、`project_plan.md`、`dev_plan.md`、`README.md`(平铺四份) -2. 在 `D:\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去 +2. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `docs`,把 `git_workflow.md` 拷进去 -3. 在 `D:\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去 +3. 在 `Z:\AIworks\tps-dashboard\` 下**新建文件夹** `logs`,把 `phase1_log.md` 拷进去 **最终结构应该是**: ``` -D:\tps-dashboard\ +Z:\AIworks\tps-dashboard\ ├── .clinerules ├── project_plan.md ├── dev_plan.md @@ -132,7 +132,7 @@ D:\tps-dashboard\ **操作**:在 VS Code 终端里执行: ```powershell -cd D:\tps-dashboard +cd Z:\AIworks\tps-dashboard notepad .gitignore ``` @@ -226,7 +226,7 @@ git push -u origin main ``` Enumerating objects: ... Writing objects: 100% (...) -To http://你的Gitea地址/你的用户名/tps-dashboard.git +To http://localhost:3000/simonkoson/tps-dashboard.git * [new branch] main -> main branch 'main' set up to track 'origin/main'. ``` @@ -244,7 +244,7 @@ branch 'main' set up to track 'origin/main'. ### 3.1 每天开工第一件事 ```powershell -cd D:\tps-dashboard +cd Z:\AIworks\tps-dashboard git status # 看看本地有没有未提交的改动 git pull # 拉 Gitea 最新(如果别的机器推过) ``` @@ -268,7 +268,7 @@ Cline(Sonnet → DeepSeek)会自动跑 git add / git commit / git push。**这 ### 3.4 你自己手工提交(备选) ```powershell -cd D:\tps-dashboard +cd Z:\AIworks\tps-dashboard git add -A git commit -m "fix: 修复登录页跳转问题" git push @@ -386,8 +386,8 @@ git push origin phase1-complete ### Q5:换了一台机器,怎么把代码搞过来 ```powershell -cd D:\ -git clone http://你的Gitea地址/你的用户名/tps-dashboard.git +cd Z:\AIworks\tps-dashboard +git clone http://localhost:3000/simonkoson/tps-dashboard.git cd tps-dashboard # 然后跟原来一样开工就行 ``` diff --git a/logs/phase0_log.md b/logs/phase0_log.md new file mode 100644 index 0000000..319942a --- /dev/null +++ b/logs/phase0_log.md @@ -0,0 +1,141 @@ +# 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。* \ No newline at end of file