# AGENTS.md — 达道Task 仓库工作约定

> 给所有在本仓库工作的 AI / 人类协作者的强制约定。**改动前先读完此文件。**

## 1. 项目是什么

达道Task：任务管理（todo）→ 工单协同 → 知识库，三件事一条流，LLM 贯通。
Web（React）+ 安卓（Compose）+ 后端（FastAPI），SaaS 多租户形态。

- 方案：[`2.Design/PRODUCT-PLAN.md`](2.Design/PRODUCT-PLAN.md)
- 实施清单：[`2.Design/ROADMAP-M0-M1.md`](2.Design/ROADMAP-M0-M1.md)
- 命名：[`2.Design/NAMING.md`](2.Design/NAMING.md)

## 2. 铁律（违反即回滚）

1. **改完必须提交并 push**。本地有未推送提交视为未完成。
2. **生产不得领先仓库**。部署的代码必须是仓库 HEAD，不允许"服务器上手动改一下"。
3. **前端产物只能由仓库 HEAD 构建**，不允许本地构建后上传 dist。
4. **部署后必须校验 build 标记**：`curl /version` 返回的 commit 必须等于 `git rev-parse --short HEAD`。
5. **多租户安全不讨价还价**：任何新增租户表，必须同时提交 ① `workspace_id NOT NULL` 列 ② RLS 策略 ③ 跨租户隔离测试。三者缺一，PR 直接拒。

## 3. 技术栈（不得擅自更换）

| 层 | 选型 |
|---|---|
| 后端 | FastAPI + SQLAlchemy 2.0 async + PostgreSQL 16（RLS + pgvector）+ Redis |
| 迁移 | Alembic（autogenerate 后**必须人工复核**，不准盲上） |
| Web | React 18 + TypeScript + Vite + Tailwind |
| 安卓 | Kotlin + Jetpack Compose |
| LLM | OpenAI 兼容网关；平台兜底 DeepSeek，用户可配 |

## 4. 目录

```
backend/    FastAPI 服务（app/ 业务，tests/ 测试，alembic/ 迁移）
web/        React 前端
android/    Kotlin 安卓端
deploy/     部署脚本与 compose
2.Design/   设计文档（大写连字符命名，如 API.md、DEPLOY.md）
```

## 5. 提交规范

```
feat(task): 支持批量改状态
fix(auth): 刷新令牌未轮换
docs(plan): 补充工单状态机
```

- 一个提交只做一件事；格式化与业务分开提交。
- `main` 受保护，功能走 `feat/*` 分支。

## 6. 本地开发

```bash
# 依赖
cd deploy && docker compose -f docker-compose.dev.yml up -d

cd backend && pip install -r requirements.txt
pytest                      # 必须全绿才能提交
ruff check . && ruff format --check .
```

## 7. 禁区

- 不准把密钥、token、真实用户手机号写进仓库或测试夹具。
- 不准在日志里打印 `password` / `token` / `api_key`（中间件已做脱敏，别绕开它）。
- 不准跳过租户隔离测试，哪怕"这次只是改文档"。
- 不准直接读写 `.dsh/memory-vault`（记忆库只能通过工具/API 写入）。