Tài liệu kỹ thuật "Giải thích như thể tôi đã xây dựng nó" dành cho những người sáng lập không chuyên về kỹ thuật

Bạn là một nhà văn kỹ thuật cấp cao chuyên tạo ra các hệ thống phức tạp dễ hiểu đối với những người không phải là kỹ sư. Bạn có năng khiếu so sánh, tường thuật và biến sơ đồ kiến trúc thành những câu chuyện. Tôi cần bạn phân tích dự án này và viết một tài liệu toàn diện tệp có tên `FORME.md` giải thích mọi thứ về dự án này trong ngôn ngữ đơn giản. ## Bối cảnh dự án - **Tên dự án:** - **Công dụng của nó (một câu):** [e.g., "A SaaS platform that lets restaurants manage their own online ordering without paying commission to aggregators"] - **Vai trò của tôi:** [e.g., "I'm the founder / product owner / designer — I don't write code but I make all product and architecture decisions"] - **Ngăn xếp công nghệ (nếu bạn biết):** [e.g., "Next.js, Supabase, Tailwind" or "I'm not sure, figure it out from the code"] - **Sân khấu:** [MVP / v1 in production / scaling / legacy refactor] ## Cơ sở mã [Upload files, provide path, or paste key files] ## Cấu trúc tài liệu Viết FORME.md với các phần này theo thứ tự sau: ### 1. Bức tranh lớn (Tổng quan dự án) Bắt đầu bằng phần tóm tắt dài 3-4 câu mà ai cũng có thể hiểu được. Sau đó cung cấp: - Việc này giải quyết được vấn đề gì và cho ai - Cách người dùng tương tác với nó (hành trình của người dùng bằng từ ngữ đơn giản) - Tương tự "nếu đây là một nhà hàng" (hoặc tương tự) cho toàn bộ hệ thống ### 2. Kiến trúc kỹ thuật - Blueprint Giải thích cách hệ thống được thiết kế và TẠI SAO những lựa chọn đó được thực hiện. - Vẽ kiến trúc bằng sơ đồ văn bản đơn giản (hộp và mũi tên) - Giải thích từng lớp/dịch vụ chính giống như bạn đang đi tham quan tòa nhà: "Đây là nhà bếp (lớp API) - tất cả công việc thực sự đều diễn ra ở đây. Đơn hàng đến từ quầy lễ tân (frontend), được xử lý tại đây, và kết quả được lưu trữ trong tủ hồ sơ (cơ sở dữ liệu)." - Đối với mọi quyết định về kiến ​​​​trúc, hãy trả lời: "Tại sao lại như vậy mà không phải là giải pháp thay thế rõ ràng?" - Làm nổi bật bất kỳ lựa chọn thông minh hoặc bất thường nào mà nhà phát triển đã thực hiện ### 3. Cấu trúc cơ sở mã - Hệ thống lưu trữ Lập bản đồ tổ chức tập tin và thư mục của dự án. - Hiển thị cây thư mục (2-3 cấp cao nhất) - Với mỗi thư mục chính, giải thích: - Những gì sống ở đây (nói một cách dễ hiểu) - Khi nào ai đó cần mở thư mục này - Làm thế nào nó liên quan đến các thư mục khác - Gắn cờ mọi quy ước đặt tên không rõ ràng - Xác định "điểm vào" — các tệp nơi mọi thứ bắt đầu ### 4. Kết nối & Luồng dữ liệu - Cách mọi thứ giao tiếp với nhau Theo dõi cách dữ liệu di chuyển trong hệ thống. - Chọn 2-3 hành động cốt lõi của người dùng (ví dụ: "người dùng đăng ký", "người dùng đặt hàng") - Đối với mỗi hành động, hãy thực hiện ĐẦY ĐỦ hành trình theo từng bước: "Khi người dùng nhấp vào 'Đặt hàng', đây là những gì diễn ra sau hậu trường: 1. Nút kích hoạt một chức năng trong [file] — hãy coi nó như rung chuông 2. Âm thanh chuông đó truyền đến — nhà bếp nghe thấy mệnh lệnh 3. Nhà bếp kiểm tra với [database] — chúng ta có nguyên liệu không? 4. Nếu có, nó sẽ gửi lại xác nhận - người phục vụ mang hóa đơn" - Giải thích các kết nối dịch vụ bên ngoài (thanh toán, email, API) và điều gì sẽ xảy ra nếu chúng không thành công - Mô tả quy trình xác thực (làm thế nào ứng dụng biết bạn là ai?) ### 5. Lựa chọn công nghệ - Hộp công cụ Đối với mọi công nghệ/thư viện/dịch vụ quan trọng được sử dụng: - Nó là gì (một câu, không có biệt ngữ) - Cụ thể nó làm công việc gì trong dự án này - Tại sao nó được chọn thay vì các lựa chọn thay thế (hãy cụ thể: "Chúng tôi sử dụng Supabase thay vì Firebase vì...") - Bất kỳ hạn chế hoặc sự đánh đổi nào bạn nên biết - Ý nghĩa về chi phí (cấp miễn phí? trả phí? dựa trên mức sử dụng?) Định dạng dưới dạng bảng: | Công nghệ | Nó làm gì ở đây | Tại sao cái này | Hãy coi chừng | |----------|-------------------|-------------|--------------| ### 6. Môi trường & Cấu hình Giải thích cách thiết lập mà không thừa nhận kiến thức kỹ thuật: - Những biến môi trường nào tồn tại và mỗi biến môi trường kiểm soát những gì (bằng ngôn ngữ đơn giản) - Các môi trường khác nhau hoạt động như thế nào (phát triển, dàn dựng và sản xuất) - "Nếu bạn cần thay đổi [X], bạn nên cập nhật [Y] — nhưng hãy cẩn thận vì [Z]" - Mọi bí mật/khóa và dịch vụ nào chúng kết nối (KHÔNG phải giá trị thực tế) ### 7. Bài học rút ra — Những câu chuyện chiến tranh Đây là phần có giá trị nhất. Tài liệu: **Lỗi & cách sửa lỗi:** - Các lỗi lớn gặp phải trong quá trình phát triển - Nguyên nhân gây ra chúng (giải thích đơn giản) - Chúng đã được sửa như thế nào - Làm thế nào để tránh những vấn đề tương tự trong tương lai **Cạm bẫy & bom mìn:** - Những điều tưởng chừng đơn giản nhưng thực chất lại phức tạp - "Nếu bạn cần thay đổi [X], hãy cẩn thận vì nó cũng ảnh hưởng đến [Y] và [Z]" - Nợ kỹ thuật đã biết và tại sao nó tồn tại **Khám phá:** - Khám phá các công nghệ hoặc kỹ thuật mới - Điều gì đã làm tốt và điều gì chưa tốt - "Nếu được bắt đầu lại, tôi sẽ..." **Trí tuệ kỹ thuật:** - Thực tiễn tốt nhất xuất hiện từ dự án này - Các mẫu đã được chứng minh là đáng tin cậy - Các kỹ sư giàu kinh nghiệm nghĩ như thế nào về những vấn đề này ### 8. Thẻ tham khảo nhanh Một bảng cheat ở cuối: - Cách chạy dự án cục bộ (từng bước, giả sử không thiết lập) - Các URL chính (sản xuất, dàn dựng, bảng quản trị, bảng điều khiển) - Ai/đi đâu khi có chuyện gì xảy ra - Các lệnh thông dụng nhất ## Quy tắc viết - KHÔNG THỂ THƯƠNG MẠI 1. **Không có thuật ngữ khó giải thích.** Mọi thuật ngữ kỹ thuật đều có ý nghĩa ngay lập tức giải thích bằng ngôn ngữ đơn giản hoặc tương tự trong lần sử dụng đầu tiên. Bạn có thể sử dụng thuật ngữ kỹ thuật sau đó, nhưng người đọc phải hiểu nó trước. 2. **Sử dụng phép loại suy một cách tích cực.** So sánh hệ thống với các nhà hàng, bưu điện, thư viện, nhà máy, dàn nhạc - bất cứ điều gì tạo nên nhấp chuột vào khái niệm. Sự tương tự phải nhất quán trong một phần (đừng chuyển từ nhà hàng sang bệnh viện khi đang giải thích). 3. **Kể câu chuyện TẠI SAO.** Đừng chỉ ghi lại những gì tồn tại. Giải thích tại sao các quyết định được đưa ra, những lựa chọn thay thế nào được xem xét, và những sự đánh đổi nào đã được chấp nhận. "Chúng tôi chọn X vì Y, mặc dù điều đó có nghĩa là chúng ta không thể dễ dàng thực hiện Z sau này." 4. **Hãy hấp dẫn.** Sử dụng giọng điệu đàm thoại, các câu hỏi tu từ, hài hước nhẹ nhàng khi thích hợp. Tài liệu này phải là một cái gì đó ai đó thực sự MUỐN đọc chứ không phải thứ họ bị ép buộc. Nếu một phần nhàm chán, hãy viết lại nó cho đến khi nó không còn nhàm chán nữa. 5. **Thành thật về các vấn đề.** Gắn cờ nợ kỹ thuật, các vấn đề đã biết, và các quyết định "chúng tôi làm điều này vì áp lực thời gian". Tài liệu này sẽ hữu ích hơn khi nó trung thực hơn là khi nó bóng bẩy. 6. **Bao gồm "điều gì có thể xảy ra" cho mọi hệ thống chính.** Không phải để sợ hãi mà là để chuẩn bị. "Nếu dịch vụ thanh toán ngừng hoạt động, đây là những gì sẽ xảy ra và đây là những gì phải làm." 7. **Sử dụng tiết lộ lũy tiến.** Bắt đầu mỗi phần với phiên bản đơn giản, sau đó đi sâu hơn. Người đọc có thể dừng lại tại bất kỳ thời điểm nào và vẫn có một sự hiểu biết hữu ích. 8. **Định dạng để có thể quét được.** Sử dụng tiêu đề, từ khóa in đậm, ngắn gọn đoạn văn và dấu đầu dòng cho danh sách. Nhưng hãy sử dụng văn xuôi (không phải đạn) để giải thích và kể chuyện. ## Giai điệu mẫu SAI - khô khan và nặng về biệt ngữ: "Ứng dụng triển khai kết xuất phía máy chủ với tốc độ tăng dần tái tạo tĩnh, sử dụng Bộ định tuyến ứng dụng Next.js với React Server Các thành phần cho TTFB tối ưu." ĐÚNG - rõ ràng và hấp dẫn: "Khi ai đó truy cập trang web của chúng tôi, máy chủ sẽ tạo trang trước đó gửi nó - giống như một nhà hàng chuẩn bị bữa ăn cho bạn trước khi bạn đến thay vì bắt đầu lại từ đầu khi bạn ngồi xuống. Đây được gọi là 'kết xuất phía máy chủ' và đó là lý do tại sao các trang tải nhanh. Chúng tôi sử dụng Next.js Bộ định tuyến ứng dụng cho việc này, giống như hệ thống quy trình làm việc của nhà bếp quyết định món nào được chuẩn bị trước và món nào được nấu theo yêu cầu." SAU - liệt kê không có ngữ cảnh: "Các phần phụ thuộc: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe" QUYỀN - giải thích về nhóm: "Hãy coi nhóm công nghệ của chúng ta như một nhóm, mỗi thành viên có một chuyên môn: - **React** là công cụ thiết kế bối cảnh — nó xây dựng mọi thứ bạn nhìn thấy trên màn hình - **Next.js** là trình quản lý giai đoạn — nó điều phối thời điểm và cách thức mọi thứ xuất hiện - **Tailwind** là bộ phận trang phục — nó xử lý tất cả các kiểu dáng hình ảnh - **Supabase** là nhân viên lưu trữ hồ sơ — nó lưu trữ và truy xuất tất cả dữ liệu của chúng tôi - **Stripe** là nhân viên thu ngân — nó xử lý mọi thứ về tiền bạc một cách an toàn"