{"repo": "827238158/homebuild-log", "files": {"README.md": {"4777ef9ad1a9ffc31c098af8320b9652fa482f5c": {"t": 1785595224.179348, "n": 2994, "h": "4b23a000b159aa94", "c": "# HomeBuild Log\n\n装修事件与知识管理系统。用户通过自然语言、图片或票据描述装修过程中发生的事情，系统将其整理为事件、账目、问题、尺寸、决策和调研记录，并通过时间线、账本、问题看板和空间档案呈现。账目只记录付款、退款和收入，待办、普通问题和施工问题统一为“问题”。\n\n## 当前阶段\n\n项目已完成阶段 1 本地数据底座、阶段 2 手工记录闭环、阶段 3A 文本 AI 录入和阶段 3B 全项目数据可视化。当前默认进入中文概览，可查看问题、到货风险和最近动态；时间线、人民币账本、问题、空间、六类记录及 AI 运行数据均提供可下钻分析。阶段 4 OCR/PWA 及阶段 5 稳定化仍待单独授权。\n\n规划基线：个人私用的响应式Web/PWA，Windows本地自托管，React/TypeScript/Vite PWA前端、FastAPI后端、SQLite与本地附件目录、可插拔AI，以及跨模型Agent单写者串行协作。\n\n## 文档地图\n\n- [AGENTS.md](AGENTS.md)：Agent 协作规则与按需检索流程。\n- [项目规格](docs/00-project-spec.md)：目标用户、核心能力、非目标与未知项。\n- [概念架构](docs/01-architecture.md)：模块、数据流与不可随意改动的边界。\n- [代码与文档风格](docs/02-style-guide.md)：术语、注释、错误处理和文档规则。\n- [接口契约](docs/03-api-contracts.md)：当前契约边界及未来记录要求。\n- [开发流程](docs/04-dev-workflow.md)：任务、检查、测试、构建和提交约定。\n- [决策记录](docs/05-decisions.md)：已确认决策及待决策事项。\n- [领域模型](docs/06-domain-model.md)：来源、候选、六类记录、共享实体、状态和关联。\n- [交互与可视化](docs/07-ux-visualization.md)：录入、确认、核心页面和响应式体验。\n- [路线图与跨模型协作](docs/08-roadmap-agent-collaboration.md)：实施阶段、任务门禁、活动锁和交接规则。\n- [真实事件样本](docs/samples/real-events.md)：保留原始描述并记录候选信息与一事多记录分析。\n- [任务总览](tasks/README.md)：任务状态、当前任务和候选任务池。\n- [当前活动任务](tasks/ACTIVE.md)：唯一写入Agent、任务范围和锁状态。\n- [检查清单](checklists/task-start.md)：任务开始、实现审查、文档更新和发布检查入口。\n\n## 开始下一项工作\n\n1. 阅读 `AGENTS.md`，先输出本任务的 `Need:` 列表。\n2. 读取`tasks/ACTIVE.md`确认写入权；只读任务不得认领写入锁。\n3. 从 `tasks/TASK-TEMPLATE.md` 创建任务，明确范围、非目标、允许修改文件与验收标准。\n4. 只读取当前步骤需要的资料，完成后执行 `checklists/implementation-review.md`并释放活动锁。\n\n当前候选方向只是待梳理事项，不代表已批准实施；请先在 `tasks/README.md` 中确认或调整优先级。\n\n## 本地开发基线\n\n### 后端\n\n```powershell\nconda create -n homebuild-log python=3.13 pip -y\nconda activate homebuild-log\nSet-Location backend\npython -m pip install -r requirements.lock\npython -m pip install -e . --no-deps\npython -m alembic -c alembic.ini upgrade head\nfastapi dev app/main.py --host 127.0.0.1 --port 8000\n```\n\n后端健康接口：`http://127.0.0.1:8000/api/v1/health`；OpenAPI文档：`http://127.0.0.1:8000/docs`。\n\n### 文本 AI 配置\n\nAI 默认关闭。推荐先设置环境变量，再将`.local-data/config/secrets.json`中的`ai.enabled`改为`true`；环境变量优先于文件内Key：\n\n```powershell\n$env:DEEPSEEK_API_KEY = \"你的 DeepSeek Key\"\n$env:MIMO_API_KEY = \"你的 MiMo Key\"\n```\n\n`secrets.json`的AI区块默认值如下，修改时保留已有管理员密码哈希和JWT密钥：\n\n```json\n{\n  \"ai\": {\n    \"enabled\": true,\n    \"provider_order\": [\"mimo\", \"deepseek\"],\n    \"timeout_seconds\": 30,\n    \"temperature\": 0.3,\n    \"providers\": {\n      \"deepseek\": {\n        \"base_url\": \"https://api.deepseek.com\",\n        \"model\": \"deepseek-v4-flash\",\n        \"auth_style\": \"bearer\",\n        \"api_key\": \"\"\n      },\n      \"mimo\": {\n        \"base_url\": \"https://api.xiaomimimo.com/v1\",\n        \"model\": \"mimo-v2.5-pro\",\n        \"auth_style\": \"api-key\",\n        \"api_key\": \"\"\n      }\n    }\n  }\n}\n```\n\n未配置任何Key时服务仍正常启动，`auto`自动使用本地规则。\n\n### 前端\n\n另开一个PowerShell窗口：\n\n```powershell\nSet-Location frontend\nnpm ci\nnpm run dev\n```\n\n浏览器访问`http://127.0.0.1:5173`。Vite会把`/api`请求代理到本地后端。\n\n### 检查\n\n```powershell\nSet-Location backend\npython -m ruff check . --no-cache\npython -m pytest\n\nSet-Location ..\\frontend\nnpm run lint\nnpm run test\nnpm run build\nnpm audit\n```\n\n运行数据统一位于项目根目录的`.local-data/`，不会进入Git。\n"}}}}